2.18.x
|
|
| VAPI API Reference Documentation 2.18.x |
|
Functions | |
| VSTATUS | VAPI_CreateConference (IN DEVID DevId, IN CONFID ConfId, IN SConfParams *pstConfParams, IN Boolean bIsEnhancedConf, IN SConfDTSParams *pstConfDTSParams, IN SRequest *pstRequest) |
| VSTATUS | VAPI_AllocateParticipant (IN CONFID ConfId, IN PARTID PartId, IN EPartType ePartType, IN U8 ucNumOfParams, IN U16 *pusParams, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_DestroyParticipant (IN PARTID PartId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_DestroyConference (IN CONFID ConfId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_EnableParticipant (IN PARTID PartId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_DisableParticipant (IN PARTID PartId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_PutParticipantOnHold (IN U32 PartId, IN EHoldState eHoldState, IN U32 uiSrcPartId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_MuteParticipant (IN U32 PartId, IN Boolean bMute, IN SRequest *pstRequest) |
| VSTATUS | VAPI_CreateTdmSideParticipant (IN CONFID ConfId, IN PARTID PartId, IN U16 usTdmTimeSlot, IN U8 ucAU_Law, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_CreateIpSideParticipant (IN CONFID ConfId, IN PARTID PartId, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_CreateTranscodingParticipant (IN CONFID ConfId, IN PARTID PartId, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_SetParticipantDgain (IN PARTID PartId, IN U16 usGain, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetParticipantOpt (IN PARTID PartId, IN U16 usRfc2833OnOff, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetConferenceDgain (IN DEVID DevId, IN U16 usGain, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetConferenceLatency (IN DEVID DevId, IN U16 usLatency, IN SRequest *pstRequest) |
| VSTATUS VAPI_AllocateParticipant | ( | IN CONFID | ConfId, | |
| IN PARTID | PartId, | |||
| IN EPartType | ePartType, | |||
| IN U8 | ucNumOfParams, | |||
| IN U16 * | pusParams, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
This API creates a participant in narrow or wide band mode on a conference. Conference ID specifies which conference this participant is a party of.
| Inputs-Outputs | |
| ConfId | The conference on which participant is to be created. |
| PartId | Participant identifier. The participant ID maybe used in the same way as connection ID for all API calls that are relevant to an IP-side connection. i.e. VAPI_SetConnIpParams(), the user application may use this API function and pass the participant ID in place of connection ID to configure the destination IP/UDP port for this participant. The library NACKs all API calls that does not apply to an IP side participant (like VAPI_StartCallerId() and VAPI_StartTone() with TDM side generation). |
| ePartType | Specifies the type of participant (eLSP eRSP, eTRANS) |
| NumParam | Number of parameters |
| pusParams | Parameters for the new connection (i.e timeslots). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this participant this event callback will be called |
Returns:
Usage:
...
CONFID conference_id = 1;
U16 timeslot1 = 0;
CONNID connection1 = 253;
CONNID connection2 = 254;
CONNID connection3 = 255;
CONNID connection4 = 256;
/* define conference parameters */
SConfParams conference_parameters;
/* use conference transcoding */
conference_parameters.bTranscoding = False;
conference_parameters.bBlockDTMF = False;
/* create a simple conference 1 on device 0 */
status = VAPI_CreateConference(device_id, conference_id, &conference_parameters, False, NULL, NULL);
/* create a a Local and a Remote participant on conference 1 in Narrow band mode */
status = VAPI_AllocateParticipant(conference_id, connection1, eLSP, 1, ×lot1, NULL, NULL);
status = VAPI_AllocateParticipant(conference_id, connection2, eRSP, 0, NULL, NULL, NULL);
...
...
U16 timeslots[4] = {2,3,4,5};
/* create a a Local and Remote participant on conference 1 in Wide band mode
The firmware used must support Wide band mode for conferencing */
status = VAPI_AllocateParticipant(conference_id, connection3, eLSPWB, 4, timeslots, NULL, NULL);
status = VAPI_AllocateParticipant(conference_id, connection4, eRSPWB, 0, NULL, NULL, NULL);
...
}
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_CreateConference | ( | IN DEVID | DevId, | |
| IN CONFID | ConfId, | |||
| IN SConfParams * | pstConfParams, | |||
| IN Boolean | bIsEnhancedConf, | |||
| IN SConfDTSParams * | pstConfDTSParams, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Creates a New conference with a user specified conference ID.
The VAPI library will map future references of conference ID to the correct device ID
to pass to the GTL layer.
Commands to enable enhanced conferencing are sent if bIsEnhancedConf is set to True.
Note: The VAPI_CreateConference() is divided in 2 main steps (if enhanced conferencing is enabled):
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| ConfId | Conference ID is specified by the user application that uniquely identifies the conference. Conference ID may overlap with the values used for connection ID (participant IDs may not overlap with connection IDs) |
| pstConfParams | To Enable/Disable Transcoding and DTMF Tone block feature. |
| bIsEnhancedConf | Whether to use enhanced conferencing for this conference. Note: This is an optional feature of the Comcerto firmware |
| pstConfDTSParams | Enhanced conferencing parameters. Valid only if bIsEnhancedConf is True. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* define conference parameters */
SConfParams conference_parameters;
/* do not use conference transcoding */
conference_parameters.bTranscoding = False;
/* do not block DTMFg */
conference_parameters.bBlockDTMF = False;
/* define complex conferencing parameters */
SConfDTSParams dominant_talkers;
dominant_talkers.bDTSOnOff = True;
dominant_talkers.usAttackConst = 60;
dominant_talkers.usNTH1 = 0xFE48;
dominant_talkers.usNTH2 = 0xFEC0;
dominant_talkers.usHoldConst = 1000;
dominant_talkers.usN1 = 1;
dominant_talkers.usG1 = 0x0000;
dominant_talkers.usN2 = 2;
dominant_talkers.usG2 = 0x0064;
dominant_talkers.usN3 = 3;
dominant_talkers.usG3 = 0x00C8;
...
...
/* create the conference 0 on device 0 using enhanced conferencing feature */
status = VAPI_CreateConference(0, 0, &conference_parameters, True, &dominant_talkers, NULL);
if (status != SUCCESS)
return status;
...
...
/* create a simple conference 1 on device 0 */
status = VAPI_CreateConference(0, 1, &conference_parameters, False, NULL, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_CreateIpSideParticipant | ( | IN CONFID | ConfId, | |
| IN PARTID | PartId, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
Creates an IP-side conference participant with the ID specified by the user application.
The conference ID specifies which conference this participant is a party of.
Note 1: The VAPI_CreateIpSideParticipant() is divided in 2 main steps:
Note 2: In case that the VAPI_InitDevice() function has not been previously issued,
VAPI_CreateIpSideParticipant() returns VAPI_ERR_DEVICE_NOT_INITIALIZED
| Inputs-Outputs | |
| ConfId | The conference on which participant is to be created. |
| PartId | Participant identifier. The participant ID maybe used in the same way as connection ID for all API calls that are relevant to an IP-side connection. i.e. VAPI_SetConnIpParams(), the user application may use this API function and pass the participant ID in place of connection ID to configure the destination IP/UDP port for this participant. The library NACKs all API calls that does not apply to an IP side participant (like VAPI_StartCallerId() and VAPI_StartTone() with TDM side generation). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this participant this event callback will be called |
Returns:
Usage:
...
/* Create the IP side Participant 0 (RSP) on conference 10*/
status = VAPI_CreateIpSideParticipant(10, 0, NULL, NULL);
switch (status)
{
case SUCCESS:
break;
default:
vapi_error_handler(status);
break;
}
...
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_CreateTdmSideParticipant | ( | IN CONFID | ConfId, | |
| IN PARTID | PartId, | |||
| IN U16 | usTdmTimeSlot, | |||
| IN U8 | ucAU_Law, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
Creates a TDM side conference participant with the ID specified by the user application.
The conference ID specifies which conference this participant is a party of.
Note 1: The VAPI_CreateTdmSideParticipant() is divided in 2 main steps:
Note 2: In case that the VAPI_InitDevice() function has not been previously issued,
VAPI_CreateTdmSideParticipant() returns VAPI_ERR_DEVICE_NOT_INITIALIZED
| Inputs-Outputs | |
| ConfId | The conference on which participant is to be created. |
| PartId | Participant identifier. The participant ID maybe used in the same way as connection ID for all API functions calls that are relevant to a TDM connection. The library NACKs all API calls that does not apply to a TDM side participant (like VAPI_SetConnIpParams() |
| usTdmTimeSlot | TDM timeslot for the new participant (Like for VAPI_CreateConnection()) |
| ucAU_Law | Encoding to be used (A_LAW or U_LAW) (Like for VAPI_CreateConnection()) |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this participant this event callback will be called |
Returns:
Usage:
...
/* Create the Local Participant 0 (LSP) on conference 1 with timeslot 10*/
status = VAPI_CreateTdmSideParticipant(1, 0, 10, U_LAW, NULL, NULL);
switch (status)
{
case SUCCESS:
break;
default:
vapi_error_handler(status);
break;
}
...
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_CreateTranscodingParticipant | ( | IN CONFID | ConfId, | |
| IN PARTID | PartId, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
Creates an transcoding type conference participant with the ID specified by the user application.
The conference ID specifies which conference this participant is a party of.
The conference must have been previously created with the transcoding option enabled (bTranscoding param of SConfParams)
| Inputs-Outputs | |
| ConfId | The conference on which participant is to be created. |
| PartId | Participant identifier. The participant ID maybe used in the same way as connection ID for all API calls that are relevant to an transcodng connection. i.e. VAPI_SetConnIpParams(), the user application may use this API function and pass the participant ID in place of connection ID to configure the destination IP/UDP port for this participant. The library NACKs all API calls that does not apply to an transcoding participant (like VAPI_StartCallerId() and VAPI_StartTone() with TDM side generation). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this participant this event callback will be called |
Returns:
Usage:
SConfParams conference_parameters; /* use conference transcoding */ conference_parameters.bTranscoding = True; conference_parameters.bBlockDTMF = False; /* create a simple conference 1 on device 0 */ result = VAPI_CreateConference(device_id, g_conference_id, &conference_parameters, False, NULL, NULL); /* Create the tanscoding Participant 0 on conference 1*/ result |= VAPI_CreateTranscodingParticipant( g_conference_id, 0, NULL, NULL); /* Create the tanscoding Participant 1 on conference 1*/ result |= VAPI_CreateTranscodingParticipant( g_conference_id, 1, NULL, NULL); /*Set participant 1 in G723*/ result |= VAPI_SetCodecType (1, eG723_1_ID, NULL); /*Function to configure the IP header */ result |= set_ip_udp_parameters(0); result |= set_ip_udp_parameters(1); /*Start transcodings*/ result |= VAPI_EnableParticipant(0, NULL); result |= VAPI_EnableParticipant(1, NULL); if (result != SUCCESS) error_handler();
Commands: List of Comcerto commands sent:
Description:
This function shuts down a conference and removes all participants, if still active.
| Inputs-Outputs | |
| ConfId | Conference session identifier. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* destroy the conference 0 */
status = VAPI_DestroyConference(0, NULL);
if (status != SUCCESS)
return status;
..
Commands: List of Comcerto commands sent:
Description:
This function destroys a participant, similar to how a connection is destroyed.
| Inputs-Outputs | |
| PartId | Participant to be destroyed. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* destroy the participant 5 */
status = VAPI_DestroyParticipant(5, NULL);
if (status != SUCCESS)
return status;
..
Commands: List of Comcerto commands sent:
Description:
Disables packet generation for IP side participant, and reverts the connection status back to signaling state.
In signaling state, the user application may detect tones and issue tone generation APIs.
| Inputs-Outputs | |
| PartId | Participant identifier. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* Disable the participant 0 */
status = VAPI_DisableParticipant(0, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
Description:
This function enables the participant to join the conference, similar to VAPI_EnableConnection API.
For TDM-side participants, this puts the connection into signaling state, so tones maybe generated and detected on the TDM side.
| Inputs-Outputs | |
| PartId | Participant identifier. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* To enable a conference participant 2 APIs are available: - VAPI_EnableParticipant - VAPI_SetConnectionState*/ ... /* enable the participant 0 */ status = VAPI_EnableParticipant(0, NULL); if (status != SUCCESS) return status; .. ... status = VAPI_SetConnectionState(0, eActive, pstRequest); if (status != SUCCESS) return status; ...
Commands: Comcerto commands sent:
Description:
Puts the participant on mute or off mute.
A muted participant does not speak into the conference, but may still monitor the conference.
| Inputs-Outputs | |
| PartId | Participant identifier. |
| bMute | If True participant muted, if False particiant unmuted |
| uiSrcPartId | Source Participant Id (for announcement hold only) |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* Set the participant 0 in simple hold*/
status = VAPI_PutParticipantOnHold(0, eSIMPLEHOLD, NULL);
if (status != SUCCESS)
return status;
...
...
/* Mute the participant 0 */
status = VAPI_MuteParticipant(0, True, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_PutParticipantOnHold | ( | IN U32 | PartId, | |
| IN EHoldState | eHoldState, | |||
| IN U32 | uiSrcPartId, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API puts the participant ON hold or OFF hold.
A held participant may hear announcements instead of the conference.
| Inputs-Outputs | |
| PartId | Participant identifier. |
| eHoldState | Hold state can be eHOLDOFF, eSIMPLEHOLDON, eANNHOLD |
| uiSrcPartId | Source Participant Id (for announcement hold only) |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* Set the participant 0 in simple hold*/
status = VAPI_PutParticipantOnHold(0, eSIMPLEHOLD, NULL);
if (status != SUCCESS)
return status;
...
...
/* Mute the participant 0 */
status = VAPI_MuteParticipant(0, True, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
Description:
This API sets the attenuation for all participants of all conferences. In effect, it sets the default gain for any participant
that is created. Every participant, when created, will have the gain value specified by this API.
The Host can override the default gain setting on a per-participant basis using the VAPI_SetParticipantDgain() call.
However, when the participant is destroyed (e.g. because the conference is over), the per-participant gain value is lost.
When a new participant is created, it will have the default gain value set by this API.
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| usGain | The attenuation value |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* set gain value = 1 (-1.5 dB) on device 0*/
status = VAPI_SetConferenceDgain(0, 1, NULL)
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
Description:
This API sets the round-trip (speaker's mouth to speaker's ear) latency for TDM-only conferences.
It must be called a single time before any conference is created, and the latency specified applies to all conferences
created subsequently. The usLatency value specifies whether enhanced conferencing will be used.
Enhanced conferencing support is needed for AGC and/or Dominant Talker algorithm.
| Inputs-Outputs | |
| DevId | Device identifier that uniquely identifies a device. |
| usLatency | The round-trip latency value |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* set latency value = 1 (20 ms) on device 0*/
status = VAPI_SetConferenceLatency(0, 1, NULL)
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
Description:
This API sets the attenuation for a particular participant of a particular conference.
| Inputs-Outputs | |
| PartId | The participant on which gain is to be changed. |
| usGain | The Gain value, the same value in MSP CRM command, 16bit. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns: SUCCESS
Usage:
...
/* Create the IP side Participant 0 (RSP) on conference 10*/
status = VAPI_CreateIpSideParticipant(10, 0, NULL, NULL);
if (status != SUCCESS)
return status;
/* set gain value = 1 (-1.5 dB) for participant 0 of 10th conference */
status = VAPI_SetParticipantDgain (0, 1, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent:
| VSTATUS VAPI_SetParticipantOpt | ( | IN PARTID | PartId, | |
| IN U16 | usRfc2833OnOff, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API enables/disables RFC2833 processing for a RSP participant.
This API can be send anytime while the conference in session.
| Inputs-Outputs | |
| PartId | The participant on which gain is to be changed. |
| usRfc2833OnOff | RFC2833 Processing Feature (0 = Disable (default), 1 = Enable). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns: SUCCESS
Usage:
...
/* Create the IP side Participant 0 (RSP) on conference 10*/
status = VAPI_CreateIpSideParticipant(10, 0, NULL, NULL);
if (status != SUCCESS)
return status;
/* set usRfc2833OnOff = True for participant 0 of 10th conference */
status = VAPI_SetParticipantOpt (0, True, NULL);
if (status != SUCCESS)
return status;
...
Commands: List of Comcerto commands sent: