Miscellaneous API functions

Functions
char *	VAPI_GetVersion (void)
VSTATUS	VAPI_Init (void *pstDeviceHeaders)
VSTATUS	VAPI_Close (void)
VSTATUS	VAPI_RegisterEventCallback (IN U32 uiID, IN U8 ucLevel, IN PFNEventCallback pfnEventCallback)
VSTATUS	VAPI_PassThru (IN U32 uiID, IN U8 ucLevel, IN SMsg pstMsg, IN SRequest pstRequest, OUT U8 pucBuffer, IN OUT U32 puBufLen)
VSTATUS	VAPI_C2CConnectUP (IN DEVID DevId, IN SC2CConnectOption pstC2CConnectOptions, IN SRequest pstRequest)
VSTATUS	VAPI_SetDebugLevel (U8 ucVapiDebugLevel, U8 ucAppDebugLevel)

typedef VSTATUS(*	PFNUSRQueryVAPIDefaultsEnumerate )(IN OUT SVAPIConfig *pstVAPIConfig)
typedef VSTATUS(*	PFNUSRQueryVAPIDefaultsClose )(void)

Typedef Documentation

typedef VSTATUS(* PFNUSRQueryVAPIDefaultsClose)(void)

Description:
This API may be implemented by the application if application wants to do some cleanup operation for the initializations done in pfnUsrQueryVapiDefaultsEnumerate.
User has to override this global before VAPI_Close() is called.
The function pointed by this global pointer is called from the implementation of VAPI_Close().

Inputs-Outputs
NONE

Returns:

SUCCESS

Commands:

No Comcerto commands sent.

typedef VSTATUS(* PFNUSRQueryVAPIDefaultsEnumerate)(IN OUT SVAPIConfig *pstVAPIConfig)

Description:
This API is implemented by Application to override the default settings done by VAPI.
If application intends to override some/all of the default parameters then it should initialize this global function pointer by its own function before calling VAPI_Init().
By default this global is initialized to NULL. When VAPI_Init() is called by application, VAPI Initializes the SVAPIConfig structure and calls the function pointed to by this global pointer. Inside this function user can override the defaults done by VAPI.
Note that not only the values can be changed, but also the pointers can be changed to point to some other memory location.
This will not cause a memory leak as the pointers inside the SVAPIConfig structure are not pointing to any dynamically allocated memory, they are just pointers to global memory locations.
Typically, users should not opt for overriding the pointers unless they want to change the size of an array, for example adding more countries in the array SVAPIConfig::pastCountryInfo.
Any memory allocated here can be cleaned up in the function pfnUsrDefaultsClose.

Inputs-Outputs
pstVAPIConfig	pointer to global SVAPIConfig VAPI structure defined in vapi_config.h

Returns:

SUCCESS

Usage:

/*============================================================================\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;
}

Commands:

No Comcerto commands sent.

Function Documentation

VSTATUS VAPI_C2CConnectUP	(	IN DEVID	DevId,
		IN SC2CConnectOption *	pstC2CConnectOptions,
		IN SRequest *	pstRequest
	)

Description:
Establish or terminate a VOIP TrFO inter or intra Comcerto connection between 2 existing connections.
This API requires previous extra configurations such as Set_UMA_Params (Function Code 0x8600) or UMA_EventDet (Function Code 0x8601).
Please check the chapter WCDMA Wireless Support or UP Transcoder Free Operation (TrFO) for more detail.

Inputs-Outputs
DevId	Id of the device to send the command to
C2CConnectOptions	C2C connection options
pstRequest	If NULL then the call is in blocking mode (synchronous).

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_LIB_NOT_INITIALIZED
VAPI_ERR_INVALID_CONNID
VAPI_ERR_DEV_IS_NOT_UP
VAPI_ERR_DEVICE_NOT_INITIALIZED
VAPI_ERR_NOMEM
VAPI_ERR_INVALID_CONNID

Usage:

...
        /*Intra Comcerto mode C2C connect UP  */
        CONNID connection_id1 = 1;
        CONNID connection_id2 = 2;
        U16 my_timeslot1 = 1;
        U16 my_timeslot2 = 2;
        VSTATUS status;
        status  = VAPI_AllocateConnection(device_id, connection_id1, eVOIP, eNarrowBand, 1, &my_timeslot1, NULL, NULL); 
        status  = VAPI_AllocateConnection(device_id, connection_id2, eVOIP, eNarrowBand, 1, &my_timeslot2, NULL, NULL); 

        SC2CConnectOption c2c_options;
        memset(&c2c_options, 0, sizeof(SC2CConnectOption));

        c2c_options.bAction = 1;                /* Enable*/
        c2c_options.ucConnType = 0;             /* Intra Comcerto type*/
        c2c_options.ConnA = connection_id1;
        c2c_options.ConnB = connection_id2; 

        status = VAPI_C2CConnectUP(device_id, &c2c_options, NULL);

