2.18.x
|
|
| VAPI API Reference Documentation 2.18.x |
|
Functions | |
| VSTATUS | VAPI_CreateConnection (IN DEVID DevId, IN CONNID ConnId, IN EConnType eConnType, IN U16 usTdmTimeSlot, IN U8 ucAU_Law, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_AllocateConnection (IN DEVID DevId, IN CONNID ConnId, IN EConnType eConnType, IN EConnMode eConnMode, IN U8 ucNumOfParams, IN U16 *pusParams, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS | VAPI_DestroyConnection (IN CONNID ConnId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_ChangeConnectionType (IN CONNID ConnId, IN SChangeConnInfo *pstChangeConnInfo, IN U16 NumParam, IN U16 *pusParams, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetConnectionState (IN CONNID ConnId, IN EConnOpMode eOpMode, IN SRequest *pstRequest) |
| VSTATUS | VAPI_Loopback (IN CONNID ConnId1, IN CONNID ConnId2, IN ELoopbackType eLoopback, IN SRequest *pstRequest) |
| VSTATUS | VAPI_StartTone (IN CONNID ConnId, U8 ucDir, EToneId eToneId, ECountryCode eCountryCode, IN SRequest *pstRequest) |
| VSTATUS | VAPI_PlayTone (IN CONNID ConnId, EToneId eToneId, EToneDir eToneDir, SPlayToneOpt *pstPlayToneOpt, U16 usParamNum, IN SRequest *pstRequest,...) |
| VSTATUS | VAPI_StopTone (IN CONNID ConnId, IN U16 usToneDuration, IN U16 usSide, IN SRequest *pstRequest) |
| VSTATUS | VAPI_StartCallerId (IN CONNID ConnId, IN CidInfo *pstCidInfo, IN SRequest *pstRequest) |
| VSTATUS | VAPI_PlayCid (IN CONNID ConnId, IN SCallerIdInfo *pstCidInfo, IN SRequest *pstRequest) |
| VSTATUS | VAPI_StopCallerId (IN CONNID ConnId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_EnableCIDDetection (IN CONNID ConnId, IN ECountryCode eCountryCode, IN U8 ucEnableType, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetCidDetection (IN CONNID ConnId, IN SCidDetCtrl *pstCidDetCtrl, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetCodecType (IN CONNID ConnId, IN ECodecIndex eCodecIndex, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetPacketInterval (IN CONNID ConnId, IN U8 ucMilliSec, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetPayloadType (IN CONNID ConnId, IN ECodecType eCodec, IN U8 ucPlTypVal, IN EDirection eDir, IN SRequest *pstRequest) |
| VSTATUS | VAPI_EchoCancellerReset (IN CONNID ConnId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SendNteEvent (IN CONNID ConnId, IN U32 uiNtePyLd, IN U16 usOverRideBitField, IN U16 usRedundancyInterval, IN U32 uiSsrc, IN U16 usPyLdType, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetRtpSsrcHeader (IN CONNID ConnId, IN U32 uiSsrcVal, IN SRequest *pstRequest) |
| VSTATUS | VAPI_ConfigureT38Options (IN U32 ConnId, IN SFaxConfigOpts *pstFaxConfigOpts, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SwitchToT38 (IN CONNID ConnId, IN SFaxConfigOpts *pstFaxConfigOpts, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetConnIpParams (IN CONNID ConnId, IN SIpParams *pstIpParams, IN SRequest *pstRequest) |
| VSTATUS | VAPI_TranscodingSession (IN CONNID ConnId1, IN CONNID ConnId2, IN STranscodingOption *pstTranscodingOption, IN SRequest *pstRequest) |
| VSTATUS | VAPI_ModifyConnection (IN CONNID ConnId, IN U16 usModifyNum, IN SModifyConnectionInfo *pstModifyConnectionInfo, IN SRequest *pstRequest) |
| VSTATUS | VAPI_SetConnVlan (IN CONNID ConnId, IN U16 usVlanId, IN SRequest *pstRequest) |
| VSTATUS | VAPI_RecoverConnection (IN DEVID DevId, IN CONNID ConnId, IN EConnType eConnType, IN U16 usTdmTimeSlot, IN U16 usRecoverOption, IN SRequest *pstRequest, IN PFNEventCallback pfnEventCallback) |
| VSTATUS VAPI_AllocateConnection | ( | IN DEVID | DevId, | |
| IN CONNID | ConnId, | |||
| IN EConnType | eConnType, | |||
| IN EConnMode | eConnMode, | |||
| IN U8 | ucNumOfParams, | |||
| IN U16 * | pusParams, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
This API creates a Comcerto device channel.
| Inputs-Outputs | |
| DevId | The device on which connection is to be created. |
| ConnId | The connection ID is specified by the user application. The connection ID is assumed unique across all devices and channels. The VAPI library keeps track of the connection resource mapped by the user-specified connection ID. The VAPI library looks up the device ID mapped to the connection ID and passes that down to GTL layer |
| eConnType | Specifies the type of channel (VoIP, VoATM, T38, etc). It can have following values:
|
| eConnMode | Channel mode Narrow or Wide band. |
| ucNumOfParam | Number of parameters contained in the usParams buffer. |
| usParams | Ponter to a buffer containing the channel parameters This buffer contains mainly timeslot number. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this connection this event callback will be called |
Returns:
Usage:
/* Blocking mode example for narrow band channel*/ ... U16 my_timeslot = 0; status = VAPI_AllocateConnection(DevID, my_connection_id, eVOIP, eNarrowBand, 1, &my_timeslot, NULL, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... /* Asynchronous mode example for wide band channel */ ... void create_endpoint(int endpoint_id, int endpoint_state) { int result; SRequest request; U16 my_timeslots[4] = {0, 1, 2, 3, 4}; request.uiReqId = endpoint_state; request.pfnIoCompCallback = &comcerto_response_handler; result = VAPI_AllocateConnection(device_id, endpoint_id, eVOIP, /* type 2*/ eWideBand, 4, /* use 4 timeslots */ my_timeslots, &request, NULL); switch (result) { case VAPI_ERR_PENDING /* If success go ahead */ break; default: vapi_error_handler(result); break; } ...
Commands: Comcerto commands sent depends on channel type required:
| VSTATUS VAPI_ChangeConnectionType | ( | IN CONNID | ConnId, | |
| IN SChangeConnInfo * | pstChangeConnInfo, | |||
| IN U16 | NumParam, | |||
| IN U16 * | pusParams, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API modifies a Comcerto device channel type.
Depending on the type the VAPI_ChangeConnectionType() handler:
| Inputs-Outputs | |
| ConnId | Connection to be switched in T38 mode. |
| pstChangeConnectionInfo | Pointer to structure that specifies the modify connection settings. |
| NumParam | Number of parameters. |
| pusParams | Parameters for the new connection (i.e. timeslots). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* VoIP to VoIP change timeslot */ ... SChangeConnInfo stChangeConnInfo; SChangeConnInfo.eConnType = eVOIP; SChangeConnInfo.eConnMode = eNarrowBand; SChangeConnInfo.ePartType = eNOTPART; SChangeConnInfo.eChangeOpMode = eOpModeIP; U16 ConnectionParams[2] = {NumParams, Timeslot}; /*New timeslot*/ VAPI_ChangeConnectionType (ConnId, & stChangeConnInfo, 2, /*2 parameters */ &ConnectionParams, NULL) ... ... /* VoIP narrow band to VoIP wide band */ SChangeConnInfo stChangeConnInfo; SChangeConnInfo.eConnType = eVOIP; SChangeConnInfo.eConnMode = eWideBand; SChangeConnInfo.ePartType = eNOTPART; SChangeConnInfo.eChangeOpMode = eOpModeIP; /* parameters are time slots */ U16 ConnectionParams[5] = {4, 1, 2, 3, 4}; VAPI_ChangeConnectionType (ConnId, &stChangeConnectionInfo, 5, /*5 parameters*/ ConnectionParams, NULL) ... ... /* VoIP to FoIP */ SChangeConnInfo stChangeConnInfo; stChangeConnInfo.eConnType = eFOIP; stChangeConnInfo.eConnMode = eNarrowBand; stChangeConnInfo.ePartType = eNOTPART; VAPI_ChangeConnectionType(ConnId, &stChangeConnInfo, 0, /*no parameters reuse same timeslot*/ NULL, NULL) ... ... /* TONEGEN to VoIP */ SChangeConnInfo stChangeConnInfo; stChangeConnInfo.eConnType = eVOIP; stChangeConnInfo.eConnMode = eNarrowBand; stChangeConnInfo.ePartType = eNOTPART; stChangeConnInfo.eChangeOpMode = eOpModeNone; VAPI_ChangeConnectionType (ConnId, & sChangeConnectionInfo, 0, /*no parameters reuse same timeslot */ NULL, NULL) ... ... /* VoIP to LSP NarrowBand*/ /* The conference must have been previously created with VAPI_CreateConference(ConfId) */ SChangeConnInfo stChangeConnInfo; stChangeConnInfo.eConnType = 0; stChangeConnInfo.eConnMode = eNarrowBand; stChangeConnInfo.ePartType = eLSP; stChangeConnInfo.eChangeOpMode = eOpModeNone; /* parameter is the conference Id */ U16 ConnectionParams[3] = {ConfId, NumParams, Timeslot}; VAPI_ChangeConnectionType (ConnId, & sChangeConnectionInfo, 3, /*3 parameter*/ &ConnectionParams, NULL) ... ... /* VoIP to RSP WideBand */ /* The conference must have been previously created with VAPI_CreateConference(ConfId) */ SChangeConnInfo stChangeConnInfo; stChangeConnInfo.eConnType = 0; stChangeConnInfo.eConnMode = eWideBand; stChangeConnInfo.ePartType = eRSP; stChangeConnInfo.eChangeOpMode = eOpModeIP; /* parameter is the conference Id */ U16 ConnectionParams[6] = {ConfId, NumParams, Timeslot1, Timeslot2, Timeslot3, Timeslot4}; VAPI_ChangeConnectionType (ConnId, & sChangeConnectionInfo, 6, /*3 parameter*/ &ConnectionParams, NULL) ...
Commands:
| VSTATUS VAPI_ConfigureT38Options | ( | IN U32 | ConnId, | |
| IN SFaxConfigOpts * | pstFaxConfigOpts, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API configures the Fax options to be used while switching over to T38 mode.
It stores the options in the channel parameters structure associated with the connection if the chnnael is VoIP.
The options will be used later on if the channel is switched to FoIP (see VAPI_SwitchToT38()).
If the channel is already in FoIP mode, the MSP FAX commands are sent to configure the channel.
| Inputs-Outputs | |
| ConnId | Connection to which the T38 options have to be changed. |
| pstFaxConfigOpts | Pointer to fax options structure which gives the fax switchover options to be used while switching to FoIP mode |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* define a fax configuration structure*/
SFaxConfigOpts fax_configuration;
/* Set the convenient parameters for this connection */
fax_configuration.bUseExistingOpts = False;
fax_configuration.ucFaxTxLevel = 8;
fax_configuration.bEnableFaxAutoSwitch = False;
fax_configuration.usSwitchoverEventMask = 0;
fax_configuration.stFaxOpts.ucT38PktLossConcealment = 1;
fax_configuration.stFaxOpts.ucECMDisable = 1;
fax_configuration.stFaxOpts.ucFaxDataRedundancyCnt = 3;
fax_configuration.stFaxOpts.ucT30RedundancyCnt = 7;
fax_configuration.stFaxOpts.ucFaxConnSpeedLimit = 6;
fax_configuration.stFaxOpts.ucErrRcvyMethod = 0;
fax_configuration.stFaxOpts.ucTCFProcedure = 0;
fax_configuration.stFaxOpts.ucNumFEC = 0;
fax_configuration.stFaxOpts.ucNumIFPs = 4;
/* Set the T38 parameters fo the connection 0 */
status = VAPI_ConfigureT38Options(0, &fax_configuration, NULL);
{
printf("Configure T38 error %d", status);
return status;
}
..
Commands: List of Comcerto commands sent (if FoIP channel):
| VSTATUS VAPI_CreateConnection | ( | IN DEVID | DevId, | |
| IN CONNID | ConnId, | |||
| IN EConnType | eConnType, | |||
| IN U16 | usTdmTimeSlot, | |||
| IN U8 | ucAU_Law, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
This API creates a Comcerto device channel.
This channel is set up as g.711 codec, and packets disabled if the channel type is VoIP.
This channel is set up as UDPTL, and packets disabled if the channel type is FoIP.
The channel is in the state to be ready to generate and detect tones on the TDM side (if VoIP).
This is known "as signaling" state or TDM Active Operation Mode.
VCEOPT Packet generation will be disabled and VOPENA enabled.
The default parameters are defined by VAPI library.
If user wants to override them, the VAPI_PassThru() can be used to issue the commands with required parameters.
The user cannot control the set of MSP commands to be issued at the time of connection creation.
Note 1: Some configurations command have to be sent when the channel is Inactive (i.e SRTP, RTCP configuration).
In this case the command VAPI_SetConnectionState() has to be called before proceeding with these kind of commands.
Note 2: When VAPI_CreateConnection() is called in ASYNC mode, the internal VAPI resources for the connection
are allocated only after getting a successful response to SUPVSR_CREATE_CHNL Comcerto command.
The application must not send any other command on that connection till the callback returns success for that connection id.
If the application sends a command before completion callback of VAPI_CreateConnection(), it will get an error response (Invalid Connection Id) as no resources exist for that particular connection ID in VAPI.
So, user should consider waiting for the completion callback to VAPI_CreateConnection before sending other commands on that Connection.
Note 3: The VAPI_CreateConnection() is divided in 2 main steps:
Note 4: In case that the VAPI_InitDevice() function has not been previously issued,
VAPI_CreateConnection() returns VAPI_ERR_DEVICE_NOT_INITIALIZED
| Inputs-Outputs | |
| DevId | The device on which connection is to be created. |
| ConnId | The connection ID is specified by the user application. The connection ID is assumed unique across all devices and channels. The VAPI library keeps track of the connection resource mapped by the user-specified connection ID. The VAPI library looks up the device ID mapped to the connection ID and passes that down to GTL layer |
| eConnType | Specifies the type of channel (VoIP, VoATM, T38, etc). It can have following values:
|
| usTdmTimeSlot | TDM timeslot for the new channel. The TS number must be in a valid range according the TDM parameters. |
| ucAU_Law | TDM side coding law to be used (A_LAW=0 or U_LAW=1). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this connection this event callback will be called |
Returns:
Usage:
/* Blocking mode example */ ... status = VAPI_CreateConnection(DevID, my_connection_id, eVOIP, my_timeslot, U_LAW, NULL, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... /* Asynchronous mode example */ ... void create_endpoint(int endpoint_id, int endpoint_state) { int result; SRequest request; request.uiReqId = endpoint_state; request.pfnIoCompCallback = &comcerto_response_handler; result = VAPI_CreateConnection(device_id, endpoint_id, eVOIP, /* type 2*/ endpoint_id, /* use the endpoint id as timeslot */ U_LAW, &request, NULL); switch (result) { case VAPI_ERR_PENDING /* If success go ahead */ break; default: vapi_error_handler(result); break; } ...
Commands: Comcerto commands sent depends on channel type required:
/*============================================================================\n * This example show how to change the default VAPI configuration defined in the * without modifying the VAPI source code SVAPIConfig structure (vapi_config.c,h) * * To get VAPI overwriting the default parameters the application must register the * QueryVapiDefaultsEnumerate before calling VAPI_Init() * * in this example not all configurations are changed but only the DTMF option and the VOPENA operation. * ============================================================================*/ void main() { ... /* registering a customized configuration */ pfnUsrQueryVapiDefaultsEnumerate = set_default_config; ... result = VAPI_Init(); if (result != SUCCESS) return result; } VSTATUS set_default_config(IN OUT SVAPIConfig * default_config) { if (default_config == NULL) return VAPI_ERR_NULL_POINTER_PASSED; /* The default values are set in the DMGR_SetVoIPDefaults() function */ /* change the default VAPI DTMF options (default is VOIP_DTMFOPT_REMOVAL_DEFAULT) */ default_config->pstVoIPChnlParams->stDtmfOpt.param_4.bits.removal = VOIP_DTMFOPT_REMOVAL_DISABLE; /* By initiaizing the uVoiceOperation to VOIP_VOPENA_MODE_DISABLE the VAPI_CreateConnection will not issue the VOPENA*/ default_config->pstVoIPChnlParams->stVopena.mode = VOIP_VOPENA_MODE_DISABLE; /* default is VOIP_VOPENA_MODE_ENABLE_RTP*/ /* This is the default PT seting for IFP codec. IFP is used by FoIP channel type, PT is assigned while VAPI_SwitchToT38() */ default_config->pstVoIPChnlParams->ucAudioPt[eIFP] = 0x62; return SUCCESS; }
Description:
Stops voice processing and destroys the channel associated with the connection ID
It also removes all the resources associated with the channel & the channel from the channel list.
| Inputs-Outputs | |
| ConnId | The identifier of connection that is to be destroyedr |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* Blocking mode example */ ... status = VAPI_DestroyConnection(my_connection_id, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... /* Asynchronous mode example */ ... void destroy_endpoint(int endpoint_id, int endpoint_state) { int result; SRequest request; request.uiReqId = endpoint_state; request.pfnIoCompCallback = &comcerto_response_handler; result = VAPI_DestroyConnection(endpoint_id, &request); switch (result) { case VAPI_ERR_PENDING /* If success go ahead */ break; default: vapi_error_handler(result); break; } ...
Commands:
Description:
Re-initializes the device's Echo Canceller.
This is to allow the user application to tell the device to retrain the EC
if the same connection is used to connect to another far-end party.
| Inputs-Outputs | |
| ConnId | Connection on which the Echo Canceller has to be reset. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
... void comcerto_response_handler(U32 connection_id, U8 command_level, S32 result, void *response_data, U32 data_length, U32 request_id) { printf("Response received on endpoint id %d, request id = 0x%04x", connection_id, request_id); if (result != SUCCESS) { print("Endpoint %d error %d", connection_id, result); /* handle the error */ vapi_error_handler(connection_id, request_id, result); } switch (request_id) { case ECHOCAN_SEND: /* mark the received response for this endpoint */ endpoints[connection_id].response_received |= ECHOCAN_SEND_MASK; break; ... } ... /* create a VoIP connection (id 0), on time slot 0 in blocking mode */ status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL); if (status != SUCCESS) return status; ... ... /* set a specific request ID for the echocan*/ request.uiReqId = ECHOCAN_SEND; /* the callback function is comcerto_response_handler*/ request.pfnIoCompCallback = &comcerto_response_handler; /* For connection 0, reset the echo canceller in non blocking mode*/ status = VAPI_EchoCancellerReset(0, &request); if (status != VAPI_ERR_PENDING) return status; ...
Commands:
| VSTATUS VAPI_EnableCIDDetection | ( | IN CONNID | ConnId, | |
| IN ECountryCode | eCountryCode, | |||
| IN U8 | ucEnableType, | |||
| IN SRequest * | pstRequest | |||
| ) |
THIS API IS OBSOLETE.
IT IS KEPT FOR NOW FOR BACKWARD COMPATIBILITY BUT MAY BE REMOVED IN A FUTURE VAPI VERSION
Description:
Enables the detection of Type I and Type II Caller ID signals from the CO over voice channel.
The VAPI library configures the Caller ID Detection parameters according to country code settings.
Note: This function will return VAPI_ERR_SPU_FEATURE_NOT_ENABLED if SPU feature is not enabled.
This feature is enabled through the VAPI_InitDevice() function.
| Inputs-Outputs | |
| ConnId | Connection on which CallerID Detection is to be done. |
| eCountryCode | Country code. |
| ucEnableType | Type of Caller ID to be detected:
|
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
...
/* Enable both OFFHOOK/ONHOOK Caller ID detection on connection 0, using eUSA country parameters */
status = VAPI_EnableCIDDetection (my_connection_id, eUSA, 2, NULL)
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_Loopback | ( | IN CONNID | ConnId1, | |
| IN CONNID | ConnId2, | |||
| IN ELoopbackType | eLoopback, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API creates and removes single channel and inter-channel loop-backs.
Loopback created of a particular type should be removed by using removal
eLoopbackType (eREMOVE_XXX) of for the same type.
| Inputs-Outputs | |
| ConnId1 | Connection id on which loopback will be done. |
| ConnId2 | Second connection in case this is an inter-connection loopback (else not relevant). |
| eLoopback | Type of loopback requested. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* create a VoIP connection (id 1), on time slot 1 in blocking mode */
status = VAPI_CreateConnection(device_id, 1, eVOIP, 1, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* Enable TDM hairpin loopback between conenction 0 & 1 in blocking mode*/
status = VAPI_Loopback(0, 1, eTHC, NULL);
if (status != SUCCESS)
{
printf("Enable THC error %d", status);
return status;
}
...
...
/* Disable a TDM hairpin loopback between connection 0 & 1*/
status = VAPI_Loopback(0, 1, eREMOVE_THC_LOOPBACK, NULL);
if (status != SUCCESS)
{
printf("Disable THC error %d", status);
return status;
}
..
Commands:
| VSTATUS VAPI_ModifyConnection | ( | IN CONNID | ConnId, | |
| IN U16 | usModifyNum, | |||
| IN SModifyConnectionInfo * | pstModifyConnectionInfo, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API changes the current connection configuration for the passed function code with the passed parameters.
Depending on the number of parameters the VAPI_ModifyConnection() handler must:
| Inputs-Outputs | |
| ConnId | The connection ID is specified by the user application. A connection with the specified ID must have been previously created with VAPI_CreateConnection() or VAPI_AllocateConnection(). The VAPI library keeps track of the connection resource mapped by the user-specified connection ID. The VAPI library looks up the device ID mapped to the connection ID and passes that down to GTL layer . |
| usModifyNum | Specifies the number of the parameters to be modified (number of element in the pstModifyConnectionInfo array) |
| pstModifyConnectionInfo | Array of SModifyConnectionInfo. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
VSTATUS status;
U16 timeslot = 0;
U16 connection_id = 0;
SModifyConnectionInfo stModConInfo[2];
status = VAPI_AllocateConnection(device_id, connection_id, eVOIP, eNarrowBand, 1, ×lot, NULL, NULL);
if (status != SUCCESS)
return -1
/*Set the delay max to 100*/
stModConInfo[0].usFunctionCode = FC_VOIP_JBOPT;
stModConInfo[0].usParam = 2;
stModConInfo[0].ucfield_shift = 0;
stModConInfo[0].ucfield_width = 16;
stModConInfo[0].usValue = 100;
/*Change the EC tail length to 40ms */
stModConInfo[1].usFunctionCode = FC_VOIP_ECHOCAN;
stModConInfo[1].usParam = 1;
stModConInfo[1].ucfield_shift = 0;
stModConInfo[1].ucfield_width = 4;
stModConInfo[1].usValue = 0x04;
status = VAPI_ModifyConnection(connection_id, 2, stModConInfo, NULL);
if (status != SUCCESS)
return -1;
status = VAPI_DestroyConnection(connection_id, NULL);
if (status != SUCCESS)
return -1;
...
Commands:
| VSTATUS VAPI_PlayCid | ( | IN CONNID | ConnId, | |
| IN SCallerIdInfo * | pstCidInfo, | |||
| IN SRequest * | pstRequest | |||
| ) |
This API replaces the VAPI_StartCallerId() API
Description:
Sends the Caller ID message string for the specified connection.
The VAPI library configures the proper Caller ID parameters according the settings previously configured by the VAPI_SetCidGenInfo() API.
The caller ID can transmit call messages or notification messages such as:
The SDMF provides the caller's telephone number, the date and time of the call.
The MDMF in addition to the information provided by SDMF format, can also provide the directory listed name for the particular number
The pucMsgStr buffer of the pstCidInfo structure must be filled by the application with a valid SDMF or MDMF caller id parameters.
The main Caller ID parameters for MDMF format are described below:
Parameter Types Type Value Length Name 0x01 8 Date and Time 0x02 20 max Calling Line Identity (CLI) 0x04 1 Reason for absence of CLI 0x07 20 max Calling Party Name (CPN) 0x08 1 Reason for absence of CPN 0x11 1 Call type 0x12 20 First Called Line Identity (in case of forwarded call) 0x15 1 Type of Forwarded call (in case of forwarded call)
Date and Time Parameter Format Byte Num Contents 1 0x01 Type Date 2 0x08 Length 3,4 Month 5,6 Day 7,8 Hours 9,10 Minutes
CLI Parameter Format Byte Num Contents 1 0x02 Type CLI 2 n length 3 Digit 1 4 Digit 2 ... ... n+2 Digit n
Reason of Absence of CLI Parameter Format Byte Num Contents 1 0x04 Type Reason for absence of CLI 2 0x01 Length 3 'O' (0x4f) Number unavailable 'P' (0x50)Private
Calling Party Name Format Byte Num Contents 1 0x07 Type Calling Party Name (CPN) 2 n Length 3 Char 1 4 Char 2 ... ... n+2 Char n
Reason of Absence of Calling Party Name Format Byte Num Contents 1 0x08 Type Reason for absence of CPN 2 0x01 Length 3 'O' (0x4f) Number unavailable 'P' (0x50)Private
Call Type Parameter Format Byte Num Contents 1 0x11 Type Call type 2 0x01 Length 3 0x01 Voice Call 0x02 CLI Ring Back when free call 0x03 Calling Name Delivery 0x81 Message Waiting Call
First Called Line Identity Parameter Format Byte Num Contents 1 0x12 Type First Called Line Identity 2 n Length 3 Digit 1 4 Digit 2 ... ... n+2 Digit n
Type of Forwarded Call Parameter Format Byte Num Contents 1 0x15 Type of Forwarded call 2 0x01 Length 3 0x00 Unavailable or unknown call type 0x01 Forwarded call on busy 0x02 Forwarded call on no reply 0x03 Unconditional forwarded call 0x04 Deflected call (after alerting) 0x05 Deflected call (immediate) 0x06 Forwarded call on inability to reach mobile subscriber
The main Caller ID parameters for Notification messages format are described below:
Parameter Types Type Value Length Name 0x01 8 Date and Time 0x02 18 max Calling Party Number 0x07 20 max Calling Party Name 0x0b 1 Action (VMWI)
VMWI Type Parameter Format Byte Num Contents 1 0x11 Type Call type 2 0x01 Length 3 0x00 Disable 0xFF Enable
| Inputs-Outputs | |
| ConnId | Connection id on which the CID has to be generated. |
| pstCidInfo | Pointer to Caller ID structure. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* Caller ID clip message*/ /* this is a static clip message. In a real case the information are dynamically updated */ /*Date: Feb/13th Time 08:51 Number: 1-949-555-1212 Name: John Smith*/ U8 mdmf_clip_msg[24] = { 0x80, /*Type MDMF*/ 0x01, 0x08, /*Date, 8 bytes*/ '0', '2', '1', '3', '0', '8', '5', '1', /*date 02-13 time 08:51*/ 0x02, 0x0B, /*Calling Line Identity (CLI), 11 bytes */ '1', '9', '4', '9', '5', '5', '5', '1', '2', '1', '2', /*number 1-949-555-1212*/ 0x07, 0x0B, /* Type Calling Party Name (CPN), 11 bytes */ 'J', 'o', 'h', 'n', ' ', 'S', 'm', 'i', 't', 'h', ' ' /*John Smith*/ }; /*Date: Feb/6th Time 12:01 Number: 800-123-4567*/ U8 sdmf_clip_msg[19] = { 0x04, /*Type SDMF*/ 0x30, 0x32, 0x30, 0x36, 0x31, 0x32, 0x30, 0x31, /* Date: 02-06 time 12:01 */ 0x38, 0x30, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37 /*Number: 800-123-4567 */ }; ... /* create a VoIP connection (id 0), on time slot 0 in blocking mode */ status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL); if (status != SUCCESS) return status; ... SCallerIdInfo CallerIdData = { .MsgLen = sizeof(mdmf_clip_msg), .pucMsgStr = mdmf_clip_msg, .bIsOnHook = True, /*Generate OnHook Caller ID*/ .ucModulType = 1 /* V23 */ }; /* Generate the MDMF message*/ status = VAPI_PlayCid(0, &CallerIdData, NULL); if (status != SUCCESS) return status; ... SCallerIdInfo CallerIdData = { .MsgLen = sizeof(sdmf_clip_msg), .pucMsgStr = sdmf_clip_msg, .bIsOnHook = True, /*Generate OnHook Caller ID*/ .ucModulType = 1 /* V23 */ }; /* Generate the SDMF message*/ status = VAPI_PlayCid(0, &CallerIdData, NULL); if (status != SUCCESS) return status; ...
Commands:
| VSTATUS VAPI_PlayTone | ( | IN CONNID | ConnId, | |
| EToneId | eToneId, | |||
| EToneDir | eToneDir, | |||
| SPlayToneOpt * | pstPlayToneOpt, | |||
| U16 | usParamNum, | |||
| IN SRequest * | pstRequest, | |||
| ... | ||||
| ) |
Description:
Start to generate a tone for the specified connection.
The tone could be either dual or quad frequency.
usParamNum defines the number of additional parameters.
It could be 2 - pass start and limit timestamps parameters as follows:
{Start Timestamp, Limit Timestamp} or 0 - no timestamps.
Repeated invocations of this function will cease the previous tone and start a new tone.
| Inputs-Outputs | |
| ConnId | Connection id on which the tone has to be played. |
| eToneId | Specifies the type of tone. |
| eToneDir | Specifies the direction to play the tone to (TDM, IP, Both). |
| pstPlayToneOpt | Tone option (only for Dual tone). If it's NULL apply the MSP API default values: usMixModeOff = 0x0; usMixModeOn = 0x0; usProtGen = 0x0; usTimestampCtrl = 0x0; Else use passed Play Tone Options. |
| usParamNum | The additional parameters number (only for dual tone). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| ... | Additional parameters. |
Returns:
Usage:
...
SPlayToneOpt stPlayToneOpt;
stPlayToneOpt.usMixModeOff = 1;
stPlayToneOpt.usMixModeOn = 1;
/* create a VoIP on connection_id), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, connection_id,
eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* play eCUSTOM_3 tone to TDM side, use default tone options from vapi_default.c*/
status = VAPI_PlayTone(connection_id, eCUSTOM_3, eTDM, &stPlayToneOpt, 0, NULL);
if (status != SUCCESS)
return status;
...
...
/* Stop the pending tone on connection_id in 1 second */
status = VAPI_StopTone(connection_id, 1000, NULL);
if (status != SUCCESS)
return status;
...
usStartTimestamp = 10;
usStopTimestamp = 10;
/* play eCUSTOM_4 tone to TDM side, use default tone options from vapi_default.c*/
status = VAPI_PlayTone(connection_id, eCUSTOM_4, eTDM, &stPlayToneOpt, 2, NULL, usStartTimestamp, usStopTimestamp);
if (status != SUCCESS)
return status;
...
...
/* Stop the pending tone on connection_id in 1 second */
status = VAPI_StopTone(connection_id, 1000, NULL);
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_RecoverConnection | ( | IN DEVID | DevId, | |
| IN CONNID | ConnId, | |||
| IN EConnType | eConnType, | |||
| IN U16 | usTdmTimeSlot, | |||
| IN U16 | usRecoverOption, | |||
| IN SRequest * | pstRequest, | |||
| IN PFNEventCallback | pfnEventCallback | |||
| ) |
Description:
This API is intended to recover a Comcerto device channel when the system is in a unsynchronized status.
Typically it may happen when Comcerto channels are up and running and the host applications stops.
In this case to be able to restart the application and have a chance to retrieve the previous status,
the application can use this API.
The reference numbers on the host application side are the Connection ID and the timeslot to use for this connection.
On VAPI side the reference numbers are the Connection ID and the Comcerto channel ID.
When VAPI_CreateConnection is used it makes a mapping between :
the Timeslot ID <-> Connection ID <-> Channel ID.
On erronenous situation this mapping can be lost. Therefore this API can be used to rebuild it mapping
VAPI_RecoverConnection() will return:
Note 1: Once the Connection is recovered, it is the responsability of the application to reconfigure the connection.
Note 2: Notes: This API requires the firmware to support the SUPERVISOR_TIMESLOT query command
| Inputs-Outputs | |
| DevId | The device on which connection is to be recovered |
| ConnId | The connection ID is specified by the user application. The connection ID is assumed unique across all devices and channels. The VAPI library keeps track of the connection resource mapped by the user-specified connection ID. The VAPI library looks up the device ID mapped to the connection ID and passes that down to GTL layer |
| eConnType | Specifies the type of channel (VoIP, VoATM, T38, etc). It can have following values:
|
| ConnId | The connection ID is specified by the user application. The connection ID is assumed unique across all devices and channels. The VAPI library keeps track of the connection resource mapped by the user-specified connection ID. The VAPI library looks up the device ID mapped to the connection ID and passes that down to GTL layer |
| usTdmTimeSlot | TDM timeslot of the channel to be recovered. The TS number must be in a valid range according the TDM parameters.. |
| usRecoverOption | this parameter is intended for future use. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
| pfnEventCallback | Connection Level event callback. When events will be received for this connection this event callback will be called |
Returns:
Usage:
...
/* Create a connection in sync mode */
status = VAPI_CreateConnection(DevID, my_connection_id, eVOIP, my_timeslot, U_LAW, NULL, NULL);
switch (status)
{
case SUCCESS: /* If success go ahead */
break;
/* If the error is timeslot in use (0xFFBD) try to recover */
case ERR_TDMDRV_INVTS:
/* recover some data: F/W MR number, Eth MAC, dev IP, etc.*/
status = VAPI_InitDevice(DevID, VAPI_DEV_OPMODE_RECOVER, VAPI_DEV_PROF_DEFAULT, NULL, NULL);
status = VAPI_RecoverConnection(DevID, my_connection_id, eVOIP, 10, NULL, NULL);
/* if the connection is recovered go ahead else call the generic error handler */
if (status == SUCCESS)
{
/* in this case we don't know what is the state of the connection
so we set it in a default configuration */
default_configuration(my_connection_id); /* this is a customer function*/
break;
}
/* destroy the connection and fall through to the default case */
else if (status == VAPI_ERR_RECOVER_WRONG_TYPE)
VAPI_DestroyConnection(my_connection_id, NULL);
/* in all other error case (i.e VAPI_ERR_RECOVER_TIMESLOT)
we fall through to the default error case */
default:
vapi_error_handler(status);
break;
}
...
Commands: Comcerto commands sent depends on channel type required:
| VSTATUS VAPI_SendNteEvent | ( | IN CONNID | ConnId, | |
| IN U32 | uiNtePyLd, | |||
| IN U16 | usOverRideBitField, | |||
| IN U16 | usRedundancyInterval, | |||
| IN U32 | uiSsrc, | |||
| IN U16 | usPyLdType, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Sends a non-DTMF NTE RTP packet.
The usOverRideBitField sets the override options for SSRC, redundancy interval, and payload type.
| Inputs-Outputs | |
| ConnId | Connection on which the NTE packet has to be sent. |
| uiNtePyLd | Payload of the NTE packet. |
| usOverRideBitField | The host can optionally override the redundancy interval time, disable redundancy, override the SSRC, or override the payload type. |
| uiSsrc | SSRC value that will override older SSRC. |
| usPyLdType | Payload_type for DTMF in RTP that will override the previous setting. |
| usRedundancyInterval | The redundancy interval value that will override the previous value. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
/* Send NTE event with payload = 0x20 to remote side*/
status = VAPI_SendNteEvent(0, 0x20,0x00, 0x00, 0x00, 0x00, NULL);
if (status != SUCCESS)
{
printf("Send NTE error %d", status);
return status;
}
..
Commands:
| VSTATUS VAPI_SetCidDetection | ( | IN CONNID | ConnId, | |
| IN SCidDetCtrl * | pstCidDetCtrl, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API replaces the VAPI_EnableCIDDetection() API
Enable or disable the detection of Type I or Type II Caller ID signals from the CO over voice channel.
The VAPI library configures the Caller ID Detection parameters according the configuration previously set by the VAPI_SetCidDetInfo() function.
Note: This function will return VAPI_ERR_SPU_FEATURE_NOT_ENABLED if SPU feature is not enabled.
This feature is enabled through the VAPI_InitDevice() function.
| Inputs-Outputs | |
| ConnId | Connection on which CallerID Detection is to be done. |
| pstCidDetCtrl | Pointer to Caller Id detection control structure. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
SCidDetCtrl CidDetectionCtrl = {
.usCidEnable = 1, /* enable */
.usHookStatus = 2 /* both on & off hook detection*/
};
...
...
/* Enable both OFFHOOK/ONHOOK Caller ID detection on connection 0 */
status = VAPI_SetCidDetection (0, &CidDetectionCtrl, NULL);
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_SetCodecType | ( | IN CONNID | ConnId, | |
| IN ECodecIndex | eCodecIndex, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Sets the codec type for the specified connection.
The codec parameter is not same as Payload type (PT) value.
The VAPI library defines a set of acceptable codec types as an enumerated value.
VAPI internally maintains the codec types valid for a particular device type.
If the codec is not valid for that device type and error is returned to the user.
| Inputs-Outputs | |
| ConnId | Connection on which the Codec has to be set. |
| eCodecIndex | Codec index. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
...
/* Set codec type to G726 32 on connection 0 */
status = VAPI_SetCodecType(0, eG726_32_ID, NULL);
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_SetConnectionState | ( | IN CONNID | ConnId, | |
| IN EConnOpMode | eOpMode, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Changes the connection operation mode accordingly the eOpMode parameter (this API is applicable to conference participant too).
It could be:
By setting the connection to Inactive:
The stream of packets from the TDM bus is not be decoded
No packet is sent to the transport interface.
By setting the connection to TDM Active:
The TDM tone detection is active and tones can be generated to the TDM
By setting the connection to Active:
The stream of packets from the TDM bus will be decoded into PCM signals on the line,
and PCM signals from the line will be encoded into a stream of packets.
Internally the API issues VoIP_VCEOPT (with packet generation enabled) and VoIP_VOPENA.
If the user application did not configure the connection using VAPI_SetCodecType(), VAPI_SetPacketInterval(),
then the default 20ms g.711 packet type is assumed.
Like for the TDM active mode, the tone detection / generation is active..
The IP header must be set before setting the connection to Active (VAPI_SetConnIpParams()).
| Current mode | New mode | Commands Sent |
| Inactive | TdmActive | VCEOPT with Bit PacketGeneration disable = 1 VOPENA |
| Inactive | Active | VCEOPT with Bit PacketGeneration disable = 0 VOPENA |
| TDM Active | Active | VOPENA |
| Active | TDM Active | VCEOPT with Bit PacketGeneration disable = 1 |
| Active | Inactive | VOPENA Disable |
| TDM Active | Inactive | VOPENA Disable |
| Inputs-Outputs | |
| ConnId | The identifier of connection to which that the processing has to be changed |
| eOpMode | The required Operation Mode. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* Blocking mode example */ ... /* disable the connection */ status = VAPI_SetConnectionState(my_connection_id, eInactive, NULL); \n switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... /* Asynchronous mode example */ ... void enable_endpoint(int endpoint_id, int endpoint_state) { int result; SRequest request; request.uiReqId = endpoint_state; request.pfnIoCompCallback = &comcerto_response_handler; /* Enable packetization and TDM tone detection/generation*/ result = VAPI_SetConnectionState(endpoint_id, eActive, &request); switch (result) { case VAPI_ERR_PENDING /* If success go ahead */ break; default: vapi_error_handler(result); break; } ...
Commands:
| VSTATUS VAPI_SetConnIpParams | ( | IN CONNID | ConnId, | |
| IN SIpParams * | pstIpParams, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Sets the source and destination IP addresses and UDP ports
required to generate complete RTP Encapsulated packets for the specified connection ID.
The source IP address is same as from VAPI_SetDeviceIPAddr().
| Inputs-Outputs | |
| ConnId | Connection on which the IP parameters have to be changed. |
| pstIpParams | Structure for destination and source side IP Addresses and UDP ports. Please note that all the addresses and ports must be provided in Network byte order (Big Endian). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/*IP address used as the IP source for the RTP/UDPTL traffic * This IP address must be unique * On master configuration this IP address must be the same as the one defined for eth0 * This IP addres is assign to the device using VAPI_SetDeviceIPAddr() */ U8 device_ip[4] = { 192, 168, 0, 5 }; int set_ip_udp_parameters(int connection_id, U8 * device_ip, U8 * dst_ip, U16 dst_port) { VSTATUS status; SIpParams ip_parameters; /* Set the device IP to be the scr IP address for the RTP traffic*/ memcpy((void *)&ip_parameters.uiSrcIpAddr, device_ip, 4); /* Set the destination IP */ memcpy((void *)&ip_parameters.uiDestIpAddr, dst_ip, 4); /* The the Source UDP port (take a base UDP port and add the connection ID which is unique) */ ip_parameters.usSrcUdpPort = htons(DEFAULT_UDP_PORT + connection_id); /* The the Destinqtion UDP port (this has been get from a IP signalling negotiation) */ ip_parameters.usDestUdpPort = htons(dst_port); /*RTP defined in comcerto_ip_device_level_api.h */ ip_parameters.ucIPServiceId = SET_IP_HDR_CHANNEL_SERVICEID_DEFAULTPKT; status = VAPI_SetConnIpParams(connection_id, &ip_parameters, NULL); return status; }
Commands:
Description:
This API programs the VLAN ID in the ethernet header of the connection.
If this API is not issued to the connection, it heritates the VLAN tag of the device (if any)
This API doesn't send any command to the device. It just set an internal variable.
It required to issue this API before the VAPI_SetEthMac() to get the VLAN Id taken in account.
| Inputs-Outputs | |
| ConnId | Connection ID. |
| usVlanId | VLAN ID. If VLAN=0, no VLAN set. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
usage
... /* This MAC address will be used in the IP/UDP/RTP (UDPTL) frame as the source MAC address. * This MAC address must be unique. * On master configuration this MAC address must be the same as the one defined for eth0 */ U8 device_mac[6] = { 0x00, 0x50, 0xFC, 0xC3, 0xBD, 0xE2 }; /* 00:50:fc:c3:bd:e2*/ /* This can be the MAC address of an equipment on the subnet having IP forward capability * (PC, Router, etc). * This destination MAC is global for the device and all channnels, unless * it is overwritten at channel level by the SET_ETH_HDR_CHAN (VAPI_SetEthMac channel level call)*/ U8 default_dest_mac[6] = { 0x00, 0x11, 0xD8, 0xE7, 0xA5, 0x52 }; /*00:11:d8:e7:a5:52*/ /* This command set the VLAN ID at device level */ /* it must be issued before VAPI_SetEthMac() */ result = VAPI_SetDeviceVlan(device_id, 0x0100,NULL); /* This command set the Device MAC address */ status = VAPI_SetEthMac(device_id, CMD_LEVEL_DEVICE, device_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; } ... U8 connection_mac[6]; /* retrieve the MAC address to be assigned to the connection (i.e from a SIP negotiation)*/ get_mac_address(connection_mac); /*This command set the VLAN ID at connection level */ /* it musr be issued before VAPI_SetEthMac()*/ result = VAPI_SetConnVlan(connection_id, 0x0101,NULL); /*This command set the Connection MAC address */ status = VAPI_SetEthMac(connection_id, CMD_LEVEL_CONN, connection_mac, default_dest_mac, NULL); switch (status) { case SUCCESS: /* If success go ahead */ break; default: vapi_error_handler(status); break; }
Commands: List of Comcerto commands sent:
Description:
Sets the packet interval in ms for the connection.
| Inputs-Outputs | |
| ConnId | Connection on which the packet size has to be set. |
| ucMilliSec | Packet interval in milliseconds. The library checks against incompatible codec and packet interval combinations (e.g. 20ms for g.723) |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
...
/* Set packet interval to 10ms connection 0 */
status = VAPI_SetPacketInterval (0, 10, NULL);
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_SetPayloadType | ( | IN CONNID | ConnId, | |
| IN ECodecType | eCodec, | |||
| IN U8 | ucPlTypVal, | |||
| IN EDirection | eDir, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Configures the payload type for each codec.
Each codec has a default PT value that can be overridden with this function.
Repeated invocations of this function are required to override more than one payload type.
VAPI internally maintains the codec types valid for a particular device type.
If the codec is not valid for that device type and error is returned to the user.
For Video Media sub layer use EVideoCodecIndex for codec ID.
| Inputs-Outputs | |
| ConnId | Connection on which the payload type has to be set. |
| ucPlTypVal | The payload type value to be set. |
| eCodec | codec ID |
| eDir | The direction field can be (eTx, eRx, eBoth) to support asymmetrical payload types. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
...
/* For connection 0, set he payload type for the codec G726 32 to 0x44 in both RX and Tx direction*/
status = VAPI_SetPayloadType(0, eG726_32, 0x44, eBoth, NULL);
if (status != SUCCESS)
return status;
...
Commands:
Description:
Sets the RTP SSRC header field. This API is only valid for RTP-encoded connections.
If the connection is not active the SSRC value is stored in the VAPI variable and used on subsequent VOPENA command.
If the connection is active the SSRC value is take in account immediately.
| Inputs-Outputs | |
| ConnId | Connection on which the SSRC has to be changed. |
| uiSsrcVal | New SSRC value. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
/* Set the SSRC (Synchronization Source) for the connection 0 to 0xaabbccdd */
status = VAPI_SetRtpSsrcHeader (0, 0xaabbccdd, NULL);
{
printf("Send SSRC error %d", status);
return status;
}
..
Commands:
THIS API IS OBSOLETE.
IT IS KEPT FOR NOW FOR BACKWARD COMPATIBILITY BUT MAY BE REMOVED IN A FUTURE VAPI VERSION
Description:
Sends the Caller ID message string for the specified connection.
The VAPI library configures the proper Caller ID parameters according to country code settings.
| Inputs-Outputs | |
| ConnId | Connection id on which the CID has to be generated. |
| pstCidInfo | Pointer to Caller ID structure. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* Caller ID clip message*/ /* this is a static clip message. clip_msg[0] - SDMF/MDMF format clip_msg[1] - PARAM TYPE (Phone number, CID name, date, etc. according to MDMF/SDMF format) clip_msg[2] - PARAM LENGTH clip_msg[3] - PARAM DATA (e.g. phone number (first byte )) In a real case the information are dynamically updated */ U8 clip_msg[24] = { 0x80, 0x01, 0x08, 0x31, 0x31, 0x30, 0x38, 0x32, 0x30, 0x30, 0x30, 0x02, 0x07, 0x39, 0x34, 0x34, 0x32, 0x38, 0x32, 0x30, 0x08, 0x01, 0x4F }; ... /* create a VoIP connection (id 0), on time slot 0 in blocking mode */ status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL); if (status != SUCCESS) return status; ... ... /* Start a ONHOOK CALLER ID generation on connection 0, using eUSA country parameters */ #if VAPI_RELEASE >= (VAPI_VERSION(2, 9, 0)) /* from vapi 2.9.0 VAPI_StartCallerId has a new prototype*/ CidInfo CallerIdData; CallerIdData.MsgLen = sizeof(clip_msg); CallerIdData.pucMsgStr = clip_msg; CallerIdData.bIsOnHook = 1; CallerIdData.eCountryCode = eUSA; status = VAPI_StartCallerId(0, &CallerIdData, NULL); #else status = VAPI_StartCallerId(0, clip_msg, 1, eUSA, NULL); #endif if (status != SUCCESS) return status; ... ... /* Stop a pending CALLER ID on connection 0 */ status = VAPI_StopCallerId (0, NULL); if (status != SUCCESS) return status; ...
Commands:
| VSTATUS VAPI_StartTone | ( | IN CONNID | ConnId, | |
| U8 | ucDir, | |||
| EToneId | eToneId, | |||
| ECountryCode | eCountryCode, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Start to generate a tone to the TDM interface for the specified connection.
The connection may be in either signaling state or packet enabled state.
Repeated invocations of this function will cease the previous tone and start a new tone.
NOTE:
There supported tones are enumerated in EToneId. If user wants to add more tones the user should modify CFG_MAX_TONES in vapi.h.
Correspondingly user will need to add elements in SCountryInfo::stToneGenParams for newly defined tones.
Also, user may have to add enumerations for new tones in the EToneId structure.
The new enumerations should be added after eDTMFTONE_HASH and before eDUMMYTONE.
The parameter eToneId is used to calculate index to array SCountryInfo:: stToneGenParams.
The calculation is done as: INDEX = eToneId - eDTMFTONE_HASH - 1.
Alternatively user can completely override the country specific settings done using
pfnUsrQueryVapiDefaultsEnumerate API. With this method information for more countries can be added.
| Inputs-Outputs | |
| ConnId | Connection id on which the tone has to be started. |
| ucDir | Specifies direction, whether to generate tone to TDM (0) or packet interface (1). |
| eToneId | Specifies the type of tone. |
| eCountryCode | The country code parameter specifies the localized tone setting. The VAPI library by default only supports a small set of country codes. The country defaults can be by overrided by assigning their own function pointer to pfnUsrQueryVapiDefaultsEnumerate which is exported by VAPI. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* Start a dialtone on connection 0 to TDM side, using eUSA country parameters */
status = VAPI_StartTone(0, 0, eDIALTONE, eUSA, NULL);
if (status != SUCCESS)
return status;
...
...
/* Stop the pending tone on connection 0 on both side (TDM & IP) in 1 second */
status = VAPI_StopTone(0, 1000, 0, NULL);
if (status != SUCCESS)
return status;
...
Commands:
Description:
Stops the Caller ID generation for the specified connection.
| Inputs-Outputs | |
| ConnId | Connection id on which the CID has to be stoped. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
/* Caller ID clip message*/ /* this is a static clip message. clip_msg[0] - SDMF/MDMF format clip_msg[1] - PARAM TYPE (Phone number, CID name, date, etc. according to MDMF/SDMF format) clip_msg[2] - PARAM LENGTH clip_msg[3] - PARAM DATA (e.g. phone number (first byte )) In a real case the information are dynamically updated */ U8 clip_msg[24] = { 0x80, 0x01, 0x08, 0x31, 0x31, 0x30, 0x38, 0x32, 0x30, 0x30, 0x30, 0x02, 0x07, 0x39, 0x34, 0x34, 0x32, 0x38, 0x32, 0x30, 0x08, 0x01, 0x4F }; ... /* create a VoIP connection (id 0), on time slot 0 in blocking mode */ status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL); if (status != SUCCESS) return status; ... ... /* Start a ONHOOK CALLER ID generation on connection 0, using eUSA country parameters */ #if VAPI_RELEASE >= (VAPI_VERSION(2, 9, 0)) /* from vapi 2.9.0 VAPI_StartCallerId has a new prototype*/ CidInfo CallerIdData; CallerIdData.MsgLen = sizeof(clip_msg); CallerIdData.pucMsgStr = clip_msg; CallerIdData.bIsOnHook = 1; CallerIdData.eCountryCode = eUSA; status = VAPI_StartCallerId(0, &CallerIdData, NULL); #else status = VAPI_StartCallerId(0, clip_msg, 1, eUSA, NULL); #endif if (status != SUCCESS) return status; ... ... /* Stop a pending CALLER ID on connection 0 */ status = VAPI_StopCallerId (0, NULL); if (status != SUCCESS) return status; ...
Commands:
| VSTATUS VAPI_StopTone | ( | IN CONNID | ConnId, | |
| IN U16 | usToneDuration, | |||
| IN U16 | usSide, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Stops the last tone generated.
| Inputs-Outputs | |
| ConnId | Connection id on which the tone has to be stopped. |
| usToneDuration | Turn off the tone after usToneDuration time (0 to 65535 ms). |
| usSide | Side on which to stop the tone generation (0=Both, 1=TDM, 2=IP). |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), on time slot 0 in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* Start a dialtone on connection 0 to TDM side, using eUSA country parameters */
status = VAPI_StartTone(0, 0, eDIALTONE, eUSA, NULL);
if (status != SUCCESS)
return status;
...
...
/* Stop the pending tone on connection 0 on both side (TDM & IP) in 1 second */
status = VAPI_StopTone(0, 1000, 0, NULL);
if (status != SUCCESS)
return status;
...
Commands:
| VSTATUS VAPI_SwitchToT38 | ( | IN CONNID | ConnId, | |
| IN SFaxConfigOpts * | pstFaxConfigOpts, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
This API is used to switch the channel to FoIP mode under the control of the application.
Alternatively the application can set the fax options to enable an automatic switchover from VAPI.
The transport parameters (MAC address, IP/UDP) are the same as the previous VoIP connection The application could use the VAPI_SetConnIpParams() and VAPI_SetEthMac() to reconfigure them if required.
the T.38 port info and then call VAPI_EnableConnection() to enable packet generation.
NOTE: The connection is not enabled after the switch.
This gives the opportunity to send other configuration commands before re-enabling the connection.
| Inputs-Outputs | |
| ConnId | Connection to be switched in T38 mode. |
| pstFaxConfigOpts | Pointer to fax options structure which gives the fax switchover options to be used while switching to FoIP mode. If NULL VAPI uses the fax options already configured on the connection or the default values if no options have been explicitly configured. |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* define a fax configuration structure*/
SFaxConfigOpts fax_configuration;
/* Set the convenient parameters for this connection */
fax_configuration.bUseExistingOpts = False;
fax_configuration.ucFaxTxLevel = 8;
fax_configuration.bEnableFaxAutoSwitch = False;
fax_configuration.usSwitchoverEventMask = 0;
fax_configuration.stFaxOpts.ucT38PktLossConcealment = 1;
fax_configuration.stFaxOpts.ucECMDisable = 1;
fax_configuration.stFaxOpts.ucFaxDataRedundancyCnt = 3;
fax_configuration.stFaxOpts.ucT30RedundancyCnt = 7;
fax_configuration.stFaxOpts.ucFaxConnSpeedLimit = 6;
fax_configuration.stFaxOpts.ucErrRcvyMethod = 0;
fax_configuration.stFaxOpts.ucTCFProcedure = 0;
fax_configuration.stFaxOpts.ucNumFEC = 0;
fax_configuration.stFaxOpts.ucNumIFPs = 4;
/* While FAX the IFP codec is used. The its PT is not set by VAPI by default.
Thus before switch VoIP channel to FoIP, PT for eIFP should be initialized.*/
result = VAPI_SetPayloadType(endpoint_id, eIFP, 0x62, eBoth, NULL);
if (status != SUCCESS){
printf("VAPI_SetPayloadType error %d", status);
return status;
}
/* Switch the connection 0 to T38 using the fax_configuration parameters */
status = VAPI_SwitchToT38(0, &fax_configuration, NULL);
if (status != SUCCESS){
printf("VAPI_SwitchToT38 error %d", status);
return status;
}
...
Commands: List of Comcerto commands sent: (if any).
| VSTATUS VAPI_TranscodingSession | ( | IN CONNID | ConnId1, | |
| IN CONNID | ConnId2, | |||
| IN STranscodingOption * | pstTranscodingOption, | |||
| IN SRequest * | pstRequest | |||
| ) |
Description:
Sets a transcoding session between 2 existing connections.
| Inputs-Outputs | |
| ConnId1 | Id of the first connection involved in the transcoding session |
| ConnId2 | Id of the second connection involved in the transcoding session |
| TranscodingOption | Start / Stop transcoding, set DSP bypass mode |
| pstRequest | If NULL then the call is in blocking mode (synchronous). |
Returns:
Usage:
...
/* create a VoIP connection (id 0), time slot 0xffff (IP only channel) in blocking mode */
status = VAPI_CreateConnection(device_id, 0, eVOIP, 0xffff, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
/* create a VoIP connection (id 1), time slot 0xffff (IP only channel) in blocking mode */
status = VAPI_CreateConnection(device_id, 1, eVOIP, 0xffff, U_LAW, NULL, NULL);
if (status != SUCCESS)
return status;
...
...
STranscodingOption transcoding_option = {
.bAction = 1, /* Enable transcoding*/
.ucDSPMode = 1, /* Enable DSP bypass mode*/
.ucVirtualTranscoding = 0; /*Not virtual transcoding*/
};
/* Enable a transcoding session between connection 0 & 1 */
status = VAPI_TranscodingSession(0, 1, &transcoding_option, NULL);
if (status != SUCCESS)
return status;
...
...
/* Disable transcoding session between connection 0 & 1 */
transcoding_option.bAction = 0 ;
status = VAPI_TranscodingSession(0, 1, &transcoding_option, NULL);
if (status != SUCCESS)
return status;
...
/* Enable Virtual transcoding session between connection 0 & 1 */
transcoding_option.bAction = 1 ;
transcoding_option.ucDSPMode = 0 ;
transcoding_option.ucVirtualTranscoding = 1 ;
status = VAPI_TranscodingSession(0, 1, &transcoding_option, NULL);
if (status != SUCCESS)
return status;
...
Commands: