|
Start Communication Notification (80)
|
Top
Previous
Next
|
|
The Start Communication Notification function begins the process by which your EHLLAPI application can determine whether the specified session is connected to a host.
After using this function, the application can use Query Communication Event (81) to determine whether the session is connected or disconnected.
Prerequisite Calls
There are no prerequisite calls for this function.
Call Parameters
|
Enhanced Interface
|
Function Number
|
Must be 80
|
Data String
|
Preallocated structure; see the following table
|
Length
|
16
|
PSPosition
|
NA
|
The calling data structure contains these elements
Byte
|
Definition
|
1
|
A 1-character presentation space short name (PSID).
|
2-4
|
Reserved
|
5
|
One of the following values: The character C asks for notification when the session either disconnects or connects to the host. The character A requests the asynchronous mode of notification. When A is specified, position 9-12 returns the address of an event object (Windows). The character C must be placed in position 13. The character M requests the asynchronous message mode of the notification. When M is specified, the event selection character C must be placed in position 13.
|
6-8
|
Reserved
|
9-12
|
When M is specified in position 5, the window handle of the window that receives the message should be set. The message is a return value of RegisterWindowMessage (PCSHLL)--(not zero).
|
13
|
This should contain the character C if position 5 is A or M.
|
14-16
|
Reserved
|
Data String
If A (asynchronous mode) is specified in position 5 of the calling data structure and the function is completed successfully, the following data string is returned:
Byte
|
Definition
|
1
|
A 1-character presentation space short-name (PSID)
|
2-8
|
Reserved
|
9-12
|
4-byte binary value in which the event object handle is returned by EHLLAPI. The application can wait for this event object.
|
If M (asynchronous message mode) is specified in position 5 of the calling data structure and the function is completed successfully, the following data string is returned:
Byte
|
Definition
|
1
|
A 1-character presentation space short-name (PSID)
|
2-8
|
Reserved
|
9-10
|
Task ID of asynchronous message mode
|
When the session connects or disconnects an application window receives a message. The message is the return value of RegisterWindow Message (PCSHLL). The wParam contains the Task ID returned by the function call. HIWORD of lParam contains a 21 if the session is connected to the host or a 22 if the session is disconnected. The LOWORD of lParam contains the function number 80.
Return Parameters
Return Code
|
Definition
|
0
|
The function was successful
|
1
|
An incorrect PSID was specified
|
2
|
An error was made in designating parameters
|
9
|
A system error was encountered
|
Remarks
| 1. | An application program can issue this function for multiple host sessions. The Query Communication Event (81) function can be used to determine the session communication status. |
| 2. | If the application chooses the asynchronous option, it can use the Windows SDK call WaitForSingleObject to wait until the sessions communication status has changed. |
| 3. | The event object is initially in a non-signaled state. It is signaled each time an event occurs. To receive notification for multiple events the application must put the event object into the non-signaled state each time it is signaled, by using the Windows SDK call ResetEvent, or by using function 81 Query Communications Event. |
| 4. | Multiple calls to this function with the same options from the same application will be ignored. |
| 5. | This is not exclusive to one application. Several applications can request this function for the same Session ID. |
|