(Page 4 of 9 in this chapter)

3.3 Setting Up a CT Access Application

Application set-up for CT Access consists of the following steps: Initializing CT Access for the process Creating event queues Creating CTA contexts and attaching them to a queue Opening services on CTA contexts

3.3.1 Initializing CT Access

CT Access initialization consists of: Registering services Specifying parameter management Enabling/disabling tracing Enabling/disabling the wait object notification event when the internal wait object list has changed.
You register services in the call to ctaInitialize by specifying the service and service manager names. Only the services specified in the call to ctaInitialize may be used by the application.
Along with the services, there are three initialization parameters in the call to ctaInitialize: parmflags, traceflags, and ctaflags.

Parameter

Description

parmflags

Specifies where the global default parameters will be stored. By default, global defaults are stored in process local memory. To store parameters in shared system memory, set parmflags to CTA_PARM_MGMT_SHARED.

If parameters are stored in shared memory, the CT Access daemon (ctdaemon) must be running. Refer to Section 3.5.2, Global Default Parameters for more information on parameter storage.

traceflags

Configures CT Access tracing in the current process. By default, tracing is disabled. To enable tracing, set traceflags to CTA_TRACE_ENABLE.

If tracing is enabled, the CT Access daemon (ctdaemon) must be running. Refer to Section 3.6.2, Error Tracing for more information on tracing.

ctaflags

Specifies whether an event will be sent to the application whenever the internal wait object list has changed. By default, wait object event notification is disabled. To enable notification, set ctaflags to CTA_NOTIFY_UPDATE_WAITOBJS.
Refer to Section 3.4, Using Wait Objects for more information.
Figure 18 shows CT Access before initialization. At this point, the application has access to the set-up functions which access the dispatcher. Figure 18. Before CT Access Initialization
After calling ctaInitialize, the CT Access environment is created as shown in Figure 19. CT Access knows:

The services that are available

All service parameter definitions and global default values
Figure 19. Registering Services

Parameter	Description
parmflags	Specifies where the global default parameters will be stored. By default, global defaults are stored in process local memory. To store parameters in shared system memory, set parmflags to CTA_PARM_MGMT_SHARED. If parameters are stored in shared memory, the CT Access daemon (`ctdaemon`) must be running. Refer to Section 3.5.2, Global Default Parameters for more information on parameter storage.
traceflags	Configures CT Access tracing in the current process. By default, tracing is disabled. To enable tracing, set traceflags to CTA_TRACE_ENABLE. If tracing is enabled, the CT Access daemon (`ctdaemon`) must be running. Refer to Section 3.6.2, Error Tracing for more information on tracing.
ctaflags	Specifies whether an event will be sent to the application whenever the internal wait object list has changed. By default, wait object event notification is disabled. To enable notification, set ctaflags to CTA_NOTIFY_UPDATE_WAITOBJS. Refer to Section 3.4, Using Wait Objects for more information.

3.3.2 Creating Queues

The next step is to create one or more event queues by calling ctaCreateQueue. You specify which service managers will be attached to each queue. When you attach or bind a service manager to a queue, you make that service manager available to the queue. After the services are opened, the events generated by services managed by the service managers will go to the attached queue.
An event queue handle (ctaqueuehd), returned from the ctaCreateQueue function, addresses the event queue. You supply the handle to retrieve events from the queue when calling ctaWaitEvent.
ctaCreateQueue may be invoked multiple times within a single process. Each invocation returns a unique queue handle.
After creating the queue shown in Figure 20, CT Access knows which services are available to the queue (specified by the service managers). You can now create CTA contexts on the queue.
Figure 20. Creating Queues

3.3.3 Creating CTA Contexts

A CTA context is created by calling ctaCreateContext. You provide the queue handle (ctaqueuehd) that was returned from ctaCreateQueue. All events for services on the context will be received in the specified event queue.
ctaCreateContext returns a CTA context handle (ctahd). The CTA context handle is supplied by the application when invoking CT Access functions. Events communicated back to the application are also associated with the context.
A user-supplied value (userid) is specified when opening the CTA context. This value is designed to facilitate asynchronous programming; it is never interpreted by CT Access. The value is echoed back to the application in the event structure when events are delivered and can be used to correlate the CTA context with an application data structure.
You can also supply a CTA context string when creating a context. The CTA context string is displayed in tracing messages.
CT Access manages parameters for services on a CTA context basis. The CTA context will maintain a copy of the parameters for all services managed by the dispatcher and specified in the call to ctaInitialize. Parameters may be modified for services not yet opened by ctaOpenServices as long as this service was registered in the call to ctaInitialize. This gives applications the flexibility to open and close services without affecting CTA context parameter values.
Figure 21 depicts CT Access after CTA contexts are created. The parameter values are copied to the CTA context. The contexts are addressed by ctahd1 and ctahd2.
Figure 21. Creating CTA contexts

3.3.4 Opening Services

