2.2.4.1.4.2 NegotiateAPIVersion

The NegotiateAPIVersion packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet MUST allow an application to negotiate a TAPI version to use for the specified phone device.

0	1	2	3	4	5	6	7	8	9	1 0	1	2	3	4	5	6	7	8	9	2 0	1	2	3	4	5	6	7	8	9	3 0	1
Req_Func
Reserved1
hPhoneApp
dwDeviceIDLocal
dwVersion
dwVersionCurrent
dwNegotiatedVersion
ExtensionID
dwSize
Reserved2
Reserved3
Reserved4
Reserved5
Reserved6
Reserved7
VarData (16 bytes)
...
...

Req_Func (4 bytes): The identifier of the function that will be invoked on the remote server. This value MUST be set to 108.

Return Values

On completion of ClientRequest, this field MUST contain the result of the encapsulated telephony request. A value of zero 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_INVALAPPHANDLE	0x00000007
PHONEERR_OPERATIONFAILED	0x0000001C
PHONEERR_BADDEVICEID	0x00000002
PHONEERR_OPERATIONUNAVAIL	0x0000001D
PHONEERR_NODRIVER	0x00000019
PHONEERR_NOMEM	0x0000001A
PHONEERR_INVALPOINTER	0x00000015
PHONEERR_RESOURCEUNAVAIL	0x0000001F
PHONEERR_INCOMPATIBLEAPIVERSION	0x00000003
PHONEERR_UNINITIALIZED	0x00000022
PHONEERR_NODEVICE	0x00000018

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.

dwDeviceIDLocal (4 bytes): An unsigned 32-bit integer. The phone device to query. A valid value of dwDeviceIDLocal is in the range 0 to dwNumDevs – 1. The client obtains dwNumDevs by sending a Initialize packet to the remote server.

dwVersion (4 bytes): An unsigned 32-bit integer. The minimum TAPI version the request will support. Set to TAPI_VERSION1_0 (0x00010003).

dwVersionCurrent (4 bytes): An unsigned 32-bit integer. The most current version of TAPI.

dwNegotiatedVersion (4 bytes): An unsigned 32-bit integer. Set to TAPI_NO_DATA (0xFFFFFFFF). Upon successful completion of the request, this field contains the TAPI version number that was negotiated.

ExtensionID (4 bytes): An unsigned 32-bit integer. Set to TAPI_NO_DATA (0xFFFFFFFF). Upon successful completion of the request, this field contains the offset, in bytes, of a PHONEEXTENSIONID packet in the VarData field, indicating the extension identifier of the provider-specific extensions.

dwSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the packet that is indicated in the ExtensionID field.

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.

Reserved7 (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 (16 bytes): Present on successful completion of the request. MUST contain a PHONEEXTENSIONID packet.

The contents of this field are DWORD-aligned.