2.2.4.1.1.5 Open
The Open packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet opens the line device that is specified by its device identifier and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Req_Func |
|||||||||||||||||||||||||||||||
|
Reserved1 |
|||||||||||||||||||||||||||||||
|
hLineApp |
|||||||||||||||||||||||||||||||
|
dwDeviceID |
|||||||||||||||||||||||||||||||
|
hLine |
|||||||||||||||||||||||||||||||
|
dwNegotiatedVersion |
|||||||||||||||||||||||||||||||
|
dwExtVersion |
|||||||||||||||||||||||||||||||
|
OpenContext |
|||||||||||||||||||||||||||||||
|
dwPrivileges |
|||||||||||||||||||||||||||||||
|
dwMediaModes |
|||||||||||||||||||||||||||||||
|
pCallParams |
|||||||||||||||||||||||||||||||
|
dwAsciiCallParamsCodePage |
|||||||||||||||||||||||||||||||
|
pGetCallParams |
|||||||||||||||||||||||||||||||
|
hRemoteLine |
|||||||||||||||||||||||||||||||
|
Reserved2 |
|||||||||||||||||||||||||||||||
|
VarData (variable) |
|||||||||||||||||||||||||||||||
|
... |
|||||||||||||||||||||||||||||||
Req_Func (4 bytes): An unsigned 32-bit integer. The identifier of the function that will be invoked on the remote server. This value MUST be set to 54.
-
Return Values
-
On completion of ClientRequest, this field will contain the result of the encapsulated telephony request. A value of 0 indicates success, and a LINEERR_Constants value indicates failure. The remote server MUST complete this call synchronously.
-
MUST return zero if the function succeeds or an error number if an error occurs. Common return values are as follows:
-
Name
Value
LINEERR_ALLOCATED
0x80000001
LINEERR_OPERATIONUNAVAIL
0x80000049
LINEERR_NODRIVER
0x80000043
LINEERR_OPERATIONFAILED
0x80000048
LINEERR_NOMEM
0x80000044
LINEERR_RESOURCEUNAVAIL
0x8000004B
Reserved1 (4 bytes): An unsigned 32-bit integer. MUST be set to zero when sent and MUST be ignored on receipt.
hLineApp (4 bytes): An HLINEAPP. A handle to the client application's registration with TAPI. This field MUST have been obtained by sending the Initialize packet.
dwDeviceID (4 bytes): An unsigned 32-bit integer. Identifies the line device to be opened. A valid value of dwDeviceID is in the range 0 to dwNumDevs – 1. The client obtains dwNumDevs by sending a Initialize packet to the remote server.
hLine (4 bytes): An HLINE. Set to TAPI_NO_DATA (0xFFFFFFFF). Upon successful completion of the request, this field MUST contain the handle representing the opened line device.
dwNegotiatedVersion (4 bytes): An unsigned 32-bit integer. The version that is negotiated via the NegotiateAPIVersion request.
dwExtVersion (4 bytes): An unsigned 32-bit integer. The extension version number under which the application and the service provider agree to operate. This number is obtained with NegotiateExtVersion.
OpenContext (4 bytes): An unsigned 32-bit integer. The Callback instance, set to 0.
dwPrivileges (4 bytes): An unsigned 32-bit integer. The privilege that the application requests when notified of a call.
dwMediaModes (4 bytes): An unsigned 32-bit integer. The media type or modes of interest to the application.
pCallParams (4 bytes): The offset, in bytes, from the beginning of the variable data area to the LINECALLPARAMS packet. This field is set to TAPI_NO_DATA (0xFFFFFFFF) if no LINECALLPARAMS packet is specified.
dwAsciiCallParamsCodePage (4 bytes): An unsigned 32-bit integer. The code page of the pCallParams field, set to TAPI_NO_DATA (0xFFFFFFFF).
pGetCallParams (4 bytes): An unsigned 32-bit integer. The value of this field is ignored by the server. On successful completion, this field is set to TAPI_NO_DATA (0xFFFFFFFF).
hRemoteLine (4 bytes): An unsigned 32-bit integer. If this field is nonzero, the server MUST use this value for ASYNCEVENTMSG.hDevice for all unsolicited events and completion notifications sent to the client, instead of the returned hLine value.
-
Similar handle-swapping semantics can exist between the TAPI service and telephony service providers.
Reserved2 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.
VarData (variable): This field MUST contain the LINECALLPARAMS packet that is indicated by the pCallParams field.