# Setting up the Natural Access environment

Before you can call functions from the CDI library, set up the Natural Access environment. Follow these steps:

- Initialize Natural Access

- Create event queues and contexts, and attach the contexts to an event queue

- Open services, including the CDI service, on each context.

## Initializing Natural Access

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

Use CDIMGR, the CX board family service manager, in the call to ctaInitialize. Refer to the Natural Access Developer's Reference Manual for more information about using ctaInitialize.

## Creating event queues and contexts

After initializing Natural Access, create the event queues and contexts. Create one or more event queues by calling ctaCreateQueue and specifying the service manager to attach to each queue. The CDI service manager is CDIMGR. When you attach or bind a service manager to an event queue, you make that service manager available to the event queue.

To create a context, call ctaCreateContext and provide the queue handle (ctaqueuehd) returned from ctaCreateQueue. All events for services on the context are received in the specified event queue.

ctaCreateContext returns a context handle (ctahd). The context handle is supplied by the application when invoking CDI service functions. Events communicated back to the application are also associated with the context.

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

## Opening services

To open services on a context, call ctaOpenServices. When opening a service on a context, you must specify information about the service and the service manager, and which resources to attach to the context.

The following table shows how to fill in this information to start CDI on a context:

Parameter | CDI service setting
--- | ---
CTA_SERVICE_NAME | svcname: set to CDI. svcmgrname: set to CDIMGR.
CTA_SERVICE_ADDR | Reserved for client/server usage. Initialize to 0.
CTA_SERVICE_ARGS | Not used by CDI.
CTA_MVIP_ADDR | board: The logical board number. bus: Set to 0. stream: Set to 0 for MVIP streams for switching and board management. Set to 4 for DSP streams for call control. timeslot: Set to 0 through 47 for station lines 1 through 48. The number of timeslots depends upon the specific board configuration. mode: Set to 0.

## Receiving CDI service events

When the CDI 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 CDI service and passes any event generated 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; /* Natural 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 informs the application which event occurred on which context and includes additional information specific to the event.

The CTA_EVENT structure contains the following fields:

Field | Description
--- | ---
id | Event code defined in the library header file. The event's prefix relates the event to a specific NMS Communications library of functions. For example, all CDI events are prefixed with CDIEVN_ (CDIEVN_SOMETHING_ HAPPENED). All Natural Access events are prefixed with CTAEVN_.
ctahd | C ontext handle (line handle) returned from ctaCreateContext.
timestamp | Time since the DSP was booted, in milliseconds (modulo 65536). The resolution for CX board events is 2 milliseconds. To provide a wider range, the timer alternates between even values (0, 2, 4, ...65534) and odd values (1, 3, 5, ...65535), approximately every 65 seconds.
userid | U ser-supplied ID. This field is unaltered by Natural Access and facilitates asynchronous programming. Its purpose is to correlate a context with an application object/context when events occur.
size | S ize (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 | Pointer to data returned with the event. The field contains an application process address. The event's size field contains the actual size of the buffer.
value | E vent-specific value. This field can hold a reason code or an error code.
objHd | Service client-side object handle.

## Linking with the CDI service

When building a Natural Access application that uses the CDI service, compile the program with cdidef.h and link to the cdiapi library (cdiapi.lib for Windows, libcdiapi.so for UNIX).

Refer to the Natural Access Developer's Reference Manual for more information about service implementation.