IsdnLib API

For all functions, the variable IsdnErrno indicates the type of error on return.

IsdnInitialize

Purpose:

Initialize the IsdnLib.

Syntax:

#include <IsdnLib.h>
int IsdnInitialize (void (*callback)());

Description:

IsdnInitialize will be used to initialize the IsdnLib and to connect the Q.931 Stack to the DLPI interface. This function has to be called prior to any of the other functions of the library. Otherwise they will report an error.

callback is a callback function that has to be registered by the application. This function will be called if a Q.931 message is received that could be of interest to the application.

After the library has been initialized, other IsdnLib functions are available for using ISDN.

Before the application terminates, it should call IsdnFini() in order to free all resources that have been reserved.

Debugging:

Debugging support exists if not switched off at library generation. The setting of the variable ISDN_DEBUG determines which kind of information the output contains. The value specifies a bitmask.

0x0001	Ouput of schedular information
0x0002	Output of the IsdnLib CallId
0x0008	Output of timer information
0x0010	Indication of incoming and outgoing Q.931 messages
0x0020	Indication of incoming and outgoing Q.921 messages
0x0040	Indication of internal Q.931 requests und indikations
0x1000	Trace of functions when leaved
0x2000	Trace of functions when started
0x4000	Output of warnings
0x8000	Error output

Return value:

IsdnInitialize returns 0 if initialization was successful, -1 otherwise.

Error values:

EISDN_SYSCALL: The call of a system call leads to an unexpected error.

Example:

#include <IsdnLib.h>
void (*IsdnCallback) (IsdnInd *ind);
main () {
  /* initalize the application */
  if (IsdnInitialize (IsdnCallback)) < 0) {
    /* handle error */
    exit (1);
  }
  IsdnMainLoop ();
  IsdnFini();
  exit (0);
}

IsdnFini

Purpose:

Release all resources used by IsdnLib.

Syntax:

#include <IsdnLib.h>
void IsdnFini();

Description:

IsdnFini terminates the IsdnLib library and releases all reserved resources.

IsdnMainLoop

Purpose:

Starts the IsdnLib main loop.

Syntax:

#include <IsdnLib.h&>
int IsdnMainLoop();

Description:

IsdnMainLoop is used to start the IsdnLib main loop. Before the loop is started it is not possible to receive or properly send Q.931 messages.

At any time after the ISDN device has been activated, Q.931 messages may arrive. Therefore, IsdnMainLoop should be called immediately after IsdnInitialize. Otherwise, old messages that have not been handled may appear in the queue and lead to confusion.

The call to IsdnMainLoop returns only when the global variable schedulerStop is set to a non-zero value.

Return value:

IsdnInitialize returns 0 when the main loop could be started correctly, -1 otherwise. The variable IsdnErrno contains error information.

Example:

#include <IsdnLib.h&>
void (*IsdnCallback) (tIsdnInd *ind);
main () {
  IsdnInitialize(IsdnCallback);
  IsdnMainLoop();
  IsdnFini();
  exit (0);
}

IsdnError

Purpose:

Formatted output of the value of variable isdnErrno.

Syntax:

#include <IsdnLib.h>
void IsdnError(const char *str, ...);

Description:

IsdnError writes the formatted value of the global error variable isdnErrno to stderr. The function expects a variable number of parameters, similar to printf.

IsdnCreateFileHandler

Purpose:

Registers a file handler.

Syntax:

#include <IsdnLib.h>
void cb (int mode, void *data);
int IsdnCreateFileHandler(int fd, int mode, void (*cb) (), void *data);

Description:

The application uses IsdnCreateFileHandler to register a file handler for file descriptor fd. The file handler is called whenever one of the events specified in mode appears. Following events may be specified: ISDN_READABLE, ISDN_WRITABLE, ISDN_EXCEPTION

A file handler that is installed can be removed with IsdnDeleteFileHandler.

Return value:

IsdnInitialize returns 0 if the file handler could be correctly installed, -1 otherwise.

Example:

#include <IsdnLib.h>
Echo(void *data, int mode)
{}

int main() {
  IsdnCreateFileHandler(0, ISDN_READABLE, Echo, NULL);
  IsdnDeleteFileHandler(0);
}

IsdnDeleteFileHandler

Purpose:

Removes a file handler that was installed before.

Syntax:

#include <IsdnLib.h>
void IsdnDeleteFileHandler(int fd);

Description:

