2.2.4.1.3.17 GatherDigits
The GatherDigits packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet initiates the buffered gathering of digits on the specified call. TAPI specifies a packet in which to place the digits and the maximum number of digits to be collected.
|
|
|
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
2 |
|
|
|
|
|
|
|
|
|
3 |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Req_Func |
|||||||||||||||||||||||||||||||
|
Reserved1 |
|||||||||||||||||||||||||||||||
|
lpContext |
|||||||||||||||||||||||||||||||
|
hCall |
|||||||||||||||||||||||||||||||
|
dwEndtoEndID |
|||||||||||||||||||||||||||||||
|
dwDigitModes |
|||||||||||||||||||||||||||||||
|
lpsDigitsContext |
|||||||||||||||||||||||||||||||
|
dwNumDigits |
|||||||||||||||||||||||||||||||
|
lpszTerminationDigits |
|||||||||||||||||||||||||||||||
|
dwFirstDigitTimeout |
|||||||||||||||||||||||||||||||
|
dwInterDigitTimeout |
|||||||||||||||||||||||||||||||
|
Reserved2 |
|||||||||||||||||||||||||||||||
|
Reserved3 |
|||||||||||||||||||||||||||||||
|
Reserved4 |
|||||||||||||||||||||||||||||||
|
Reserved5 |
|||||||||||||||||||||||||||||||
|
Reserved6 |
|||||||||||||||||||||||||||||||
|
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 18.
-
Return Values
-
On completion of ClientRequest, this field contains 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_INVALCALLHANDLE
0x80000018
LINEERR_RESOURCEUNAVAIL
0x8000004B
LINEERR_INVALCALLSTATE
0x8000001C
LINEERR_NOMEM
0x80000044
LINEERR_INVALTIMEOUT
0x8000003B
LINEERR_OPERATIONUNAVAIL
0x80000049
LINEERR_INVALDIGITMODE
0x80000027
LINEERR_OPERATIONFAILED
0x80000048
LINEERR_INVALDIGITS
0x80000028
LINEERR_INVALPARAM
0x80000032
Reserved1 (4 bytes): An unsigned 32-bit integer. MUST be set to zero when sent and MUST be ignored on receipt.
lpContext (4 bytes): An unsigned 32-bit integer. The opaque, client-specified value that is used by the client upon request completion; MUST be returned by the server in the request completion packet.
hCall (4 bytes): An HCALL. The handle to the call on which digits are to be gathered. One way of obtaining a valid hCall is by sending the MakeCall packet. The application MUST be an owner of the call. The call state of hCall can be any state.
dwEndtoEndID (4 bytes): An unsigned 32-bit integer. A unique, uninterpreted identifier of the request for its entire lifetime, that is, until the matching LINE_GATHERDIGITS packet is sent. The service provider MUST include this identifier as one of the parameters in the packet.
dwDigitModes (4 bytes): An unsigned 32-bit integer. The digit modes that are to be monitored. This parameter MUST use one or more of the following LINEDIGITMODE_Constants:
-
LINEDIGITMODE_PULSE
-
Detect digits as audible clicks that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are "0" through "9".
-
LINEDIGITMODE_DTMF
-
Detect digits as DTMF tones. Valid digits for DTMF mode are "0" through "9", "A", "B", "C", "D", "*", "#".
lpsDigitsContext (4 bytes): An unsigned 32-bit integer. Set to 0 if digit gathering is to be canceled; otherwise, digit gathering is initiated.
dwNumDigits (4 bytes): An unsigned 32-bit integer. The number of digits to be collected before a LINE_GATHERDIGITS packet is sent to TAPI. This function MUST return a LINEERR_INVALPARAM if dwNumDigits is zero.
lpszTerminationDigits (4 bytes): An unsigned 32-bit integer. The offset, in bytes, in the varData field of a null-terminated Unicode string of termination digits as text characters, or if none are supplied, the value TAPI_NO_DATA (0xFFFFFFFF).
dwFirstDigitTimeout (4 bytes): An unsigned 32-bit integer. The time duration, in milliseconds, in which the first digit is expected. If the first digit is not received in this time frame, digit collection is terminated and a LINE_GATHERDIGITS packet is sent to TAPI. A single null character is written to the packet, indicating no digits were received and the first digit time-out terminated digit gathering. The line device capabilities of the call specify the valid range for this parameter or indicate that time-outs are not supported. This parameter is not validated by TAPI when this function is called.
dwInterDigitTimeout (4 bytes): An unsigned 32-bit integer. The maximum time duration, in milliseconds, between consecutive digits. If no digit is received in this time frame, digit collection is terminated and a LINE_GATHERDIGITS packet is sent to TAPI. A single null character is written to the packet, indicating that an interdigit time-out terminated digit gathering. The LINEDEVCAPS packet MUST specify the valid range for this parameter or indicate that time-outs are not supported. This parameter is not validated by TAPI when this function is called.
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.
VarData (variable): Present if the lpszTerminationDigits field is not set to TAPI_NO_DATA (0xFFFFFFFF). Contains a null-terminated Unicode string as specified by lpszTerminationDigits.