(Page 1 of 1 in this chapter) Version

Appendix C

BRI Service Events

Introduction

The BRI service employs an asynchronous programming model in order to capitalize on the concurrent processing between BX 2000 board processors and the host CPU. In response to commands executed by the application, the BRI service generates events which indicate the occurrence of certain conditions or state changes. This appendix is a summary of the events generated by the BRI service.

Event Data Structure

All events are represented as a CTA_EVENT C data structure as shown below: typedef struct { DWORD id; /* event id (BRIEVN_xxx in 'bridef.h') */ CTAHD ctahd; /* context handle */ DWORD timestamp; /* timestamp */ DWORD userid; /* user id (defined by ctaCreateContext) */ DWORD size; /* size of buffer if buffer != NULL */ /* otherwise, may contain event */ /* specific data */ void *buffer; /* buffer pointer */ DWORD value; /* Event status or event-specific data */ DWORD reserved ; /* must be 0 */ } CTA_EVENT;
This structure, returned by ctaWaitEvent, informs the application which event occurred on which CTA context, as well as including additional information specific to the event.
The CTA_EVENT structure contains the following fields:

Field

Description

id

A BRI service event code defined in the bridef.h header file. All BRI events are prefixed with BRIEVN_ (e.g., BRIEVN_SOMETHING_HAPPENED).

ctahd

