Setting up the NaturalAccess environment

Before you can call functions from the NCC library, follow these steps to set up the NaturalAccess environment:

  1. Initialize NaturalAccess

  2. Create event queues

  3. Create contexts and attach them to event queues.

  4. Open services, including NCC, on each context.

To set up a second NaturalAccess application that shares a context with the first application:

  1. Initialize the NaturalAccess application.

  2. Create event queues.

  3. Attach the application to the existing context.

Once the application has performed these tasks, it can receive events associated with the event queues it has created.

Initializing NaturalAccess

Use ctaInitialize to initialize NaturalAccess, registering the services available to the application. Specify the service and service manager names in the call to ctaInitialize. The application can open only the services initialized with ctaInitialize. Service managers are dynamic link libraries (DLLs) in Windows and shared libraries in UNIX.

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

Creating event queues and contexts

After initializing NaturalAccess, create one or more event queues by invoking ctaCreateQueue. Specify the service managers to attach to each queue. By attaching a service manager to a queue, you make that service manager available to the queue. After the services are opened, the events generated by the managed service go to the attached queue. ctaCreateQueue returns an event queue handle (ctaqueuehd) that the application uses to address the event queue.

The next step is to create a context and attach it to an event queue. Invoke ctaCreateContext and provide the queue handle (ctaqueuehd) returned from ctaCreateQueue. ctaCreateContext returns a context handle (ctahd) that the application uses when invoking NCC service line functions. Events communicated back to the application are also associated with the context.

Refer to the Dialogic® NaturalAccess™ Software Developer’s Manual for details on the programming models created by the use of contexts and event queues.

Opening services

Invoke ctaOpenServices to open services on a context. When opening a service on a context, use the substructures of the CTA_SERVICE_DESC structure to specify information about the service and the service manager, and the resources to attach to the context.

The following table shows the information to enter to start NCC on a context, assuming an implementation using an AG board:

Substructure

Parameter

Set as follows for the ADIMGR implementation of NCC

CTA_SERVICE_NAME

svcname

ncc

svcmgrname

The name of the implementation DLL for the protocols to be used: ADIMGR.

CTA_SERVICE_ADDR

N/A

Reserved for client/server usage. Initialize to 0.

CTA_SERVICE_ARGS

N/A

Not used by NCC.

CTA_MVIP_ADDR

board

The board number 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

MVIP95_LOCAL_BUS

stream

See Streams and timeslots.

timeslot

See Streams and timeslots.

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. Typically used with the NOCC protocol and allows media (for example, voice, fax) reception and transmission.

ADI_FULL_DUPLEX

This mode is both ADI_SIGNAL_DUPLEX and ADI_VOICE_DUPLEX. The port receives and transmits both inband media and out-of-band signaling. Typically used when running a network protocol on the port. Allows both voice (inband) and network signaling transmission and reception.

Streams and timeslots

When you open NCC with ADIMGR, specify a DSP address. A DSP address is specified as a complete MVIP address including a stream/timeslot pair.

The following table shows valid addresses for boards that support NCC:

Board

Stream
Bus=MVIP95_LOCAL_BUS

Timeslot

AG 2000

4

0 - 7

AG 2000C

4

0 - 23

AG 2000-BRI

4

0 - 7

CG 6060, CG 6060C

64

0 - 899*

CG 6565, CG 6565C, CG 6565E

64

0 - 899*

*The timeslot's upper limit is configurable. For information, see the board manuals.

The demonstration program ctatest verifies the proper installation and operation of the NCC API. Refer to the Dialogic® NaturalAccess™ Software Developer’s Manual for more information about ctatest.

Receiving NCC API events

When the NCC API 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 NCC and passes all generated events back to the calling function.

Events arrive in the form of the standard event data structure defined in ctadef.h. For more information, see Overview of the NCC API events.