3.1 Introduction

3.2 Setting Up the CT Access Environment

3.2.1 Initializing CT Access

3.2.2 Creating Event Queues and CTA Contexts

3.2.3 Opening Services

3.2.4 Receiving NCC Service Events

3.3 Loading and Starting a Protocol

3.3.1 Starting a Protocol on a CTA Context

3.4 Linking with the NCC Service

3.1 Introduction

This chapter describes how to set up the CT Access environment and start the NCC service.

3.2 Setting Up the CT Access Environment

Before you can call functions from the NCC library, the application must initialize CT Access and open the NCC 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, including the NCC service.

3.2.1 Initializing CT Access

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

When using an AG board, a CG board, or a CX board, specify the ADIMGR service manager with ctaInitialize.

When using a QX board, specify the QDIMGR service manager with ctaInitialize.

3.2.2 Creating Event Queues and CTA Contexts

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

Create one or more event queues by invoking 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.

Create a CTA context by invoking 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 NCC service line 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.

3.2.3 Opening Services

Services are opened on a CTA context by invoking ctaOpenServices. When opening a service on a CTA context, you must specify information about the service and the service manager, and which resources to attach to the CTA context. This information is specified in substructures of the CTA_SERVICE_DESC structure referenced in the function invocation.

For example, the following table shows how to fill in this information to start NCC on a CTA context. It assumes an AG implementation using an AG board:

Parameter	Set as follows for the ADIMGR implementation of NCC:
CTA_SERVICE_NAME:
svcname	ncc
svcmgrname	The name of the implementation DLL for the protocol(s) to be used: ADIMGR.
CTA_SERVICE_ADDR:	Reserved for client/server usage. Initialize to 0.
CTA_SERVICE_ARGS:	Not used by NCC.
CTA_MVIP_ADDR:
board	The board number you wish to use. The configuration file contains a Board directive identifying each board in the system. Refer to your board-specific installation and developer's manual for more detail.
bus	Set bus and stream to 0. Note: If you are using AG-24/30/48/60 boards (used with versions of CT Access prior to 4.0), you must specify an MVIP-90 stream.
stream	(See the following table.)
timeslot	(See the following table.)
mode	The value of mode can be: 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.

When you open the NCC service with the ADIMGR or the QDIMGR, 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, CX, and QX boards:

Board	Stream	Stream	Timeslot
	Bus=0	Bus=MVIP95_LOCAL_BUS
AG Quad T1, AG Quad E1 AG Dual T1, AG Dual E1	0	16	0 - 127
AG 2000	0	4	0 - 7
AG 4000	0	16	0 - 127
AG 4000C	0	16	0 - 127
CX 2000	0	4	0 - 31
CX 2000C	0	4	0 - 47
CG 6000C	0	16	0 - 127
QX 2000	0	4	0 - 3
AG-8 (used with versions of CT Access prior to 4.0)	0, 181	4	0 - 7
AG-T1, AG-E1 (used with versions of CT Access prior to 4.0)	0, 181	4	0 - 312
AG-24/30/48/60 (used with versions of CT Access prior to 4.0)	03, 23 43, 63		as configured3

1 Provided for compatibility with existing applications, using MVIP-90 stream conventions.

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

3 Valid streams/timeslots specified by MVIPSLOTS statements in the configuration file.

The demonstration program ctatest verifies the proper installation and operation of the NCC service. Refer to the CT Access Developer's Reference Manual for more information about ctatest.

3.2.4 Receiving NCC Service Events

When the NCC service manager is attached to an event queue, it opens the 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 NCC service and passes all generated events back to the calling function.

Events arrive in the form of the standard CTA event data structure (defined in ctadef.h):

typedef struct CTA_EVENT
{
    DWORD    id;                /* Event code (and source service id)    */
    CTAHD    ctahd;             /* CT Access context handle              */
    DWORD    timestamp;         /* Timestamp                             */
    DWORD    userid;            /* User id (defined by ctaCreateContext) */
    DWORD    size;              /* Size of buffer if buffer != NULL      */
    void     *buffer;           /* Buffer pointer                        */
    DWORD    value;             /* Event status or event-specific data   */
    DWORD    objHd;             /* Service client side object handle     */
} CTA_EVENT;

This structure, returned by ctaWaitEvent, informs the application which event occurred on which CTA context and includes additional information specific to the event.

The CTA_EVENT structure contains the following fields:

Field	Description
id	Contains an event code defined in the library header file. The event's prefix relates the event to a specific Natural MicroSystems library of functions. For example, all NCC events are prefixed with NCCEVN_ (NCCEVN_SOMETHING_ HAPPENED). All CT Access events are prefixed with CTAEVN_.
ctahd	Contains the CTA context handle (line handle) returned from ctaCreateContext.
timestamp	Contains the time when the event was created in milliseconds since midnight, January 1, 1970, modulo 49 days. The resolution for AG board events is 10 milliseconds.
userid	Contains the user-supplied id. This field is unaltered by CT Access and facilitates asynchronous programming. Its purpose is to correlate a CTA context with an application object/context when events occur.
size	The 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	This field points to data returned with the event. The field contains an application process address and the event's size field contains the actual size of the buffer.
value	This is an event-specific value. This field can hold a reason code or an error code.
objHd	Contains the call handle, if the event concerns a particular call. If the event concerns the line and not a particular call, objHd is NULL.

3.3 Loading and Starting a Protocol

Once CT Access has been initialized, and event queues and CTA contexts have been created, the line represented by each CTA context is in Uninitialized line state. The application should now start a protocol (TCP) instance on each context. Doing so changes the line state to idle, preparing it to accept an incoming call or place an outbound call.

To start a TCP instance:

1. The CT Access Parameter Management Service loads protocol parameters and default values. (For more information about NCC service parameters, see Appendix C.)

2. The application modifies the values, if necessary.

3. The application calls nccStartProtocol to start the protocol instance. The instance is parameterized according to the loaded parameters.

The following sections provide general information about loading and starting protocols. For specific information about the protocol you wish to start, see the developer's manual which documents the protocol.

3.3.1 Starting a Protocol on a CTA Context

Once a CTA context is open and the protocol parameters are loaded, the application starts a protocol on that context using the loaded parameters. The function nccStartProtocol starts a protocol on a CTA context. If the protocol starts successfully, the application can then use call control functions to place and answer calls on that line.

Note: In order to start a protocol from within an application, the protocol must have been downloaded to the board at system initialization time. The configuration utility downloads all protocols specified in the configuration file. For more information about the configuration file, see your board-specific installation and developer's manual.

protname passed to nccStartProtocol should be the name of the protocol, as specified in the configuration file. For example, for AG ISDN, you would specify isd0. Unless you wish to load custom parameters, set startparms, mgrstartparms, and protostartparms to NULL, so the default protocol parameters (loaded as described in Appendix C) are used.

When nccStartProtocol is called, NCCEVN_START_PROTOCOL_DONE is returned. If the protocol is started successfully, the event value field contains CTA_REASON_FINISHED. Otherwise, the value field contains another reason code.

If the TCP is started successfully, the line state changes from Uninitialized to Idle. The application may now use other NCC call control functions to perform call control on the line.

3.4 Linking with the NCC Service

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

For existing applications, modify your makefiles to link with nccapi.lib (libnccapi.so).