2.18.x
|
|
| VAPI API Reference Documentation 2.18.x |
|
Functions | |
| void * | VAPI_AllocateMessage (U16 usSize) |
| VSTATUS | VAPI_FreeMessage (void *pvMsg) |
| void | VAPI_InitMessage (void *pvMsg) |
| VSTATUS | VAPI_SetMessage (OUT void *pvMsg, IN U8 ucCmdClass, IN U8 ucCmdType, IN U16 usFcode, IN U16 ucNumParams,...) |
| VSTATUS | VAPI_SetMessageFromBuffer (OUT void *pvMsg, IN U8 ucCmdClass, IN U8 ucCmdType, IN U16 usFcode, IN U16 ucNumParams, IN U16 *pusParameters) |
| VSTATUS | VAPI_SendDeviceMessage (IN U32 uiID, IN SMsg *pstMsg, IN SRequest *pstRequest, OUT U8 *pucBuffer, IN OUT U32 *puBufLen) |
| VSTATUS | VAPI_SendConnectionMessage (IN U32 uiID, IN SMsg *pstMsg, IN SRequest *pstRequest, OUT U8 *pucBuffer, IN OUT U32 *puBufLen) |
| VSTATUS | VAPI_SendConferenceMessage (IN U32 uiID, IN SMsg *pstMsg, IN SRequest *pstRequest, OUT U8 *pucBuffer, IN OUT U32 *puBufLen) |
| VSTATUS | VAPI_SetTone (EToneId eToneId, EToneType eToneType, U16 usCadenceRpt, U16 usParamNum,...) |
| VSTATUS | VAPI_SetCidGenInfo (EAction eAction, ECidGenInfoType eCidGenInfoType, U16 usParamNum,...) |
| VSTATUS | VAPI_SetCidDetInfo (EAction eAction, ECidDetInfoType eCidDetInfoType, U16 usParamNum,...) |
The VAPI utilities is a set of API intended to help in the Comcerto command construction.
The constructed command is not linked to a particular device, connection or conference.
Once constructed the command can be sent using one of the API:
The same message can be used for several connection.
| void* VAPI_AllocateMessage | ( | U16 | usSize | ) |
Description:
Allocate a gtl_msg_t structure message and the associated fifo buffer.
The gtl_msg_t is an VAPI internal structure and some fields are initialized.
The passed size is used to internally allocate the fifo buffer which will contain the Comcerto commands.
This size must be big enougth to contain:
It is mandatory to use VAPI_AllocateMessage() to use the VAPI help functions such as:
The allocated buffers can be freed using VAPI_FreeMessage().
Note 1: The size of the fifo can be Firmware release and control interface dependent.
It is recommended to take in account to the device fifo size capability
| Inputs-Outputs | |
| usSize | Size of the fifo |
Returns:
Usage:
...
/* If the Voice Option and Echo Canceller commands have to be sent,
the size can be calculated this way :*/
U16 my_size = sizeof(struct _VOIP_VCEOPT) + /* size of VCEOPT parameters */
sizeof(struct _VOIP_ECHOCAN) + /* size of ECHOCAN parameters */
(2 * comcerto_api_hdr) + /* size of 2 API command headers */
(2 * PADDING_SIZE) + /* size of 2 potential inter command padding */
(2 * PADDING_SIZE) + /* size of terminator 4 bytes padding */
my_message = VAPI_AllocateMessage(my_size);
if (my_message == NULL)
vapi_error_handler(status);
else
{
...
Commands: List of the Comcerto commands:
| VSTATUS VAPI_FreeMessage | ( | void * | pvMsg | ) |
Description:
Frees a previously allocated message structure and the associated fifo buffer
| Inputs-Outputs | |
| pstMsg | Pointer to the message structure to free |
Returns:
Usage:
...
status = VAPI_FreeMessage(my_message);
if (status != SUCCESS)
vapi_error_handler(status);
else
{
...
Commands: List of the Comcerto commands:
| void VAPI_InitMessage | ( | void * | pvMsg | ) |
Description:
Reinitialises all the fields of the gtl_msg_t structure message
| Inputs-Outputs | |
| pvMsg | Pointer to the message structure to initialize |
Returns:
Commands: List of the Comcerto commands:
| VSTATUS VAPI_SendConferenceMessage | ( | IN U32 | uiID, | |
| IN SMsg * | pstMsg, | |||
| IN SRequest * | pstRequest, | |||
| OUT U8 * | pucBuffer, | |||
| IN OUT U32 * | puBufLen | |||
| ) |
Description:
This API is equivalent to VAPI_PassThru() with the level set to CMD_LEVEL_CONF
| VSTATUS VAPI_SendConnectionMessage | ( | IN U32 | uiID, | |
| IN SMsg * | pstMsg, | |||
| IN SRequest * | pstRequest, | |||
| OUT U8 * | pucBuffer, | |||
| IN OUT U32 * | puBufLen | |||
| ) |
Description:
This API is equivalent to VAPI_PassThru() with the level set to CMD_LEVEL_CONN
| VSTATUS VAPI_SendDeviceMessage | ( | IN U32 | uiID, | |
| IN SMsg * | pstMsg, | |||
| IN SRequest * | pstRequest, | |||
| OUT U8 * | pucBuffer, | |||
| IN OUT U32 * | puBufLen | |||
| ) |
Description:
This API is equivalent to VAPI_PassThru() with the level set to CMD_LEVEL_DEVICE
| VSTATUS VAPI_SetCidDetInfo | ( | EAction | eAction, | |
| ECidDetInfoType | eCidDetInfoType, | |||
| U16 | usParamNum, | |||
| ... | ||||
| ) |
Description:
This API sets the Caller ID information blocks used to detect a Caller ID.
With this API the user adds, modifies or removes Caller ID detection information blocks.
The Caller ID parameters are stored in a VAPI internal array.
The parameters are applied to a connection when the VAPI_SetCidDetection() is called.
The number of passed parameters must match the expected number for each different info blocks.
If the eAction = eRemove (0) the number of parameters is not taken it account.
| Block info type | Number of expected parameters |
| DataFormatInfoType | 2 |
| FSKInfoType | 3 |
| OnHookDetInfoType | 2 |
| OffHookDetInfoType | 1 |
| AckDetInfoType | 4 |
| NTTDetInfoType | 1 |
This API can be called any time after VAPI_Init(), but it is convenient to initialize the caller ID during the VAPI initialization phase (i.e just after VAPI_Init().
When VAPI_Init() is called, VAPI_SetCidDetInfo() is internally issued to configure a "default Caller ID detection".
Please see the default caller ID configuration below:
DataFormatInfoType: {0, 0}
Where 0: Data bits and parity 8 bits, no parity
0: Checksum used for message integrity FSKInfoType: {2, 0, 0}
Where 2: FSK detection type Both B202 and V.23
0: FSK Pull in threshold default
0: FSK Pull out threshold default OnHookDetInfoType: {192, 96}
Where 192: Channel Seizure Threshold 192 bits
96: Mark bits Threshold 96 bits OffHookDetInfoType: {96}
Where 96: Mark bits Threshold 96 bits AckGenInfoType: {0x0D, 20, 60,112}
Where 0x0D: DTMF Digit to generate
20: Delay time from CPE Alert Detected 20ms
60: Ack Tone Duration 60ms
112: Ack Tone Tx level -11.2 dBoV NTTDetInfoType: {0}
Where 0: NTT Detector disabled
| Inputs-Outputs | |
| eAction | CID Info block to modify, add or remove. |
| eCidDetInfotype | Specifies information block type. |
| usParamNum | Number of parameters to be passed. |
| ... | List of parameters (integers of type int). |
Returns:
Usage:
/* set parameters for SASToneInfoType */
Status = VAPI_SetCidGenInfo (
eModify, /*Modify the default SAS tone */
eSASToneInfoType,
8 /* 8 parameters*/
0, /* Tone ctrl (direction, protect, etc ...) */
440, /* primary frequency 440 hz*/
212, /* primary frequency amplitude -21.2dBv0*/
500, /* secondary freq 500 hz*/
212, /* secondary tone amplitude -21.2dBv0 */
400, /* on time */
300, /* off time */
40); /* Transition time before CAS 40ms*/
/* set parameters for NTTInfoType */
status = VAPI_SetCidGenInfo(
eAdd, /*Add this block*/
eNTTInfoType,
17, /* 17 parameters*/
1, /* Enable NTT */
1, /* Enable IIT1 */
212, /* IIT1 level -21.2 dBov */
39, /* IIT1 Squelch period 3.9 sec */
10, /* IIT1 to CAT time delay 1 sec */
1, /* Comcerto handles CAT*/
0x45, /* CAT digit 1 'E'*/
0x46, /* CAT digit 2 'F'*/
60, /* CAT digit on time 60ms*/
60, /* CAT digit off time 60ms*/
152, /* CAT digit high transmit level -15.2 dBv0*/
152, /* CAT digit low transmit level -15.2 dBv0*/
15, /* CAT to FSK_time_delay 300ms (unit 20ms) */
5, /* FSK to IIT2 time delay 100ms (unit 20ms) */
1, /* Enable IIT2 */
212, /* IIT2 level -21.2 dBov */
39); /* IIT2 Squelch period 3.9 sec */
/* Remove SAS Tone InfoType */
status = VAPI_SetCidGenInfo (eRemove, eSASToneInfoType, 0);
Commands: no commands sent
| VSTATUS VAPI_SetCidGenInfo | ( | EAction | eAction, | |
| ECidGenInfoType | eCidGenInfoType, | |||
| U16 | usParamNum, | |||
| ... | ||||
| ) |
Description:
This API sets the Caller ID information blocks used to generate a Caller ID.
With this API the user adds, modifies or removes Caller ID information blocks.
The Caller ID parameters are stored in a VAPI internal array.
The parameters are applied to a connection when the VAPI_PlayCid is called.
The number of passed parameters must match the expected number for each different info blocks, except for the
SASToneInfoType where the user can pass less than all parameters. If the eAction = eRemove (0) the number of parameters is not taken it account.
| Block info type | Number of expected parameters |
| OnHookXmitInfoType | 6 |
| OffHookXmitInfoType | 4 |
| CPEAlertToneInfoType | 5 |
| CPEAckInfoType | 7 |
| SASToneInfoType | 8 (1 dual tone block) 14 (2 dual tone blocks) 20 (3 dual tone blocks) 26 (4 dual tone blocks) |
| NTTInfoType | 17 |
| StopBitsInfoType | 1 |
| PacketProcessingInfoType | 1 |
This API can be called any time after VAPI_Init(), but it is convenient to initialize the caller ID during the VAPI initialization phase (i.e just after VAPI_Init().
When VAPI_Init() is called, VAPI_SetCidGenInfo() is internally issued to configure a "default Caller ID".
Please see the default caller ID configuration below:
OnHookXmitInfoType: {0xB6, 0x00, 0x01, 0x012C, 0x00, 0x00B4}
Where 0xB6: FSK amplitude = -18.2dbv0
0x00: Data Tx phase during ring
0x01: Alert info byte DT-AS
0x012C: Channel seizure bits: 300 bits
0x00: Channel seizure First Bit Space
0x00B4: Mark bits 180 Bits. OffHookXmitInfoType: {0xD4, 0x00, 0x01, 0x0064}
Where 0xB6: FSK ampliture = -18.2dbv0
0x00: Modulation freq Bell 202
0x01: Alert info byte DT-AS
0x0064: Mark Bits 100 bits CPEAlertToneInfoType: {0x0852, 0x0ABE, 0x50, 0xD4, 0xD4}
Where 0x0852: Low nominal frequency 2130 Hz
0x0ABE: High nominal frequency 2750 Hz
0x50: Duration 80ms
0xD4: Low frequency level -21.2 dbv0
0xD4: High frequency level -21.2 dbv0 CPEAckInfoType: { 0x41, 0x44, 0x1E, 0xC8, 0xA0, 0x00, 0x012C}
Where 0x41: DTMF Digit 1 'A'
0x44: DTMF Digit 2 'D'
0x1E: Min Duration 30ms
0xC8: Time out for ACK 200ms
0xA0: Time to data transmission 160ms
0x00: Data transmit if no ack: No
0x012C Ack tone min level -30dBv0The following block info types are not configured by default (set to 0x00):
| Inputs-Outputs | |
| eAction | CID Info block to modify, add or remove. |
| eCidGenInfotype | Specifies information block type. |
| usParamNum | Number of parameters to be passed. |
| ... | List of parameters (integers of type int). |
Returns:
Usage:
/* set parameters for SASToneInfoType */
Status = VAPI_SetCidGenInfo (
eModify, /*Modify the default SAS tone */
eSASToneInfoType,
8 /* 8 parameters*/
0, /* Tone ctrl (direction, protect, etc ...) */
440, /* primary frequency 440 hz*/
212, /* primary frequency amplitude -21.2dBv0*/
500, /* secondary freq 500 hz*/
212, /* secondary tone amplitude -21.2dBv0 */
400, /* on time */
300, /* off time */
40); /* Transition time before CAS 40ms*/
/* set parameters for NTTInfoType */
status = VAPI_SetCidGenInfo(
eAdd, /*Add this block*/
eNTTInfoType,
17, /* 17 parameters*/
1, /* Enable NTT */
1, /* Enable IIT1 */
212, /* IIT1 level -21.2 dBov */
39, /* IIT1 Squelch period 3.9 sec */
10, /* IIT1 to CAT time delay 1 sec */
1, /* Comcerto handles CAT*/
0x45, /* CAT digit 1 'E'*/
0x46, /* CAT digit 2 'F'*/
60, /* CAT digit on time 60ms*/
60, /* CAT digit off time 60ms*/
152, /* CAT digit high transmit level -15.2 dBv0*/
152, /* CAT digit low transmit level -15.2 dBv0*/
15, /* CAT to FSK_time_delay 300ms (unit 20ms) */
5, /* FSK to IIT2 time delay 100ms (unit 20ms) */
1, /* Enable IIT2 */
212, /* IIT2 level -21.2 dBov */
39); /* IIT2 Squelch period 3.9 sec */
/* Remove SAS Tone InfoType */
status = VAPI_SetCidGenInfo (eRemove, eSASToneInfoType, 0);
Commands: no commands sent
| VSTATUS VAPI_SetMessage | ( | OUT void * | pvMsg, | |
| IN U8 | ucCmdClass, | |||
| IN U8 | ucCmdType, | |||
| IN U16 | usFcode, | |||
| IN U16 | ucNumParams, | |||
| ... | ||||
| ) |
Description:
This function add the passed comcerto Command Class, Type, Function code and parameters
to an existing message structure
. If the message already contains a command, the new command is added to the message to build
a multi command message. The padding for the 32 bit alignment is performed by the VAPI_SetMessage().
Note 1: Multi command is not allowed if the command class is device level.
Note 2: This command can be used prior to VAPI_Init().
Note 3: The message structure need to be preallocated and initialized.
This is done using the VAPI_AllocateMessage() API
| Inputs-Outputs | ||
| pstMsg | Pointer to the message structure to be updated | |
| ucCmdClass | Comcerto Command Class | |
| ucCmdType | Comcerto Command type | |
| usFcode | Comcerto Function code | |
| ucNumParams | Number of parameters to be added | |
| .... | List of parameters. The parameters need to be provided in the correct endianness |
Returns:
Usage:
...
/* Note the UT_CPU2LE16() are only required on Big Endian host */
my_message = VAPI_AllocateMessage(MAX_FIFO_SIZE);
if (my_message == NULL)
vapi_error_handler(status);
else
{
/*add VOICE OPTIONS to the message */
status = VAPI_SetMessage(my_message , CMD_CLASS_CONF_CHANNEL, CMD_TYPE_CONF_CHANGE,
FC_VOIP_VCEOPT,
5, /* 5 parameters */
UT_CPU2LE16(0x1431), UT_CPU2LE16(0x7C00),
UT_CPU2LE16(0x0004), UT_CPU2LE16(0X0000),
UT_CPU2LE16(0x0000));
/* add DTMF OPTIONS to the message */
status = VAPI_SetMessage(my_message , CMD_CLASS_CONF_CHANNEL, CMD_TYPE_CONF_CHANGE,
FC_VOIP_DTMFOPT,
1, /* 1 parameter */
UT_CPU2LE16(0x0001));
}
...
Commands: List of the Comcerto commands:
| VSTATUS VAPI_SetMessageFromBuffer | ( | OUT void * | pvMsg, | |
| IN U8 | ucCmdClass, | |||
| IN U8 | ucCmdType, | |||
| IN U16 | usFcode, | |||
| IN U16 | ucNumParams, | |||
| IN U16 * | pusParameters | |||
| ) |
Description:
This function add the passed comcerto Command Class, Type, Function code and parameters
to an existing message structure
. If the message already contains a command, the new command is added to the message to build
a multi command message. The padding for the 32 bit alignment is performed by the VAPI_SetMessage().
Note 1: Multi command is not allowed if the command class is device level.
Note 2: This command can be used prior to VAPI_Init().
Note 3: The message structure need to be preallocated and initialized.
This is done using the VAPI_AllocateMessage() API
| Inputs-Outputs | ||
| pstMsg | Pointer to the message structure to be updated | |
| ucCmdClass | Comcerto Command Class | |
| ucCmdType | Comcerto Command type | |
| usFcode | Comcerto Function code | |
| ucNumParams | Number of parameters to be added | |
| pusParameters | Buffer containing the parameters of the command. The parameters need to be provided in the correct endianness |
Returns:
Usage:
...
my_vce_params[5] = {0x1431, 0x7C00, 0x0004, 0X0000, 0x0000}
my_dtmf_params[1] = {0x0001}
my_message = VAPI_AllocateMessage(MAX_FIFO_SIZE);
if (my_message == NULL)
vapi_error_handler(status);
else
{
/*add VOICE OPTIONS to the message*/
status = VAPI_SetMessageFromBuffer(my_message ,
CMD_CLASS_CONF_CHANNEL, CMD_TYPE_CONF_CHANGE, FC_VOIP_VCEOPT,
5, /* 5 parameters */
&my_vce_params);
// add DTMF OPTIONS to the message
status = VAPI_SetMessageFromBuffer(my_message,
CMD_CLASS_CONF_CHANNEL, CMD_TYPE_CONF_CHANGE, FC_VOIP_DTMFOPT,
1, /* 1 parameter */
&my_dtmf_params);
}
...
Commands: List of the Comcerto commands:
| VSTATUS VAPI_SetTone | ( | EToneId | eToneId, | |
| EToneType | eToneType, | |||
| U16 | usCadenceRpt, | |||
| U16 | usParamNum, | |||
| ... | ||||
| ) |
Description:
This API set the frequencies, amplitudes, on/off time, cadences for Dual (Function code 0x8009) or Quad tone (Function code 0x8040).
With this API the user adds or modifies existing tone definition.
The tone parameters are stored in a VAPI internal tone array: astToneGeneric_g.
The parameters such as direction, mixing mode, etc. are handled when the tone is play with VAPI_PlayTone().
The tone parameters are passed through a list which depends on the type of the tone.
For Dual Tone parameters list could be up to 4 blocks (5 blocks for Comcerto 100 and 1000 devices) with 6 parameters per block as follows:
{Primary Tone Frequency, Primary Tone Amplitude, Second Tone Frequency, Second Tone Amplitude, On Time, Off Time).
For Quad Tone parameters list is as follows:
{First Tone Frequency, First Tone Amplitude, Second Tone Frequency, Second Tone Amplitude,
Third Tone Frequency, Third Tone Amplitude, Fourth Tone Frequency, Fourth Tone Amplitude, On Time, Off Time}
This API can be used only after VAPI_Init() call and before VAPI_InitDevice.
Actually before channel creation the tone to be played on.
When VAPI_Init() is called, VAPI_SetTone() is internally issued to configure a set of "default tone".
Please see the default tone configuration below:
Pre defined DTFM tones.
eDTMFTONE_1 697, 100, 1209, 100, 80, 80 eDTMFTONE_2 697, 100, 1336, 100, 80, 80 eDTMFTONE_3 697, 100, 1477, 100, 80, 80 eDTMFTONE_4 770, 100, 1209, 100, 80, 80 eDTMFTONE_5 770, 100, 1306, 100, 80, 80 eDTMFTONE_6 770, 100, 1477, 100, 80, 80 eDTMFTONE_7 852, 100, 1209, 100, 80, 80 eDTMFTONE_8 852, 100, 1336, 100, 80, 80 eDTMFTONE_9 852, 100, 1477, 100, 80, 80 eDTMFTONE_A 697, 100, 1633, 100, 80, 80 eDTMFTONE_B 770, 100, 1633, 100, 80, 80 eDTMFTONE_C 852, 100, 1633, 100, 80, 80 eDTMFTONE_D 941, 100, 1633, 100, 80, 80 eDTMFTONE_STAR 941, 100, 1209, 100, 80, 80 eDTMFTONE_0 941, 100, 1336, 100, 80, 80 eDTMFTONE_HASH 941, 100, 1477, 100, 80, 80
Call progess Tones
Repeat Tone frequencies, amplitudes, on/off time definition
eNULLTONE 1, 0, 0, 0, 0, 0, 0
eCONGESTIONTONE 0xFF, 480, 100, 620, 100, 250, 250
eWARNINGTONE 1, 440, 100, 0, 0, 1500, 8000, 440, 100, 0, 0, 500, 8000
eWAITINGTONE 1, 440, 100, 0, 0, 300, 10000
eCONFIRMATIONTONE 0 350, 170, 440, 170, 100, 100, 350, 170, 440, 170, 100, 100, 350, 170, 440, 170, 100, 100
eDIALTONE 0xFF, 350, 100, 440, 100, 0, 0
eBUSYTONE 0xFF, 480, 100, 620, 100, 500, 500
eRINGBACKTONE 0xFF, 440, 100, 480, 100, 1000, 3000
eSPECIALTONE 1, 950, 100, 0, 0, 330, 0, 1400, 100, 0, 0, 330, 0, 1800, 100, 0, 0, 330, 0
eSASTONE 0 440, 0xD4, 00, 00, 0x12C, 0x12C
Customizable Tones
30 customizable tones are avialable (eCUSTOM_1 to eCUSTOM_30)
The user can add new tones definitions to the existing tones.
Please check the usage section for more details on tone customization.
After setting parameters for particular eToneId VAPI_PlayTone() may be called
to play tone to defined direction (please refer to VAPI_PlayTone doc for details).
NOTE: The current number of tone supported is 35 defined by eDUMMYTONE.
To increase the number of tones, please add new values to the EToneId enumeration and make
sure that eDUMMYTONE is correctly updated.
| Inputs-Outputs | |
| eToneId | The tone index. |
| eToneType | Specifies tone type dual/quad. |
| usCadenceRpt | Cadence repeat (only for Dual tone). Determines the number of times the cadence pattern (defined by the cadence blocks that follow) is repeated (only for Dual Tone) |
| usParamNum | Number of parameters to be passed. |
| ... | List of parameters. |
Returns:
Usage:
...
/* Changing WARNING TONE parameters (dual tone) with 2 cadences and played 2 times*/
status = VAPI_SetTone(eWARNINGTONE, eDualTone, 1, /*cadence repeated once */
12, /*12 parameters*/
/* first cadence block*/
440, 100, /* Freq (Hz), Amp*/
0, 0, /* No sec Freq , Amp*/
1500, 8000, /* On Time, Off Time*/
/* second cadence block*/
550, 100, /* Freq (Hz), Amp*/
0, 0, /* No sec Freq (Hz), Amp*/
500, 8000); /* On Time, Off Time*/
/* Adding a custom quad tone */
Status = VAPI_SetTone (eCUSTOM_1, eQuadTone, 0, /*cadence repeat not used for quad tone*/
10, /*10 parameters*/
1000, 70, /* Prim Freq, Amp*/
1500, 80, /*Sec Freq, Amp*/
2000, 120, /* Third Freq, Amp*/
2500, 170, /* Fourth Freq, Amp*/
80, 50); /* On Time, Off Time */
/* Adding a custom dual tone with 3 cadences blocks and played 4 times*/
status = VAPI_SetTone(eCUSTOM_2, eDualTone, 3, /*cadence repeated third time */
18, /*18 parameters*/
/* first cadence block*/
350, 100, /* Freq (Hz), Amp*/
450, 100, /* Sec Freq (Hz) , Amp*/
500, 8000, /* On Time, Off Time*/
/* second cadence block*/
450, 100, /* Freq (Hz), Amp*/
550, 100, /* Sec Freq (Hz), Amp*/
500, 8000, /* On Time, Off Time*/
/* third cadence block*/
550, 100, /* Freq (Hz), Amp*/
650, 100, /* Sec Freq (Hz), Amp*/
500, 8000); /* On Time, Off Time*/
...
Commands: no commands sent