Contains the context handle (the same as the one 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

The user-supplied value to ctaCreateContext. This field is unaltered by the BRI service and facilitates asynchronous programming. Its purpose is to correlate a port with an application object/context when events occur.

value

An event-specific value.

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

A pointer 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.

Field	Description
`id`	A BRI service event code defined in the `bridef.h` header file. All BRI events are prefixed with `BRIEVN_` (e.g., `BRIEVN_SOMETHING_HAPPENED`).
`ctahd`	Contains the context handle (the same as the one 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`	The user-supplied value to ctaCreateContext. This field is unaltered by the BRI service and facilitates asynchronous programming. Its purpose is to correlate a port with an application object/context when events occur.
`value`	An event-specific value.
`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`	A pointer 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.

DONE Events

A DONE event is a CT Access event informing the application that an asynchronous function has completed processing. DONE event codes are in the form BRI_function_DONE where function is the completed function (e.g., START_PROTOCOL). DONE events have no special physical or processing characteristics; they have the same physical structure and are retrieved identically as all other events.
An asynchronous function may return SUCCESS to the application when invoked and the function can later fail on the BX 2000 board. If a BX 2000 board detects an error when running a function, the BRI service delivers a DONE event to the application and the event value field contains an error code.

Events Ordered Alphabetically

The following table is an alphabetical listing of BRI events and their descriptions: Event Name Hex Decimal Description BRIEVN_ACCEPTING_CALL 0x16201d 1450013 The BRI service has entered the accepting call state. BRIEVN_ANSWERING_CALL 0x162011 1450001 Call control is answering an inbound call. BRIEVN_BOARD_ERROR 0x1620FF 1450239 Unexpected board error returned. BRIEVN_CALL_CONNECTED 0x162018 1450008 Call control is in connected state. BRIEVN_CALL_DISCONNECTED 0x162019 1450009 Call control is in disconnected state. BRIEVN_CALL_PROCEEDING 0x162015 1450005 Low-level: outbound dial done. BRIEVN_CALL_RELEASED 0x16201a 1450010 Acknowledgment of released call. BRIEVN_CALLS_BLOCKED 0x162022 1450018 Request to block now active. BRIEVN_CALLS_UNBLOCKED 0x162023 1450019 Request to unblock is completed. BRIEVN_INCOMING_CALL 0x162010 1450000 Call control has presented the application with a call. BRIEVN_PLACING_CALL 0x162014 1450004 Acknowledgment of placing call. BRIEVN_REJECTING_CALL 0x162012 1450002 Call control is rejecting an inbound call. BRIEVN_REMOTE_ALERTING 0x162016 1450006 Low-level: outbound ring detected. BRIEVN_REMOTE_ANSWERED 0x162017 1450007 Low-level: outbound answer detected. BRIEVN_STARTPROTOCOL_DONE 0x162111 1450257 Acknowledgment of start protocol. BRIEVN_STATUS_UPDATE 0x16201f 1450015 Arrival of asynchronous information about the call. BRIEVN_STOPPROTOCOL_DONE 0x162112 1450258 Acknowledgment of stop protocol.

Event Name	Hex	Decimal	Description
`BRIEVN_ACCEPTING_CALL`	`0x16201d`	`1450013`	The BRI service has entered the accepting call state.
`BRIEVN_ANSWERING_CALL`	`0x162011`	`1450001`	Call control is answering an inbound call.
`BRIEVN_BOARD_ERROR`	`0x1620FF`	`1450239`	Unexpected board error returned.
`BRIEVN_CALL_CONNECTED`	`0x162018`	`1450008`	Call control is in connected state.
`BRIEVN_CALL_DISCONNECTED`	`0x162019`	`1450009`	Call control is in disconnected state.
`BRIEVN_CALL_PROCEEDING`	`0x162015`	`1450005`	Low-level: outbound dial done.
`BRIEVN_CALL_RELEASED`	`0x16201a`	`1450010`	Acknowledgment of released call.
`BRIEVN_CALLS_BLOCKED`	`0x162022`	`1450018`	Request to block now active.
`BRIEVN_CALLS_UNBLOCKED`	`0x162023`	`1450019`	Request to unblock is completed.
`BRIEVN_INCOMING_CALL`	`0x162010`	`1450000`	Call control has presented the application with a call.
`BRIEVN_PLACING_CALL`	`0x162014`	`1450004`	Acknowledgment of placing call.
`BRIEVN_REJECTING_CALL`	`0x162012`	`1450002`	Call control is rejecting an inbound call.
`BRIEVN_REMOTE_ALERTING`	`0x162016`	`1450006`	Low-level: outbound ring detected.
`BRIEVN_REMOTE_ANSWERED`	`0x162017`	`1450007`	Low-level: outbound answer detected.
`BRIEVN_STARTPROTOCOL_DONE`	`0x162111`	`1450257`	Acknowledgment of start protocol.
`BRIEVN_STATUS_UPDATE`	`0x16201f`	`1450015`	Arrival of asynchronous information about the call.
`BRIEVN_STOPPROTOCOL_DONE`	`0x162112`	`1450258`	Acknowledgment of stop protocol.

Events Ordered Numerically

The following table is a list of events in numerical order: Hex Decimal Event Name 0x162010 1450000 BRIEVN_INCOMING_CALL 0X162011 1450001 BRIEVN_ANSWERING_CALL 0x162012 1450002 BRIEVN_REJECTING_CALL 0x162014 1450004 BRIEVN_PLACING_CALL 0x162015 1450005 BRIEVN_CALL_PROCEEDING 0x162016 1450006 BRIEVN_REMOTE_ALERTING 0x162017 1450007 BRIEVN_REMOTE_ANSWERED 0x162018 1450008 BRIEVN_CALL_CONNECTED 0x162019 1450009 BRIEVN_CALL_DISCONNECTED 0x16201a 1450010 BRIEVN_CALL_RELEASED 0x16201d 1450013 BRIEVN_ACCEPTING_CALL 0x16201f 1450015 BRIEVN_STATUS_UPDATE 0x162022 1450018 BRIEVN_CALLS_BLOCKED 0x162023 1450019 BRIEVN_CALLS_UNBLOCKED 0x1620FF 1450239 BRIEVN_BOARD_ERROR 0x162111 1450257 BRIEVN_STARTPROTOCOL_DONE 0x162112 1450258 BRIEVN_STOPPROTOCOL_DONE

Hex	Decimal	Event Name
`0x162010`	`1450000`	`BRIEVN_INCOMING_CALL`
`0X162011`	`1450001`	`BRIEVN_ANSWERING_CALL`
`0x162012`	`1450002`	`BRIEVN_REJECTING_CALL`
`0x162014`	`1450004`	`BRIEVN_PLACING_CALL`
`0x162015`	`1450005`	`BRIEVN_CALL_PROCEEDING`
`0x162016`	`1450006`	`BRIEVN_REMOTE_ALERTING`
`0x162017`	`1450007`	`BRIEVN_REMOTE_ANSWERED`
`0x162018`	`1450008`	`BRIEVN_CALL_CONNECTED`
`0x162019`	`1450009`	`BRIEVN_CALL_DISCONNECTED`
`0x16201a`	`1450010`	`BRIEVN_CALL_RELEASED`
`0x16201d`	`1450013`	`BRIEVN_ACCEPTING_CALL`
`0x16201f`	`1450015`	`BRIEVN_STATUS_UPDATE`
`0x162022`	`1450018`	`BRIEVN_CALLS_BLOCKED`
`0x162023`	`1450019`	`BRIEVN_CALLS_UNBLOCKED`
`0x1620FF`	`1450239`	`BRIEVN_BOARD_ERROR`
`0x162111`	`1450257`	`BRIEVN_STARTPROTOCOL_DONE`
`0x162112`	`1450258`	`BRIEVN_STOPPROTOCOL_DONE`

Events Ordered by Category

The following tables summarize all BRI events, briefly describing the contents of the value, size, and buffer fields (where applicable) for each.
The following fields are always assigned, regardless of the event: id ctahd timestamp userid
The remaining fields - value, size, and buffer - vary depending upon the event. They may be empty if there is no relevant information for that field for the specific event.
The buffer field is only filled if data is given to the application. Any events that yield data are footnoted in the event's size field.
The value field may contain an error code, BRIERR_xxx or CTAERR_xxx if the operation was in error when started or if the function fails.

Administrative Events


ID	Value Field	Description
`BRIEVN_BOARD_ERROR`	`BRI_REASON_ERRORCONF`	An incorrect acknowledgement to a command arrived.
	`BRI_REASON_UNEXPECTEDCONF`	An unexpected acknowledgement to a command arrived.
	`BRI_REASON_INVALIDSTATE`	An unexpected event arrived on a CTA context.
`BRIEVN_STARTPROTOCOL_DONE`	`BRI_REASON_xxx`
`BRIEVN_STOPPROTOCOL_DONE`	`BRI_REASON_xxx`

Call Control Events

ID

Value Field

Description

`BRIEVN_ACCEPTING_CALL`

`BRIEVN_ANSWERING_CALL`

`BRIEVN_CALL_CONNECTED`

`BRIEVN_CALL_DISCONNECTED`

`BRI_DIS_UNKNOWN`

No cause was specified by the network.

`BRI_DIS_NORMAL_TERMINATION`

The remote party hung up after the call was connected (after receiving `BRIEVN_CALL_CONNECTED`).

`BRI_DIS_REMOTE_ABANDONED`

The remote party hung up before the call was connected (before receiving `BRIEVN_CALL_CONNECTED`).

`BRI_DIS_MULTIPOINT_CONTENTION`

In point-to-multipoint configurations, several terminals may attempt to accept or answer the call. Only the first one will be able to establish the call.

`BRI_DIS_LAYER`1`_ERROR`

The network is not connected to the BRI trunk that is associated to the CTA context.

`BRI_DIS_LAYER`2`_ERROR`

A protocol error occurred at the ISDN layer 2 level between the board's BRI trunk and the network.

`BRI_DIS_LAYER`3`_ERROR`

A protocol error occurred at the ISDN layer 3 level between the board's BRI trunk and the network.

`BRI_DIS_CONNECT_FAILED`

The BRI service could not establish the connection. In this case, no `BRIEVN_PLACING_CALL` is sent.

`BRIEVN_CALL_PROCEEDING`

`BRIEVN_CALLS_BLOCKED`

`BRIEVN_CALLS_UNBLOCKED`

`BRIEVN_CALL_RELEASED`

`BRIEVN_INCOMING_CALL`

`BRIEVN_IN_SERVICE`

`BRIEVN_OUT_OF_SERVICE`

`BRIEVN_PLACING_CALL`

`BRIEVN_REJECTING_CALL`

`BRIEVN_REMOTE_ALERTING`

`BRIEVN_REMOTE_ANSWERED`

`BRIEVN_STATUS_UPDATE`

`CALL_STATUS_xxx`

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com