|
|
|
|
A Windows application accesses LUA using the following functions:
Issues an LUA verb. If the verb completes asynchronously, LUA indicates the completion by signaling an event handle supplied by the application.
Registers the application as a Windows LUA user, and determines whether the LUA software supports the level of function required by the application.
Issues an LUA verb. If the verb completes asynchronously, LUA will indicate the completion by posting a message to the application window.
Checks the status of an LUA session (initiated by a previous RUI_INIT verb that is still outstanding), requests notification of changes to the session status, or cancels this notification.
Unregisters the application when it has finished using LUA.
Generates a printable character string for the primary and secondary return codes obtained on an LUA verb.
The application must call WinRUIStartup before attempting to issue any LUA verbs using the WinRUI call..
While an RUI_INIT verb is outstanding, the application can use WinRUIGetLastInitStatus to determine the status of the LUA session initiated by this verb; it can then cancel the RUI_INIT verb if necessary. The WinRUIGetLastInitStatus function can be used to check the current status without requesting notification of subsequent changes, to request asynchronous notification of subsequent changes to the session status, or to cancel a previous request for notification of status changes.
If a verb returns with non-LUA_OK return codes, the application can use GetLuaReturnCode to obtain a text string representation of these return codes, which can be used to generate standard error messages.
When it has finished issuing LUA verbs using the WinRUI call, it must call WinRUICleanup before terminating; it must not attempt to issue any more LUA verbs after calling WinRUICleanup .
The following sections describe these functions.
The application uses this function to issue an LUA verb. If the verb completes asynchronously, LUA indicates the completion by signaling an event handle supplied by the application.
The application does not need to issue a WinRUIStartup verb before making this call.
void WINAPI LOADDS RUI(verb)
LUA_VERB_RECORD FAR * verb;
Supplied parameter is:
Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure is defined in the LUA header file winlua.h; this file is installed in the subdirectory /sdk within the directory where you installed the Windows Client software. For an explanation of the VCB structure, see LUA Verbs.
The LUA VCB contains many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The entry point does not return a value. When the call returns, the application can examine the parameters in the VCB to determine whether the verb has completed synchronously or will complete asynchronously. For more information, see Usage.
Sometimes LUA is able to complete all the processing for a verb as soon as it is issued. When this happens, the verb returns synchronously; the primary return code is set to a value other than LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 0 (zero). (For information about these returned parameters, see LUA Verbs.)
At other times, LUA must wait for information from the remote LU or from the node before it can complete the verb. In this case, the verb returns asynchronously; the primary return code is set to LUA_IN_PROGRESS , and the lua_flag2.async bit is set to 1. The application can now perform other processing, or wait for notification from LUA that the verb has completed. LUA issues this notification by setting the primary return code to its final value, leaving the lua_flag2.async bit set to 1.
As part of the supplied VCB, the application supplies an event handle in the lua_post_handle parameter. The event must be in the nonsignaled state and the handle must have EVENT_MODIFY_STATE access to the event. If the verb completes synchronously, LUA does not signal this event handle. If the verb completes asynchronously, LUA indicates the verb completion by signaling the event handle.
The application issues a WaitForSingleObject or WaitForMultipleObject call to wait on the event handle. When the event is signaled, the application examines the primary return code and secondary return code to check for errors.
It is not possible for an application to predict whether a particular verb will complete synchronously or asynchronously.
The application uses this function to register as a Windows LUA user, and to determine whether the LUA software supports the Windows LUA version that it requires.
int WINAPI LOADDS WinRUIStartup (
WORD wVersionRequired;
LUADATA far * lpData;
)
typedef struct
{
WORD wVersion;
char szDescription[41];
} LUADATA;
Supplied parameter is:
The version of Windows LUA that the application requires. SNAP-IX supports Version 1.0.
The low-order byte specifies the major version number, and the high-order byte specifies the minor version number. For example:
| Version | wVersionRequired |
| 1.0 | 0x0001 |
| 1.1 | 0x0101 |
| 2.0 | 0x0002 |
If the application can use more than one version, it should specify the highest version that it can use.
The return value from the function is one of the following:
The application was registered successfully, and the Windows LUA software
supports either the version number specified by the application or a lower
version. The application should check the version number in the
The version number specified by the application is not supported by the Windows LUA software. The application was not registered.
The application has already called WinRUIStartup and registered successfully. It must not call this function more than once.
The SNAP-IX software has not been started, or the local node is not active. The application was not registered.
An operating system error occurred during initialization of the Windows LUA software. The application was not registered. Check the log files for messages indicating the cause of the failure.
If the return value from WinRUIStartup
is 0 (zero), the
The Windows LUA version number that the software supports, in the same format as the wVersionRequired parameter (see Supplied Parameters). SNAP-IX supports Version 1.0.
If the software supports the requested version number, this parameter is set to the same value as the wVersionRequired parameter; otherwise it is set to the highest version that the software supports, which will be lower than the version number supplied by the application. The application must check the returned value and take action as follows:
If the returned version number is the same as the requested version number, the application can use this Windows LUA implementation.
If the returned version number is lower than the requested version number, the application can use this Windows LUA implementation but must not attempt to use features that are not supported by the returned version number. If it cannot do this because it requires features not available in the lower version, it should fail its initialization and not attempt to issue any LUA verbs.
A text string describing the Windows LUA software.
The application uses this function to issue an LUA verb. If the verb completes asynchronously, LUA will indicate the completion by posting a message to the application's window handle.
Before using the WinRUI call for the first time, the application must use RegisterWindowMessage to obtain the message identifier that LUA will use for messages indicating asynchronous verb completion. For more information, see Usage.
int WINAPI LOADDS WinRUI (
HWND hWnd,
LUA_VERB_RECORD far * lpVCB
);
For the definition of the LUA_VERB_RECORD structure, see LUA Verbs.
Supplied parameters are:
A window handle that LUA will use to post a message indicating asynchronous verb completion.
A pointer to the VCB structure for the verb. For the WinRUI function, the lua_post_handle parameter is reserved; leave it as 0 (zero).
For more information about the VCB structure and on its usage for individual verbs, see LUA Verbs.
The LUA VCB contains many parameters marked as reserved
;
some of these are used internally by the SNAP-IX software, and others are
not used in this version but may be used in future versions. Your application
must not attempt to access any of these reserved parameters; instead, it must
set the entire contents of the VCB to zero to ensure that all of these parameters
are zero, before it sets other parameters that are used by the verb. This
ensures that SNAP-IX will not misinterpret any of its internally-used parameters,
and also that your application will continue to work with future SNAP-IX
versions in which these parameters may be used to provide new functions.
To set the VCB contents to zero, use memset:
memset(vcb, 0, sizeof(vcb));
The return value from the function is one of the following:
The function call was accepted, and the LUA verb will be processed. The application should check the lua_flag2.async parameter in the VCB structure to determine whether the verb has already completed synchronously or will complete asynchronously, as described in Synchronous and Asynchronous Verb Completion.
The supplied hWnd parameter was not a valid window handle.
The application has not issued the WinRUIStartup call, which is required before issuing any LUA verbs.
For information about the parameters returned in the VCB structure, see the descriptions of individual verbs in LUA Verbs.
Before using WinRUI for the first time, the application must use the RegisterWindowMessage call to obtain the message identifier that LUA will use for messages indicating asynchronous verb completion. RegisterWindowMessage is a standard Windows function call, not specific to LUA; refer to your Windows documentation for more information about the function. (There is no need to issue the call again before subsequent LUA verbs; the returned value will be the same for all calls issued by the application.)
The application must pass the string WinRUI to the function; the returned value is a message identifier (the value returned from the RegisterWindowMessage call).
Each time an LUA verb that was issued using the WinRUI entry point completes asynchronously, LUA posts a message to the window handle specified on the WinRUI call. The format of the message is as follows:
The message identifier is the value returned from the RegisterWindowMessage call.
The lParam argument contains the address of the VCB that was supplied to the original WinRUI call; the application can use this address to access the returned parameters in the VCB structure.
The wParam argument is undefined.
Sometimes LUA is able to complete all the processing for a verb as soon as it is issued. When this happens, the verb returns synchronously; the primary return code is set to a value other than LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 0 (zero). (For information about these returned parameters, see LUA Verbs.)
To enable the verb to return asynchronously, the application supplies a window handle to the LUA entry point. If the verb completes synchronously, LUA does not use this window handle. If the verb completes asynchronously, LUA indicates the verb completion by posting a message to this window handle; the message includes a pointer to the original VCB.
It is not possible for an application to predict whether a particular verb will complete synchronously or asynchronously.
Verbs can be issued from a callback, but they will not always complete asynchronously. Such verbs may be returned synchronously if they fail from within the library. The application should not reissue the failed verb from within the callback.
If the user repeatedly issues RUI_INITs in parallel from the callback context, the RUI_INITs will eventually fail with a memory error. However, if verbs are issued from the application thread, allowing the availability of all the system memory, more attempts will complete successfully.
The application uses this function to determine the status of a previous RUI_INIT verb that is still outstanding. It can use the returned information to decide whether to cancel the session initiation (by issuing RUI_TERM) or to wait for the session to be established.
The function can be used to do any of the following:
Request information about the current status of the session initiated by a specific RUI_INIT verb.
Request asynchronous notification of changes to session status for a specific session or for all sessions. When the session status changes, LUA will indicate this by either posting a message to the application's window handle or by signaling the application's event handle.
Cancel a previous request for asynchronous notification of changes to session status.
Before using the WinRUI call for the first time, the application must use WinRUIStartup to register as a Windows LUA application. If it requires asynchronous notification of status changes, it must also use RegisterWindowMessage to obtain the message identifier that LUA will use for this notification. For more information about these calls, see WinRUIStartup and Usage.
int WINAPI LOADDS WinRUIGetLastInitStatus (
DWORD Sid,
HANDLE StatusHandle,
DWORD NotifyType,
BOOL ClearPrevious
);
Supplied parameters are:
To obtain information about the session status for a specific RUI_INIT verb, or to cancel a previous request for notification of session status changes for this verb, specify the session ID returned on the initial return from the RUI_INIT verb.
To request notification on session status changes for all outstanding RUI_INIT verbs, specify 0 (zero). In this case, the StatusHandle parameter must specify a valid Windows handle, because the information will always be returned asynchronously.
To cancel notification of session status changes for all outstanding RUI_INIT verbs, specify 0 (zero).
To obtain the current session status for a specific RUI_INIT verb, without requesting notification of subsequent changes, specify a null handle.
To request notification on session status changes, either for a specific RUI_INIT verb or for all outstanding RUI_INIT verbs, specify a Windows handle or an event handle that LUA will use when the session status changes.
If the ClearPrevious parameter is set to
If requesting asynchronous notification, this parameter determines how LUA should identify the RUI_INIT verb on the asynchronous notification message. Allowed values:
The StatusHandle parameter contains a window handle. Identify the verb using the lua_correlator value supplied on the RUI_INIT verb.
The StatusHandle parameter contains a window handle. Identify the verb using the lua_sid value returned on the RUI_INIT verb.
The StatusHandle parameter contains an event handle.
If the StatusHandle parameter is null (to request
current status information), or if the ClearPrevious
parameter is set to
To cancel a previous notification request, set this parameter to
If the function completed successfully, the return value from the function is one of the following:
The communications link to the host is not yet active.
The communications link to the host is active, but an activate physical unit (ACTPU) has not yet been received.
An ACTPU has been received from the host.
The PU has been reactivated by the host.
The communications link to the host is active, and an ACTPU has been received, but an ACTLU has not yet been received.
The LU is active.
The LU has been reactivated.
The application is establishing contact with the node.
If the application requested notification of status changes, one of these values will be included in a Windows message sent to the application each time the status changes. For more information, see Usage.
The following return values indicate that the function failed:
The SNA software is not running.
The NotifyType parameter was set to a value that was not valid.
The supplied StatusHandle parameter was not a valid window handle.
The application has not issued the WinRUIStartup call, which is required before issuing any LUA verbs.
Internal error: the session status is unknown.
The supplied Sid parameter did not match the session ID of an outstanding RUI_INIT verb.
The application supplied a zero session ID (indicating all
sessions), but did not specify either a Windows handle (to indicate
asynchronous notification) or a ClearPrevious value
of
The application has previously requested notification of status changes
for all RUI_INIT verbs; it cannot request notification for a specific session
unless it first clears the all sessions
notification.
If the application is requesting asynchronous notification of status changes using a Windows message, it must use the RegisterWindowMessage call before its first WinRUIGetLastInitStatus call, to obtain the message identifier that LUA will use for messages indicating status changes.
The RegisterWindowMessage call is a standard Windows function call, not specific to LUA; refer to your Windows documentation for more information about the function. (There is no need to issue the call again before subsequent calls to this function; the returned value will be the same for all calls issued by the application.)
The application must pass the string WinRUI
to the function; the returned value is a message identifier (the value returned
from the RegisterWindowMessage call).
Each time the session status changes, LUA posts a message to the window handle specified on the WinRUI call. The format of the message is as follows:
The message identifier is the value returned from the RegisterWindowMessage call.
The lParam argument contains either the correlator value supplied to the original RUI_INIT verb or the session ID returned on the original RUI_INIT verb, as defined by the NotifyType parameter. The application can use this value to correlate the message with the original verb.
The wParam argument contains the session status (one of the values listed for successful execution in Returned Values), or the value WLUAUNKNOWN if an internal error occurred during processing.
If the application is requesting asynchronous notification of status changes using an event handle, implement it as follows:
WinRUIGetLastInitStatus(Sid,EventHandle,WLUA_NOTIFY_EVENT,FALSE);
The event whose handle is given will be signaled when a change in state occurs. Since no information is returned when an event is signaled, a further call must be issued to determine the status, as follows:
Status = WinRUIGetLastInitStatus(Sid,NULL,0,FALSE);
In this case, a Sid must be specified.
The application uses this function to obtain a printable character string indicating the primary and secondary return codes from a supplied VCB. The string can be used to generate application error messages for non-LUA_OK return codes.
int WINAPI LOADDS GetLuaReturnCode (
struct LUA_COMMON FAR * vcbptr,
unsigned int buffer_length,
unsigned char far * buffer_addr
);
Supplied parameters are:
A pointer to the VCB structure for the verb. For more information about the VCB structure and on its usage for individual verbs, see LUA Verbs.
The length (in bytes) of the buffer supplied by the application to hold the returned data string. The recommended length is 256 bytes.
The address of the buffer supplied by the application to hold the returned data string.
The return value from the function is one of the following:
The function completed successfully.
LUA could not read from the supplied VCB, or could not write to the supplied data buffer.
The supplied data buffer is too small to hold the returned character string.
The dynamic link library, LUASTR32.DLL, which generates the returned character strings for this function, could not be loaded.
If the return value is 0 (zero), the returned character string is in the buffer identified by the buffer_addr parameter. This string is terminated by a null character (binary zero), but does not include a trailing new-line (\n) character.
The application uses this function to unregister as a Windows LUA user, after it has finished issuing LUA verbs.
BOOL WINAPI LOADDS WinRUICleanup (void);
There are no supplied parameters for this function.
The return value from the function is one of the following:
The application was unregistered successfully.
An error occurred during processing of the call, and the application was not unregistered. Check the log files for messages indicating the cause of the failure.
|
|
|
 |
|