This topic describes the contents and naming conventions for binary files and source files of a Natural Access service.
Two DLLs or libraries are created for a service: one for the service interface and one for the service implementation. Developers link with the interface library when compiling an application. The corresponding implementation library is dynamically loaded at runtime. The CTA_SERVICE_NAME structure passed to ctaInitialize controls which service interface the application uses and which implementation of that interface should be dynamically linked in. For example, using ADI, ADIMGR states that the application is making calls to the ADI service and that the implementation of those calls is performed by ADIMGR (for the AG hardware). Similarly, using ADI, QDIMGR, directs the application to make calls to the ADI service, and directs QDIMGR to perform the implementation of those calls. In both cases, the application links with adiapi.lib.
Having two libraries allows a service developer to leverage an existing service by simply re-implementing the service implementation. For example, the ADI interface can be used for another vendor's telephony board by creating a new service implementation component that communicates with the board. The service interface remains the same.
The naming conventions for service binary files are:
|
|
Windows DLL |
UNIX library |
|---|---|---|
|
Service interface |
xxxapi.dll |
libxxxapi.so |
|
Service implementation |
xxxmgr.dll |
libxxxmgr.so |
The appropriate implementation library is dynamically loaded at runtime. The loading process is controlled by the CTA_SERVICE_NAME structure passed to ctaInitialize.
For example:
|
This service and service manager... |
links with... |
and loads... |
|---|---|---|
|
ADI, ADIMGR |
adiapi.lib |
adimgr.dll |
|
ADI, QDIMGR |
adiapi.lib |
qdimgr.dll |
The service implementation can be written in either C or C++. However, the service interface must be written in C to prevent issues associated with name mangling. Ensure that function declarations within header files are declared as having C style linkage characteristics, so that all functions are callable by both C and C++ programs. For instance, header files should contain:
/* At the top of the header: */
#ifdef __cplusplus
extern "C" {
#endif
...
/* At bottom of header: */
#ifdef __cplusplus
}
#endif
The service interface typically consists of the following source files:
|
File |
Description |
|---|---|
|
xxxapi.c |
Implements the service API by calling the corresponding SPI function and handling API errors. |
|
xxxspi.c |
Implements the service SPI functions and the client side binding functions. |
|
xxxdef.h |
Header file containing API data structures, function prototypes, and definitions. |
|
xxxspi.h |
Header file containing SPI function prototypes. |
|
xxxparm.pf |
ASCII file containing definition of service parameters. |
The service implementation typically consists of the following source files:
|
File |
Description |
|---|---|
|
xxxbnd.c[cpp] |
Implements the service manager (binding) functions. |
|
xxxcmd.c[cpp] |
Implements the service functions that interact with the managed resource. |
|
xxxparm.c[cpp] |
Parameter source file automatically generated from xxxparm.pf. |
|
xxxparm.h |
Parameter header file automatically generated from xxxparm.pf. |
|
xxxsys.h |
Header file containing internal data structures, function prototypes, and definitions. |
Additional source files for a service can also exist as required. These files should also follow the Natural Access naming conventions (for example, xxxsomething.c). File names should follow the 8.3 format convention.
The following illustration shows the relationship between service source files, binaries, and the dispatcher functions available to service writers:
Natural Access software structure