2.2.4.1.3.19 GenerateTone

The GenerateTone packet is transmitted from a TAPI client to a TAPI server in a remote procedure call. Sending this packet generates the specified tone inband over the specified call. Invoking this function with a zero for dwToneMode aborts any tone generation that is currently in progress on the specified call. Sending a GenerateTone or GenerateDigits packet while tone generation is in progress aborts the current tone generation or digit generation in progress and initiates the generation of the newly specified tone or digits.


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

hCall

dwToneMode

dwDuration

dwNumTones

lpTones

dwSize

dwEndToEndID

Reserved2

Reserved3

Reserved4

Reserved5

Reserved6

Reserved7

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 20.

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_NOMEM

0x80000044

LINEERR_INVALCALLSTATE

0x8000001C

LINEERR_OPERATIONUNAVAIL

0x80000049

LINEERR_INVALTONEMODE

0x8000003E

LINEERR_OPERATIONFAILED

0x80000048

LINEERR_INVALTONE

0x8000003C

LINEERR_RESOURCEUNAVAIL

0x8000004B

Reserved1 (4 bytes): An unsigned 32-bit integer. MUST be set to zero when sent and MUST be ignored on receipt.

hCall (4 bytes): An HCALL. The handle to the call on which a tone is to be generated. 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.

dwToneMode (4 bytes): An unsigned 32-bit integer. Defines the tone to be generated. Tones can be either standard or custom. A custom tone is composed of a set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone MUST be specified by dwDuration for both standard and custom tones. If dwToneMode is set to zero, any digit or tone generation in progress is canceled. This parameter MUST use one of the LINETONEMODE_Constants.

dwDuration (4 bytes): An unsigned 32-bit integer. The duration, in milliseconds, during which the tone is sustained. A value of 0 for dwDuration uses a default duration for the specified tone. Default values are:

  • CUSTOM: infinite

  • RINGBACK: infinite

  • BUSY: infinite

  • BEEP: infinite

  • BILLING: fixed (single cycle)

This parameter is not validated by TAPI when this function is called.

dwNumTones (4 bytes): An unsigned 32-bit integer. The number of entries in the lpTones array. This parameter is ignored if dwToneMode is not equal to LINETONEMODE_CUSTOM.

lpTones (4 bytes): An unsigned 32-bit integer. If dwToneMode is set to LINETONEMODE_CUSTOM, this field contains the offset, in bytes, of a LINEGENERATETONE packet in the VarData field. Otherwise, this field is set to the value TAPI_NO_DATA (0xFFFFFFFF).

dwSize (4 bytes): An unsigned 32-bit integer. If dwToneMode is set to LINETONEMODE_CUSTOM, this field is set to the value of (dwNumTones * sizeof (LINEGENERATETONE)). Otherwise, this field is set to zero.

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_GENERATE packet is sent. The service provider MUST include this identifier as one of the parameters in the packet.

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 (variable): Contains a number of LINEGENERATETONE packets that are equal to the value of the dwNumTones field.

The contents of this field MUST be DWORD-aligned, as specified in [MS-DTYP] section 2.2.9.