D. Manualpages for the IsdnLib

In the following, we describe the functions of the IsdnLib. The description of the functions will look like manual pages.

D.1. 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. As far as a Q.931 is received, that could be of any interest for the application, this function will be called.

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

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

  • DEBUGGING A 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 spezifies a bitmask which can be given as hexadecimal value, as well, when prefixed with0x. The following values are defined: 
    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. Then, the error is contained in the variable IsdnErrno.
  • ERROR EISDN_SYSCALL The call of a system call leads to an unexpected error.
  • EXAMPLE #include <IsdnLib.h>

    void (*IsdnCallback) (tIsdnInd *ind);

    main ()

    /* initalize the application */ if (IsdnInitialize (IsdnCallback)) < 0) /* handle error */ exit (1); IsdnMainLoop (); ... IsdnFini (); exit (0); T>

    D.2. IsdnFini

  • ZWECK Freigabe aller Ressourcen, die von der IsdnLib benutzt wurden
  • SYNTAX #include <IsdnLib.h>

    void IsdnFini ();

  • BESCHREIBUNG IsdnFini beendet die IsdnLib und gibt alle belegten Ressourcen wieder frei.

    D.3. 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 afterIsdnInitialize. Otherwise, old messages that has not been handled yet may still appear in the queue and lead to confusion.

    The call to IsdnMainLoop only returns when it is forced by setting of the global variable schedulerStop to a value different 0.

  • RETURN VALUE IsdnInitialize returns 0 when the main loop could be started correctly, -1 otherwise. The error is then contained in the variable IsdnErrno.
  • EXAMPLE
    #include <IsdnLib.h>

    void (*IsdnCallback) (tIsdnInd *ind);

    main ()

    ... IsdnInitialize (IsdnCallback); IsdnMainLoop (); IsdnFini (); exit (0);

    D.4. 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 amount of parameters anlog to printf.
  • EXAMPLE ... IsdnError ("Error occured at ...

    D.5. 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 at any time removed with IsdnDeleteFileHandler.

  • RETURN VALUE IsdnInitialize returns 0, if the file handler could be correctly installed, -1 otherwise. The value will then be contained in the variable IsdnErrno.
  • EXAMPLE #include <IsdnLib.h>

    Echo (void *data, int mode)

    ... T> main ()

    ... IsdnCreateFileHandler (0, ISDNREADABLE, Echo, NULL); ...

    D.6. IsdnDeleteFileHandler

  • ZWECK 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.
  • EXAMPLE #include <IsdnLib.h>

    Echo (void *data, int mode)

    ... T> main ()

    ... IsdnCreateFileHandler (0, ISDNREADABLE, Echo, NULL); ... IsdnDeleteFileHandler (0);

    D.7. IsdnCreateTimerHandler

  • PURPOSE<-/TD> 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 passed 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. The variable IsdnErrno then contains the error.
  • EXAMPLE #include <IsdnLib.h>

    Beep (void *data, int mode)

    ... T> main ()

    ... /* create timer for one second ***/ IsdnCreateTimerHandler (1000, Echo, NULL); ...

    D.8. 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 is already started and removes the assocciated timer handler.
  • EXAMPLE #include <IsdnLib.h>

    void Cb (); main ()

    ... /* create timer for one second ***/ timerId = IsdnCreateTimerHandler (1000, Cb, NULL); ... IsdnDeleteTimerHandler (timerId); ... T>

    D.9. 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 possibly ready to accept the call it calls IsdnAlertingReq. If the call is a telephone call, ringing is generated at the caller side.

    The parameter ireq defines further parameter specifying the request.

    typedef struct int callId; /* req. */ IsdnAlertingReq;
  • callId Reference to the logical connection. If the application does not want to handel the call it should reject the call with IsdnReleaseReq. If there is no reaction to an incoming call within 8 seconds the IsdnLib generates a IsdnReleaseInd by itself.
  • RETURN VALUE IsdnAlertingReq returns 0, if the Request was successful, -1 otherwise. The error is then contained in the variable IsdnErrno.
  • ERROR
  • EISDN_INV_CALLID The callId given in ireq could not be associated to a logiccal connection.
  • EISDN_Q931 An unexpected Q.931 message has been received that is not according to the protocol specification.
  • EXAMPLE HandleIncommingCall (int callId)

    tIsdnAlertingReq req;

    ... /* check the incomming call */ req.callId = callId; if (IsdnAlertingReq (req)) IsdnError ("Error in IncommingCall"); else ... /* ok */ T>

    D.10. 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 defienes further parameter specifying the request.

    typedef struct int callId; /* n/a */ tCalledPartyNo calledNo; /* opt. no to be called */ tCalledPartySubAddr calledSubAddr; /* opt. subAddr to be called */ tCallingPartyNo callingNo; /* opt. calling no */ tCallingPartySubAddr callingSubAddr; /* opt. calling subAddr */ tIsdnService service; /* opt. complete service */ tBearerCap bearerCap[2]; /* opt. bearer cap */ tHighLayerComp highLayerComp[4]; /* opt. HLC */ tLowLayerComp lowLayerComp[4]; /* opt. LLC */ T>IsdnCallReq;
    meaning of the fields:
  • callId has no value when the function is called. If the request was successful this field contains the callId for the logical connection that was assigned by the IsdnLib.
  • calledNo specifies the number to be called. If no number was given, in Overlap Sending Mode t he 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 Dfines 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 does not exist, 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 the connection establishment was requested. The connection is completely established if the IsdnLiB generates a IsdnConnectInd.

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

  • RETURNVALUE IsdnCallReq return 0 if the request was successful, -1 otherwise. The error is then conatined in the variable IsdnErrno.
  • EXAMPLE InitiateCall ()

    tIsdnCallReq req;

    memset (req, '', sizeof (req)); strcpy (req.calledNo.number, "+493025499203"); strcpy (req.callingNo.number, "+4930999888777"); req.service = ISDNSVOICEALAW; if (IsdnCallReq (req)) IsdnError ("Error in InitiateCall"); else return req.callId; /* return the callId */ T>

    D.11. IsdnConnectReq

  • PURPOSE Accepting 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 further parameter for the request.

    typedef struct /* connect to incomming call */ int callId; /* req. */ tIsdnService service; /* opt. short cut service */ tBearerCap bearerCap; /* opt. selected bearer cap */ tHighLayerComp highLayerComp; /* opt. selected HLC */ tLowLayerComp lowLayerComp; /* opt. selected LLC */ IsdnConnectReq;
    Meaning of the fields:
  • callId identifies the logical connection.
  • service Defines the service used, if given. In ISDN it is possible for the calling site to specify several services. The called site has to choose the preferred one from the list. If this parameter does not exist, the preferred service must be specified with the following fields. Otherwise the 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. After a successful use of this 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. The variable IsdnErrno then contains the error.
  • EXAMPLE ConnectToCaller (int callId, int service)

    tIsdnConnectReq req;

    memset (req, '', sizeof (req)); req.callId = callId; req.service = service; if (IsdnConnectReq (req)) IsdnError ("Error in ConnectToCaller"); else ... /* ok */ T>

    D.12. IsdnDialReq

  • PURPOSE Number to be called for Overlap Sending.
  • SYNTAX #include <IsdnLib.h>

    int IsdnDialReq (const t_IsdnDialReq *req)

  • DESCRIOTION IsdnDialReq transfers dial information in Overlap Sending mode. Therefore, it is possible to dial like using an ordinary telephone.

    The parameter ireq defines further parameter for request:

    typedef struct int callId; /* req. */ tCalledPartyNo calledPartyNo; /* req. */ T>IsdnDialReq;
    Meaning of the fields:
  • callId Identifies the logical connection.
  • calledPartyNo The dial information to be transfered.
  • RETURNVALUE IsdnDialReq returns 0, if the request was successful, -1 otherwise. The error is then contained in the variable IsdnErrno.
  • EXAMPLE Dial (int callId, char *number)

    tIsdnDialReq req;

    memset (req, '', sizeof (req)); req.callId = callId; strcpy (req.calledPartyNo.number, number); if (IsdnCallReq (req)) IsdnError ("Error in Dial"); else ... /* OK */ T>

    D.13. IsdnKeypadReq

  • PURPOSE Transfer of additional information according to Q.931[itu9303:Q.932]
  • SYNTAX #include <IsdnLib.h>

    int IsdnKeypadReq (const t_IsdnKeypadReq *req)

  • DESCRIPTION IsdnKeypadReq transfers additional information used to realize further ISDN features (e.g."makeln"(?)). This features is not supported by all network providers.

    The parameter ireq defines further parameter for the request.

    typedef struct int callId; /* req. */ char keypad[20+1]; /* req. 1..20 chars, terminated */ IsdnKeypadReq;
    Meaning of the fields:
  • 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 these features.
  • RETURN VALUE IsdnKeypadReq return 0, if the request was successful, -1 otherwise. The variable IsdnErrno then contains the error.
  • EXAMPLE SendKeypad (int callId, char *keypad)

    tIsdnKeypadReq req;

    memset (req, '', sizeof (req)); req.callId = callId; strcpy (req.keypad, keypad); if (IsdnKeypadReq (req)) IsdnError ("Error in SendKeypad"); else ... /* OK */

    D.14. 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 further parameter for the request.

    typedef struct int callId; /* req. */ tCause 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 particulat values are taken from the ITU Recommendation Q.850[itu9303:Q.850] zu entnehmen. The connection release is completed only if the IsdnLib generates an IsdnReleaseInd.
  • RETURN VALUE IsdnReleaseReq returns 0, if the request was successful, -1 otherwise. The variable IsdnErrno then contains the errror.
  • EXAMPLE Disconnect (int callId, int cause)

    tIsdnReleaseReq req;

    memset (req, '', sizeof (req)); req.callId = callId; req.cause.value = cause; req.cause.location = CALUSER; if (IsdnReleaseReq (req)) IsdnError ("Error in Disconnect"); else ... /* OK */ T>

    D.15. IsdnAlertInd

  • PURPOSE Indicates that the calling side is ready to accept the call.
  • SYNTAX #include <IsdnLib.h>

    IsdnCallback (t_IsdnInd *ind);

  • DESCRIPTION If the calling side is ready to accept the call, the already registered callback function is called by the IsdnLib with IsdnAlertInd. Thus, the ringing of the old fashioned telephone is replaced.

    The parameter t_IsdnAlertInd defines further information about the indication:

    typedef struct /* alerting indication */ tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ T>IsdnAlertInd;
    Meaning of the fields:
  • indType ISDN_ALERT_IND
  • callId identifies the logical connection the ringing is indicated for.
  • EXAMPLE IsdnCallback (tIsdnInd *ind)

    tIsdnAlertInd *alert = (tIsdnAlertInd*)ind;

    if (ind->indType == ISDNALERTIND) printf ("Alerting for

    D.16. 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 the IsdnLib parameterized with a IsdnCallInd. The application has to decide weather it is ready to accept the call. If it is, the applications reaction is aN IsdnCallInd. Otherwise, the call is rejected by a IsdnReleaseReq.

    The parameter t_IsdnCallInd defines further information about the indication:

    typedef struct tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ tCalledPartyNo calledPartyNo; tCalledPartySubAddr calledPartySubAddr; tCallingPartyNo callingPartyNo; tCallingPartySubAddr callingPartySubAddr; tChannelId channelId; /* identifies the B* channels */ tBearerCap bearerCap[2]; tHighLayerComp highLayerComp[4]; tLowLayerComp lowLayerComp[4]; T>IsdnCallInd;
    Meaning of the fields:
  • indType 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 it was transfered.
  • callingPartySubAddr Returns the subaddres of the calling site if it was transfered.
  • 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, if it exists.
  • lowLayerComp Defines the Low Layer Compatibility, if it exists.
  • EXAMPLE IsdnCallback (tIsdnInd *ind)

    tIsdnCallInd *call = (tIsdnCallInd*)ind;

    if (ind->indType == ISDNCALLIND) printf ("Incomming CALL for printf (" called no = printf (" calling no = ... T>

    D.17. IsdnChannelInd

  • PURPOSE Indicates that an ISDN data channel was reserved for the connection.
  • SYNTAX #include <IsdnLib.h>

    IsdnCallback (t_IsdnInd *ind);

  • DESCRIPTION The IsdnLib calls the callback function that was registered with a IsdnChannelInd as parameter in order to provide the application with access to the reserved data channel. From that point in time data may be sent or received on the logical connection.

    The parameter defines further information about the indication:

    typedef struct /* indicates the available channel(s) */ tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ tChannelId channelId; /* the ID of the selected channel(s) */ int fd; /* fd for the selected channel */ T>IsdnChannelInd;
    Meaning of the fields:
  • indType ISDN_CHANNEL_IND
  • callId Identifies the logical connection.
  • channelId Defines the ISDN channel used for the connection.
  • fd The file descriptor the logical channel can be applied with.
  • EXAMPLE void DataCb(); IsdnCallback (tIsdnInd *ind)

    tIsdnChannelInd *channel = (tIsdnChannelInd*)ind;

    if (ind->indType == ISDNCHANNELIND) printf ("Channel got for IsdnCreateFileHandler (channel->fd, DataCb, ISDNREADABLE, NULL); ... T>

    D.18. IsdnChargeInd

  • PURPOSE Transfer of charging information.
  • SYNTAX #include <IsdnLib.h>

    IsdnCallback (t_IsdnInd *ind);

  • DESCRIPTION If charging information was received from the ISDN network, the IsdnLib calls the callback function that was registered with a IsdnChargeInd as a parameter (compare Q.956 [itu9510:Q.956]).

    The parameter t_IsdnChargeInd provides further information about the indication.

    typedef struct tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ int units; /* # of charge units */ T>IsdnChargeInd;
    Meaning of the fields:
  • indType ISDN_CHARGE_IND
  • callId Identifies the logical connection.
  • units Number of charging units.
  • EXAMPLE IsdnCallback (tIsdnInd *ind)

    tIsdnChargeInd *alert = (tIsdnChargeInd*)ind;

    if (ind->indType == ISDNCHARGEIND) printf ("Charging for printf ("the call costs

    D.19. IsdnConnectInd

  • PURPOSE Indicates that the connection to the peer is established.
  • SYNTAX #include <IsdnLib.h>

    IsdnCallback (t_IsdnInd *ind);

  • DESCRIPTION If the connection to the peer is established, the IsdnLib calls the callback function, that was registered with a IsdnConnectInd as a parameter. From that point in time, data may be exchange between the sites by use of the file descriptor. The file descriptor was provided by IsdnChannelInd before.

    The parameter t_IsdnConnectInd provides further information about the indication.

    typedef struct /* indicates that the call is connected (active) now */ tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ T>IsdnConnectInd;
    Meaning of the fields:
  • indType ISDN_CONNECT_IND
  • callId Identifies the logical connection.
  • EXAMPLE IsdnCallback (tIsdnInd *ind)

    tIsdnConnectInd *alert = (tIsdnConnectInd*)ind;

    if (ind->indType == ISDNCONNECTIND) printf ("Call T>

    D.20. IsdnDisconnectInd

  • PURPOSE Indicates that the connection was released.
  • SYNTAX #include <IsdnLib.h>

  • DESCRIPTION If the connection between two site was released, the IsdnLib calls the callback function that was registered with IsdnDisconnectInd as a parameter.

    The parameter t_IsdnDisconnectInd provides further information about indication:

    typedef struct tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ tCause cause; T>IsdnDisconnectInd;
    Meaning of the fields:
  • indType ISDN_DISCONNECT_IND
  • callId Identifies the logical connection.
  • cause Indicates the reason the connection was released. For the meaning see Q.850 [itu9303:Q.850]. As a consequence of this indication the application should close the data chaannel and terminate the connection by IsdnReleaseReq. If this is not done within 15 seconds, it is initiated by the Vermittlungsstelle???.
  • EXAMPLE IsdnCallback (tIsdnInd *ind)

    tIsdnDisconnectInd *disc = (tIsdnDisconnectInd*)ind;

    if (ind->indType == ISDNDISCONNECTIND) printf ("%d disconnected", disc->callId); printf ("Cause:"); DumpCause (stdout, disc->cause); T>

    D.21. IsdnReleaseInd

  • PURPOSE Indicates that the logical connection was released.
  • SYNTAX #include <IsdnLib.h>

    IsdnCallback (t_IsdnInd *ind);

  • DESCRIPTION The IsdnLib calls the callback function, that was registered, with IsdnReleaseInd as a parameter in order to indicate the application the logical connection was released.

    The parameter t_IsdnReleaseInd provides further information aout the indication:

    typedef struct tIsdnIndType indType; /* type of inication */ int callId; /* unique ID of the call */ tCause cause; T>IsdnReleaseInd;
    Meaning of the fields??:
  • indType ISDN_ALERT_IND
  • callId Identifies the logical connection.
  • cause Indicates the reason the connection was released. For the meaning see Q.850 [itu9303:Q.850]. At least after receiving this message, the application should close the file descriptor applied to the data channel if still open. After this indication the application should not initiate further messages for this callId. Otherwise an error is reported. No further messages for this callId can be expected from the IsdnLib.

    The message can be sent at any time for each valid callId

  • EXAMPLE??? IsdnCallback (tIsdnInd *ind)

    tIsdnReleaseInd *rel = (tIsdnReleaseInd*)ind;

    if (ind->indType == ISDNRELEASEIND) printf ("%d released now", disc->callId); printf ("Cause:"); DumpCause (stdout, disc->cause); T>