Table of Contents Index NMS Glossary Previous Page Next Page Version

Chapter 1

Overview of CT Access

1.1 Introduction
1.2 CT Access Environment
1.2.1 Programming Model
1.2.2 CT Access Components
1.2.3 Managing Parameters in CT Access
1.3 Setting Up the CT Access Environment
1.3.1 Initializing CT Access
1.3.2 Creating Event Queues and CTA Contexts
1.3.3 Opening Services
1.3.4 Linking with the ADI Service
1.3.5 Using the ADI Service in Driver-Only Mode
1.3.6 Using ADI with the Natural Call Control Service
1.4 ADI Service Functionality

1.1 IntroductionTop of Page

The ADI Service Developer's Manual explains how to develop an application using the ADI service within the CT Access environment.

This manual defines telephony terms where applicable, but assumes that the reader is familiar with telephony concepts. It also assumes that the user is familiar with the C programming language.

Read the CT Access Developer's Reference Manual before using this manual. The CT Access Developer's Reference Manual contains detailed information concerning CT Access concepts, architecture, and application development. This information must be fully understood before you use the ADI service with CT Access.

1.2 CT Access EnvironmentTop of Page

This section provides background information about CT Access and summarizes the main elements of the CT Access environment. CT Access is a development environment providing standard programming interfaces for telephony functions that are hardware-independent. You must have CT Access installed on your system to build applications using the ADI service.

For detailed information about CT Access, refer to the CT Access Developer's Reference Manual.

1.2.1 Programming ModelTop of Page

CT Access employs an asynchronous programming model in order to take advantage of concurrent processing. When called, most functions return immediately, indicating the operation was initiated. The application may then call other functions while CT Access is processing the command.

There are two types of functions in CT Access: synchronous and asynchronous.

Synchronous functions are complete when the return value is received. The return value may be either SUCCESS or an error code.

For asynchronous functions, if the return value is SUCCESS, the function has been successfully initiated, and the execution result will arrive asynchronously through an event. If the return code is not SUCCESS, the function was never initiated; therefore, no subsequent events associated with the function will be generated.

During the function execution, events are generated indicating the occurrence of certain conditions or state changes. If an asynchronous function fails after being initiated, CT Access delivers a DONE event to the application and the event value field contains an error code.

The following table summarizes the differences between asynchronous and synchronous functions. Refer to the ADI Service Function Reference Manual for information on the ADI service functions.

Asynchronous

 Synchronous

Operation complete when function returns.

 No

 Yes

Returns a DONE event when function is complete.

 Yes

 No

Function can fail after function returns.

 Yes

 No

For asynchronous functions, CT Access sends a 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 (for example, function was started, function is complete, etc.). The service sends events to CT Access which makes them available to the application.

Refer to the ADI Service Function Reference Manual for a complete list of ADI service errors and events.

1.2.2 CT Access ComponentsTop of Page

A CT Access service is a group of logically related functions. The ADI service is a CT Access service.


chap1a.gif

Figure 1. CT Access and the ADI Service 



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.



An event queue is the communication path from a CT Access service to an application. A CT Access service generates events indicating certain conditions or state changes. An application retrieves the events from the event queue.






1.2.3	 Managing Parameters in CT AccessTop of Page





The characteristics for CT Access services can be altered by modifying associated parameters. Each ADI service parameter structure has default values that are sufficient for most configurations.



CT Access manages parameters for services on a CTA context basis. The CTA context will maintain a copy of the parameters for all services opened on the context.



The following CT Access functions allow you to obtain or change parameter information: 





 Function



 Description




 ctaGetParmByName



 Retrieves a single field for a given parameter name.




 ctaSetParmByName



 Modifies a single field for a given parameter name.




 ctaGetParmID



 Retrieves the parameter ID for a given parameter descriptor name.




 ctaGetParmInfo



 Retrieves a parameter field definition.




 ctaGetParms



 Returns parameter values for a given parameter structure.




 ctaRefreshParms



 Resets the values of all context parameters on a CTA context to the global defaults.
















Refer to the CT Access Developer's Reference Manual for information about the parameter functions. Refer to the ADI Service Function Reference Manual for detailed descriptions of ADI service function parameters.






1.3	 Setting Up the CT Access EnvironmentTop of Page





Before you can call functions from the ADI library, the application must initialize CT Access and open the ADI service. Application setup for CT Access consists of the following steps:


    


  1. Initializing CT Access for the process.
    

    

  2. Creating event queues.
    

    

  3. Creating CTA contexts and attaching them to an event queue.
    

    

  4. Opening services on each CTA context.
    








1.3.1	 Initializing CT AccessTop of Page





Register services in the call to ctaInitialize by specifying the service and service manager names. Only the services initialized in the call to ctaInitialize may be opened by the application. Service managers are dynamic link libraries (DLLs) in Windows NT and shared libraries in UNIX. 



There are two service managers (representing the two families of boards) implementing the ADI service. Use the appropriate service manager in your call to ctaInitialize: 





 Board Family



 Manager




 AG


ADIMGR



 CG


ADIMGR



 QX


QDIMGR


















1.3.2	 Creating Event Queues and CTA ContextsTop of Page