...

...
        /*Inter Comcerto mode C2C connect UP  */
        CONNID connection_id1 = 1;
        U16 my_timeslot1 = 1;
        VSTATUS status;
        status  = VAPI_AllocateConnection(device_id, connection_id1, eVOIP, eNarrowBand, 1, &my_timeslot1, NULL, NULL); 

        memset(&c2c_options, 0, sizeof(SC2CConnectOption));
        c2c_options.bAction = 1;                /* Enable*/
        c2c_options.ucConnType = 1;             /* Inter Comcerto type*/
        c2c_options.ucInterMode = 1;            /* Inter Comcerto mode HDLC 2 timeslots*/
        c2c_options.ConnA = connection_id1;
        c2c_options.ucRateControl = 0;
        c2c_options.ucTimerInterval = 0;
        /*RFCIs*/
        c2c_options.usRFCIModeGroup1 = 0x0302;
        c2c_options.usRFCIModeGroup2 = 0x0504;
        c2c_options.usRFCIModeGroup3 = 0x0706;
        c2c_options.usRFCIModeGroup4 = 0x0908;
        c2c_options.usRFCIModeGroup5 = 0xffff;
        c2c_options.usRFCIModeGroup6 = 0xffff;

        VAPI_C2CConnectUP(device_id, &c2c_options, NULL);
...

Commands:

FC_C2C_CONNECT_UP

VSTATUS VAPI_Close ( void )

Description:
Releases all resources used for the VAPI library such as memory, timer, etc.
The VAPI will clear internal data structures and shuts down the GTL layer.

Inputs-Outputs
NONE

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_LIB_NOT_INITIALIZED

Commands:

No Comcerto commands sent.

char* VAPI_GetVersion ( void )

Description:
Returns version information in a string format.
The string is similar to "VAPI Library Release 2.4.0, API Version 4.0".
This includes the Library release version that is implementation dependent
The API version that depends on API changes, that is parameter types, etc.
This function uses definitions (in vapi.h):

VAPI_VERSION_MAJOR
VAPI_VERSION_MINOR
VAPI_VERSION_PATCH
VAPI_API_VERSION_MAJOR
VAPI_API_VERSION_MINOR
Some macros are also available to help on version identification:
VAPI_VERSION
VAPI_RELEASE
VAPI_API_VERSION
VAPI_API_RELEASE

Inputs-Outputs
NONE

Returns:
Release string

Usage:
NOTE: VAPI_RELEASE didn't exist before VAPI 2.4.x

/* compilation time usage */
...

#ifdef VAPI_RELEASE
#if VAPI_RELEASE >= (VAPI_VERSION(2, 6, 0))
        /* from vapi 2.6.0 VAPI_BootDevice has a new parameter (IN SHwCfg * pstSHwCfg)*/
        result = VAPI_BootDevice(device_id, firmware_buf, firmware_size, NULL, NULL);
#else
        result = VAPI_BootDevice(device_id, firmware_buf, firmware_size, NULL);
#endif
#endif
...

