WinISDN

An Open Specification for ISDN voice and data communications under Microsoft Windows

Last edited 2 February 1995

Authors:

Amatzia Ben-Artzi - NetManage, Inc,
Mark Fedor - Performance Systems International
Ed Klingman - ISDN*tek, Inc.
Tmima Koren - NetManage, Inc.
Dieter Giessler - ISDN*tek, Inc.

Introduction

The following document is a proposed open standard for a set of APIs for direct access to ISDN adapter cards used on IBM compatible PCs running the Microsoft Windows operating system. This proposed standard set of APIs may be used to create a driver for ISDN cards called WinISDN.DLL. The advantage of this driver is that it features direct communications to the ISDN card, avoiding the problems and limitations associated with either Ethernet card emulation, or COM port diversion. The WinISDN driver allows an application to use a dialer to initiate a connection, but achieve block at a time rather than byte at a time serial style communications. This mode of operation also allows an application to take advantage of the Point to Point Protocol (PPP) that is an integral part of TCP/IP communications packages, thus avoiding the requirement to supply it as a part of the driver.

ISDN Connect to Internet:

The following sequence of function calls is sufficient to establish an ISDN connection and pass packets across it:

It is very useful for the application to know when the connection is established. This can be achieved by using the function ISDNSetEventMask() setting the event ISDN_EVENT_CONNECT. The application will be notified by the WINISDN driver when the connection is established.

ISDN Connection from Peer:

While the above functions are sufficient for Internet access (beneath a TCPIP/PPP application) it is also desirable to receive ISDN calls from a peer. This can be achieved using the following functions:

Again, it is very useful for the application to get notification about incoming connections. This can be achieved by using the function ISDNSetEventMask() setting the event ISDN_EVENT_ACCEPT. The application will be notified by the WINISDN driver about incoming connections.

Basic Functions

WinISDN was initially created to simplify data communications over ISDN. The WinISDN.DLL transparently encapsulates data packets of any type with HDLC framing. In addition to HDLC packet transfer across ISDN B-channels, WinISDN supports streaming data, for Voice and Video applications.

Advanced Functions

Finally, for those applications that demand it, access to the ISDN protocol is granted. These extensions enable the use of ISDN Supplementary Services associated with Voice communications, including HOLD, CONFERENCE, REDIRECT, and other Q.932 functions. These same extensions allow the use of third party control such as Automated Call Distribution, etc. The full use of these capabilities demands more from the application, and an effort has been made to improve compatibility with both TAPI and CAPI standards, in order to facilitate the mapping into WinISDN functions from either of these.

Table of APIs:

The following are obsolete:

*** ISDNDiagnose() -- replaced by: ISDNSetBoardEventMask()
*** ISDNReset() -- replaced by: ISDNSetRequest( ISDN_REQ_RESET_BOARD )
*** ISDNGetDiagnostics() -- replaced by: ISDNReadCallControl()
*** ISDNListen() -- replaced by: ISDNListenForConnection()

These functions are replaced by equivalent functionality, for example ISDNReset() is now achieved via the ISDN_REQ_RESET_BOARD command issued by ISDNSetRequest(). ISDNGetDiagnostics() has been renamed ISDNReadCallControl(). The three original functions still exist in order not to ‘break’ applications that depend upon them, but their use is not recommended for new applications.

ISDNOpen()

int FAR PASCAL ISDNOpen (int iBoardID, char FAR* lpConfig);

The application may pass NULL as the lpConfig parameter if the application does not care to get the configuration data.

This function is responsible for initializing the ISDN board.

This MUST be the first function called to address an ISDN board.

This function may be called more than once. The first time actually initializes the board. Subsequent calls are counted. The structure pointed to by lpConfig is returned each call.

RETURN:

The Return value is a positive integer if initialization was successful: this number is a count of the difference between the successful ISDNOpen() and ISDNClose() calls issued for this board. It is always >= 1. If the call failed, an error code (which is a negative number) is returned to represent failure information.

ISDNClose()

int FAR PASCAL ISDNClose (int iBoardID);

This function is responsible for closing the board. There must be a call to ISDNClose() for every call to ISDNOpen(). Only the final ISDNClose() does the actual close.