IsdnDeleteFileHandler removes the file handler that was installed for the file descriptor fd before.

Return value:

Error values:

Example:

See IsdnCreateFileHandler

IsdnCreateTimerHandler

Purpose:

A timer is started and a handler for that timer is installed.

Syntax:

#include <IsdnLib.h>
void cb (int mode, void *data);
int IsdnCreateTimerHandler (int ms, void (*cb) (), void *data);

Description:

IsdnCreateTimerHandler starts a timer with ms miliseconds. When the timer expires, the callback routine cb registered for the timer is called. A timer that was started and the associated timer handler can be removed at any time with IsdnDeleteTimerHandler

Return value:

When the timer is installed correctly IsdnCreateTimerHandler returns a timer id greater 0, -1 otherwise.

Error values:

Example:

#include <IsdnLib.h>
Cb (void *data, int mode)
...
timerId = IsdnCreateTimerHandler (1000, Cb, NULL);
IsdnDeleteTimerHandler(timerId);

IsdnDeleteTimerHandler

Purpose:

A timer is stopped and the associated timer handler removed.

Syntax:

#include <IsdnLib.h>
void IsdnDeleteTimerHandler (int timerId);

Description:

IsdnDeleteTimerHandler stops the timer timerId that had been started and removes the assocciated timer handler.

Example:

See IsdnCreateTimerHandler.

IsdnAlertingReq

Purpose:

Indicates that the system is ready to accept an incoming call.

Syntax:

#include <IsdnLib.h>
int IsdnAlertingReq (const t_IsdnAlertingReq *ireq);

Description:

The IsdnLib indicates an incoming call by IsdnCallInd. When the application is ready to accept the call, it calls IsdnAlertingReq. If the call is a telephone call, ringing is generated at the caller. The parameter ireq further defines the request.

typedef struct {
  int callId;
} t_IsdnAlertingReq;

callId identifies the logical connection.

Return value:

IsdnAlertingReq returns 0 if the request was successful, -1 otherwise.

Error values:

EISDN_INV_CALLID

The callId given in ireq could not be associated with any logical connection.

EISDN_Q931

Unexpected Q.931 message.

Example:

HandleIncomingCall(int callId)
{
  t_IsdnAlertingReq req;

  req.callId = callId;
  if (IsdnAlertingReq(&req))
    IsdnError("Error in IncomingCall");
}

IsdnCallReq

Purpose:

Initiates an outgoing call.

Syntax:

#include <IsdnLib.h>
int IsdnCallReq (t_IsdnCallReq *req);

Description:

IsdnCallReq is used to initiate an outgoing call. The IsdnLib produces a new Q.931 CallReference Value and tries to make the call.

The parameter ireq defines the request:j

typedef struct {
  int callId;
  t_CalledPartyNo       calledNo;         /* opt. number to be called */
  t_CalledPartySubAddr  calledSubAddr;    /* opt. subAddr to be called */
  t_CallingPartyNo      callingNo;        /* opt. calling number */
  t_CallingPartySubAddr callingSubAddr;   /* opt. calling subAddr */
  t_IsdnService         service;          /* opt. complete service */
  t_BearerCap           bearerCap[2];     /* opt. bearer cap */
  t_HighLayerComp       highLayerComp[4]; /* opt. HLC */
  t_LowLayerComp        lowLayerComp[4];  /* opt. LLC */
} t_IsdnCallReq;

callId

Ignored when invoking the function; on return, it contains the callId for the logical connection that was assigned by the IsdnLib.

calledNo

Specifies the number to be called. If no number is given, in Overlap Sending Mode the application may indicate the number by use of IsdnDialReq.

calledSubAddr

Specifies the subaddress of the number that was called.

callingNo

Specifies the number of the caller, if given. In many cases the network checks and changes this number.

callingSubAddr

Specifies the subaddress of the caller, if given.

service

Defines the service to be used for the call initiation, if given. With this field it is possible to define this service in a very simple way.

ISDN_S_VOICE_ALAW

Telephony with 3.1 kHz, PCM A-law coded.

ISDN_S_VOICE_MULAW

Telephony with 3.1 kHz, PCM µ-law coded.

If this field is undefined, the value must be defined with one of the following Fields. Otherwise, these fields do not have any meaning.

bearerCap

Defines the Bearer Capability to be used according to Q.931.

highLayerComp

Defines the High Layer Compatibility to be used according to Q.931.

lowLayerComp

Defines the Low Layer Compatibility to be used according to Q.931.

