WinRUIGetLastInitStatus()

This function provides a way for an application to determine the status of an RUI_INIT so that the application can determine whether the RUI_INIT should be timed out. Use this call to initiate the reporting of status, terminate the reporting of status, or find the current status. For details, see the Usage Notes section.

Syntax

int WINAPI WinRUIGetLastInitStatus (DWORD dwSid,
                                    HANDLE hStatusHandle,
                                    DWORD dwNotifyType,
                                    BOOL bClearPrevious);

Parameters

dwSid

Session identifier of the session for which status will be determined. If the value is 0, hStatusHandle is used to report status on all sessions. The lua_sid parameter in the RUI_INIT VCB is valid as soon as the call to RUI() or WinRUI() for the RUI_INIT returns.

hStatusHandle

A handle used for signaling the application that the status for the session has changed. Can be a window handle, an event handle, or NULL; dwNotifyType must be set accordingly:

If hStatusHandle is a window handle, status is sent to the application through a window message. The program obtains the message from RegisterWindowMessage using the string WinRUI. The parameter wParam contains the session status (see Return Values). Depending on the value of dwNotifyType, lParam contains either the RUI session ID of the session, or the value of lua_correlator from the RUI_INIT verb.
If hStatusHandle is an event handle, when the status for the session specified by dwSid changes, the event is put into the signaled state. The application must then make a further call to WinRUIGetLastInitStatus() to find out the new status. The event should not be the same as one used for signaling completion of any RUI verb.
If hStatusHandle is NULL, the status of the session specified by dwSid is returned in the return code. In this case, dwSid must not be 0 unless bClearPrevious is TRUE. If hStatusHandle is NULL, dwNotifyType is ignored.

dwNotifyType

The type of indication required. This determines the contents of the lParam of the window message and how WinRUIGetLastInitStatus() interprets hStatusHandle. Permitted values are:

WLUA_NTFY_EVENT: The hStatusHandle parameter contains an event handle.
WLUA_NTFY_MSG_CORRELATOR: The hStatusHandle parameter contains a window handle and the lParam of the returned window message should contain the LUA correlator and RUI.
WLUA_NTFY_MSG_SID: The hStatusHandle parameter contains a window handle and the lParam of the returned window message should contain the LUA session identifier.

bClearPrevious

If TRUE, status messages are no longer sent for the session identified by dwSid. If dwSid is 0, status messages are no longer sent for any session. If bClearPrevious is TRUE, hStatusHandle and dwNotifyType are ignored.

Usage Notes

This function is intended to be used either with a window handle or an event handle to enable asynchronous notification of status changes, but it can also be used on its own to find out the current status of a session.

To use this function with a window handle, you can implement it in one of two ways as follows:

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NTFY_MSG_CORRELATOR,FALSE);

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NTFY_MSG_SID,FALSE);

With this implementation, changes in status are reported by a window message sent to the window handle specified. If WLUA_NTFY_MSG_CORRELATOR is specified, the lParam field in the window message contains the lua_correlator field for the session. If WLUA_NFTY_MSG_SID is specified, the lParam field in the window message contains the LUA session identifier for the session.

When the function has been used with a window handle, use the following command to cancel the reporting of status:

WinRUIGetLastInitStatus(Sid,NULL,0,TRUE);

For this implementation, note that if Sid is nonzero, status is only reported for that session. If Sid is 0, status is reported for all sessions.

To use this function with an event handle, implement it as follows:

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NOTIFY_EVENT,FALSE);

The event whose handle is given will be signaled when a change in state occurs. Because no information is returned when an event is signaled, the following call must be issued to find out the status:

Statu = WinRUIGetLastInitStatus(Sid,NULL,0,0,FALSE);

In this case, a Sid must be specified.

When the function has been used with an event handle, use the following command to cancel the reporting of status:

WinRUIGetLastInitStatus(Sid,NULL,0,TRUE);

To use this function to query the current status of a session, it is not necessary to use an event or window handle. Instead, use the following command:

Status = WinRUIGetLastInitStatus(Sid,NULL,0,0,FALSE);

Note: WinRUIGetLastInitStatus is not supported on the Communications Server SNA API clients.