(Page 1 of 1 in this chapter) Version

Chapter 2

DPNSS Programming Model

2.1 Introduction

2.2 CT Access Environment

: 2.2.1 Programming Model
: 2.2.2 CT Access Components
: 2.2.3 Managing Parameters in CT Access

2.3 DPNSS Application Overview

2.4 Receiving DPNSS Events

2.1 Introduction

This chapter: Provides an overview of the CT Access environment. Provides an overview of a typical DPNSS application. Explains DPNSS event handling.

2.2 CT Access Environment

A DPNSS Call Control application is built primarily on the CT Access platform. This section provides background information about CT Access and summarizes the main elements of the CT Access environment. You must have CT Access installed on your system to build applications using DPNSS software.
For more detailed information about CT Access, see the CT Access Developer's Reference Manual.

2.2.1 Programming Model

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 via 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. Chapter 5 lists all DPNSS service functions and indicates if they are synchronous or asynchronous. Characteristic 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
As shown in Figure 4, for asynchronous functions, CT Access sends a command to the service which sends a command to a telephony board. The board performs the functions and sends events to the service indicating its state (e.g., function was started, function is complete, etc.). The service sends events to CT Access, which makes them available to the application. Figure 4. Asynchronous Programming Model
Appendix B contains a complete list of DPNSS errors. Appendix C contains a complete list of DPNSS events.

Characteristic	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

2.2.2 CT Access Components

CT Access telephony functions are subdivided into groups of logically related functions, called services. Each service has a standard API. The DPNSS service is a CT Access service.
The following is a partial list of available services: Service Hardware that service can address Description Switching AG, QX, BX Controls Multi-Vendor Integration Protocol (MVIP) switch blocks on telephony boards. This service is able to drive any board providing a MVIP compliant DLL. DPNSS BX-3000 only Performs Call Control: establishes and maintains telephone network connections. Sends and receives DPNSS supplementary service messages. Voice Message AG, QX Used for playing, recording, and editing voice messages in files or memory. ADI AG, QX · Call Control: Establishing and maintaining telephone network connections. · Playing/Recording: Playing and recording voice buffers. · Call Progress: Analyzing the progression of outbound calls. · Tone Detection: Detecting tones. · Tone Generation: Generating tones. · DTMF Detection: Detecting and generating DTMF and MF tones. · Auxiliary Functions: Signaling, low-level control, and timing.
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.
Appendix B contains a complete list of DPNSS errors. Appendix C contains a complete list of DPNSS events.

Service	Hardware that service can address	Description
Switching	AG, QX, BX	Controls Multi-Vendor Integration Protocol (MVIP) switch blocks on telephony boards. This service is able to drive any board providing a MVIP compliant DLL.
DPNSS	BX-3000 only	Performs Call Control: establishes and maintains telephone network connections. Sends and receives DPNSS supplementary service messages.
Voice Message	AG, QX	Used for playing, recording, and editing voice messages in files or memory.
ADI	AG, QX	· Call Control: Establishing and maintaining telephone network connections. · Playing/Recording: Playing and recording voice buffers. · Call Progress: Analyzing the progression of outbound calls. · Tone Detection: Detecting tones. · Tone Generation: Generating tones. · DTMF Detection: Detecting and generating DTMF and MF tones. · Auxiliary Functions: Signaling, low-level control, and timing.

2.2.3 Managing Parameters in CT Access

The characteristics for CT Access services, including the DPNSS service, can be altered by modifying associated parameters. Each 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 Appendix E of this manual for detailed descriptions of DPNSS service parameters.

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.

2.3 DPNSS Application Overview

An application implementing DPNSS call control typically performs the following tasks: Figure 5. DPNSS Application Flowchart
The following is a summary of the tasks pictured in Figure 5.

In this phase...

Documented in...

The application...

Initialize CT Access

Chapter 3

· Initializes CT Access services, and creates one context for each channel.
· Makes MVIP switch connection to route BX-3000 channels on DSP resource present on other AG boards.

