COMMON-ISDN-API COMMON ISDN API Standard Interface between Application Programs and ISDN Adapters Specification Version 1.1, Profile A Date of issue: September 7, 1990 COMMON-ISDN-API Table of Contents 1 Introduction ........................................1 2 Features ............................................1 3 Overview ............................................2 3.1 Message queues ......................................3 3.2 Operations on message queues ........................3 3.2.1 Registering an application ..........................3 3.2.2 Messages from the application to the COMMON ISDN API 4 3.2.3 Messages from the COMMON ISDN API to the application 4 3.2.4 Releasing an application ............................4 3.3 General message protocol ............................4 3.4 Message structure ...................................5 3.5 Structure of the data area ..........................6 3.6 Other functions .....................................6 3.7 Manufacturer-specific expansions ....................6 4 Messages and functions ..............................7 4.1 Operations on message queues ........................7 4.2 Messages ............................................7 4.3 Other operations ....................................8 5 Message descriptions ................................9 5.1 General messages ...................................11 5.2 Protocol level 2 ...................................36 5.3 Protocol level 3 ...................................39 5.4 Telephone service ..................................64 5.5 Manufacturer-specific messages .....................66 5.6 Other functions ....................................70 5.6.1 Manufacturer identification ........................70 5.6.2 COMMON ISDN API version number .....................70 5.6.3 COMMON ISDN API serial number ......................70 6 Flowcharts .........................................71 Annex A - Implementation with different operating systems Annex B - Profile COMMON-ISDN-API 1 Introduction The COMMON ISDN API enables applications to access ISDN adapter boards in a straightforward manner and allows unre- stricted use of their functions through a standardized soft- ware interface. Applications that use this interface will not be affected by future expansions or hardware changes. The COMMON ISDN API makes the changes transparent to the user application. Futu- re expansions that retain compatibility with the existing software basis are possible. This means that it is possible to link higher-level proto- cols and specific ISDN applications to the ISDN via a defi- ned, standardized interface, which is supported by different ISDN adapter manufacturers. The COMMON ISDN API provides a basis for modular applications development in ISDN systems. 2 Features The COMMON ISDN API includes a number of important features. 1 Support for the basic call features, such as call setup and cleardown and display of the caller's ISDN number 2 Support for several B-channels for voice and/or data connections 3 Support for several logical channels for data links wit- hin a physical connection 4 Possibility of selecting different services and proto- cols during connection setup and incoming call 5 Transparent interface for protocols above Layer 3 6 Support for one or more S0 bus connections on one or more ISDN adapters 7 Non-operating-system-specific approach for different operating systems 8 Asynchronous mechanism (high throughput) 9 Defined mechanism for manufacturer-specific expansions 10 Simple implementation in a minimal configuration with a supported ISDN controller - 1 - COMMON-ISDN-API 3 Overview From its logical viewpoint, the COMMON ISDN API provides a connection between any number of application programs (ap- plications) and any number of ISDN drivers and ISDN control- lers via a standard interface. The applications can be free- ly assigned to drivers and controllers. The COMMON ISDN API enables both one application to be used for several drivers and controllers and several applications to be used for sin- gle drivers. The applications can use different protocols at different protocol levels, the COMMON ISDN API providing the selection mechanism needed for this. The COMMON ISDN API also ab- stracts from different protocol variants, thus creating a standard network access. The basic concept can be adapted to both national and international variants. The profile speci- fication (see Annex for Profile A) defines the representa- tion of data elements in the signaling channel. All connection information relevant to the application such as charging information, display messages, etc., is availa- ble at all times. The COMMON ISDN API is an entity. This specification defines and standardizes both the entity and the protocol between an application and the COMMON ISDN API. The protocol between the COMMON ISDN API and the supported drivers is manufacturer-specific. The COMMON ISDN API covers protocol levels 1 to 3 (physical layer, data link layer, network layer) for the B-channel. The COMMON ISDN API interface lies above level 3 and thus provides the reference point for applications and higher- level protocols. The X.75 protocol in accordance with T.90 is prescribed for layer 2, and implementation in accordance with T.70 NL for layer 3. Defined as options are a transpa- rent layer 2 and separate access to the protocols T.90 with LLC mechanism, ISO 8208 and transparent at level 3, as well as support for the telephone service. The description below first presents the basic mechanism used for the COMMON ISDN API. It is based on message queues provided for the exchange of commands and data. The opera- tions on these message queues are described, then the struc- ture of the exchanged messages is indicated. There follows a description of other functions for identification, and the mechanism for manufacturer-specific expansions is explained. - 2 - COMMON-ISDN-API 3.1 Message queues Communication between an application program and the COMMON ISDN API takes place via message queues. As diagram 2 shows, there is precisely one message queue for the COMMON ISDN API itself and for each registered application program. Messages are exchanged between the applications programs and the COM- MON ISDN API by way of these message queues. For high-volume data transfer, the messages are used for indication purposes only, and the data is transferred via a data area common to the application and the COMMON ISDN API. An exception to this is data transfer in the D-channel with the aid of user information; in this case the data is directly linked with the relevant message. The COMMON ISDN API itself and the supported drivers ensure message processing in the order of their arrival. An application issues commands to an ISDN driver or control- ler by placing an appropriate message in the COMMON ISDN API message queue. In the reverse direction, a message from an ISDN driver or controller is transferred to the message queue of the application which it is addressing. This method, particularly as used in higher-level protocols and multifunctional systems, allows flexible access by seve- ral applications to different ISDN drivers and controllers. It also provides a powerful mechanism for processing events that arrive asynchronously. The message queue structure is not specified but is manufacturer-dependent and is transparent to the application program. The necessary access operations are defined by the COMMON ISDN API. The memory needed for an application's mes- sage queue is provided by the application. 3.2 Operations on message queues The message queues described represent the link between an application and the COMMON ISDN API and the connected ISDN drivers and controllers. Only four operations are required to use the message queues. The operations on the message queues are not restricted to a particular system specifica- tion. Their respective characteristics and implementation are operating-system-specific. At the same time, these operations form the complete inter- face which has to be matched to the particular operating sy- stem. The four operations are described below. 3.2.1 Registering an application Before an application can issue commands to the COMMON ISDN API, it must be registered with the COMMON ISDN API. The API - 3 - COMMON-ISDN-API _REGISTER function is used to do this. The COMMON ISDN API uses this function to assign a unique system-wide applica- tion number (APPL-ID) to the application. In this context, system-wide means unique within a network. The message queue for the application is set up at the same time. The applica- tion makes the storage space needed for this available to the COMMON ISDN API. 3.2.2 Messages from the application to the COMMON ISDN API All messages from an application to the COMMON ISDN API are put in the message queue of the COMMON ISDN API. The opera- tion API_PUT_MESSAGE is provided for this purpose. When this operation is used, the application transfers the message. If the COMMON ISDN API message queue cannot accept any more messages, the operation API_PUT_MESSAGE delivers an error value. 3.2.3 Messages from the COMMON ISDN API to the application The COMMON ISDN API manages a message queue for each appli- cation; in it, the COMMON ISDN API or the ISDN driver and controller put all messages to the application. The opera- tion API_GET_MESSAGE is provided for receiving new messages. When this operation is used, it returns the received messa- ge. If the application does not read out the messages quick- ly enough, the queue may overflow. In this case subsequent messages from the COMMON ISDN API are lost. The application is informed of this error on the next API_GET_MESSAGE opera- tion. 3.2.4 Releasing an application After an application has registered, it must always release itself from the COMMON ISDN API. This can be done at any time with the API_RELEASE operation. Note that when this is done the application must clear down all existing connec- tions. Releasing the application frees the previously used message queue. 3.3 General message protocol Communication between the application and the COMMON ISDN API always uses the following general protocol: Each message is given a message number. Two different sets of numbers are used, depending on the initiator: between 0x0000 and 0x7FFF in the case of the application and between 0x8000 and 0xFFFF in the case of the COMMON ISDN API. - 4 - COMMON-ISDN-API When the application sends a request ( _REQ) to the COMMON ISDN API, a message number from the application's set of numbers is used. The COMMON ISDN API confirms this request with a corresponding confirmation (_CONF), using the same message number as in the request. When a asynchronous event is shown to the application by an indication (_IND), a message number from the COMMON ISDN API's set of numbers in used. The application replies to the indication with the corresponding response (_RESP), using the same message number as in the indication. Protocol violations by the application that cannot be dis- played are ignored. 3.4 Message structure All messages exchanged between the application and the COM- MON ISDN API consist of a fixed-length header and a data area of variable length. The specified format is used for both transfer directions. The data in the message is packed in bytes. ÚÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄ Ä Ä ÄÂÄÄÄÄÄÄÄÄÄ¿ ³ Message-³ Message-³ Message-³ ³ Message-³ ³ Header ³ Daten ³ Daten ³ ³ Daten ³ ÀÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄ Ä Ä ÄÁÄÄÄÄÄÄÄÄÄÙ The message header has the following structure: ÚÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄ¿ ³ Total ³ APPL-ID ³ Command ³ Sub- ³ Message-³ ³ Length ³ ³ ³ command ³ number ³ ÀÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÙ The meanings are as follows: Total length Word, total length of the message in- cluding header in bytes APPL-ID Word, identification of the applica- tion. The APPL_ID assigned to the ap- plication by the COMMON ISDN API in the API_REGISTER operation is used. Command Byte, command Subcommand Byte, command subdivision Messagenumber Word, unique number assigned to each message (see also 3.3) - 5 - 3.5 Structure of the data area COMMON-ISDN-API The data area consists of one, more than one, or no parame- ters. A distinction is made between variable and fixed- length parameter structures. Hence there exist: for variable-length type STRUCT ÚÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Parameter-³ Parameter-³ ³ length ³ data ³ ÀÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÙ Diagram 5: Variable-length parameter coding The meanings are as follows: Parameter length Byte, size of data area in bytes Parameter data Byte(s), data area and for basic fixed-length types BYTE, WORD and DWORD ÚÄÄÄÄÄÄÄÄÄÄÄ¿ ³ Parameter-³ ³ data ³ ÀÄÄÄÄÄÄÄÄÄÄÄÙ Diagram 6: Parameter coding of basic types The arrangement of the basic data types in memory are shown in the Annex. The number of parameters transferred in a message and their data types are defined implicitly by the particular message. The maximum length of a message is 180 bytes. 3.6 Other functions Various additional functions, such as manufacturer indica- tion, determination of the version number, and a procedure for serial numbers, are provided. As this is a local function of the COMMON ISDN API, it is called as described under message queues under MS-DOS (see below). 3.7 Manufacturer-specific expansions The manufacturer-specific expansions of the COMMON ISDN API presented here are possible without altering the basic structure. They are identified by an appropriate com- mand/subcommand field in the message. - 6 - COMMON-ISDN-API 4. Messages and functions 4.1 Operations on message queues API_REGISTER - Register an application API_RELEASE - Release an application API_PUT_MESSAGE - Transfer message to the API API_GET_MESSAGE - Fetch message from the API 4.2 Messages CONNECT_REQ - Set up B-channel connection CONNECT_IND - Indicate a call on the B-channel CONNECT_INFO_REQ - Send further dialing information CONNECT_ACTIVE_IND - Indicate B-channel through- connected DISCONNECT_REQ - Clear down B-channel connection DISCONNECT_IND - Indicate cleardown on the B-channel LISTEN_REQ - Set the processed service GET_PARAMS_REQ - Request B-channel parameters INFO_REQ - Set the information to be reported INFO_IND - Report B-channel events DATA_REQ - Send data in the D-channel DATA_IND - Receive data in the D-channel SELECT_B2_PROTOCOL_REQ - Select level 2 protocol SELECT_B3_PROTOCOL_REQ - Select level 3 protocol LISTEN_B3_REQ - Set level 3 processing CONNECT_B3_REQ - Set up level 3 connection CONNECT_B3_IND - Indicate a level 3 connection CONNECT_B3_ACTIVE_IND - Indicate level 3 through-connected DISCONNECT_B3_REQ - Clear down a level 3 connection DISCONNECT_B3_IND - Indicate a level 3 cleardown GET_B3_PARAMS_REQ - Request level 3 parameters DATA_B3_REQ - Send level 3 data DATA_B3_IND - Indicate incoming data RESET_REQ - Reset a connection RESET_IND - Reset indication, connection HANDSET_IND - Reports of handset events MANUFACTURER_REQ - Manufacturer-specific request MANUFACTURER_IND - Manufacturer-specific indication List 4.2 only contains the messages that are issued by the initiator. The corresponding confirmations and responses are not given separately in this list. - 7 - COMMON-ISDN-API 4.3 Other operations API_SET_SIGNAL - Set signaling function API_DEINSTALL - Remove COMMON ISDN API API_GET_MANUFACTURER - Fetch manufacturer identification API_GET_VERSION - Fetch API version number ZPI_GET_SERIAL NUMBER - Fetch (optional) serial number API_MANUFACTURER - Manufacturer-specific function - 8 - COMMON-ISDN-API 5 Message descriptions The messages exchanged between the application and the COM- MON ISDN API are described below. The following basic types are converted to the specified message format: Type definition: BYTE := 8-bit parameter, no sign. The sequen- ce of bits is described in Annex A. WORD := 16-bit parameter, no sign. The se- quence of bits is described in Annex A. DWORD := 32-bit parameter, no sign. The se- quence of bits is described in Annex A. STRUCT := Structure (field) with variable length. The first byte of the field indicates the length of the field (cf. Structure of the data area). Reserved bits in bit fields must be assigned the value 0. Notation Hexadecimal values: hexadecimal values are given in the standard notation of the programming language C in the form 0xhh (bytes) and 0xhhhh (words). Binary values: binary values are given in the form of a bit field followed by a "b". The least significant bit is placed on the right. Example: 00110010b (binary) is equivalent to 0x32 (hexadeci- mal) and corresponds to 50 (decimal). Terms and abbreviations used Application ID: Unique system-wide identification of an application for the COMMON ISDN API. Controller: A controller is a hardware unit used to gain access to the ISDN network. The controller supports none, one, or more than one data and/or telephone links. Controllers are numbers in as- cending order starting at 0. - 9 - COMMON-ISDN-API DLPD Data Link Protocol Description. Structure with protocol-dependent ad- ditional information. ff: And the following pages ffs: For further study NCCI: Network Control Connection Identi- fier. An NCCI describes a logical connection on level 3. If the appro- priate protocol is implemented in the COMMON ISDN API, selection of a mul- tiplexed level 3 is possible. This allows several NCCIs NCPD: Network Control Protocol Description. Structure with protocol-dependent ad- ditional information. NCPI: Network Control Protocol Information. Protocol-dependent additional infor- mation about a network connection. PLCI: Physical Link Connection Identifier. A PLCI describes a physical connec- tion between two users. It is supp- lied by the COMMON ISDN API on initi- ation of connection setup. A PLCI in- itially describes a signaling link. When activated, the signaling channel is assigned a physical channel. A PCLI is always linked to a controller and an application program. - 10 - COMMON-ISDN-API 5.1 General messages CONNECT_REQ - Set up B-channel connection Description This messages initiates setup of a physical B-channel link to the stipulated destination address (destination address as per profile A). The B-channel parameter (coding as per profile A) can be used to specify the desired B-channel. The info mask is used to stipulate which of the W elements are to be displayed in the message INFO_IND. The parameter source EAZ (EAZ corresponds to profile A) in- dicates the EAZ of the initiator. The parameter outgoing service and outgoing service add in- dicate the service to be used in accordance with profile A. Message Command/subcommand: 0x02 / 0x00 BYTE Controller BYTE B-channel DWORD Info mask BYTE Outgoing service BYTE Outgoing service add. BYTE Source EAZ STRUCT Destination address Parameters Controller Transparent (can be set in applica- tion) B-channel Bit field, channel identification as per profile A Info mask Bit field with following coding: [0] Charging information [1] Date [2] Display [3] User-user information [4] Cause [5] Status of called party [6 to 31] Reserved Outgoing service Service indicator as per profile A Outgoing service add. Additional info as per profile A Source EAZ EAZ as per profile A Destination address Destination address as per profile A Note The info mask bit field specifies which W elements are to trigger an INFO_IND when they are received - 11 - COMMON-ISDN-API CONNECT_CONF Description This message confirms the initiation of call setup. This connection is thus assigned a PLCI which serves as an iden- tifier in further processing. Any errors are returned to the parameter info. Message Command/subcommand: 0x02 / 0x01 WORD PLCI WORD Info Parameter PLCI Physical Link Connection Identifier, transparent Info 0: Connect initiated 0x2001 Incorrect controller 0x3101 B-channel incorrectly coded 0x3102 Info mask incorrectly coded Note The connection is in the setup phase at this point in time. Subsequent switching is indicated by the message CONNECT_AC- TIVE_IND. - 12 - COMMON-ISDN-API CONNECT_IND - Indicate an incoming call on the B-channel Description This message indicates the request for call setup from a re- mote station. At this point the call is in the setup phase, no physical connection having been established yet. Subse- quent switching of the B-channel is indicated by the message CONNECT_ACTIVE_IND For the incoming call, a PLCI is assigned which can be used to identify and activate the call in the following. The ad- dresses and the wanted service are indicated by the parame- ters caller address, requested EAZ, requested service and requested service add Message Command/subcommand: 0x02 / 0x02 WORD PLCI BYTE Controller BYTE Requested service BYTE Requested service add BYTE Requested EAZ STRUCT Caller address Parameter PLCI Physical Link Connection Identifier, transparent Controller Transparent Requested service Service indicator as per profile A Req. service a. Additional info as per profile A Requested EAZ EAZ as per profile A Caller address Caller address as per profile A Note To activate the signaling of incoming calls, the message LI- STEN_REQ must be sent beforehand for each controller to be used. - 13 - COMMON-ISDN-API CONNECT_RESP Description This message is used to accept or reject an incoming call for the application. The incoming call is identified via pa- rameter PLCI. The parameter reject is used to accept or re- ject the call. A value unequal to 0 is treated as the cause as per profile A. Message Command/subcommand: 0x02 / 0x03 WORD PLCI BYTE Reject Parameters PLCI Physical Link Connection Identifier, transparent Connect 0: Accept call <>0: Reject call, value reserved (cause) - 14 - COMMON-ISDN-API CONNECT_INFO_REQ - Transmit further dialing information Description This message permits overlap sending. It can be used repea- tedly following a CONNECT_REQ up to indication of the con- cluding message CONNECT_ACTIVE_IND. Message Command/subcommand: 0x03 / 0x02 WORD PLCI STRUCT Destination address Parameters PLCI Physical Link Connection Identifier, transparent Destination address Destination address as per profile A Note For teletex and fax services, this message may not be used, since block dialing is prescribed for these services. - 15 - COMMON-ISDN-API CONNECT_INFO_CONF Description This message confirms acceptance of CONNECT_INFO_REQ. Message Command/subcommand: 0x09 / 0x01 WORD PLCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Initiates transmission of dialing information 0x2002 Incorrect PLCI - 16 - COMMON-ISDN-API CONNECT_ACTIVE_IND - Indicate, B-channel switched through Description This message indicates the switching through of a B-channel. The connection that is identified via the PLCI is thus set up correctly. The address of the far-end station is notified in the parameter connected address. Message Command/subcommand: 0x03 / 0x02 WORD PLCI STRUCT Connected address Parameters PLCI Physical Link Connection Identifier, transparent Connected address Connected address as per profile A - 17 - COMMON-ISDN-API CONNECT_ACTIVE_RESP Description With this message, the application confirms notification of the switching of a B-channel. Message Command/subcommand: 0x03 / 0x03 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent Note This message has no function. - 18 - COMMON-ISDN-API DISCONNECT_REQ - Clear down B-channel connection Description This message initiates cleardown of a B-channel. The B- channel is identified via the stipulated PLCI. The parameter cause can be used to indicate a cause of cleardown (coding as per profile A). Message Command/subcommand: 0x04 / 0x00 WORD PLCI BYTE Cause Parameter PLCI Physical Link Connection Identifier, transparent Cause Cause as per profile A (user to network) Note If there are level 3 connections on the activated B-channel at this stage, cleardown of all level 3 connections set up on the B-channel is indicated via the appropriate B3_DISCONNECT_IND. Cleardown of the B-channel is then started. - 19 - COMMON-ISDN-API DISCONNECT_CONF Description This message confirms the initiation of cleardown of a B- channel. Any faults are coded in the parameter info. Message Command/subcommand: 0x04 / 0x01 WORD PLCI BYTE Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Disconnect initiated 0x2002 Incorrect PLCI - 20 - COMMON-ISDN-API DISCONNECT_IND - Indicate a cleardown on the B-channel Description This message indicates cleardown of the B channel. The B- channel is identified via the stipulated PLCI. The parameter info indicates a reason. Message Command/subcommand: 0x04 / 0x02 WORD PLCI WORD Info Parameter PLCI Physical Link Connection Identifier, transparent Info 0x3301 Error on setup of D-channel, level 1 0x3302 Error on setup of D-channel, level 2 0x3305 Abort D-channel, level 1 0x3306 Abort D-channel, level 2 0x3307 Abort D-channel, level 3 0x34xx Abort by network. The cause is coded in xx as per profile A. - 21 - COMMON-ISDN-API DISCONNECT_RESP Description With this message, the application confirms cleardown of the B-channel. Message Command/subcommand: 0x04 / 0x03 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent Note With this message the PLCI is enabled. - 22 - COMMON-ISDN-API LISTEN_REQ - Set services Description As preset, incoming calls are not notified to an applica- tion. The message LISTEN_REQ can be used to select which of the incoming calls should be indicated to the application via the message CONNECT_IND. The selection is made according to two criteria. The parame- ter serviced EAZ mask allows the application to select which EAZ(s) are to be processed. The reaction is possible on one, several, or all of the EAZs. The parameter serviced SI mask allows the application to se- lect which of the services identified via the associated service indicators are to be processed. The W elements to be notified are preset via the info mask for the treatment of incoming calls. The preset applies to all calls received via the stipulated controller. The message LISTEN_REQ can be used as often as required. The final setting always applies to each application. If inco- ming calls are not to be notified, the parameters serviced EAZ mask and serviced SI mask must be set to 0. Mesage Command/subcommand: 0x05 / 0x00 BYTE Controller DWORD Info mask WORD Serviced EAZ mask WORD Serviced SI mask Parameters Controller Transparent (can be set in applica- tion) Info mask Bit field, coding as follows: [0] Charging information [1] Date [2] Display [3] User-user information [4] Cause [5] Status of called party [6 to 31] Reserved Serviced EAZ mask Bit field [0 to 9] to indicate which EAZs can be serviced; the bit number corresponds to the EAZ. Bit number 0 is for a global call. Several EAZs can be serviced by one application. The serviced EAZ mask parameter has the following codings: Response to global call only - 23 - COMMON-ISDN-API 000000001b Response to precisely one EAZ 000000010b to 100000000b Response to global call and precisely one EAZ 000000011b to 100000001b Response to global call and all EAZs 1111111111b Serviced SI mask Bit field [0 to 15] to indicate which services can be operated. One appli- cation can serve several services. The bit numbers are coded as follows: [0] Videophone [1] Telephony [2] a/b services [3] X.21 services [4] Fax (Group 4) [5] Videotex (64 kbit/s) [6] - [7] Data transmission (64 kbit/s) [8] X.25 services [9] Teletex 64 [10] Mixed mode [11] - [12] - [13] Remote control [14] Graphic telephone service [15] Videotex (new standard) The additional byte in the service indicator (see profile A) is not eva- luated and is forwarded transparently to the application. Note The info mask bit field specifies which W elements are to trigger an INFO_IND when they are received. - 24 - COMMON-ISDN-API LISTEN_CONF Description This message confirms the preset for the treatment of inco- ming calls. Any errors are coded in the parameter info. Message Command/subcommand: 0x05 / 0x01 BYTE Controller WORD Info Parameter Controller Transparent (can be set in applica- tion) Info 0: Listen is active 0x2001 Incorrect controller 0x3102 Info mask incorrectly coded 0x3103 Serviced EAZ mask incorrectly coded 0x3104 Serviced SI mask incorrectly coded 0x3202 Conflict between registra- ations - 25 - COMMON-ISDN-API GET_PARAMS_REQ - Request B-channel parameters Description This message can be used to determine the values of various parameters of a B-channel connection. The B-channel connec- tion is identified by the specified PLCI. Message Command/subcommand: 0x06 / 0x00 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent - 26 - COMMON-ISDN-API GET_PARAMS_CONF Description This message returns the current parameters of a B-channel connection. The parameter B3 link count contains the number of level 3 connections on this physical B-channel connec- tion. The meaning of the other parameters is described in the message CONNECT_REQ or CONNECT_ACTIVE_IND. Message Command/subcommand: 0x06 / 0x01 WORD PLCI BYTE Controller BYTE B-channel WORD Info BYTE B3 link count BYTE Service BYTE Service add BYTE Serviced EAZ STRUCT Connected address Parameters PLCI Physical Link Connection Identifier, Controller transparent (can be set in applica- tion) B-channel Bit field, channel identification as per profile A Info 0: Parameter value valid 0x2002 Incorrect PLCI 0x3204 PLCI not active B3 link count Number of B3 connections currently being handled via this B link Service Service indicator as per profile A Service add Additional info as per profile A Serviced EAZ EAZ as per profile A Connected address Connected address as per profile A - 27 - COMMON-ISDN-API INFO_REQ - Set the B-channel information to be reported Description This message sets the W elements relating to the B-channel that are to notified to the application. The individual W elements are stipulated via the parameter info mask. The pa- rameter PLCI identifies the B-channel connection. An INFO_REQ can be used as often as required during a con- nection. The last stipulated info mask always applies. The indication of W elements can be disabled by an info mask with the value 0. Message Command/subcommand: 0x07 / 0x00 WORD PLCI DWORD Info mask Parameters PLCI Physical Link Connection Identifier, transparent Info mask Bit field, coding as follows: [0] Charging information [1] Date [2] Display [3] User-user information [4] Cause [5] Status of called party [6 to 31] Reserved Note The info mask bit field specifies which W elements are to trigger an INFO_IND when they are received. - 28 - COMMON-ISDN-API INFO_CONF Description This message confirms the setting of the W elements to be reported. Any errors are coded in the parameter info. Message Command/subcommand: 0x07 / 0x01 WORD PLCI BYTE Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: W elements selected 0x2002 Incorrect PLCI 0x3102 Info mask incorrectly coded - 29 - COMMON-ISDN-API INFO_IND - Report B-channel events Description This message indicates an event for a B-channel as expressed by a W element (info element). The B-channel connection is identified via the stipulated PLCI. The reported W element is identified via the parameter info number (coding as per profile A). The value of the W element is indicated in the parameter info element (coding as per profile A). Message Command/Subcommand: 0x07 / 0x02 WORD PLCI WORD Info number STRUCT Info element Parameters PLCI Physical Link Connection Identifier, transparent Info number Identification of the W element as per profile A Info element W-element-dependent structure Note An individual INFO_IND is displayed for each W element. - 30 - COMMON-ISDN-API INFO_RESP Description With this message the application confirms the receipt of an INFO_IND. Message Command/Subcommand: 0x07 / 0x03 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent Note This message has no function. - 31 - COMMON-ISDN-API DATA_REQ - Send data in the D-channel with USER-INFO messa- ges Description This message can be used to transmit date in the form of user-user information. The B-channel is identified via the PLCI. The data to be transmitted is stipulated in a data structure. Message Command/subcommand: 0x08 / 0x00 WORD PLCI STRUCT User data Parameters PLCI Physical Link Connection Identifier, transparent User data User-user information as per profile A Note This function is not supported in all networks. - 32 - COMMON-ISDN-API DATA_CONF Description This message confirms acceptance of the DATA_REQ. Any errors are coded in the parameter info. Message Command/subcommand: 0x08 / 0x01 WORD PLCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Transmission of user infor- mation initiated 0x2002 Incorrect PLCI 0x3203 Function is not supported 0x3204 PLCI not active - 33 - COMMON-ISDN-API DATA_IND - Receive data in the D-channel via USER-INFO mes- sages Description This message displays incoming data transmitted in the form of user-user information. The B-channel connection is iden- tified via the PLCI. The incoming data is supplied in a user data structure. Message Command/subcommand: 0x08 / 0x02 WORD PLCI STRUCT User data Parameter PLCI Physical Link Connection Identifier, transparent User Data User-user information as per profile A Note This function is not supported in all networks. - 34 - COMMON-ISDN-API DATA_RESP Description With this message the application confirms receipt of a DA- TA_IND. Message Command/subcommand: 0x08 / 0x03 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent Note This message has no function. - 35 - COMMON-ISDN-API 5.2 Protocol level 2 SELECT_B2_PROTOCOL_REQ - Select level 2 protocol Description This message selects the level 2 protocol to be used. The B- channel connection is identified via the PLCI parameter. The protocol is identified via the B2 protocol. If protocol se- lection is not performed for a PLCI, the preset is adopted. Additional protocol-independent information can be set via the parameter DLPD. Message Command/subcommand: 0x40 / 0x00 WORD PLCI BYTE B2 protocol STRUCT DLPD Parameters PLCI Physical Link Connection Identifier, transparent B2 protocol Protocol identification: 0x01 X.75 SLP basic operation mode, with implementation rules as per T.90 (default) 0x02 Transparent HDLC with bit stuffing, frame detection and CRC check 0x03 Bit transparent 0x04 SNA-SDLC 0x05 X.75 Vtx 0x.. Reserved DLPD Data Link Protocol Description structure with the following additio- nal information: WORD Data length BYTE Link address A BYTE Link address B BYTE Module mode BYTE Window size STRUCT XID Data length Max. length of a level 2 information field Link address A Link address A Link address B Link address B Modulo mode 8: Modulo 8 128: Modulo 128 Window size Window size XID Structure for XID information in SNA protocol - 36 - COMMON-ISDN-API Preset for different level 2 protocols: B2 protocol 0x01 0x02 0x03 0x04 0x05 Data length 130 512 512 262 130 Link address A 0x03 N/A N/A 0xC1 0x03 Link address B 0x01 N/A N/A N/A 0x01 Modulo mode 8 N/A N/A 8 8 Window size 7 N/A N/A 7 7 XID N/A N/A N/A * N/A *: Structure of length 0 N/A not applicable Note If SELECT_B2_PROTOCOL_REQ is not called, the preset protocol X.75 is adopted. The structure DLPD with length 0 selects the preset of the selected level 2 protocol. Initialization and processing of level 2 is performed implicitly together with the messages of level 3. The X.75 protocol stipulated for this protocol level must be supported by all COMMON ISDN API implementations, together with the associated preset values of the DLPD. The data length can be set up to 2048 bytes. If further protocols are supported on level 2 by the particular implementat-ion, the associated preset values of the DLPD must also be supported. - 37 - COMMON-ISDN-API SELECT_B2_PROTOCOL_CONF Description This message confirms the protocol setting. Any errors are coded in the parameter info. Message Command/subcommand: 0x40 / 0x01 WORD PLCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Protocol selected 0x2002 Incorrect PLCI 0x3105 B2 protocol incorrect 0x3106 DLPD incorrect 0x3206 B2 protocol is not suppor- ted 0x3207 Changeover of B2 protocol not possible in this state 0x320A Parameters used not suppor- ted in DLPD - 38 - COMMON-ISDN-API 5.3 Protocol level 3 SELECT_B3_PROTOCOL_REQ - Select level 3 protocol Description With this message it is possible to select the level 3 pro- tocol to be used. The B-channel connection is identified by way of the parameter PLCI. The protocol is selected by sti- pulating the B3 protocol. If no protocol is selected for a PLCI, the preset value is adopted. The parameter NCPD can be used to set additional protocol-independent information. Message Command/subcommand: 0x80 / 0x00 WORD PLCI BYTE B3 protocol STRUCT NCPD Parameters PLCI Physical Link Connection Identifier, transparent B3 protocol Protocol identification: 0x01 T70 NL for line switching (CSPDN) (default) 0x02 ISO 8208 (DTE/DTE) 0x03 Level 3 as per T.90, Appen- dix II 0x04 Transparent 0x.. Reserved NCPD Network control protocol description with protocol-dependent additional information: WORD LIC WORD HIC WORD LTC WORD HTC WORD LOC WORD HOC BYTE Modulo mode LIC ffs. HIC ffs. LTC ffs. HTC ffs. LOC ffs. HOC ffs. Modulo mode 8: Modulo 8 128: Modulo 128 Preset for different level 3 protocols: - 39 - COMMON-ISDN-API B3 protocol 0x01 0x02 0x03 0x04 LIC 130 512 512 262 HIC N/A ffs. ffs. N/A LTC N/A ffs. ffs. N/A LTC N/A ffs. ffs. N/A LOC N/A ffs. ffs. N/A HOC N/A ffs. ffs. N/A Modulo mode 8 ffs. ffs. 8 N/A not applicable Note The preset protocol T70 NL is used without calling SE- LECT_B3_PROTOCOL_REQ. The structure NCPD with length 0 se- lects the preset value of the selected level 3 protocol. For transparent level 3, activation, deactivation and the ex- change of data is performed with level 2 via the correspon- ding level 3 operations. The parameter NCPI used in the messages CONNECT_B3_REQ, CON- NECT_B3_IND, CONNECT_B3_RESP, CONNECT_B3_ACTIVE_IND, DISCON- NECT_B3_REQ and DISCONNECT_B3_IND has no meaning for the T70 NL and transparent protocols and is transferred as a struc- ture with length 0. If the ISO 8208 protocols or level 3 as per T.90 are selected, the parameter NCPI contains the con- tents of the X.25 PLP packets according to the packet type. The reset procedure varies according to the protocol set. For protocols T70 NL, ISO 8208 and T.90, the reset procedure in executed in accordance with the protocol recommendations. For the transparent protocol, a RESET_B3_REQ is answered with a successful RESET_B3_CONF without further consequen- ces. The T70 NL protocol stipulated as preset for this protocol level must be supported with the associated preset values of the NCPD by all COMMON ISDN API implementations. If further protocols are implemented on level 3 by the particular ap- plication, the associated preset values of the NCPD must also be supported. - 40 - COMMON-ISDN-API SELECT_B3_PROTOCOL_CONF Description This message confirms the protocol setting. Any errors are coded in the parameter info. Message Command/subcommand: 0x81 / 0x01 WORD PLCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Protocol selected 0x2002 Incorrect PLCI 0x3107 B3 protocol incorrect 0x3108 NCPD incorrect 0x3208 B3 protocol is not suppor- ted 0x3209 Changeover of B3 protocol in this state not possible 0x320B Parameters used in NCPD are not supported - 41 - COMMON-ISDN-API LISTEN_B3_REQ - Set up level 3 connection Description As preset, incoming calls on level 3 of an application are not reported. The message LISTEN_B3_REQ can be used to report incoming calls on level 3. The B-channel connection is identified via the PLCI. A LI- STEN_B3_REQ can thus be sent only when a PLCI is available. There are no other restrictions for the time at which this message can be sent to the API. The effect of the LISTEN_B3_REQ is not cancelled until the associated PLCI becomes invalid, i.e until the layer 1 con- nection in the network is cleared down. Message Command/subcommand: 0x81 / 0x00 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent - 42 - COMMON-ISDN-API LISTEN_B3_CONF Description This message confirms the preset value for treatment of in- coming calls on level 3. Any errors are coded in the parame- ter Info. Message Command/subcommand: 0x81 / 0x01 WORD PLCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent Info 0: Listen is active 0x2002 Incorrect PLCI - 43 - COMMON-ISDN-API CONNECT_B3_REQ - Setup of the level 3 connection Description This message initiates the setup of a level 3 connection. The B-channel connection is identified via the parameter PLCI. Additional protocol-dependent information can be transferred with the parameter NCPI. Message Command/subcommand: 0x82 / 0x00 WORD PLCI STRUCT NCPI Parameters PLCI Physical Link Connection Identifier, transparent NCPI Network control protocol information, structure with additional protocol- dependent information. Note The meaning of the parameter NCPI depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 44 - COMMON-ISDN-API CONNECT_B3_CONF Description With this message the initiation of a level 3 connection se- tup is confirmed. This connection is thus assigned an NCCI, by way of which it is subsequently identified. Any errors are supplied in the parameter info. Message Command/subcommand: 0x82 / 0x01 WORD PLCI WORD NCCI WORD Info Parameters PLCI Physical Link Connection Identifier, transparent NCCI Network Control Connection Identi- fier, transparent Info 0: Connect initiated 0x2002 Incorrect PLCI 0x3109 NCPI incorrect 0x3204 PLCI not active 0x320C Parameters used not suppor- ted in NCPI Note The connection is in the setup phase at this stage. The switching is indicated later by the message CON- NECT_B3_ACTIVE_IND. - 45 - COMMON-ISDN-API CONNECT_B3_IND - Indicate an incoming level 3 connection Description This message displays an incoming call for a level 3 connec- tion. At this point in the message the connection is in the setup phase. The subsequent switching is indicated by the message CONNECT_B3_ACTIVE_IND. For the incoming call an NCCI is assigned, by way of which this call is subsequently identified and can be addressed. Additional protocol-dependent information can be transferred with parameter NCPI. To activate the reporting of incoming calls, the message LI- STEN_B3_REQ must first be sent for each PLCI to be used. Message Command/subcommand: 0x82 / 0x02 WORD NCCI WORD PLCI STRUCT NCPI Parameters NCCI Network Control Connection Identifier, transparent PLCI Physical Link Connection Identifier, transparent NCPI Network Control Protocol Information, structure with protocol-dependent ad- ditional information Note The meaning of the parameter NCPI depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 46 - COMMON-ISDN-API CONNECT_B3_RESP Description With this message, the application accepts or rejects an in- coming call on level 3. The incoming call is identified via the parameter NCCI. The call can be accepted or rejected via the parameter reject. The parameter NCPI can be used to transfer additional protocol-dependent information. Message Command/subcommand: 0x82 / 0x03 WORD NCCI BYTE Reject STRUCT NCPI Parameter NCCI Network Control Connection Identifier, transparent NCPI Network Control Protocol Information, structure with protocol-dependent ad- ditional information. Reject 0: Accept call <>0: Reject call Note The meaning of the parameter NCPI depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 47 - COMMON-ISDN-API CONNECT_B3_ACTIVE_IND - Indicate B-channel level 3 is active Description This message displays the switching of the level 3 connec- tion. The connection is identified via the parameter NCCI. The parameter NCPI can be used to transfer additional protocol-dependent information. Message Command/subcommand: 0x83 / 0x02 WORD NCCI STRUCT NCPI Parameters NCCI Network Control Connection Identifier, transparent NCPI Network Control Protocol Information, structure with protocol-dependent ad- ditional information. Note The meaning of the parameter NCPI depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 48 - COMMON-ISDN-API CONNECT_B3_ACTIVE_RESP Description With this message the application confirms the switching of a level 3 connection. Message Command/subcommand: 0x83 / 0x03 WORD NCCI Parameter NCCI Network Control Connection Identifier, transparent Note This message has no function. - 49 - COMMON-ISDN-API DISCONNECT_B3_REQ - Clear down a level 3 connection Description This message initiates the cleardown of a level 3 connec- tion. The connection is identified via the NCCI stipulated. The parameter NCPI can be used to transfer additional protocol-dependent information. Message Command/subcommand: 0x84 / 0x00 WORD NCCI STRUCT NCPI Parameters NCCI Network Control Connection Identifier, transparent NCPI Network Control Protocol Information, structure with additional protocol- dependent information. Note The meaning of the parameter NCPI depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 50 - COMMON-ISDN-API DISCONNECT_B3_CONF Description With this message the initiation of the connection setup is confirmed. Any errors are coded in the parameter info. Message Command/subcommand: 0x84 / 0x01 WORD NCCI WORD Info Parameters NCCI Network Control Connection Identifier, transparent Info 0: Disconnect initiated 0x2003 Incorrect NCCI 0x3109 NCPI incorrect 0x320C Parameters used in NCPI not supported DISCONNECT_B3_IND - Indicate cleardown of a level 3 connec- tion Description This message displays the cleardown of a level 3 connection. The connection is identified via the stipulated NCCI. The parameter NCPI can be used to transfer additional protocol- dependent information. Message Command/subcommand: 0x84 / 0x02 WORD NCCI WORD Info STRUCT NCPI Parameters NCCI Network Control Connection Identifier, transparent Info 0x3303 Error during setup of B- channel level 1 0x3304 Error during setup of B- channel level 2 0x3308 Abort B-channel level 1 0x3309 Abort B-channel level 2 0x330A Abort B-channel level 3 NCPI Network Control Protocol Information, structure with additional protocol- dependent information. Note - 51 - COMMON-ISDN-API The meaning of the NCPI parameter depends on the protocol used. See SELECT_B3_PROTOCOL_REQ. - 52 - COMMON-ISDN-API DISCONNECT_B3_RESP Description With this message the application confirms cleardown of a level 3 connection. Message Command/subcommand: 0x84 / 0x03 WORD NCCI Parameter NCCI Network Control Connection Identifier,transparent Note The NCCI is released with this message. - 53 - COMMON-ISDN-API GET_B3_PARAMS_REQ - Request level 3 parameters Description This message can be used to request additional information on a level 3 connection. The level 3 connection is identi- fied via the NCCI. Message Command/subcommand: 0x85 / 0x00 WORD NCCI Parameter NCCI Network Control Connection Identifier, transparent - 54 - COMMON-ISDN-API GET_B3_PARAMS_CONF Description This message supplies the additional information on a level 3 connection as requested with GET_B3_PARAMS_REQ. The level 3 connection is identified via the NCCI. The parameter PLCI indicates the B-channel connection carrying the level 3 con- nection. Any errors are coded in the parameter info. Message Command/subcommand: 0x85 / 0x00 WORD NCCI WORD PLCI WORD Info Parameters NCCI Network Control Connection Identifier, transparent PLCI Physical Link Connection Identifier, transparent Info 0: Parameter available 0x2003 Incorrect NCCI 0x3205 NCCI not active - 55 - COMMON-ISDN-API DATA_B3_REQ - Send level 3 data Description This message sends data on a level 3 connection. The level 3 connection is identified by way of the NCCI. The length of the data area to be sent is stipulated via the parameter data length. The data to be sent is referenced via the parameter data. The data is thus not part of the message. The application issues a block number for this data area by way of the parameter number. On subsequent confirmation by a DATA_B3_CONF, this block number is also supplied. It is possible to set the additional information, such as more-data, delivery-confirmation, etc., via the parameter flags. The stipulated flags are not supported by all proto- cols. Message Command/subcommand: 0x86 / 0x00 WORD NCCI WORD Data length DWORD Data BYTE Number WORD Flags Parameters NCCI Network Control Connection Identifier, transparent Data length Size of data area to be sent Data Pointer to the data to be sent Number Block number, transparent for the COMMON ISDN API, but referenced in DATA_B3_CONF Flags [0] Qualifier bit [1] More-data bit [2] Delivery confirmation bit [3 to 15] Reserved Note The data area only counts as free if the COMMON ISDN API has sent a corresponding DATA_B3_CONF. The data transfer does not support assembly functions. - 56 - COMMON-ISDN-API DATA_B3_CONF Description This message confirms the acceptance of a data package to be sent. The level 3 connection is identified by the parameter NCCI. The parameter number supplies the block number used by the application in the associated DATA_B3_REQ as a reference to the transferred data area. Message Command/subcommand: 0x86 / 0x01 WORD NCCI BYTE Number WORD Info Parameters NCCI Network Control Connection Identifier, transparent Number Block number, reference to number in corresponding DATA_B3_REQ Info 0: Data transmission initiated 0x2003 Incorrect NCCI 0x310A Incorrectly coded flags 0x3205 NCCI not active 0x320D Data length not supported - 57 - COMMON-ISDN-API DATA_B3_IND - Indicate incoming level 3 data Description This message displays incoming data on a level 3 connection. The level 3 connection is identified via the NCCI. The length of the incoming data area is stipulated via the pa- rameter data length. The incoming data to be sent is referenced via the parameter data. The data is thus not part of the message. The COMMON ISDN API issues a block number for this data area via the parameter number. On subsequent confirmation by a DATA_B3_RESP, this block number must also be supplied by the application. Additional information, such as more-data, delivery- confirmation, etc., is supplied by way of the parameter flags. The stipulated flags are not supported by all proto- cols. Message Command/subcommand: 0x86 / 0x02 WORD NCCI WORD Data length DWORD Data BYTE Number WORD Flags Parameters NCCI Network Control Connection Identifier, transparent Data Pointer to data received Data length Size of data area received Number Block number, continuous, referenced in DATA_B3_RESP Flags [0] Qualifier bit [1] More-data bit [2] Delivery confirmation bit [3 to 15] Reserved Note The data area only counts as free for the COMMON ISDN API if the application program has sent a corresponding DA- TA_B3_CONF. The data transfer does not support reassembly functions. - 58 - COMMON-ISDN-API DATA_B3_RESP Description With this message the application confirms acceptance of an incoming data package. The level 3 connection is identified by the parameter NCCI. The parameter number stipulates the block number used by the COMMON ISDN API in the associated DATA_B3_IND as the reference to the transferred data area. Message Command/subcommand: 0x86 / 0x03 WORD NCCI BYTE Number Parameters NCCI Network Control Connection Identifier, transparent Number Block number, reference to number in corresponding DATA_B3_IND - 59 - COMMON-ISDN-API RESET_B3_REQ - Reset a connection / controller Description With this message the specified level 3 connection is reset. The level 3 connection is identified by way of an NCCI. Message Command/subcommand: 0x01 / 0x00 WORD NCCI Parameter NCCI Network Control Connection Identifier, transparent Note The reaction to a RESET_B3_REQ is dependent on the protocol employed. See also SELECT_B3_PROTOCOL_REQ. - 60 - COMMON-ISDN-API RESET_B3_CONF Description With this message the resetting of a level 3 connection is indicated. Message Command/subcommand: 0x01 / 0x01 WORD NCCI WORD Info Parameters NCCI Network Control Connection Identifier, transparent Info 0: Reset executed 0x2003 NCCI incorrect 0x330A Abort B-channel level 3 0x330C Reestablish B-channel level 3 Note If level 3 implementation does not provide for a reesta- blish, the corresponding connection is cleared down; this is reported in the parameter info. - 61 - COMMON-ISDN-API RESET_B3_IND - Display connection reset Description With this message the resetting of a level 3 connection is signalled. The level 3 connection is identified by way of an NCCI. Message Command/subcommand: 0x01 / 0x02 WORD NCCI Parameter NCCI Network Control Connection Identifier, transparent - 62 - COMMON-ISDN-API RESET_B3_RESP Description With this message the application confirms the resetting of a level 3 connection. Message Command/subcommand: 0x01 / 0x03 WORD NCCI Parameter NCCI Network Control Connection Identifier, transparent Note This message has no function. - 63 - COMMON-ISDN-API 5.4 Telephone service HANDSET_IND - Report handset events Description The message HANDSET_IND transfers the events that occur on a connected telephone set. The telephone set here is taken to be an autonomous unit, i.e. the telephone service can be used at any time, even without the application program. In addition, it is also possible to link the set to an applica- tion program, which is then informed of all events occurring at the telephone set and can also setup and clear down con- nections independently. Message Command/subcommand: 0x87 / 0x02 WORD PLCI BYTE Controller BYTE Status Parameters Controller Transparent PLCI Physical Link Connection Identifier, transparent Status IA5 characters '0'..'9','#','*','a','b','c','d': selected characters '+' : Handset off-hook ' - ' : Handset on-hook Note A telephone set is coupled to an application program under the following conditions: 1 A LISTEN_REQ for the telephone service has been performed for the corresponding controller, or: 2 The application has set up a connection for the telephone service with the message CONNECT_REQ. As long as the asso- ciated PLCI is valid, the events at the telephone set are reported. The "+" and "-" signs relate to status changes, they do not describe states. - 64 - COMMON-ISDN-API HANDSET_RESP Description With this message the application confirms events at the te- lephone set. Message Command/subcommand: 0x87 / 0x03 WORD PLCI Parameter PLCI Physical Link Connection Identifier, transparent Note This message has no function. - 65 - COMMON-ISDN-API 5.5 Manufacturer-specific messages The manufacturer-specific messages are described below. Only the protocol is specified; information about the contents and the associated functions must be obtained from the manu- facturer. MANUFACTURER_REQ - manufacturer-specific request Message Command/subcommand: 0xFF / 0x00 Parameter Manufacturer-specific - 66 - COMMON-ISDN-API MANUFACTURER_CONF Message Command/subcommand: 0xFF / 0x01 Parameter Manufacturer-specific - 67 - COMMON-ISDN-API MANUFACTURER_IND - Manufacturer-specific indication Message Command/subcommand: 0xFF / 0x02 Parameter Manufacturer-specific - 68 - COMMON-ISDN-API MANUFACTURER_RESP Message Command/subcommand: 0xFF / 0x03 Parameter Manufacturer-specific - 69 - COMMON-ISDN-API 5.6 Other functions There are other local operations in addition to the message operations. Since these operations are operating-system-dependent, exam- ples of their implementation under MS-DOS are described in Annex A, Section 1, where the operations are dealt with in principle. 5.6.1 Manufacturer identification Manufacturer identification is provided in plain text in AS- CII coding. The end of the identification is indicated by a 0 byte. The maximum length of a manufacturer identification is 64 bytes. Examples of manufacturer identifications are given below: - AVM-GmbH - Version 1.0, revision 1.0 - Stollmann GmbH - Systec It is proposed to add a version and revision number in plain text to the manufacturer identification. The format for this information can be ascertained from the manufacturer concer- ned. 5.6.2 COMMON ISDN API version number The version number of the COMMON ISDN API is supplied in plain text in the format "Version 1.1, Profile A". This can optionally be followed by a manufactur-er's own revision number and a date. The end is indicated with a 0 byte. 5.6.3 COMMON ISDN API serial number The (optional) serial number is provided in plain text in the form of a 7-digit number. If no serial number is to be used, the buffer must be returned empty. The end is indica- ted with a 0 byte. - 70 - COMMON-ISDN-API 6 Flowcharts For the specification of the flowcharts please ask for the written copy of the COMMON ISDN API specification. - 71 - COMMON-ISDN-API COMMON-ISDN-API Annex A ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Implementation with different operating systems Version 1.1 COMMON-ISDN-API 1. Implementation under MS-DOS As MS-DOS does not provide any multitasking facilities, the COMMON ISDN API is incorporated into the system as a back- ground driver (terminate and stay resident). The interface between the application and the COMMON ISDN API is implemen- ted by way of a software interrupt. The vector used for this must be configurable both in the COMMON ISDN API and in the application. The default value for the software interrupt is 241 (0xF1). If another value is to be used, it can be speci- fied as a parameter when the COMMON ISDN API is called. The functions described above are defined by appropriate re- gister assignments at this software interrupt interface. The return values are supplied in register AX. The contents of all registers not used are retained. The COMMON ISDN API requires a maximum stack area of 512 by- tes for the execution of all the functions incorporated. This stack area must be made availabe to the application program. Implementation of the software interrupt The software interrupt for the COMMON ISDN API is defined according to the BIOS interrupt chaining structure. API PROC FAR ;ISDN API interrupt service JMP SHORT DOIT ;Jump to start of routine O_API DD ? ;chained interrupt DW 424BH ;interrupt chaining signature DB 80H ;first in chain flag DB 'IA' ;CAPI signature DOIT: The characters 'IA' can be requested by the application at offset 9 on the basis of this structure. Representation of a pointer The pointer stipulated in messages DATA_B3_REQ and DA- TA_B3_IND is implemented as a FAR pointer under MS DOS. Annex A - 1 - COMMON-ISDN-API Memory layout of basic data types ³ low-order word (adress n) ³ ³ ³ ³<-- low order ³ ³ ³ ³<------ Byte 0 ------->³<------ Byte 1 ------->³ ³ ³ ³ ÚÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄ¿ ³ ³ 7³ 6³ 5³ 4³ 3³ 2³ 1³ 0³ ³ ÀÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÙ ³ ³ ³ ³ ÚÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄ¿ ³ 7³ 6³ 5³ 4³ 3³ 2³ 1³ 0³15³14³13³12³11³10³ 9³ 8³ ÀÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÙ ³ ³ ³ ÚÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂ ³ 7³ 6³ 5³ 4³ 3³ 2³ 1³ 0³15³14³13³12³11³10³ 9³ 8³ ÀÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁ ³ low-order word (adress n+1) ³ ³ ³ ³ higher order-->³ ³ ³ ³<------ Byte 2 ------->³<------ Byte 3 ------->³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ³ ÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄÂÄÄ¿ ³23³22³21³20³19³18³17³16³31³30³29³28³27³26³25³24³ ÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÁÄÄÙ Fig. 1: Memory layout Note: The figures in the boxes are bit numbers. The numbe- ring scheme starts at the low-order bit (0). 1.1 Message operations under MS-DOS API_REGISTER - Registration of an application with the COM- MON ISDN API Description This is the function the application uses to report its pre- sence to the COMMON ISDN API. In doing so, the application Annex A - 2 - COMMON-ISDN-API provides the COMMON ISDN API with a memory area. A FAR poin- ter to this memory area is transferred in registers ES:BX. The size of the memory area is calculated according to the following formula: ( 180 * CX ) + ( DX * SI * DI ) The minimum number of messages that can be stored before data is lost is transferred to the CX register. In the DX register the application indicates the maximum number of level 3 connections opened simultaneously. An at- tempt to open more level 3 connections than stipulated here can be acknowledged with an error message by means of COMMON ISDN API. In the SI register the application sets the maximum number of received B3 data blocks that can be reported to the ap- plication simultaneously. The number of simultaneously avai- lable B3 data blocks has a decisive effect on the throughput of B3 data in the system. and should be between 2 and 7. There must be room for a B3 data block at least. In the DI register the application sets the maximum size of the B3 data to be transmitted and received. The setting of protocols that process larger packets, and the tranmis- sion/reception of larger packets can be acknowledged with an error message by the COMMON ISDN API. The application number is supplied in the AX register. In the event of an error, the AX register is returned with the value 0. The cause of the error is held in the BX register in this case. Parameters AH 0x01 ES:BX FAR pointer to a memory block provi- ded by the application. This memory area can be used by the COMMON ISDN API to manage the message queue of the application. In addition, the COMMON ISDN API can provide the re- ceived level 3 data in this memory area. CX No. of messages that can be stored before loss of data. DX Maximum no. of level 3 connections SI No. of B3 data blocks available si- multaneously DI Maximum size of a B3 data block Annex A - 3 - COMMON-ISDN-API Return value AX 0x000 Registration error, cause of error in BX register <>0 Application no. (Appl-ID) 0x1001 Registration error Note The maximum length of a message is defined as 180. If the application has opened a maximum of one level 3 connection simultaneously and the standard protocols are used, the fol- lowing register assignment is recommended: CX =10, DX = 1, SI = 7, DI = 130 The resulting memory requirement is 2710 bytes. Annex A - 4 - COMMON-ISDN-API API_RELEASE - Release an application from the COMMON ISDN API Description The application uses this function to log off from the COM- MON ISDN API. The memory area indicated in the API_REGISTER thus becomes free. The application is identified by way of the application number in the DX register. Any error that occur are returned in the AX register. Parameters AH 0x02 DX Application number Return value AX 0x0000 No error 0x1002 Incorrect application number Annex A - 5 - COMMON-ISDN-API API_PUT_MESSAGE - Transfer message to the COMMON ISDN API Description With this function, the application transfers a message to the COMMON ISDN API. A FAR pointer is transferred to the message in the ES:BX registers. The application is identi- fied via the application number in the DX register. Any er- rors that occur are returned in the AX register. Parameters AH 0x03 DX Application number ES:BX FAR pointer to the message Return value AX 0x00 No error 0x01 Message too small or messa- ge number incorrectly coded 0x1004 Incorrect command or sub- command 0x1005 Message queue full Note After API_PUT_MESSAGE the application can again use the me- mory area for the message. Annex A - 6 - COMMON-ISDN-API API_GET_MESSAGE - Fetch message from COMMON ISDN API Description With this function, the application retrieves a message from the COMMON ISDN API. The application can only retrieve those messages intended for the stipulated application number. A FAR pointer is set to the message in the ES:BX registers. If there is no message for the application, the function imme- diately returns to the AX register with a corresponding er- ror value. The application is identified via the application number in the DX register. Any errors that occur are retur- ned to the AX register. Parameters AH 0x04 DX Application number Return values AX 0x0000 No error 0x1002 Incorrect application num- ber 0x1006 Message queue was empty 0x1007 At least one message to the application has been lost, since the message queue was full. ES:BX FAR pointer to the message Note The message may be invalidated the next time API_GET_MESSAGE is called Annex A - 7 - COMMON-ISDN-API 1.2 Other functions under MS-DOS API_SET_SIGNAL - Set address of a signaling function Description The application can use this function to activate use of the signaling function. A FAR pointer to a signaling function is specified in the ES:BX registers. The signaling function can be deactivated by an API_SET_SIGNAL with register assignment ES:BX = 0000:0000. The application is identified via the application number in the DX register. Any errors that occurred are returned in the AX register. Parameters AH 0x05 DX Application number ES:BX FAR pointer to signaling function Return value AX 0 No error 0x1002 Invalid application number Note This signaling function settable with this function is cal- led by the COMMON ISDN API in the same manner as an inter- rupt. The flags are on the stack, the interrupts disabled. The signaling function must be terminated with IRET. None of the registers may be changed. At the time of calling, 32 by- tes are available on the stack. Care must be taken to ensure that this function can be cal- led at any time, e.g. even when an MS-DOS call is being pro- cessed. Annex A - 8 - COMMON-ISDN-API API_DEINSTALL - Remove the COMMON ISDN API Descirption The COMMON ISDN API is removed from memory and the memory area is released. The controllers are reset to their initial status. All ISDN connections, except for telephone connec- tions, on level 1 are released. If one or more application programs is registered with the COMMON ISDN API, the call API_DEINSTALL is terminated with an error value. In this case, setting the parameter Force to 0x001 can be used to force deinstallation. Parameters AH 0x06 BX Force 0x0000 Normal deinstallation 0x001 Forcible deinstallation Return value AX 0 No error 0x1008 Error during deinstallation Note If other application programs that call the COMMON ISDN API after deinstallation are installed, the results are not de- fined. Annex A - 9 - COMMON-ISDN-API API_GET_MANUFACTURER - Fetch manufacturer identification Description With this function, the application determines the manufac- turer identification of the COMMON ISDN API. In registers ES:BX a FAR pointer is transferred to a data area of a least 64 bytes. The manufacturer identification is present in this data area after the function has been executed. The end is indicated by a 0 byte. Parameters AH 0xF0 ES:BX FAR pointer to buffer (at least 64 bytes in size) Return value ES:BX Manufacturer identification with AS- CII coding. The end of the identifi- cation is indicated with a 0 byte. API_GET_VERSION - Fetch version number of the COMMON ISDN API Description With this function the application determines the version of the COMMON ISDN API. In registers ES:BX a FAR pointer is transferred to a data area of a least 64 bytes. The version is present in this data area in the form "Version 1.1, Pro- file A ..." after the function has been executed. The end is indicated by a 0 byte. Parameters AH 0xF1 ES:BX FAR pointer to buffer (at least 64 bytes in size) Return value ES:BX The version number of the COMMON ISDN API is returned in plain text in the form Version 1.1, Profile A. It may optionally be followed by a revision number and date. The end of the ver- sion number is indicated with a 0 byte. Annex A - 10 - COMMON-ISDN-API API_GET_SERIAL_NUMBER - Fetch (optional) serial number Description With this function, the application determines the (optio- nal) serial number of the COMMON ISDN API. In registers ES:BX a FAR pointer is transferred to a data area of a least 64 bytes. The serial number is present in this data area in the form of a seven-digit number after the function has been executed. The end is indicated by a 0 byte. If no serial number is supplied, the end of the serial number is marked in the first digit position. Parameters AH 0xF2 ES:BX FAR pointer to buffer (at least 64 bytes in size) Return value ES:BX The (optional) serial number is re- turned in plain text in the form of a 7-digit number. If no serial number is to be used, a 0 byte must be writ- ten at the first position in the buf- fer. The end of the serial number is indicated with a 0 byte. Annex A - 11 - COMMON-ISDN-API API_MANUFACTURER - Manufacturer-specific function Description This function is manufacturer-specific. Parameter AH 0xFF Use of the other registers is manufacturer-specific. Return value Manufacturer-specific. Annex A - 12 - COMMON-ISDN-API COMMON-ISDN-API Annex B ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Profile Version 1.1 COMMON-ISDN-API 1. Profile of the COMMON ISDN API The different signaling protocols used internationally in ISDN systems differ particularly with respect to their re- presentation of data. Accordingly, within the COMMON ISDN API the data representation is defined with profiles, in which the necessary decis This ensures that the COMMON ISDN API can be adapted to fu- ture expansions and modifications of the data representa- tion. At present, profile A provides referencing to 1TR6. Annex B - 1 - COMMON-ISDN-API 1.1 Profile A - Representation in accordance with 1TR6 Data element Reference ------------------------------------------------- Additional byte of service ind. 1 TR 3, Part 5 Chapter 3.2.3.4.5.3 Octet 4 Caller address 1 TR 3, Part 5 Chapter 3.2.3.4.4.10 Octet 3ff Cause 1 TR 3, Part 5 Chapter 3.2.3.4.4.4 Octet 3 Channel identification 1 TR 3, Part 5 Chapter 3.2.3.4.4.7 Octet 3 Charging information 1 TR 3, Part 5 Chapter 3.2.3.4.5.4 Octet 3ff. Connected address 1 TR 3, Part 5 Chapter 3.2.3.4.4.5 Octet 3ff. Date 1 TR 3, Part 5 Chapter 3.2.3.4.5.5 Octet 3ff. Destination address 1 TR, Part 5 Chapter 3.2.3.4.4.11 Display 1 TR 3, Part 5 Chapter 3.2.3.4.4.9 EAZ IA5 character, '0' to '9' 1 TR 3, Part 5 Chapter 3.2.3.4.3, Table 3-60b Annex B - 2 - COMMON-ISDN-API Data element Reference ---------------------------------------------------- Info number bits 0 to 7: Number of W element 1 TR 3, Part 5 Chapter 3.2.3.4.4ff bits 8 to 10: Code set 1 TR 3, Part 5 Chapter 3.2.3.4. ff Service indicator 1 TR 3, Part 5 Chapter 3.2.3.4.5.3 Octet 3 Status of called party 1 TR 3, Part 5 Chapter 3.2.3.4.4.3 Octet 3 Type/plan 1 TR 3, Part 5 Chapter 3.2.3.4.4.11 Octet 3 User-user information 1 TR 3, Part 5 Chapter 3.2.3.4.4.15 Octet 3ff Annex B - 3 - COMMON-ISDN-API This documentation has been prepared with great care. Never- theless, it may contain certain errors and inconsistencies. The right to incorporate modifications in the interests of technological progress is reserved. Protected trademarks are not identified as such in this do- cumentation. The fact that such identification is not provi- ded does not signify that the name may be used freely. This document may be copied and distributed, provided the publication details are stated. Publisher: ISDN-PC working group of the german Deutsche Bundespost TELEKOM and the companies AVM, Stollmann and Systec Editor: AVM Berlin GmbH Voltastraáe 5 D-1000 Berlin 65 Tel: 030/46 45 051 Fax: 030/46 45 056 Annex B - 4 -  .