|
The Start Host Notification function begins the process by which your EHLLAPI application program determines if the host presentation space or OIA have been updated.
After using this function, your application program can use the Query Host Update (24) function to determine when a host event has occurred.
Prerequisite Calls
There are no prerequisite calls for this function.
Call Parameters
|
Standard Interface
|
Enhanced Interface
|
Function Number
|
Must be 23
|
|
Data String
|
Preallocated string; see the following table
|
|
Length
|
6 or 7 implied
|
16
|
PS Position
|
NA
|
|
The calling data string contains these elements:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
One of the following values: A 1-character presentation space short name (PSID) A blank or null indicating a request for the host-connected host presentation space
|
|
2-4
|
Reserved.
|
2
|
5
|
One of the following values:
| • | The character B asking for notification of both host presentation space and OIA updates. |
| • | The character O asking for notification of only OIA updates. |
| • | The character P asking for notification of only host presentation space updates. The character A requesting the asynchronous mode of the notification When A is specified, position 9-12 returns the address of an event object. The event selection character B, O, or P must be placed in position 13. |
The character M requesting the asynchronous message mode of the notification. When M is specified, the event selection character B, O, or P must be placed in position 13 (7 for 16-bit).
| • | The character E asking for notification of completion during a printer session. |
|
|
6-8
|
Reserved.
|
3-4
|
9-12
|
When M is specified in position 5 (2 for 16-bit), the window handle of the window that receives the message should be set. The message is a return value of RegisterWindowMessage (PCSHLL) (not equal 0).
|
7
|
13
|
One of the following values if position 5 (2 for 16-bit) is A or M:
| • | The character B asking for notification of both host presentation space and OIA updates |
| • | The character O asking for notification of only OIA updates |
| • | The character P asking for notification of only host presentation update. |
|
|
14-16
|
Reserved.
|
Return Parameters
This function returns a data string and a return code.
Data String
If A (asynchronous mode of notification) is specified in position 5 and the function is completed successfully, the following data string is returned:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
A 1-character presentation space short name (PSID).
|
|
2-8
|
Reserved.
|
|
9-12
|
4-byte value in which the event object address is returned by EHLLAPI. The application can wait for this event object (32-bit only).
|
Data String
If M (asynchronous message mode) is specified in position 5 (2 for standard interface) and the function is completed successfully, the following data string is returned:
Byte
|
|
Definition
|
Standard
|
Enhanced
|
|
1
|
1
|
A 1-character presentation space short name (PSID)
|
|
2-8
|
Reserved
|
3-4
|
9-10
|
Task ID of asynchronous message mode
|
Note:
If OIA or presentation space is updated, an application window receives a message. The message is a return value of RegisterWindowMessage (PCSHLL). The wParam parameter contains the Task ID returned by the function call. HIWORD of lParam contains Return Code 21 (shows the OIA is updated), 22 (shows the host presentation space is updated), or 23 (shows both the OIA and the host presentation space are updated), and LOWORD of lParam parameter contains function number 23.
Return Code
The following codes are defined:
Return Code
|
Definition
|
0
|
The Start Host Notification function was successful.
|
1
|
An incorrect host presentation space 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 Pause (18) function can notify the application when one or more host sessions (PS, OIA, or both of them) are updated. The Query Host Update (24) function can be used to determine whether a PS, OIA, or both of them have been updated. |
| 2. | If the application chooses the asynchronous option, it can wait for the returned event object or semaphore to determine when a host event has occurred. |
| 3. | The event object or semaphore is initially in a non-signaled state and is signaled each time an appropriate event occurs. To receive notification for multiple events, the application must put the event object into the non-signaled state each time it has been signaled using either the ResetEvent or the Query Host Update (24) function. |
| 4. | An application cannot request Start Host Notification more than once with the same options. |
| 5. | This is not an exclusive call. Multiple applications can request this function for the same short session ID. |
|