RETURN:

The Return value is an integer if closing was successful. This number is a count of the difference between the successful ISDNOpen() and ISDNClose() calls issued for this board. It is always >= 0. If the call failed, an error code (which is a negative number) is returned to represent the failure.

ISDNConnect()

int FAR PASCAL ISDNConnect (char FAR* lpCallStruct, char FAR * lpEvent);

struct isdn_call {
} FAR* lpCallStruct;

This function is responsible for establishing an ISDN connection on a given board. The isdn_call structure is used as both input and output. On entry the application fills in the data structure with values to be used for connection. On the return the WINISDN.DLL will fill in the data structure with the values that will actually be used in the connection. The call_type variable represents how many B channels are to be used for a connection or if a D channel is to be used in the case of ISDN_D_16K. This function is asynchronous and should return immediately with the handle describing a connection. The application can poll the connection status by calling ISDNGetStatus() or can be notified of the connection completion via the event notification mechanism. If event notification is used, connection errors should be returned using that mechanism. The listen_mask field is not used by ISDNConnect().

Values to be used in defining call types for ISDNConnect.

These values represent the call_type parameter.

The structure below is used to pass in the event notification.

struct isdn_notify {

The event Mask is a bitwise OR of the events defined above. If win_handle and msg_value fields are not NULL the ISDN Driver should post a message ‘msg_value’ to the window ‘win_handle’. The wParam of the PostMessage() should be used to hold the ISDN connection handle. The low word of the lParam will hold the event that triggered the message. The high word of the lParam is used to return the error code. In case of failure ISDNGetStatus() can be used to get more detailed failure information. The Event notification mechanism is identical to the one described in the ISDNSetEventMask(). Refer to the ISDNSetEventMask() section for the more detailed description.

RETURN:

This function returns a unique handle representing the connection. A negative return value indicates a function failure, such as a bad parameter value.

NOTE:

Because multiple concurrent sessions can be established on a single board it is important to note that the event notification mechanism is connection oriented and not board oriented. Thus the given event data structure is tied to the connection handle, which is returned by the ISDNConnect() and not to the iBoardID which is passed into the ISDNConnect().

ISDNDisconnect()

int FAR PASCAL ISDNDisconnect (int iHandle);

This function disconnects a currently active call or releases a handle assigned by ISDNListenForConnection that has not yet received an incoming call.

ISDNDisconnect must also be called to release internal resources if the remote side disconnects a call. The event notification mechanism or polling with ISDNGetStatus are used to determine a remote disconnect.

When this function succeeds, the specified handle is discarded, and will not be valid for other function calls.

RETURN:

This function returns ISDN_RETCD_SUCCESS or a negative error code.

ISDNListenForConnection()

int FAR PASCAL ISDNListenForConnection( char FAR* lpCallStruct, char FAR* lpEvent)

This function enables the reception of an incoming call. It creates a connection handle in anticipation of making a connection and allocates structures for the call within the driver.

ISDNListenForConnection() may be called multiple times, and will return a unique connection handle for each call, so long as the driver can support the number of outstanding connections requested. For each call, the application must specify the board_id or line_id in the isdn_call structure, along with the listen_mask, indicating which types of calls the application would like to accept.

If this is the first ISDNListenForConnection() call for a particular line_id or listen_mask, the function returns the connection handle as the return value. Note that the connection handle is also written into the isdn_call structure.

If this is not the first call to ISDNListenForConnection() for a particular line_id or listen_mask, the connection handle is still returned in the isdn_call structure, but the function returns ISDN_RETCD_PREVIOUSLISTENER as the error code, as a warning that this connection handle will not receive the first notification of an incoming call.

With multiple connection handles defined, an incoming call will be given to the first handle that matches the listen_mask and line_id specified. That handle has the option of accepting the call with ISDNAccept(), which will produce a live connection, or rejecting the call with ISDNReject(), which will disconnect the call without first making a connection, avoiding any billing charges for unwanted calls. Note that the call is not offerred to any other connection handles, it is accepted or rejected by the first handle that matches the calling parameters.

Once a call has been accepted or rejected, the next incoming call is offered to the next connection handle that matches the calling parameters. This process will continue until all outstanding connection handles have been serviced by incoming calls.

The application may also specify the desired event notification mechanism for the call, using the isdn_notify structure. If a win_handle and msg_value are specified, or if a callback is specified, and the ISDN_EVENT_ACCEPT bit is set, the specified notification process will be used to indicate the receipt of an incoming call. Otherwise, the WinISDN.DLL driver will not perform any notification.

However the application can poll for incoming calls, using the connection handle and ISDNGetStatus(). When an incoming call is received, the driver will fill in relevant entries in the isdn_status structure for that call, including the call_type and call_state values. A polling application may use a non-null call_state to determine when a call is present. Once an incoming call has been processed by ISDNAccept() the connection handle represents an active call. After an ISDNReject(), the connection handle is discarded. The application may also use ISDNDisconnect() to discard a connection handle that has not yet received an incoming call.

To accept additional incoming calls, the application must use ISDNListenForConnection() to create an additional connection handle.

The Listen_Mask bit assignments are as follows:

RETURN:

This function returns the connection handle to the listener, a warning error if a previous listener is ahead of this handle in the listen chain, or a negative error code.

The call_state values follow the ITU standards, and are defined as follows:

ISDNAccept()

int FAR PASCAL ISDNAccept (int iHandle, char FAR* lpCallStruct, char FAR* lpEvent);

This function accepts the incoming call, modifies the event notification mechanism for the call and retrieves the call information. On input the desired size for the Tx and Rx queue sizes can be entered into the isdn_call structure, or 0 for default queue sizes. The isdn_notify structure can be modified to set up the event notification mechanism for the active call. On returning from this call the isdn_call structure is filled in with the information describing the call, including call handle, actual Tx and Rx queue sizes, and the phone number of the call originator (if available).

A previous connection handle must have been created by ISDNListenForConnection and an incoming call must be received for that handle before ISDNAccept will succeed.

ISDNAccept may return the same handle value for the active connection as was used during the listen phase.

To accept the pending call as is, the call_type parameter should be set to zero (ISDN_ACCEPT_ANY) or to the basic call type of the incoming call, as specified in the call_type of the isdn_status structure, as returned by ISDNGetStatus. The same call_type value is also indicated in the high word of lParam in the notification mechanism.

Alternatively, the application may cause a dynamic change in call type as the call is connected. This is done by using ISDNSetRequest() with the ISDN_REQ_CALL_TYPE_CHANGE command, before the ISDNAccept() call is made.

In this case, the call_type parameter of the ISDN_Accept() call should be zero (ISDN_ACCEPT_ANY) or the new call type specified by the ISDNSetRequest() function call.

The basic call types returned are ISDN_B_VOICE, ISDN_B_56K, and ISDN_B_64K. A change in call type must be compatible with the basic type, for example, changing ISDN_B_56K to ISDN_B_DS_56K. The ISDNSetRequest() function call will return an error if an incompatible call type is specified.

WinISDN.DLL will not change the bearer capability of the incoming call, it will only change the way the call data flow is handled, for example, HDLC packets or clear channel. The application cannot change a 56K call type to a 64K call type, or a voice call type to a 56K data call type.

If WinISDN.DLL returns an error code for ISDNAccept(), the call is not connected or rejected. Another call to ISDNAccept(), after correcting the problem, will succeed in connecting to the incoming call.

RETURN:

This function returns the handle for the accepted call or a negative error code.

ISDNReject()

int FAR PASCAL ISDNReject( int iHandle);

This function is used to disconnect an incoming call without first connecting it. This avoids any billing for unwanted calls.

The application may qualify an incoming call and decide to reject it if the call is of the wrong type (after specifying that it will listen for that type of call) or if the calling party is not one of those qualified by a caller id data base (where available). This will provide an added measure of security to those applications that can take advantage of the information presented before a call is connected.

Once a call is rejected, the connection handle is discarded. If an application wishes to continue processing incoming calls, it must again call ISDNListenForConnection() to create a new listen handle.

RETURN:

This function returns ISDN_RETCD_SUCCESS or a negative error code.

ISDNRead()

int FAR PASCAL ISDNRead (int iHandle, char FAR* lpBuffer, int iLen, int iFlags, int FAR* lpLen);

This function is responsible for copying a data packet from the ISDN buffer into a local buffer. It should copy complete packets to the local buffer. If the local buffer is not big enough to copy the incoming packet, part of the packet is copied to the local buffer, and the function should return an error. The length of the packet is always returned in the last parameter, lpLen, so if the local buffer was too small, the buffer size required to read this packet can be found in lpLen. The Event notification mechanism can be used to get the length of the incoming packet. The wParam will contain the handle of the ISDN connection on which the packet arrived. The low word of the lParam will contain the event (ISDN_EVENT_READ) that triggered the notification. The high word of the lParam will contain the length of the packet to be read. In case of an error the high word of the lParam will contain the appropriate error code, which is represented by a negative value.

The iFlags parameter can be either 0 or MSG_PEEK (== 1).

if iFlags is equal to MSG_PEEK, the packet is copied to the local buffer, but not removed from the incoming packet queue, so the next ISDNRead() call will read the same packet. The packet will be removed from the incoming packet queue only when iFlags is 0.

RETURN:

This function returns the size of the packet copied to the local buffer. 0 return means no data is available, and negative return value represents an error. Also the lpLen parameter should be filled in with the length of the received packet. The WINISDN.DLL may copy a packet with bad checksum or with a framing error to the provided buffer, in this case it should return an error code indicating that a bad packet has been copied to the provided buffer. The lpLen parameter should still be filled in with the length of the packet. This option provides the protocol driver the capability to detect and report bad packets.

ISDNWrite()

int FAR PASCAL ISDNWrite (int iHandle, char FAR* lpBuffer, int iLen);

This Function is responsible for sending a packet. It is an asynchronous function which copies the data to the ISDN send Queue and returns immediately. If there is no room in the ISDN send queue for the whole packet the function should return an error code. If the application enabled the write notification via the event_mask, the write notification should be posted when connection is first established or when write notification is turned on with the ISDNSetEventMask().The notification should be reenabled only after the WINISDN.DLL fails to accept the incoming packet from the application due to lack of room in the TxQueue. When the notification has been enabled the WINISDN.DLL should send the Write Event to the application whenever it sends out a packet from the TxQueue.

RETURN:

This function returns the number of bytes sent or an error code representing the error.

ISDNGetStatus()

int FAR PASCAL ISDNGetStatus (int iHandle, char FAR* lpStatus);

This function retrieves the status of a given ISDN connection. lpStatus is a pointer to the buffer containing the status format.

The data structure for the status:

struct isdn_status{ 
} FAR * lpStatus;

RETURN:

This function returns 0 or error code for failure.

ISDNFlush()

int FAR PASCAL ISDNFlush (int iHandle, int iQueue);

This function is responsible for flushing data from the read/write queues associated with the given ISDN connection.

iQueue can be ISDN_READ_QUEUE, ISDN_WRITE_QUEUE or ISDN_READ_WRITE_QUEUE

RETURN:

This function returns a 0 for success or an error code for failure.

ISDNGetConfiguration()

int FAR PASCAL ISDNGetConfiguration (int iBoardID, char FAR* lpConfig);

struct isdn_config{
} FAR* lpConfig;

Each B-channel is defined as a “line” and each line is described by a line_config structure:

struct line_config{
} FAR* lpLineConfig; 
struct line_config line_config;

RETURN:

This function returns 0 or error code for failure.

ISDNSetConfiguration()

int FAR PASCAL ISDNSetConfiguration (int iBoardID, char FAR* lpConfig);

Use this function with caution. Modification of an existing board configuration could cause failures in WinISDN driver access to the board. In general, the application should call ISDNGetConfiguration, then modify only the desired fields before using ISDNSetConfiguration.

RETURN:

This function returns 0 or error code for failure.

ISDNGetEventMask()

int FAR PASCAL ISDNGetEventMask (int iHandle, char FAR* lpEvent);

This function retrieves the event notification data structure associated with the given connection.

RETURN:

This function returns 0 for success and error code for failure.

The structure below is used to pass in the event notification.

struct isdn_notify {

ISDNSetEventMask()

int FAR PASCAL ISDNSetEventMask (int iHandle, char FAR* lpEvent);

This function is used to request that the WINISDN.DLL should send the message ’msg_value’ to the window ‘win_handle’ whenever it detects any of the events specified in ‘event_mask’. The connection for which notification is required is identified by iHandle.

Issuing a ISDNSetEventMask() call for a connection cancels any previous ISDNSetEventMask() call for the same connection.

To cancel all notification related to a connection, the ‘event_mask’ should be set to zero.

This function can be used to override the event notification mechanism set through the ISDNConnect().

The event Mask is a bitwise OR of the events defined below. If win_handle and msg_value fields are not NULL the ISDN Driver should post a message ‘msg_value’ to the window ‘win_handle’. If either of msg_value or win_handle fields are NULL the callback pointer should be used to access the callback routine. The wParam of the PostMessage() should be used to hold the handle of the ISDN connection. The low word of the lParam contains the event which triggered the notification. The high word of the lParam contains the error status.

int FAR PASCAL callback(unsigned short wParam, unsigned long lParam);

This is a callback function that can be registered with the event notification mechanism of the ISDN driver for notification. It is important to note that the callback function will be called from the Interrupt service routine, so appropriate precautions should be taken. The callback function should not call Windows APIs other than PostMessage(). The callback function can be used to examine the incoming data packets or connection requests. It is illegal to call ISDNAccept() from the callback(). Return values can be used to indicate the rejection of a particular data.

Meaning of the events.

Want to receive notification when:

ISDN_EVENT_READ         There is a data packet to read 
ISDN_EVENT_WRITE        There is more space available in the send buffer 
ISDN_EVENT_CONNECT      A connection is completed 
ISDN_EVENT_DISCONNECT   The peer disconnected the connection 
ISDN_EVENT_ACCEPT       An incoming connection arrived 
ISDN_EVENT_CALL_CONTROL There is a Q.931 (diagnostic) message packet to read 
ISDN_EVENT_INFO_ELEMENT There is an info element to read 
ISDN_EVENT_INDICATION   There was a non-call related event detected

The WINISDN.DLL will not continually flood the application with messages for a particular event. Having successfully posted notification for a particular event, no further messages for that event will be posted until the application makes the function call which implicitly reenables notification of that event. If an event is true when the application initially calls ISDNSetEventMask() or when the reenabling function is called, then a message is posted as appropriate.

Reenabling functions:

ISDN_EVENT_READ           ISDNRead() 
ISDN_EVENT_WRITE          ISDNWrite() failed because WINISDN.DLL send buffer is full 
ISDN_EVENT_CONNECT        NONE 
ISDN_EVENT_DISCONNECT     NONE 
ISDN_EVENT_ACCEPT         ISDNAccept() 
ISDN_EVENT_CALL_CONTROL   ISDNGetCallControl() 
ISDN_EVENT_INFO_ELEMENT   ISDNGetInfoElement() 
ISDN_EVENT_INDICATION     ISDNGetIndication()

Examples:

The application sets ISDN_EVENT_READ. If there are data packets queued for the connection, WINISDN.DLL posts immediately. If there is no data to read, WINISDN.DLL does not post at this time. When new data arrives, WINISDN.DLL posts one message to the application. WINISDN.DLL will not post again until the application called the reenabling function which is ISDNRead(). After the packet is read, if there are more packets to read, WINISDN.DLL posts again since ISDNRead() reenabled the event. If there are no more packets to read, there is no posting. WINISDN.DLL will post again when a packet will arrive for that connection.

The application sets ISDN_EVENT_WRITE. If the connection is established, and there is room in the WINISDN.DLL send buffer, WINISDN.DLL posts immediately. If the send buffer is full, WINISDN.DLL will post only after it sends one packet. If the connection is not established yet, WINISDN.DLL will post when the connection is established. If the application sent data faster than WINISDN.DLL can put on the ISDN line and the send buffer is full, ISDNWrite() fails, which reenables the write event. The message will be posted after WINISDN.DLL sends one packet out.

It is recommended to set ISDN_EVENT_CONNECT and ISDN_EVENT_DISCONNECT in the ISDNConnect() call. WINISDN.DLL will post the message when the connection is established. At this time the application can set the event ISDN_EVENT_DISCONNECT, and it will be notified if the peer disconnected the connection. Setting ISDN_EVENT_DISCONNECT after the connection notification may allow a disconnect to occur without notification.

Set ISDN_EVENT_ACCEPT after a ISDNListen() call, and the application will be notified about incoming connections.

Set ISDN_EVENT_CALL_CONTROL to get Q.931 messages from the board. It is recommended to set this event before ISDNConnect().

RETURN:

This function returns 0 for success and error code for failure.

ISDNGetBoardEventMask()

int FAR PASCAL ISDNGetBoardEventMask(int iBoardID, char FAR* lpEvent);

This function retrieves the event notification data structure associated with the specified board number. This structure is used for events associated with a board rather than events associated with a specific connection. The event structure has the same format as that used by ISDNGetEventMask.

RETURN:

This function returns 0 for success and a (negative) error code for failure.

ISDNSetBoardEventMask()

int FAR PASCAL ISDNSetBoardEventMask(int iBoardID, char FAR* lpEvent);

This function replaces ISDNDiagnose() in previous definitions of WinISDN. It has been expanded to include addition events, with ISDN_EVENT_DIAGNOSE replaced by ISDN_EVENT_CALL_CONTROL.

This function is used to enable or disable the notification mechanism for events associated with a board rather than events associated with a specific connection. The event structure has the same format as that used by ISDNSetEventMask. Although any event bits may be set, only the board related events (ISDN_EVENT_CALL_CONTROL, and ISDN_EVENT_INDICATION) will be used. Other events are connection related, and will be ignored by this function.

In the notification process, wParam will contain the board number (iBoardID) rather than a connection handle.

NOTE: Connection handles should be unique from BoardID numbers.

RETURN:

This function returns 0 for success and a (negative) error code for failure.

ISDNSetRequest()

int FAR PASCAL ISDNSetRequest(int FAR* lpParameters);

This function passes specific requests between the application and WINISDN.DLL driver. These requests can enable additional features or modes of the adapter cards, and may return requested data.

The parameter structure may be used for both input and output, with the application filling in relevant parameter values for the given request and the WINISDN.DLL driver filling in relevant return values in servicing the request. The same parameter structure is used for all requests, so similarly named parameters will always occupy the same offset within the structure. The only required parameter is the command value. Other parameters used will depend on the needs of the request.

The data buffer is used to hold additional information, especially string type values. If the data buffer is not used by a particular request, the lpBuffer value may be NULL.

RETURN:

This function returns 0 for success and a (negative) error code for failure.

The structure below is used for the parameter values.

struct request_values {
}FAR* lpParameters;

Defined ISDN Request commands include:

Description of ISDNSetRequest() Commands:

ISDN_REQ_NULL              do nothing 
ISDN_REQ_RESET_BOARD       reset the board specified by board_id 
ISDN_REQ_IS_CAPI           expect CAPI message in buffer 
ISDN_REQ_CODEC             enable/disable CODEC for call_handle connection 
ISDN_REQ_STREAM            enable/disable bi-directional data stream for call_handle 
ISDN_REQ_L1_ACTIVATE       initiate Layer 1 activation (board_id, Data1 = line_id) 
ISDN_REQ_TEI_REQUEST       initiate TEI_Request (board_id, Data1 = line_id) 
ISDN_REQ_L1_STATE          return Layer 1 status for (board_id, Data1 = line_id) 
ISDN_REQ_L2_STATE          return Layer 2 status ... 
ISDN_REQ_L3_STATE          return Layer 3 status ... 
ISDN_REQ_INFO_EL_MASK      send Info_El_Mask to (board_id, call_handle, Data1=mask) 
ISDN_REQ_INDICATIONS_MASK  Set the indications mask (see ISDNGetIndication() ) 
ISDN_REQ_L3_AUTO_ON        (=Default), ISDN adapter automatically handles Q.931 
ISDN_REQ_L3_AUTO_OFF       disable Q.931 handling, application must manage Q.931 
ISDN_REQ_VOICE_ENERGY      enable (one-shot) Voice Energy detection (Data1=threshold) 
ISDN_REQ_VOICE_CAPTURE     enable Input stream on call_handle connection 
ISDN_REQ_DATA_PUMP         enable Output stream on call_handle connection 
ISDN_REQ_LOOP_TEST         hardware specific loopback test control function 
ISDN_REQ_ACTION            (board_id)-specific action request 
ISDN_REQ_L3_DECODE_ON      (=Default), convert Q.931 to printable ASCII in buffer 
ISDN_REQ_L3_DECODE_OFF     return binary Q.931 message in buffer 
ISDN_REQ_FACILITY          ... 
ISDN_REQ_LISTEN_MODEM      enable modem CED monitoring on call_handle connection 
ISDN_REQ_LISTEN_DTMF       enable DTMF monitoring on call_handle 
ISDN_REQ_SEND_DTMF         generate DTMF tone on call_handle connection (Data1=tone) 
ISDN_REQ_X25_SABME         issue X.25 SABME on call_handle connection 
ISDN_REQ_X25_RESET         issue X.25 RESET on call_handle connection 
ISDN_REQ_LISTEN_MASK       see ISDNListen() function description (Data1=listen mask) 
ISDN_REQ_DLL_ACTION        request DLL specific action 
ISDN_REQ_SERIAL_NUM        return board_id Serial number in buffer 
ISDN_REQ_VOLUME_CTRL       issue Volume control command (call_handle, Data1=volume) 
ISDN_REQ_CHANNEL_B1        associate channel B1 with call_handle 
ISDN_REQ_CHANNEL_B2        associate channel B2 with call_handle 
ISDN_REQ_AUTO_DISCONNECT   enable timed Disconnect on call_handle connection 
                           (Data1 = seconds, Data2 = minutes) 
ISDN_REQ_CALL_TYPE_CHANGE  dynamically change the call type of an active call

ISDNGetIndication()

int FAR PASCAL ISDNGetIndication(int iBoardID, char FAR* lpBuffer, int iLen, int FAR* lpType);

This function is used to read indications from the specified board. Indication values, such as detected DTMF tones, will be returned in lpBuffer, while the indication type will be specified in the lpType parameter. If the buffer is too small for the indication, a partial indication will be copied into the buffer, and the function will return an appropriate error code. The rest of the indication will be lost. It is expected that normal indications will be very short. The notification mechanism uses ISDN_EVENT_INDICATION to indicate that a new indication is available to the application.

RETURN:

This function returns the size of the indication copied to the local buffer. 0 return means no indication is available, while a negative return value represents an error.

The indications that will be reported are determined by the mask supplied with the ISDNSetRequest parameter: ISDN_REQ_INDICATIONS_MASK

Defined Indications:

Note that the indications supported will be a function of the hardware/firmware present on the ISDN adapter board. Because the WinISDN.DLL will often be unaware of the hardware capabilities, the act of requesting specific indications should not imply that indications will actually be returned. If an indication is requested that is unsupported by the hardware, the DLL may return either an error code or a success code (0) depending upon its awareness of board capabilities. The success code may imply simply that the mask was successfully set, not that any indication will ever be returned. Future versions may include a capabilities query that will allow specific boards to report their capabilities.

ISDNReadCallControl()

int FAR PASCAL ISDNReadCallControl(int iBoardID, char FAR* lpBuffer, int iLen);

This function replaces ISDNGetDiagnostics in previous definitions of WinISDN. The returned messages and notification mechanism are identical, although additional options are now supported. In particular, raw message data may be returned by selecting a raw data mode through ISDNSetRequest. The default is to return printable messages, useful for logging purposes.

This function will copy a call control (Q.931/Q.932) message from the WINISDN.DLL buffer into the local buffer specified by the lpBuffer parameter. If the buffer is too small, part of the call control message will be copied to the buffer, and the function will return an appropriate error code. The rest of the message will be lost. The notification mechanism uses ISDN_EVENT_CALL_CONTROL to indicate that a new call control message is available.

RETURN:

This function returns the size of the call control message copied to the local buffer. 0 return means no call control message is available, while a negative return value represents an error.

Note: In the Basic Telephony Service mode of operation, and for data communications over ISDN, it is in general never necessary for the application to read call control messages, since the hardware/firmware performs this function.

For advanced control of Supplementary Services and Automated Call Distribution applications, it will in general be required that the application read the network layer call control messages in order to obtain the greatest degree of control.

ISDNWriteCallControl()

int FAR PASCAL ISDNWriteCallControl(int iBoardID, char FAR* lpBuffer, int iLen);

This function will send a call control (Q.931/Q.932) message to the D channel. The message supplied starts at the protocol discriminator and contains all desired info-element components. The WINISDN.DLL and ISDN card will build a complete D channel message, by prefixing SAPI, TEI, and packet number controls, and will perform the normal LAPD HDLC framing functions on the message. This function allows an application to take over the call control functions normally handled by the ISDNConnect function, and allows custom call handling. In combination with ISDNSetRequest and ISDNReadCallControl, an application can take over all call placement activity with this function.

RETURN:

This function returns the number of bytes sent (normally iLen) or a negative error code representing the error.

Note:

The ‘ISDNGetDiagnostics’ function has been renamed ‘ISDNReadCallControl’ and a ‘ISDNWriteCallControl’ has been added to WinISDN. Both of these functions manage Q.931-Q.932 Network layer messages, from the Protocol Discriminator to the end of the message, including all info elements.

This new functionality allows an application to gain complete control of the network layer communications, without having to deal with data link layer behavior or network layer flow control. The control of network messages enables applications such as third party call control, for example ISDN PBX’s such as the Definity can be controlled in this manner. Other Automated Call Distribution applications should become possible with network layer control.

Graphical User Interface (GUI) Telephony applications that make use of Q.932 Supplementary Services will also benefit from this ability to send Network Layer messages over the D-channel.

WinISDN now allows an ISDN adapter to work in three modes:

Auto_L3_response provides the simplest mode of operation. For data calls and Basic Telephony Services, almost no knowledge of L3 messages is required by the application. This provides the extreme ease of use that first inspired WinISDN. Applications taking advantage of this (default) mode of operation need only OPEN/CLOSE, CONNECT/DISCONNECT and READ/WRITE to make use of ISDN connectivity, such as ISDN-to-the-INTERNET.

Transparent_L3 operation provides full control of Network communications, opening ALL of the ISDN Services to the application, without the necessity of managing Layer 1, Layer 2, or the Layer 3 Flow Control. The application however, must be intimately aware of Layer 3 Network messages, and the corresponding increase in complexity will be reflected in the application programming.

Finally, Semi_Auto_L3 operation allows the ISDN adapter to handle the Basic Telephony Services and also allows the application to “insert” Layer 3 messages for Supplementary Services, such as HOLD, DROP, etc. If the ISDN adapter can respond properly to the HOLD_ACK messages from the switch, then the application can achieve maximum control with minimum interpretation of switch messages required. The ability to work in this mode will likely by very dependent on the specific ISDN adapter hardware/firmware.

Note:

While ISDNWriteCallControl() is necessary to obtain the most complete use of ISDN services, it is not mandated for WinISDN to perform checking of messages. This is left for individual implementations. As a result, it is possible for the user to send invalid messages to the ISDN switch. This may cause problems in certification for certain PTTs.

ISDNReadInfoElement()

int FAR PASCAL ISDNReadInfoElement(int iHandle, char FAR* lpBuffer, int iLen);

This function will copy an info element from the WINISDN.DLL buffer into the local buffer specified by the lpBuffer parameter. If the buffer is too small, part of the info element message will be copied to the buffer, and the function will return an appropriate error code. The rest of the message will be lost. The notification mechanism uses ISDN_EVENT_INFO_ELEMENT to indicate that a new info element is available.

The ISDNReadInfoElement function should be called only when specific info elements are desired. If ALL info elements are desired, then ISDNReadCallControl will return them. The info element indications that will be reported are determined by the mask supplied with the ISDNSetRequest parameter: ISDN_REQ_INFO_EL_MASK

Defined Indications:

Note that the first seven info element flags are identical with CAPI info mask mapping.

RETURN:

This function returns the size of the info element copied to the local buffer. A zero (0) return means no message is available, while a negative return value represents an error.

WinISDN Function Return Codes:

The following function return codes are currently defined for WinISDN. The list is not intended to be exhaustive,

[Back]... Back to WinISDN SDK