Services are opened on a CTA context by calling ctaOpenServices, passing a CTA context handle and a list of service descriptors. The service descriptor specifies the name of the service, service manager, and service specific arguments (e.g., MVIP address).
Opening a service on a CTA context creates 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). The 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.
Services are referenced by the CTA context handle (ctahd). Applications do not directly address the service; they call a service function with the CTA context handle. For example, the API command, vceOpenFile (ctahd...), implies the ctahd instance of the Voice Message service.
The call to ctaOpenServices is asynchronous and returns immediately. When all services have been opened, CTAEVN_OPENSERVICES_DONE is returned to the application.
CT Access supports opening and closing services on an as needed basis to share scarce resources. For example, the Diva II daughterboard has 16 ports for voice recognition. The voice recognition service may be opened and closed as needed so the 16 ports may be used to process calls from an AG-T1 with 24 channels.
Once the services are opened as depicted in Figure 22, all paths in CT Access are defined. The dispatcher knows all the command paths to send commands to the services and the event paths to place events in the appropriate queue. The application programmer can now use the service API.
Figure 22. Opening Services

3.3.5 Opening the ADI Service

When opening the ADI service, you must specify a CTA context, a specific board, and an MVIP timeslot and mode.
The parameter structure mvipaddr contains the following parameters: board, bus, stream, timeslot, and mode.
The board specifies the board number you wish to use. The agmon configuration file contains a Board directive identifying each board in the system. See the ADI Service Installation Manual for details on agmon.
The bus, stream, timeslot, and mode parameters are used to calculate which streams and timeslots are allocated to the service. The stream and timeslot specify the base timeslot, while the mode dictates how many timeslots are allocated.
The value of mode can be: Value Description ADI_VOICE_INPUT Receives inband data only. The data is received by the DSP on the given stream and timeslot. ADI_VOICE_OUTPUT Transmits inband data only. The data is transmitted by the DSP on the given stream and timeslot. ADI_VOICE_DUPLEX Receives and transmits inband data. The same stream and timeslot address is used by the DSP for transmitting and receiving. ADI_SIGNAL_INPUT Receives out-of-band signaling only. The data is received by the DSP on the given stream and timeslot. ADI_SIGNAL_OUTPUT Transmits out-of-band signaling only. The data is transmitted by the DSP on the given stream and timeslot. ADI_SIGNAL_DUPLEX Receives and transmits network out-of-band signals. The same stream and timeslot address is used by the DSP for transmitting and receiving. ADI_FULL_DUPLEX This is both ADI_SIGNAL_DUPLEX and ADI_VOICE_DUPLEX. The port receives and transmits both inband media and out-of-band signaling.
The two most common modes are ADI_VOICE_DUPLEX and ADI_FULL_DUPLEX. The ADI_VOICE_DUPLEX mode is typically used with the NOCC protocol and allows media (voice, fax, etc.) reception and transmission.
The ADI_FULL_DUPLEX mode is typically used when running a network protocol on the port. This mode allows both voice (inband) and network signaling transmission and reception.
The demonstration program ctatest verifies the proper installation and operation of the ADI service. Refer to Section 13.2.1, Interactive Test Program: ctatest.

Value	Description
ADI_VOICE_INPUT	Receives inband data only. The data is received by the DSP on the given stream and timeslot.
ADI_VOICE_OUTPUT	Transmits inband data only. The data is transmitted by the DSP on the given stream and timeslot.
ADI_VOICE_DUPLEX	Receives and transmits inband data. The same stream and timeslot address is used by the DSP for transmitting and receiving.
ADI_SIGNAL_INPUT	Receives out-of-band signaling only. The data is received by the DSP on the given stream and timeslot.
ADI_SIGNAL_OUTPUT	Transmits out-of-band signaling only. The data is transmitted by the DSP on the given stream and timeslot.
ADI_SIGNAL_DUPLEX	Receives and transmits network out-of-band signals. The same stream and timeslot address is used by the DSP for transmitting and receiving.
ADI_FULL_DUPLEX	This is both ADI_SIGNAL_DUPLEX and ADI_VOICE_DUPLEX. The port receives and transmits both inband media and out-of-band signaling.

3.3.6 Closing Services, Destroying Contexts and Queues

Close functions parallel each of the initialization functions.
ctaCloseServices closes one or more services on a CTA context. The function is asynchronous and returns immediately. You must wait for the completion event, CTAEVN_CLOSE_SERVICES_DONE, to be returned on the event queue before all the services are closed.
ctaDestroyContext destroys a CTA context. All currently opened services are closed. The function is asynchronous and returns immediately. You must wait for the completion event, CTAEVN_DESTROY_CONTEXT_DONE, to be returned on the event queue before the CTA context is destroyed and resources are released.
ctaDestroyQueue destroys the queue and all CTA contexts associated with the queue. This is a synchronous function so the application will remain blocked until all cleanup and close activity has completed. If the services and contexts were already closed, the function will return immediately.

(Page 4 of 9 in this chapter)

Tech_Support@nmss.com