Start DPNSS Protocol

Chapter 3

· Calls dpnStartProtocol to start up DPNSS protocol on each CTA context.

Establish Connection

Chapter 4

· Uses DPNSS service functions such as dpnAcceptCall, dpnAnswerCall, dpnRejectCall, or dpnPlaceCall to place outgoing calls and/or receive incoming calls.

Perform Tasks

Chapter 6

· Exchanges DPNSS supplementary service messages and performs other tasks on DSP resource boards connected over the MVIP bus.

Disconnect Connection

Chapter 4

· Uses dpnReleaseCall to release the call.

Stop DPNSS Protocol

Chapter 3

· Calls dpnStopProtocol to stop the DPNSS protocol.

In this phase...	Documented in...	The application...
Initialize CT Access	Chapter 3	· Initializes CT Access services, and creates one context for each channel. · Makes MVIP switch connection to route BX-3000 channels on DSP resource present on other AG boards.
Start DPNSS Protocol	Chapter 3	· Calls dpnStartProtocol to start up DPNSS protocol on each CTA context.
Establish Connection	Chapter 4	· Uses DPNSS service functions such as dpnAcceptCall, dpnAnswerCall, dpnRejectCall, or dpnPlaceCall to place outgoing calls and/or receive incoming calls.
Perform Tasks	Chapter 6	· Exchanges DPNSS supplementary service messages and performs other tasks on DSP resource boards connected over the MVIP bus.
Disconnect Connection	Chapter 4	· Uses dpnReleaseCall to release the call.
Stop DPNSS Protocol	Chapter 3	· Calls dpnStopProtocol to stop the DPNSS protocol.

2.4 Receiving DPNSS Events

All messages and events from the DPNSS protocol are presented to the application through the standard CT Access event handling mechanism, along with standard CT Access events and any events specific to CT Access extensions. They arrive in the form of the standard CTA event data structure: typedef struct CTA_EVENT { DWORD id; /* event id (LIBEVN_xxx in 'libdef.h') */ CTAHD ctahd; /* CTA context handle */ DWORD timestamp; /* timestamp */ DWORD userid; /* user-supplied ID */ DWORD size; /* size of buffer if buffer is not NULL */ void *buffer; /* buffer pointer */ DWORD value; /* Event status or reason or other data */ DWORD reserved; /* must be 0 */ } CTA_EVENT;
The CTA_EVENT structure fields are used as follows:

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 DPNSS events are prefixed with DPNEVN_ (e.g., DPNEVN_SOMETHING_HAPPENED. All CT Access events are prefixed with CTAEVN_.

ctahd

Contains the CTA context 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 events is 1 millisecond.

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. The DPNSS service uses this buffer to pass DPNSS feature messages to the application.

value

This is an event-specific value. This field can hold a reason code or an error code.
To receive these events, a CT Access application can call ctaWaitEvent.
A comprehensive list of events is given in Appendix C.
When an asynchronous function has completed processing, a DONE event is returned. DONE event codes are in the form DPN_function_DONE where function is the completed function. DONE events have no special physical or processing characteristics; they have the same physical structure and are retrieved in the same way as all other events.
An asynchronous function may return SUCCESS to the application when invoked and the function can later fail on the BX board. If a BX board detects an error when running a function, the DPNSS service delivers a DONE event to the application and the event value field contains an error code.
Some call control-related CT Access events are unsolicited: they can occur at any time, regardless of the application's current activities. Usually, unsolicited events indicate that something has happened on the trunk. These events are summarized in Section 4.3.2.

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 DPNSS events are prefixed with `DPNEVN_` (e.g., `DPNEVN_SOMETHING_HAPPENED`. All CT Access events are prefixed with `CTAEVN_`.
`ctahd`	Contains the CTA context 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 events is 1 millisecond.
`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. The DPNSS service uses this buffer to pass DPNSS feature messages to the application.
`value`	This is an event-specific value. This field can hold a reason code or an error code.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com