lineGetRequest
The lineGetRequest
function retrieves the next by-proxy request for the specified request mode.
LONG lineGetRequest(
|
HLINEAPP hLineApp, |
|
|
DWORD dwRequestMode, |
|
|
LPVOID lpRequestBuffer |
|
|
); |
|
Parameters
hLineApp
The
application's usage handle for the line portion of TAPI.
dwRequestMode
The type of
request that is to be obtained. Note that dwRequestMode can only have
one bit set. This parameter uses the following LINEREQUESTMODE_ constants:
LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
lpRequestBuffer
A pointer to
a memory buffer where the parameters of the request are to be placed. The size
of the buffer and the interpretation of the information placed in the buffer
depends on the request mode. The application-allocated buffer is assumed to be
of sufficient size to hold the request.
If dwRequestMode
is LINEREQUESTMODE_MAKECALL, interpret the content of the request buffer using
the LINEREQMAKECALL
structure.
If dwRequestMode
is LINEREQUESTMODE_MEDIACALL, interpret the content of the request buffer using
the LINEREQMEDIACALL structure.
Return Values
Returns zero
if the request is successful or a negative error number if an error has
occurred. Possible return values are:
LINEERR_INVALAPPHANDLE,
LINEERR_NOTREGISTERED, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED,
LINEERR_INVALREQUESTMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM,
LINEERR_UNINITIALIZED, LINEERR_NOREQUEST.
Remarks
A
telephony-enabled application can request that a call be placed on its behalf
by invoking tapiRequestMakeCall. These requests are queued by TAPI and the highest
priority application that has registered to handle the request is sent a LINE_REQUEST message with indication of the
mode of the request that is pending. Typically, this application is the user's
call-control application. The LINE_REQUEST message indicates that zero or more
requests may be pending for the registered application to process; after
receiving LINE_REQUEST, it is the responsibility of the recipient application
to call lineGetRequest until LINEERR_NOREQUEST is returned, indicating
that no more requests are pending.
Next, the
call-control application that receives this message invokes lineGetRequest,
specifying the request mode and a buffer that is large enough to hold the
request. The call-control application then interprets and executes the request.
After
execution of lineGetRequest, TAPI purges the request from its internal
queue, making room available for a subsequent request. It is therefore possible
for a new LINE_REQUEST message to be received immediately upon execution of lineGetRequest,
should the same or another application issue another request. It is the responsibility
of the request recipient application to handle this scenario by some mechanism
(for example, by making note of the additional LINE_REQUEST and deferring a
subsequent lineGetRequest until processing of the preceding request
completes, by getting the subsequent request and buffer as necessary, or by
another appropriate means).
Note that the
subsequent LINE_REQUEST should not be ignored because it will not be repeated
by TAPI.
See Also