The basic principles of Natural Access operation involve an asynchronous programming model that utilizes concurrent processing and provides a flexible method of organizing applications.
The application uses the services' functions. When called, most functions return immediately, where SUCCESS indicates the function was initiated. The application can call other functions while Natural Access is processing the command.
Natural Access sends the command to the service, which in turn sends a command to a telephony board. The board performs the requested functions and sends events to the service indicating its state, for example, function was started. The service sends events to Natural Access, which makes them available to the application.
The client-server architecture of Natural Access enables Natural Access to process application commands locally and remotely. Applications and Natural Access can run on the same host or on separate hosts. A host runs multiple instances of Natural Access Server (ctdaemon) and is identified by a host name or IP address.
This topic describes:
Natural Access organizes services and accompanying resources around a single processing context. To access service functionality, an application creates a context and attaches the services it requires. A context usually represents an application instance controlling a single call. The context maintains defined parameters for each type of service, allowing each call to have its own characteristics.
Not all contexts are associated with a call. For example, an application performing voice conversions does not require a telephone line.
When an application creates or attaches to a context, a context handle is returned. A context handle provides a programming reference to the resources allocated for a context by the Natural Access implementation.
Void context handles provide an application with access to the Natural Access Server (ctdaemon) when an associated context object is not applicable. The void context handle is only a reference to addressing information that uniquely identifies the server on which Natural Access commands are executed and not an actual context object. For example, ctaGetVersionEx returns the build date and compatibility level of the server itself. This information is global to the server and is associated with all contexts created by the server, not with just one context.
For more information, refer to Creating contexts.
When an application opens a service on a context, it creates a service instance. A service instance defines a service (a logical group of functions) and its associated resource data (for example, MVIP board, stream, and timeslot). A context is a collection of service instances that groups functions and resources, creates service dependencies, and handles parameter management. A service must always be associated with a context, but not all contexts require a service.
An application can create only one service instance of a particular type (for example, ADI or Switching) on each context. For example, to use the ADI service functions on all 120 channels of a CG resource board, you must create 120 contexts and open the ADI service on each context.
A service object is a collection of data representing a particular instance of the resource. For example, the Natural Call Control service is a logical group of functions that supports answering, placing, transferring, and disconnecting a call. The managed resource is the telephone line. The Natural Call Control service uses service objects to manage information about each call. The service object maintains such information as the telephone number being called, the state of the call, and the direction of the call.
Natural Access Server returns a service object handle that uniquely identifies an instance of the service object. A service object handle provides a programming reference to an instance of a service object. A service object handle is similar to a context handle.
All service object handles indirectly refer to a context handle. Natural Access can derive a context handle from a service object handle.
Multiple service object handles can be associated with one instance of a service object, but each service object handle is unique.
All Natural Access functions return a status or return code. For asynchronous functions, the return code indicates whether the function was initiated. During function execution, events are generated indicating the occurrence of certain conditions or state changes.
Events are represented as CTA_EVENT C data structures, which contain the following fields:
|
Field |
Description |
|---|---|
|
id |
Natural Access event code for the event. All Natural Access event codes are prefixed with XXXEVN_ where XXX is the three-letter service abbreviation, for example, VCEEVN_PLAY_DONE. |
|
ctahd |
Context handle on which the event occurred as returned from ctaCreateContext, ctaCreateContextEx, or ctaAttachContext. |
|
timestamp |
Time, in milliseconds, when the event was generated. |
|
userid |
User context value supplied to ctaCreateContext or ctaCreateContextEx. |
|
value |
Event-specific value used to communicate a single 32-bit datum. |
|
size |
Size (in bytes) of the area pointed to by buffer. This field also indicates whether a data buffer associated with the event must be freed using ctaFreeBuffer. If the buffer is NULL, this field can be used to hold an event-specific value. |
|
buffer |
If a buffer is returned with the event, this field points to data that is event-specific. The field contains an application buffer address while the event's size field contains the actual size of the buffer. |
|
objHd |
Service object handle (for example, swihd, vcehd, callhd). |
An event queue is the communication path from a service to an application. A service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue.
When the event queue is created, you can specify the service managers to be attached to it. Only services supported by the specified service managers are allowed to be opened on the contexts attached to the queue.
When creating a context, you specify an event queue. All events from the services that you open on the context are sent to the associated event queue.
One event queue can be created for the entire application process or multiple event queues can be used. The number of event queues you create depends on the programming model used. Some models use one event queue to handle all contexts; multiple telephone calls are handled with the same event queue. Other models use one event queue for each call. Refer to Creating event queues for more information.
The following illustration shows the interaction between the application and Natural Access components when the application calls a Voice Message (VCE) service function. Commands are processed from the application program down to the hardware.
Commands are processed in the following sequence:
|
Stage |
Description |
|
1 |
The application invokes a Voice Message service (VCE) function with a context handle or service object handle. |
|
2 |
The Voice Message service instance accesses its context parameters when processing the command. |
|
3 |
Because the Voice Message service requires hardware resources and the ADI service on the same context provides the player/recorder functionality, the Voice Message service sends a command to the ADI service instance. |
|
4 |
The ADI service accesses its context parameters when processing the command. |
|
5 |
The ADI service sends a command to the board driver. |
The following illustration shows the interaction between the application and Natural Access components when the application retrieves an event for the Voice Message service. Events are processed from the hardware up to the application.
Events are processed in the following sequence:
|
Stage |
Description |
|
1 |
The application calls ctaWaitEvent to wait for asynchronous events requiring processing by Natural Access services. |
|
2 |
The ADI service receives a board event from the board driver and processes the event. |
|
3 |
The ADI service sends an ADI event to the Voice Message service instance. |
|
4 |
The Voice Message service processes the ADI event and sends a VCE event to the event queue associated with the context. |
For more information, refer to Receiving events on event queues.