HP-UX SNAplus2 R7 LUA Programmer's Guide

Designing and Writing LUA Applications
LUA Entry Points for Windows Applications
Returned Values
The return value from the function is one of the following:
0
(zero)
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 Section 2.2.3, WinRUI.
WLUAINVALIDHANDLE
The supplied hWnd parameter was not a valid window handle.
WLUASTARTUPNOTCALLED
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
Chapter 4, RUI Verbs.
Usage
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 ap-
plication can use this address to access the returned parameters in the VCB structure.
• The wParam argument is undefined.
Synchronous and Asynchronous Verb Completion
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 Chapter 4, RUI 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.
32