Introduction
This document describes the services provided by VAPI layer
APIs are discussed in detail in subsequent subsections.
The key features of VAPI services are as follows:
- Provide a high-level Voice API abstraction not tied to a particular device-specific command set or implementation. Provide abstractions for miscellaneous services such as boot loading, PCI messaging, CSME messaging, etc.
- In cases where it makes sense, all API functions can be blocking (synchronous) or non-blocking (asynchronous). This is accomplished by passing a callback function pointer. If the callback pointer is NULL, the operation is assumed to be blocking. If the callback pointer is provided, the API function returns immediately with status code equals VAPI_ERR_PENDING and when the processing is completed the VAPI layer calls the callback function with the completion status.
- Provides flexibility for the application to define unique Connection IDs. A Connection ID uniquely identifies a channel across all devices. A Connection ID that is used for creating a connection on one device cannot be used for creating a connection on another device.
- A pass-thru or proxy API function is provided to allow the user application to send Comcerto(TM) commands as defined by the Command Reference Manual. The pass-thru allows applications to send newly defined commands that are not yet available in the VAPI library.
This also prevents cluttering of the VAPI layer with trivial services not usually required by applications in most scenarios.
- A versatile event callback mechanism is provided. Event callback is used to send asynchronous event messages to the user application. The application can choose to register an event callback with different granularities explained as follows:
- Generic event callback: This callback is called if no device level or connection level event callback is registered with the VAPI for a particular event.
- Device Level event callback: This callback is called when an event is received for a particular device, specified at the time of callback registration, and no connection level callback is registered for the channel on which the event is received.
- Connection Level event callback: This callback is called when the event is received on the channel specified at the time of registration.
It is up to application to choose a suitable granularity level. Applications can choose to have a combination of all three event callbacks.
- All API functions return a status value to indicate if the operation completed successfully or not. In case of an asynchronous call, the callback carries the completion status of the VAPI API. Success is indicated by return value of SUCCESS; defined as 0. The status is a negative value in error cases. When an error is generated by the VAPI internally, the returned status is a negative value starting from the VAPI_ERROR_BASE. If the error is generated by the GTL then the returned status is a negative value starting from the GTL_ERROR_BASE. If the error is returned by the Comcerto then the returned status is the negative of the error code received from the Comcerto.
Some example of VAPI based applications are available:
Some examples of VAPI APIs usage are available in the Related pages section.