The successful use of this request does not mean that a connection was established, but only that connection establishment was requested. The connection is completely established if the IsdnLib generates a IsdnConnectInd.

The initiated call can be canceled at any time by IsdnReleaseReq.

Return value:

IsdnCallReq return 0 if the request was successful, -1 otherwise.

Error values:

Example:

InitiateCall ()
{
  t_IsdnCallReq req;
  memset(&req, '\0', sizeof (req));
  strcpy(req.calledNo.number, "+493025499203");
  strcpy(req.callingNo.number, "+4930999888777");
  req.service = ISDN_S_VOICE_ALAW;
  if (IsdnCallReq(&req))
    IsdnError("Error in InitiateCall");
  else
    return req.callId;  /* return the callId */
}

IsdnConnectReq

Purpose:

Accept an incoming call.

Syntax:

#include <IsdnLib.h>
int IsdnConnectReq(const t_IsdnConnectReq *ireq);

Description:

IsdnConnectReq accepts an incoming call. Before the call can be accepted, the application must indicate that it is ready to accept by IsdnAlertingReq. The parameter ireq defines the request:

typedef struct                    /* connect to incomming call */
  int callId;                     /* request */
  t_IsdnService service;          /* opt. service */
  t_BearerCap   bearerCap;        /* opt. selected bearer cap */
  t_HighLayerComp highLayerComp;  /* opt. selected HLC */
  t_LowLayerComp lowLayerComp;    /* opt. selected LLC */
} t_IsdnConnectReq;

callId

identifies the logical connection.

service

Defines the service used, if given. In ISDN it is possible for the caller to specify several services. The callee then has to choose the preferred one from the list. If this parameter is undefined, the preferred service must be specified with the following fields. Otherwise, these fields are ignored.

bearerCap

Defines the Bearer Capability to be used according to Q.931.

highLayerComp

Defines the High Layer Compatibility to be used according to Q.931.

lowLayerComp

Defines the Low Layer Compatibility to be used according to Q.931.

After a successful request, the connection is not completely established. Only if the IsdnLib indicates an IsdnConnectInd the connection is established.

Return value:

IsdnCallReq returns 0 if the request was successful, -1 otherwise.

Example:

ConnectToCaller (int callId, int service)
  t_IsdnConnectReq req;
  memset(&req, '\0', sizeof (req));
  req.callId  = callId;
  req.service = service;
  if (IsdnConnectReq (&req))
    IsdnError ("Error in ConnectToCaller");
  else
    ... /* ok */
}

IsdnDialReq

Purpose:

Number to be called for Overlap Sending.

Syntax:

#include <IsdnLib.h>
int IsdnDialReq (const t_IsdnDialReq *req)

Description:

IsdnDialReq transfers dial information in Overlap Sending mode. Therefore, it is possible to dial like when using an ordinary telephone. The parameter ireq further defines the request:

typedef struct {
  int  callId;                    /* req. */
  t_CalledPartyNo calledPartyNo;  /* req. */
} t_IsdnDialReq;

callId

Identifies the logical connection.

calledPartyNo

The dial information to be transfered.

Return value:

IsdnDialReq returns 0 if the request was successful, -1 otherwise.

Example:

Dial(int callId, char *number)
{
  t_IsdnDialReq req;
  memset(&req, '\0', sizeof (req));
  req.callId = callId;
  strcpy(req.calledPartyNo.number, number);
  if (IsdnCallReq (&req))
    IsdnError ("Error in Dial");
  else
    ... /* OK */
}

IsdnKeypadReq

Purpose:

Transfer of additional information according to Q.932.

Syntax:

#include <IsdnLib.h>
int IsdnKeypadReq (const t_IsdnKeypadReq *req)

Description:

IsdnKeypadReq transfers information used to support additional ISDN features (e.g., switching between calls). This feature is not supported by all network providers.

The parameter ireq defines the request:

typedef struct {
  int   callId;        /* req. */
  char  keypad[20+1];  /* req. 1..20 chars,  terminated */
} t_IsdnKeypadReq;

callId

Identifies the logical conection.

keypad

Further information to be transfered. The meaning is beyond the Q.931 specification. The user has to ask the ISDN service provider for the features that it supports.

Return value:

IsdnKeypadReq returns 0 if the request was successful, -1 otherwise.

Example:

