(Page 1 of 1 in this chapter) Version

Chapter 2

BRI Service Programming Model

2.1 Introduction
2.2 CT Access Environment
2.2.1 CT Access Components
2.2.2 CT Access Programming Model
2.3 BRI Service Overview
2.4 Receiving BRI Events

2.1 Introduction

This chapter:

2.2 CT Access Environment

A BRI service application is built 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 the BRI service.

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

2.2.1 CT Access Components

CT Access telephony functions are subdivided into groups of logically related functions, called services. Each service has a standard API. The following services are available:
This service...

 Provides...

Switching service

 Control for MVIP switch blocks on telephony boards.

Point-to-Point Switching service

 An application programming interface (API) for making switch connections between boards connected by a telephony bus without having to specify the intervening bus timeslots.

Voice Message service

 Playing, recording and editing voice messages in files or memory.

ADI service

 · 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.

· Call Control: Establishing and maintaining telephone network connections using AG boards or QX boards.

When using the BRI service, call the BRI service call control functions. Do not call the ADI service call control functions.

· Auxiliary Functions: Signaling, low-level control, and timing.

BRI service

 Call control on BX 2000 boards only.

Parameter Management service

 Loading and managing user-supplied parameters.

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. A service may only be opened once on a CTA context.

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

2.2.2 CT Access Programming Model

CT Access employs an asynchronous programming model to take advantage of concurrent processing. When called, most functions return immediately indicating that the operation was initiated. The application may perform 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 result will arrive asynchronously via an event. If the return code is not SUCCESS, the function was never initiated, and no events associated with the function will be generated.

During execution, events are generated that indicate certain conditions or state changes. If an asynchronous function fails, CT Access delivers a DONE event to the application. The event value field contains an error code.

The following table summarizes the differences between asynchronous and synchronous functions. Chapter 5 lists all BRI service functions and indicates if they are synchronous or asynchronous.

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 7, 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 7. Asynchronous Programming Model



Refer to Appendix B for a complete list of BRI service errors, and to Appendix C for a complete list of BRI service events.






2.3	 BRI Service Overview





A BRI service application typically performs the following tasks:





Figure 8.	 BRI Service Application Flowchart




The following is a summary of the tasks pictured in Figure 8: 





 In this phase...



 The application...




 Initialize CT Access



·	 Initializes CT Access services, and creates one CTA context for each B channel.




 Initialize Protocol Stack



·	 Calls briStartProtocol to start up an ISDN protocol stack instance on each CTA context.




 Initialize Media Functions (optional)



·	 If using the ADI service for media functions, calls adiStartProtocol with nocc protocol (to disable call control functions on AG boards or QX boards).




 Establish Call



·	 Uses briAcceptCall, briAnswerCall, briRejectCall, or briPlaceCall to respectively receive incoming calls and/or place outgoing calls.




 Perform Tasks



·	 Establishes the switching between BX 2000 boards and media boards (optional).


·	 Uses functions from CT Access, or other service's APIs to play or record voice, generate or detect DTMF tones, send and receive faxes, and other tasks.




 Disconnect Call



·	 Uses briReleaseCall to release the call.




 Release DSP Resources (optional)



·	 Stops the media functions used.




 Stop Protocol Stack



·	 Calls briStopProtocol to stop the ISDN protocol stack.



















2.4	 Receiving BRI Events





All messages and events from the ISDN protocol stack 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 a standard CT Access 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 BRI events are prefixed with BRIEVN_
(e.g., BRIEVN_SOMETHING_ HAPPENED). All ADI service events are prefixed with ADIEVN_. 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. To provide this functionality, the BRI service uses the Windows function QueryPerformanceCounter if your system supports it. If your system does not support QueryPerformanceCounter, the BRI service uses GetTickCount. timestamp contains the time (in milliseconds) when the event was created since the installation of your system.


 The resolution for the BRI service events is, in the worst case, 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.


















To receive these events, a CT Access application can call ctaWaitEvent.



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.


Note:  The eventmask parameter in the BRI_START_PARMS structure dictates whether certain informational call control events are generated. For more information about this structure, refer to Appendix D.







 
    (Page 1 of 1 in this chapter)  Version




 




tech_support@nmss.com



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