/* run time usage */
        printf("VAPI version: %s\n",VAPI_GetVersion());

        if (VAPI_RELEASE >= (VAPI_VERSION(2,4,0))
        {
                ...
        }

Commands:

No command sent to the Comcerto

VSTATUS VAPI_Init ( void * pstDeviceHeaders )

Description:
This function initializes the VAPI Library resources.
Before making any other calls to the library, the user must initialize the library by calling this function.
VAPI exports a function pointer pfnUsrQueryVapiDefaultsEnumerate
for the user to customize VAPI defaults.
The user can override VAPI default configuration by using providing a value to this function pointer.

Inputs-Outputs
pstDeviceHeaders	Pointer to list of device configuration structures.

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_UNDEFINED
VAPI_ERR_NOMEM

Commands:

No Comcerto commands sent.

VSTATUS VAPI_PassThru	(	IN U32	uiID,
		IN U8	ucLevel,
		IN SMsg *	pstMsg,
		IN SRequest *	pstRequest,
		OUT U8 *	pucBuffer,
		IN OUT U32 *	puBufLen
	)

Description:
A pass-thru or proxy API function is provided to allow the user application to send Comcerto commands as defined by the Command Reference Manual directly. This gives user the flexibility to use newly defined MSP APIs that are not yet used from the VAPI APIs internally.
Also, pass-through API will be used to modify connection options (DGAIN, ECHOCAN etc) or to do the device related configuration.
It is not meant to be used for either creating or destroying connections / conferences / participants. Also, the use of this API should be minimized i.e. if there is a VAPI API available for certain functionality then only that API should be used and pass-through must be avoided. For pass-thru commands, the VAPI layer performs minimum processing on each command:

Translate the mapping between Connection ID and MSP channel number for all the channel related commands (CMD_LEVEL_CONN).
Translate the mapping between Device ID and the device for all the device related commands (Supervisor channel is used). (CMD_LEVEL_DEV).
Translate the mapping between user defined Conference ID and MSP assigned conference ID for conference related commands (CMD_LEVEL_CONF).
Parse the function code and its parameters to make sure the specific bit-fields are not changed by a subsequent VAPI function.
For example, if the user application sends a VCEOPT command using the pass-thru API, this is treated like an override command for VCEOPT.
Therefore, subsequent VAPI functions that also issue VCEOPT should retain the same parameters as intended by the original pass-thru function call. Some fields which VAPI has explicitly defined behavior, like packet generation field, is controlled by VAPI and should not be overridden by the pass through command.

User has to take care of the following points while using VAPI_PassThru:

FIFO contents should be 4-byte aligned (include padding)
User can send multiple-command messages using VAPI_PassThru.
However, FIFO must have the correct padding (between commands for 4-byte alignment)
as defined in the Command Reference Manual.
In return VAPI provides complete FIFO containing all the response messages returned by MSP.
The status returned is as per the latest failed command (if any) present in multi-command response.
Currently there is a limitation regarding conference commands that only one conference related
command is currently supported (CONF_SPECIFY_DOMINANT_TALKERS).
This is because the position of participant ID inside the FIFO is dependent on function code.
Also if mapping for both the Participant ID and the Conference ID is required in a MSP command
then VAPI_PassThru cannot be used, because uiID can take only one value that can be either a
Participant ID (CMD_LEVEL_CONN) or a Conference ID (CMD_LEVEL_CONF).
In coming releases this issue will get resolved.
Whether the host is Big-Endian or Little-Endian, it would be the user's responsibility to provide the FIFO words in correct byte order as defined by the Command Reference Manual.
Currently the following commands are tracked in order to update VAPI stored channel parameters.
This ensures that these commands shall use the modified values when sent from inside VAPI defined APIs.
These function codes are:
at connection level
- FC_VOIP_VOPDIS
- FC_VOIP_VOPENA
- FC_VOIP_VCEOPT
- FC_VOIP_DGAIN
- FC_VOIP_DTMFOPT
- FC_VOIP_ECHOCAN
- FC_VOIP_JBOPT
- FC_SET_ALT_HDR_CHANNEL
- FC_SET_IP_HDR_CHANNEL
at connection level
- FC_IP_SERVICE_CONFIG
- FC_ALT_HDR_DEVICE
- FC_IP_ADDRESS
- FC_MULTI_IP_ADDR_LIST
- FC_SET_ETH_HDR
- FC_SPU_FEATURES_CONTROL

Inputs-Outputs
uiID	It is device ID or Connection ID depending upon ucLevel.
ucLevel	Indicates whether the command is a device level command or connection level
pstMsg	Message to be sent to MSP. It is required to only fill the pusFifo and the uiFifoSize fields. The sMailbox is no longer used.
pstRequest	If NULL then the call is in blocking mode (synchronous).
pucBuffer	Buffer to hold the response message's fifo.
puBufLen	This is an IN/OUT parameter, it should hold the length of input buffer, and when the request completes it will hold the length of output buffer

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_LIB_NOT_INITIALIZED
VAPI_ERR_INVALID_DEVID
VAPI_ERR_DEV_IS_NOT_UP
VAPI_ERR_NOMEM
VAPI_ERR_NULL_POINTER_PASSED
VAPI_ERR_INVALID_PARAM
VAPI_ERR_INVALID_CONNID
VAPI_ERR_INVALID_CONFID
VAPI_ERR_UNSUPP_FEATURE

Usage:

/* Connection level example */

/* define a complex tone */
/* Note that from VAPI 2.7.0 is more convenient to use the VAPI utilities API
(i.e VAPI_SetMessageFromBuffer) to build a such command*/
U8 complex_tone[] = {
         /*CADENCE_ENGINE, length = 0x18 (24) no padding required*/
                        0x18, 0x00, 0x00, 0x02, 0x6f, 0x80, 0x00, 0x00, /*CC, CT, FC*/
                        0x01, 0x00, 0x00, 0x40, 0x32, 0x00, 0x00, 0x10,
                        0x02, 0x00 ,0xc8, 0x00, 0x2c, 0x01, 0x00, 0x20,
        /* PROGRAM_TONE_ENGINE, length =  0x2e (46) 2 bytes of padding required*/
                        0x2e, 0x00, 0x00, 0x02, 0x6e, 0x80, 0x00, 0x00,
                        0x02, 0x00, 0x6c, 0x07, 0xd3, 0x00, 0x00, 0x00,
                        0x00, 0x00 ,0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                        0x00, 0x00 ,0x00, 0x00, 0x78, 0x05, 0xfb, 0x00,
                        0x00, 0x00 ,0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                        0x00, 0x00 ,0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        /* VOPENA_TONEGEN , length = 0x0a (10) 2 bytes of padding required*/
                        0x0a, 0x00, 0x00, 0x02, 0x00, 0x80, 0x00, 0x00,
                        0x0d, 0x00 ,0x00, 0x00
};

        SMsg MyMsg;                     /* message structure which handle the passthru commands */
        U8 OutBuff[MAX_FIFO_SIZE];      /* buffer to handle the passthru response */
        U32 OutBuffLen = MAX_FIFO_SIZE;

        /* 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;

        /* assign the complex tone commands buffer address to the msg fifo buffer*/
        MyMsg.pusFifo = (U16 *)&complex_tone;
        /* set the right size */
        MyMsg.uiFifoSize = sizeof(complex_tone);

        /* send the complex tone generation parameters to the connection 0 in blocking mode*/);
        status =  VAPI_PassThru(0, CMD_LEVEL_CONN, &MyMsg, NULL, OutBuff, &OutBuffLen);
        if (status != SUCCESS)
        {
                print("VAPI_PassThru complex_tone error %d", status);
                return status;
        }

