(Page 5 of 5 in this chapter)

2.4 Principles of Operation

The basic principles of CT Access operation involve an asynchronous programming model and a flexible method of organizing applications.

2.4.1 Asynchronous Programming Model

CT Access employs an asynchronous programming model in order to take advantage of concurrent processing.
The application uses the services' API functions. When called, most API functions return immediately which indicates the function was initiated. The application may then perform other functions while CT Access is processing the command.
CT Access sends the command to the service which sends a command to a telephony board. The board performs the requested functions and sends events to the service indicating its state (e.g., function was started, function is complete, etc.). The service sends events to CT Access which makes them available to the application.
Figure 9. Asynchronous Programming

2.4.2 Events

All CT Access functions return a status or return code. For asynchronous functions, the return code means the function was initiated. During function execution, events are generated indicating the occurrence of certain conditions or state changes.
The contents of the event structure informs the application about what event occurred and provides additional information specific to the event. Events are represented as a CTA_EVENT C data structure which contains the following information: Field Description id A CT Access event code for the event. All CT Access event codes are prefixed with XXXEVN_ (e.g., VCEEVN_PLAY_DONE). ctahd The CTA context handle on which the event occurred as returned from ctaCreateContext. timestamp The time in milliseconds when the event was generated. The resolution for AG board events is 10 milliseconds. userid The user context value supplied to ctaCreateContext. value An event-specific value used to communicate a single 32-bit datum. size Size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may 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.
A list of events can be found in Appendix C of the CT Access Function Reference Manual and in the ADI Service Function Reference Manual.

Field	Description
id	A CT Access event code for the event. All CT Access event codes are prefixed with XXXEVN_ (e.g., VCEEVN_PLAY_DONE).
ctahd	The CTA context handle on which the event occurred as returned from `ctaCreateContext`.
timestamp	The time in milliseconds when the event was generated. The resolution for AG board events is 10 milliseconds.
userid	The user context value supplied to `ctaCreateContext`.
value	An event-specific value used to communicate a single 32-bit datum.
size	Size (bytes) of the area pointed to by buffer. If the buffer is NULL, this field may 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.

2.4.3 CTA Context

A CTA context organizes services and accompanying resources around a single processing context. A CTA context usually represents an application instance controlling a single telephone call. Some contexts are not associated with a call; an application performing voice conversions does not require a telephone line.
Service functionality is attached to a CTA context by opening a service on a context, creating a service instance. A service instance defines a service (i.e., a logical group of functions) and its associated resource (e.g., MVIP board, stream, and timeslot). A CTA context is a bound collection of service instances; this binding groups functions and resources with a state, creates service dependencies (integration services depend on device services), and handles parameter management.
A service may only be opened once on a CTA context. For example, in order to use the ADI service functions on all 24 channels of an AG resource board, 24 CTA contexts are needed with the ADI service opened on each context.
Each type of service has defined parameters. Each service instance has its own copy of these parameters maintained by the CTA context. This allows each call to have its own characteristics. Figure 10. CTA Contexts
An integration service which requires telephony hardware is dependent on a device service which must be opened on the same CTA context.
When invoking a function which needs hardware resources, the integration service will address commands to the device service on the same CTA context.
For example, the Voice Message service in Figure 11 requires hardware resources when performing playing and recording. It is dependent on the ADI service which is opened on the same context.
Figure 11. Integration Service on a CTA context

2.4.4 Event Queue

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 specify the service managers to be attached to it. Only services supported by the specified service managers are allowed to be opened on the CTA contexts attached to the queue.
When creating a CTA context, you specify an event queue. All events from the services on the CTA context are sent to the event queue attached to the context.
One queue can be created for the entire application process or multiple queues may be used. The number of queues you create depends on the programming model used. Some models use one queue to handle all CTA contexts; multiple telephone calls are handled with the same queue. Other models use one queue for each call.
Figure 12. Event Queue - Single Queue/Multiple Contexts

2.4.5 Command and Event Processing

Figure 13 and Figure 14 are block diagrams depicting the interaction between the application program and CT Access components when calling a Voice Message service API function. Figure 13. Command Path for a Voice Message Function
Commands are processed in the downward direction from the application program to the hardware. Commands are processed in the following sequence: The application invokes a Voice Message function with a CTA context handle. The dispatcher routes the command to the Voice Message service manager on the specified CTA context. The Voice Message service accesses its context parameters when processing the command. The Voice Message service is an integration service. The command requested requires hardware resources. The ADI service on the same context is providing the Player/Recorder functionality. The Voice Message service sends a command to the ADI service via the dispatcher. The dispatcher routes the command to the ADI Service. The ADI service accesses its context parameters when processing the command. The ADI service sends a command to the AG board driver.
Figure 14. Event Path
Events are processed in the upward direction from the hardware to the application. CT Access events are processed in the following sequence:

The application calls ctaWaitEvent to wait for asynchronous events that require processing by CT Access services.

The ADI service receives an AG event from the AG board driver.

The ADI service sends an event to the Voice Message service through the dispatcher.

The dispatcher sends the event to the Voice Message service.

The Voice Message service processes the event and sends an event to the application via dispatcher.

The dispatcher places the event in the event queue associated with the CTA context.

The application returns from ctaWaitEvent with the retrieved event.

Note: The application must call ctaWaitEvent in a timely manner to ensure prompt processing of time critical events. ctaWaitEvent may not return an event to the application for every internal event that it processes.

(Page 5 of 5 in this chapter)

Tech_Support@nmss.com