After initializing CT Access, create the event queues and CTA contexts.



Create one or more event queues by calling ctaCreateQueue. You specify which service managers will be attached to each queue. The ADI service's service manager is ADIMGR (or QDIMGR). When you attach or bind a service manager to a queue, you make that service manager available to the queue.



Create a CTA context by calling ctaCreateContext. You provide the queue handle (ctaqueuehd) that was returned from ctaCreateQueue. All events for services on the CTA 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 ADI service functions. Events communicated back to the application are also associated with the CTA context.



Refer to the CT Access Developer's Reference Manual for details on the programming models created by the use of CTA contexts and event queues.






1.3.3	 Opening ServicesTop of Page





Services are opened on a CTA context by calling ctaOpenServices. When opening the ADI service, you must specify a CTA context, a specific board, timeslot, and mode.



The parameter structure CTA_MVIP_ADDR contains the following fields: board, bus, stream, timeslot, and mode. For all boards except AG-24/30/48/60 boards, bus and stream can be 0.


Note:  For AG-24/30/48/60 boards, you must also specify an MVIP-90 stream.


The board field specifies the board number you wish to use. For AG hardware initialized with agmon, the configuration file contains a Board keyword identifying each board in the system. Refer to the AG Runtime Configuration and Developer's Manual for details on agmon.



For AG hardware initialized with OAM , the configuration file contains a Board keyword identifying each board in the system.  Refer to the OAM System User's Manual for more information. 



 For QX boards, the qx.cfg configuration file contains a Board section identifying each board in the system. Refer to the QX 2000 Installation and Developer's Manual for more details.



The timeslot and mode fields are used to calculate which timeslots are allocated to the service. The timeslot specifies 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 timeslot.




 ADI_VOICE_OUTPUT



 Transmits inband data only. The data is transmitted by the DSP on the given timeslot.




 ADI_VOICE_DUPLEX



 Receives and transmits inband data on the given timeslot.




 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 the CT Access Developer's Reference Manual for more information about ctatest.



When you open the ADI service, you must specify a DSP address. A DSP address is specified as an MVIP address (stream/timeslot pair). 



The following table shows valid bus, stream, and timeslot values for AG, CG, or QX boards: 





 Board



 Stream



 Stream



 Timeslot




 



 Bus=0



 Bus=MVIP95_LOCAL_BUS



 




 CG 6000C



 0



 16



 0 - 240




 AG Quad T1/E1, AG Dual T1/E1, AG 4000, AG 4000C



 0



 16



 0 - 127




 AG 2000



 0



 4



 0 - 7




 QX 2000



 0



 4



 0 - 3




 AG-8



 0, 18A



 4



 0 - 7




 AG-T1, AG-E1



 0, 18A



 4



 0 - 31B




 AG-24/30/48/60



 0C, 2C


 4C, 6C



 



 as configuredC















 A Provided for compatibility with existing applications.


 B 0 - 29 are valid when the board is configured for primary rate ISDN.


 C Valid streams/timeslots specified by MVIPSLOTS statements in ag.cfg.






When the ADI service manager is attached to an event queue, it opens the AG board driver and associates the muxable wait object returned by the driver open command with the event queue. When this wait object is signaled on receipt of events from the board, ctaWaitEvent processes the events through the ADI service and passes any event generated back to the calling function.






1.3.4	 Linking with the ADI ServiceTop of Page





The CT Access ADI service contains two components, the ADI service interface and the ADI service implementation. When building a CT Access application that uses the ADI service, link to adiapi.lib (under UNIX, libadiapi.so). 



For existing applications, modify your makefiles to link with adiapi.lib (libadiapi.so). Since earlier applications using the ADI service linked to adimgr.lib (under UNIX, libadimgr.so), it is included only for backward compatibility.



See the CT Access Service Writer's Manual for more details about service implementation. 






1.3.5	 Using the ADI Service in Driver-Only ModeTop of Page





In order to access only the AG driver, use the special board argument ADI_AG_DRIVER_ONLY in place of a real board number in the MVIP_ADDR structure. This permits the application to use a "virtual port." The application can use the following functions on a CTA context in driver-only mode, since they do not require physical AG board resources:




adiGetTimeStamp and adiGetEEPromData are not available for QX boards.


Note:  All other functions that take a CTA context handle (ctahd) require AG board-level DSP resources.





1.3.6	 Using ADI with the Natural Call Control ServiceTop of Page





The Natural Call Control service supercedes call control functions in ADI.  Created as a separate service to only handle call control functions, NCC uses new function calls and events to improve functionality and versatility.



When the NCC service is active, a call to an ADI call control function will produce the CTAERR_FUNCTION_NOT_ACTIVE error to avoid conflicts in call control functionality.



For more information about the Natural Call Control service, refer to the Natural Call Control Service Developer's Reference Manual.






1.4	 ADI Service FunctionalityTop of Page





The ADI service provides the following functionality:




The ADI service supports AG, CG,  and QX boards.








 
Table of Contents Index NMS Glossary Previous Page Next Page Version




 




Want to send us feedback on our documentation?  Email: Tech_Pubs@nmss.com



Copyright © 2000, Natural MicroSystems, Inc.   All rights
reserved.