SendKeypad (int callId, char *keypad)
{
  t_IsdnKeypadReq req;
  memset (&req, '\0', sizeof (req));
  req.callId = callId;
  strcpy (req.keypad, keypad);
  if (IsdnKeypadReq (&req))
    IsdnError ("Error in SendKeypad");
  else
    ...      /* OK */
}

IsdnReleaseReq

Purpose:

Releases a logical connection.

Syntax:

#include <IsdnLib.h>
int IsdnReleaseReq (const t_IsdnReleaseReq *req);

Description:

IsdnReleaseReq initiates the release of an existing connection or a connection in the estalishment phase.

The parameter ireq defines the request:

typedef struct {
  int      callId;     /* req. */
  t_Cause  cause;      /* opt. reason */
} t_IsdnReleaseReq;

Meaning of the fields:

callId

Identifies the logical connection.

cause

Specifies the reason for the connection release. The meaning of the values are taken from the ITU Recommendation Q.850.

The connection release is completed only if the IsdnLib generates an IsdnReleaseInd.

Return value:

IsdnReleaseReq returns 0 if the request was successful, -1 otherwise.

Error values:

Example:

Disconnect (int callId, int cause)
{
  t_IsdnReleaseReq req;
  memset (&req, '\0', sizeof (req));
  req.callId         = callId;
  req.cause.value    = cause;
  req.cause.location = CA_L_USER;
  if (IsdnReleaseReq(&req))
    IsdnError ("Error in Disconnect");
  else
    ...      /* OK */
}

IsdnAlertInd

Purpose:

Callback case that indicates that the calling side is ready to accept the call.

Syntax:

#include <IsdnLib.h>
IsdnCallback(t_IsdnInd *ind);

Description:

If the callee is ready to accept the call, the IsdnLib callback function is called with parameter IsdnAlertInd. This is equivalent to ringing. The parameter t_IsdnAlertInd describes the call:

typedef struct           /* alerting indication */
  t_sdnIndType indType;  /* type of inication */
  int callId;            /* unique ID of the call */
} t_IsdnAlertInd;

Meaning of the fields:

indType

always ISDN_ALERT_IND

callId

identifies the logical connection the ringing is indicated for.

Example:

IsdnCallback (t_IdnInd *ind)
{
  t_IsdnAlertInd  *alert = (t_IsdnAlertInd *)ind;

  if (ind->indType == ISDN_ALERT_IND)
    printf("Alerting for %d\n", alert->callId)
}

IsdnCallInd

Purpose:

Indicates an incoming call.

Syntax:

#include <IsdnLib.h>
IsdnCallback(t_IsdnInd *ind);

Description:

If there is a new incoming call, the callback function that was registered is called by IsdnLib parameterized with a IsdnCallInd. The application has to decide wether it is ready to accept the call. If it is, the applications invokes IsdnCallInd. Otherwise, the call should be rejected with IsdnReleaseReq. The parameter t_IsdnCallInd provides more information about the indication:

typedef struct {
  t_IsdnIndType          indType;             /* type of indication */
  int                    callId;              /* unique ID of the call */
  t_CalledPartyNo        calledPartyNo;
  t_CalledPartySubAddr   calledPartySubAddr;
  t_CallingPartyNo       callingPartyNo;
  t_CallingPartySubAddr  callingPartySubAddr;
  t_ChannelId            channelId;           /* identifies the B* channels */
  t_BearerCap            bearerCap[2];
  t_HighLayerComp        highLayerComp[4];
  t_LowLayerComp         lowLayerComp[4];
} t_IsdnCallInd;

indType

always ISDN_CALL_IND

callId

Identifies the logical connection for the new call.

calledPartyNo

Returns the number that was called.

calledPartySubAddr

Returns the subaddres that was called.

callingPartyNo

Returns the number of the calling site, if available.

callingPartySubAddr

Returns the subaddres of the calling site, if available.

channelId

Defines the ISDN channels that were reserved for this connection and should be used.

bearerCap

Defines the Bearer Capabilities offered by the calling site

highLayerComp

Defines the High Layer Compatibility.

lowLayerComp

Defines the Low Layer Compatibility.

Example:

IsdnCallback (t_IsdnInd *ind) {
  t_IsdnCallInd *call = (t_IsdnCallInd *)ind;

  if (ind->indType == ISDN_CALL_IND) {
    printf("Incoming CALL for %d\n", call->callId);
    printf("  called no  = %s\n", call->calledPartyNo.number);
    printf("  calling no = %s\n", call->calledPartyNo.number);
  }
}