2.2.4.1.4.4 Open
The Open packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet MUST open the specified phone device.
A phone device can be opened by using either owner privilege or monitor privilege. An application that opens the phone with owner privileges can control the lamps, display, ringer, and hookswitch or hookswitches of the phone. An application that opens the phone device with monitor privilege is notified only about events that occur at the phone, such as hookswitch changes or button presses. Opening a phone device in owner mode also provides monitoring of the phone device.
Ownership of a phone device is exclusive; that is, at any time, only one application can have a phone device opened with owner privileges. However, a phone device can be opened multiple times with monitor privilege.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Req_Func |
|||||||||||||||||||||||||||||||
|
Reserved1 |
|||||||||||||||||||||||||||||||
|
hPhoneApp |
|||||||||||||||||||||||||||||||
|
dwDeviceID |
|||||||||||||||||||||||||||||||
|
hPhone |
|||||||||||||||||||||||||||||||
|
dwNegotiatedVersion |
|||||||||||||||||||||||||||||||
|
dwExtVersion |
|||||||||||||||||||||||||||||||
|
OpenContext |
|||||||||||||||||||||||||||||||
|
dwPrivilege |
|||||||||||||||||||||||||||||||
|
hRemotePhone |
|||||||||||||||||||||||||||||||
|
Reserved2 |
|||||||||||||||||||||||||||||||
|
Reserved3 |
|||||||||||||||||||||||||||||||
|
Reserved4 |
|||||||||||||||||||||||||||||||
|
Reserved5 |
|||||||||||||||||||||||||||||||
|
Reserved6 |
|||||||||||||||||||||||||||||||
Req_Func (4 bytes): The identifier of the function that will be invoked on the remote server. This value MUST be set to 107.
-
Return Values
-
On completion of ClientRequest, this field MUST contain the result of the encapsulated telephony request. A value of 0 indicates success, and a PHONEERR_Constants value indicates failure. The remote server MUST complete this call synchronously.
-
Returns zero if the request succeeds or a negative error number if an error occurs. Common return values are:
-
Name
Value
PHONEERR_ALLOCATED
0x00000001
PHONEERR_NODRIVER
0x00000019
PHONEERR_BADDEVICEID
0x00000002
PHONEERR_NOMEM
0x0000001A
PHONEERR_INCOMPATIBLEAPIVERSION
0x00000003
PHONEERR_OPERATIONFAILED
0x0000001C
PHONEERR_INCOMPATIBLEEXTVERSION
0x00000004
PHONEERR_OPERATIONUNAVAIL
0x0000001D
PHONEERR_INVALAPPHANDLE
0x00000007
PHONEERR_RESOURCEUNAVAIL
0x0000001F
PHONEERR_INVALPOINTER
0x00000015
PHONEERR_UNINITIALIZED
0x00000022
PHONEERR_INVALPRIVILEGE
0x00000016
PHONEERR_REINIT
0x00000023
PHONEERR_INUSE
0x00000006
PHONEERR_NODEVICE
0x00000018
PHONEERR_INIFILECORRUPT
0x00000005
Reserved1 (4 bytes): An unsigned 32-bit integer. MUST be set to zero when sent and MUST be ignored on receipt.
hPhoneApp (4 bytes): An HPHONEAPP. The handle to the application registration with TAPI. This field MUST have been obtained by sending the Initialize packet.
dwDeviceID (4 bytes): An unsigned 32-bit integer. The identifier of the phone 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.
hPhone (4 bytes): An HPHONE. Set to TAPI_NO_DATA (0xFFFFFFFF). Upon successful completion of the request, this field contains the handle for the phone device to be used by TAPI in subsequent calls to identify the 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 zero if the application does not use any extensions. This number is obtained from NegotiateExtVersion.
OpenContext (4 bytes): An unsigned 32-bit integer. The Callback instance, set to 0.
dwPrivilege (4 bytes): An unsigned 32-bit integer. The privilege that is requested. This parameter MUST use one of the PHONEPRIVILEGE_Constants.
hRemotePhone (4 bytes): An unsigned 32-bit integer. If this field is nonzero, the server MUST use this value for ASYNCEVENTMSG.hDevice for all unsolicited event and completion notifications that are sent to the client, instead of the returned hPhone value.
-
Similar handle-swapping semantics can exist between 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.
Reserved3 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.
Reserved4 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.
Reserved5 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.
Reserved6 (4 bytes): An unsigned 32-bit integer. This field is used for padding and MUST be ignored on receipt. It can be any value.