Commands:

The Comcerto commands sent depends on the psMsg.

VSTATUS VAPI_RegisterEventCallback	(	IN U32	uiID,
		IN U8	ucLevel,
		IN PFNEventCallback	pfnEventCallback
	)

Description:
This function is used to register a callback function for events coming from the MSP devices.
Whenever any event is received from a device, the callback routine is invoked with the event code.
Other information related to the event is stored in the buffer pointed
to by pvData of the callback function.
The library allocates memory for the buffer which is freed upon return of control
from the user specified callback function.
The user must free this thread immediately as this thread is created at the GTL layer
and GTL will need it to report further received messages to VAPI.

Inputs-Outputs
uiID	Device or Connection ID.
ucLevel	Level at which the callback is to be registered. (EVENT_LEVEL_GENERIC,EVENT_LEVEL_DEVICE,EVENT_LEVEL_CONN)
pfnEventCallback	Callback to be registered. If it is NULL then it will erase the previously registered callback (if any).

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_LIB_NOT_INITIALIZED

Usage:

#include <vapi/comcerto-voip-types.h>
...

/* This function handles the indications comming from the device through VAPI */
...

void comcerto_indication_handler(EEventCode eEventCode, void *pvData)
{
        SToneDetectEventParams *tone_detected;
        SSsrcChangeEventParams *ssrc_changed;
        SUndefinedEventParams *this_event;
        
        switch(eEventCode)
        {
                case eVAPI_TONE_DETECT_EVENT:
                        tone_detected = (SToneDetectEventParams *)pvData;

                        printf("Tone %d detected on Connection ID %d",
                                        tone_detected->usDetectedTone, tone_detected->ConId);

                        switch (tone_detected->usDetectedTone)
                        {
                        case VOIP_TONEDET_TONE_START_V21_FLAGS:
                                printf("======== FAX V.21 detected =========\n");
                                set_endpoint_event(ENDPOINT_EVENT_V21FLAG_DETECTED, 

...
}


...
        /* register the indication handler for the device */
        VAPI_RegisterEventCallback(device_id, EVENT_LEVEL_GENERIC, comcerto_indication_handler);

...

Commands:

No Comcerto commands sent.

VSTATUS VAPI_SetDebugLevel	(	U8	ucVapiDebugLevel,
		U8	ucAppDebugLevel
	)

Description:
This API is used to change the VAPI debug levels dynamically.
Various debug levels are defined to customize the type of debug information being generated from VAPI modules
To print debug info to console VAPI should be compiled with
-UVAPI_NODBG key

Inputs-Outputs
ucVapiDebugLevel	Debug level pertaining to internal VAPI debug information: NO_DEBUG ALL_ERRORS API_LEVEL API_PACKET_LEVEL VAPI_INFO VAPI_GTL_INFO VAPI_UT ALL_INFO.
ucAppDebugLevel	Debug level pertaining to the user application INFO DEBUG PACKET WARN ERRORS

Returns:

SUCCESS or VAPI_ERR_PENDING
VAPI_ERR_LIB_NOT_INITIALIZED

Commands:

No Comcerto commands sent.

Miscellaneous API functions

Functions

Typedef Documentation

Function Documentation