E. Source-Code für die IsdnLib

E.7. Für das Allgemeine

E.7.1. README, eine allgemeine Einführung

WELCOME
=======
Welcome to the IsdnLib, a library which implements the Q.931 stack and
gives the user an easer way to communicate with the ISDN card in a SUN.

The very first version of an Q.931 module was written by Bengt Olof Sahlin
(bos@mail.cs.hut.fi). This is a total rewrite of the first version and
looks very different. It was written by (Christian Zahl, zahl@fokus.gmd.de)
as an part of my master-thesis.

TABLE OF CONTENTS:
=================
	1 OVERVIEW OF THE PACKAGE
		1.1 ISDN-LIB INTERFACE
		1.2 HANDLING OF IE's
		1.3 HANDLING OF Q.931 MESSAGES
		1.4 SCHEDULER
		1.5 MISCELLANEOUS
		1.6 DLPI INTERFACE
	2 COMPILING
		2.1 DEBUGGING
	3 RUNNING
	4 FURTHER WORK
		4.1 PROBLEMS / QUESTSIONS
		4.2 TODO
	5 ACKNOWLEDGEMENTS
	6 DOCUMENTATION
	7 AUTHOR, FINAL WORDS
----------------------------------------------------------------------------

1 OVERVIEW OF THE PACKAGE
=========================
The package is devided into several logical areas:
	o the IsdnLib interface
	o handling of Information Elements (IE's)
	o handling of Q.931 messages
	o the scheduler
	o misc files
	o the DLPI interface to the Q.921 module

The files and their contents is described in 00FILES. Below is a brief
description of the parts mentioned above.

1.1 ISDN-LIB INTERFACE
----------------------
The IsdnLib is a library for using an ISDN interface in a more comfortable
way. Because SUN does not provides an appriate API for it's ISDN card, we
decided to create such a beast.

The main problem is, that because ot the nature of the ISDN, the whole
library must be event driven. So the library implements an scheduler,
which is the core of the whole lib. It is also possible to "overwrite"
the default scheduler for using another one, e.g. to make use of it
in tcl/tk.

Because messages from the ISDN can arrive at any time, there is a way to
"register" your-self. This is done by calling IsdnInitialize(), with a
callback function as parameter. Whenever a new message from the ISDN
arrives, the callback function is called with an argument, a pointer
to the arrived message. The callback function then can handle the message
and can make the right decissions. E.g. it can call other IsdnLib function
to send another message out.

Because there can be several messages for different and new (not yet
established) connection, we need an identifier to decide to which connection
the given message belongs. This is done a "CallId", which will be send
with every message and indication. This CallId can be understood as a
filedescriptor for the connection.

For a detailed description of the IsdnLib interface, refer to the man-page
IsdnLib (3).

1.2 HANDLING OF IE's
--------------------
Because the Q.931 representation of the IE's is very complex and bit oriented,
we have decided to use another representation for the internal handling.
There is one .c and .h file for each supported IE. In the .h file, the struct
for representing the IE in C is defined (e.g. t%Cause). The .c files contains
two functions, one for converting the Q.931 representation into the interal
C struct, named Q931Pop###() (e.g. Q931PopCause), and one for the other direction,
named Q931Push###() (e.g. Q931PushCause).

Currently not all possible IE's are implemented, but it should be very easy
to extend the set of IE's. There is one thing you should keep in mind when
doing so. For an easy and fast conversion, the internal values in the
members of each struct is the value in the Q.931 recommendation, plus 0x100!
So every valid value for the internal fields is in the range of 0x100 to
0x1ff. If an filed is missing in the Q.931 message (can happen VERY often),
then the value SHALL be set to 0. By doing so, the user can easily decide,
if the field was present or not.

	File			IE
	----			--
	BearerCap.[ch]		Bearer Copability
	CallRef.[ch]		Call Reference Value
	CallingPartyNo.[ch]	Calling Party Number
	CalledPartyNo.[ch]	Called Party Number
	Cause.[ch]		Cause
	ChannelId.[ch]		Channel Indication
	HighLayerComp.[ch]	High Layer Compatibility
	Keypad.[ch]		Keypad
	LowLayerComp.[ch]	Low Layer Compatibility
	NotifyInd.[ch]		Notification Indicator
	ProgressInd.[ch]	Progress Indicator
	
1.3 HANDLING OF Q.931 MESSAGES
------------------------------
To keep the files small and fine, there is one .c and one .h file for each
possible Q.931 message. The .h file defines the struct, which is the internal
representation of the message (e.g. t-Q931SetupReq). Unused fields are
filled with 0, acording to the rules described above. The .c file implements
(in most cases) four function.

Q931###Req() is called by the library, when there is a message to be send to
the network (e.g. Q931SetupReq). This function is responsible to handle the
internal state machine, according to Q.931.

It then calls the second function, Q931Send###(), which converts the internal
message into a valid Q.931 message (e.g. Q931SendReq).

The third function is called Q931xxxInd() and is called whenever this
message is received from the network (e.g. Q931SetupInd). It handles the
internal Q.931 state machine, handles the CallReferenceValues and the timers.

It then calls the fourth function, xxxInd(), which generates the internal
indication and calls the users callback routine.

Files:
	File				Q.931 message
	----				-------------
	Q931Alerting.[ch]		ALERTING
	Q931CallProceeding.[ch]		CALL-PROCEEDING
	Q931Connect.[ch]		CONNECT
	Q931ConnectAck.[ch]		CONNECT-ACKNOWLEDGE
	Q931Disconnect.[ch]		DISCONNECT
	Q931Information.[ch]		INFORMATION
	Q931Notify.[ch]			NOTIFY
	Q931Progress.[ch]		PROGRESS
	Q931Release.[ch]		RELEASE + RELEASE-COMPLETE
	Q931Setup.[ch]			SETUP
	Q931SetupAck.[ch]		SETUP-ACKNOWLEDGE

The other Message Types are not implemented yet:
	RESUME
	RESUME ACKNOWLEDGE
	SUSPEND
	SUSPEND ACKNOWLEDGE
	SUSPEND REJECT
	USER INFORMATION
	RESTART
	RESTART ACKNOWLEDGE
	SEGMENT
	CONGESTION CONTROL
	STATUS
	STATUS ENQUIRY

1.4 SCHEDULER
-------------
The scheduler is a main-loop, which waits for any incomming events. When an
event occurs, the appropiate handler will be called. It is possible to
register so called "FileHandler" and "TimerHandler". A FileHandler can
be installed for a given fd and an event to occur:
	SCHEDULER-READABLE		signals when fd becomes readable
	SCHEDULER-WRITABLE		signals when fd becomes writable
	SCHEDULER-EXECPTION		signals any other exception

A TimerHandler can be installed for any given timeout value (in ms). When
any of the handlers has to signal an event, it calls the installed callback
routine for the given fd or timer (identified by a TimerId).

The parameters are the same as for the tcl/tk interface. To make use of
another scheduler, e.g. the one from tcl/tk, simply write six function,
which calls the right funtions:
	SchedulerInitialize ()
	SchedulerCreateFileHanlder ()
	SchedulerDeleteFilehandler ()
	SchedulerCreateTimerHandler ()
	SchedulerDeleteTimerHandler ()
	SchedulerMainLoop ()

NOTE: to "overwrite" the funtions has not been tested up to now :-O

1.5 MISCELANEOUS
----------------
Of course, there are some other impotant files. They are responsable for
receiving and scheduling incomming messages to the right functions, handle
all the various Q.931 timers and give some debugging support.

Files:
	Q931Main.[ch]
	Q931Msg.[ch]
	Q931Timer.[ch]
	Debug.[ch]
	Dump.[ch]

1.6 DLPI INTERFACE
------------------
The Q.921 module we are using has been implemented by Bengt Olof Sahlin as
an DLPI interface. He also wrote some routines for easy handling of DLPI
messages, which was simply included in the distribution.

Files:
	Dlpi.[ch]

--------------------------------------------------------------------------
2. COMPILING
============
There is a Makefile.in available, which is used as a source for "make depend".
The Makefile will then be recreated, so don't make any changes in the Makefile
itself! To create the library, do the following:
	o Make any necessarry changes in Makefile.in
	o run "make depend" to create the correct Makefile
	o run "make" to create the IsdnLib

This will result in a library called "src/libisdn.a", which is the IsdnLib.
There are some test programms available in the "test" subdirectory:
	test1	Dumps any Q.931 message received by the IsdnLib through the
		callback routine. It doesn't send any message by itself!

2.1 DEBUGGING
-------------
I have implemented some kind of debugging, which can be totaly turned off
in the Makefile. When "WITH-DEBUG" is defined, debugging support is inclueded,
otherwise not. You can turn on and off various kinds of debugging by setting
the environment variable "ISDN-DEBUG" to a specific value. It's an good idea
to use the haxadecimal representation (e.g. "0x1234"). So, to turn on all
debugging, so the following:
	ksh:	export ISDN-DEBUG=0xffff
	csh:	setenv ISDN-DEBUG 0xffff

To turn off debugging without recompiling:
	ksh:	export ISDN-DEBUG=0
	csh:	setenv ISDN-DEBUG 0

The see which values are available, look into "src/debug.h". All debugging
output is send to stdout.

--------------------------------------------------------------------------
3. RUNNING
==========
	# cd driver
	# make install
	# insertmux open
	# cd ..
	# cd q931/NEW
	# test/test1
	# test/test2

--------------------------------------------------------------------------
4. FURTHER WORK
===============

4.1 PROBLEMS / QUESTIONS
------------------------
o called party no in overlap sending in keypad or calledPartyNo???

4.2 TODO
--------
There is still a lot of stuff that can be done. E.g. implementing the
handling of other messages like AOC[DE]. Also using more than one ISDN
card and using a PRI card can be added. There are also some IE's and
messages not fully implemented.

	o Check if all IE's will be "received" and handled
	o Check, if all the IE's which can occur more than one, are handled
	  in the right way

--------------------------------------------------------------------------
5. ACKNOWLEDGEMENTS
===================
Many thanks to Bengt Olof Sahlin, who implemented the first Q.931 module.
He also implements the Q.921 module, which will be used by this package.

--------------------------------------------------------------------------
6. DOCUMENTATION
================
It is planed to describe the whole library and all functions in several
man pages. Because my time is limited, this has not been done up to now.

To get an idea of how to use the library, refer to the file "DOC".

--------------------------------------------------------------------------
7. AUTHOR, FINAL WORDS
======================
Well, the whole library and all the related files were written by me,
Christian Zahl (zahl@fokus.gmd.de). As also noted, this is one
(unfortunately not the only) part of my master-thesis.

Currently (Oct-96) I will stop with any further work on the IsdnLib. It is
planed that Frank Oertel will use the IsdnLib in his master-thesis in the
first real application. Bengt Olof Sahlin will also use the library for the
ongoing SunShine project in Finnland.

I stoped with any further work, because I have also to make the remaining
part of my master-thesis. Anyway, any bugs found can be send to me:
	zahl@fokus.gmd.de

Please don't expect quick responses, because of the remaining stuff; there
is allways toooo less time :-(

E.7.2. DOC, allgemeine Beschreibung

0 HELLO
=======
IsdnLib -- a library for using the ISDN device in a SUN

This file gives a overview of the IsdnLib, how it works and how it can be
used. There should be also the man-pages available for all the requests
and indication, but currently they are in an incomplete and old state.
And on the other side, the man-pages don't give you an good explaination
of how the library can be used.

1.0 INTRODUCTION
================
The main idea was to design an interface to the ISDN world, which is much
simpler than using ISDN directly. The first attempt was to write some
funktion, so that the interface is very simmilar to the socket interface.
Because everyone (or not :-) knows the socket interface, it should be
easy to use the library.

The problem was, that it should still be possible to use the library for
%EVERY- kind of ISDN application. Because of this, I had to make a compromise.
Using some kind of socket interface will not give us the wanted results.
We need an event driven interface, because events can occur on every time,
like in the X-interface.

Secondly, it should be possible to combine tcl/tk with the library. This
results in the interface which currently exists.

2 DESIGN
==========
The core of the library (called IsdnLib) is a scheduler function, which
reveices ISDN and other messages and handles them in a (hopefully) correct
way. The application have to install filehandlers for any input or
output device, it is using. When a given filedescriptor has someting
to signal, the application provided callback function is called. This
callback function then can handle the event, and have to return (relative
quickly, because of the nature of the ISDN). So, let's say that the
callback function shouldn't be active for more than 1s!

The application also installs a callback function for ISDN events. This
function will be called, when (interesting, not all) messages arrives
from the ISDN. The IsdnLib translates the ISDN messages into indications,
which will be signalled via the callback.

When the application wants to make use of ISDN features, it has to call
one of the various requests to issue the right ISDN messages.

Below is a very simple prototype of an application source file, when
using the IsdnLib:
	...
	#include "IsdnLib.h"
	...
	void IsdnCb (t-IsdnInd *ind)
	{
		switch (ind) {
			case ISDN-CALL-IND:
				printf ("incomming call from...");
				...
			case ISDN-DISC-IND:
				...
			...
		}
	}
	ControlCb (int mask, void *data)
	{
		/* read from the control fd and handle the request */
	}
	...
	main ()
	{
		...
		IsdnInitialize (IsdnCb);
		...
		IsdnCreateFileHandler (controlFd, ISDN-READABLE, ControlCb, NULL);
		...
		IsdnMainLopp ();
		IsdnFini ();
		...
	}

Every application has to follow the prototype above.

3. REQUESTS AND INDICATION
==========================
As mentioned above, there are a lot of requests and indications available.
The following is a brief description of them. First let's see how to issue
a call and which indications will arrive.

3.1 IsdnCallReq (t-IsdnCallReq *req)
------------------
Whenever the user wants to issue a call through the ISDN, it calls this
function. The req specifies all the necessarry informations. E.g. the
number to be called can be specified, but because of the nature of the
ISDN don't have to be specified (see IsdnDialReq).

On return, the "callId" field in req was set to the unique callId given
for this (not yet established) connection. This callId has to be used in
all the other requests, and will be used in other indications belonging
to the same connection.

Note, that this requests only issues a call request. The call has NOT been
established when the function returns. Other indications will arrive
via the IsdnCb function (see above).

The IsdnCallReq results in an outgoing SETUP message send to the ISDN.

3.2 IsdnChannelInd
------------------
Normaly, the ISDN responds with an SETUP-ACKNOWLEDGE. When this message
arrives, the IsdnLib calls the IsdnCb function with an IsdnChannelInd
as parameter. The callId in the parameter is set to the same as returned
by the IsdnCallReq().

This indication informs the application that a B-chnannel has been assigend
and opened now. The filedescriptor of the opened fd is included in the
indication (IsdnChannelInd.fd). The application can use this fd to send the
received data to an audio hardware. Normaly, you will hear some kind of
tone from the ISDN network, specially when no number to be dialed has been
given.

Again, the connection has not been established up to now!

3.3 IsdnProgressInd
-------------------
At any time IsdnProgressInd can arrive, for an active call and for those
currently initiated or terminated. This simply gives the application an
idea of the current state of the connection. Specially, the tones available
in most ISDN environments, which are intended to be understood by the human
user, will be described via this indication.

3.4 IsdnDialReq ()
------------------
Analog to the old analog telephne, you have still the chance the dial the
number after an SETUP has been send to the ISDN. This can be done by
using the IsdnDialReq(). The request can be called multiple times with
one ore more "digits" included.

3.4 IsdnAlertInd
----------------
When the number to be dialed is complete, the calling user will be informed.
If he is able and willing to receive the call, he will answer by sending
an ISDN ALERTING message. This message will be send to the caller (to us
in this example). The application is then informed by invoking the IsdnCb
with an IsdnAlertInd as the parameter.

After this indication has been reveiced, no further IsdnDialReq() will be
accepted (according to the Q.931 spec).

3.5 IsdnConnectInd ()
---------------------
When the called user accepts the call and sends an ISDN CONNECT message
(the same as putting the phone off-hook), then the call is connected.
The application is informed by the invokation of IsdnCb with an IsdnConnectInd.
At this point a circuit connection has been established between the
calling and the called user. All B-Channel data will be transmitted in both
directions from now on.

3.6 IsdnReleaseReq ()
---------------------
When the calling user wish to terminate the call, it should issue an
IsdnReleaseReq. The connection will be terminated then and the application
will be informaed of this onve again (IsdnReleaseInd).

Because of the nature of the ISDN, this will be done in a two phase
way. First, (in this case) an ISDN DISCONNECT message will be send, and
the network will answer with an ISDN RELEASE. The IsdnLib then sends an
ISDN RELEASE COMPLETE message and sends a IsdnReleaseInd ().

3.7 IsdnReleaseInd ()
---------------------
When the ISDN network sends a RELEASE message, the IsdnLib will inform the
application by calling the IsdnCb with an IsdnReleaseInd. This informs
the application to release all resources associated with the call indicated
by callId.

After return from the IsdnCb, the IsdnLib also closes any open B-channel for
the given context and released ISDN resources. So NEVER use the B-Channel fd
after the receiption of an IsdnReleaseInd!

Also note that this indication can occur at any time for any given callId!
This can happen when the ISDN resets, the call is beeing aborted etc.
In any case, after receipt of the IsdnReleaseInd, free ALL resources
for the associated call!

3.8 IsdnDisconnectInd ()
------------------------
Of course, it can also happen that not you, but the other party will terminate
the call. The ISDN then sends an ISDN DISCONNECT message to inform the user.
I decided to keep this message, because additional messages / tone can be
available via the B-Channel.

When the user no longer needs the B-Channel for any messages, it has to call
the IsdnReleaseReq(). If the users doesn't do this, the ISDN will generate
an RELEASE message after some timeout.

The IsdnDisconnectInd can also occur when the (not yet connected) call will
be terminated. So as with the IsdnReleaseInd, you should expect that this
indication can arrive at any time for a given callId!

3.9 IsdnCallReq ()
------------------
After we took a look at the outgoing call, let's see the other direction,
incomming calls. At any time, an IsdnCallInd can arrive. Included in the
indication are all the necessary informations for deciding what to do.
E.g. the called party number is included, so that the application can decide
if it is responsible for this number. Also the bearer capabilities etc.
are included.

If the application cannot handle the call, there are two possiblities.
First, it can simply ignore the indication (an IsdnReleaseInd will be
send after some timeout), or can call the IsdnReleaseReq(). The latter
can be used to inform the ISDN network of the cause, why the application
will not accept the call (e.g. "User is busy"). Depending of the kind of
ISDN interface (singlepoint of multipoint environment), the call will be
rejected by the ISDN.

3.10 IsdnAllertingReq ()
------------------------
When the application want's to signal it's interest in the call, it shall
anser with an IsdnAllertReq() This signals the ISDN network, that there
is someone who is able to accept the call. The calling party then gets
the well-known ringing tone.

Note that you have to issue this request relative fast after the receipt
of the IsdnCallInd. There is a timeout defined by the ISDN network, after
which an unanswered call will be rejected. This timeout is aprox. 4s,
so don't use this time for the "normal ringing procedure of a telephone".

3.11 IsdnConnectReq ()
----------------------
After an incomming call has been signaled, and the user wishes to accept
the call, the application should call this request. This requests the
ISDN network to establish the ciruit switched connection to the calling
user. The connection is not installed at this time, you have to wait
for the IsdnChannelInd() and IsdnConnectInd () (see above).

When the network is not able to create the connection, an IsdnReleaseInd
or IsdnDisconnectInd will be invoked. This can happen e.g. when there is
a collision (calling user gives up, called user takes the phone).

3.12 IsdnKeypadReq ()
---------------------
The ISDN network provides the ability to issue other ISDN related procedures.
These can be invoked via this request. The meaning of the contents of the
keypad IE, and if the network supports this, depends on the provinding
ISDN network. In my test environment I never used this request :-)

3.13 IsdnChargeInd
------------------
Of course, billing is also an interesting information. The ISDN provides
the ability to generate several kinds of AOC informations (AOCD, AOCE, AOCR).
Whenever such an message assives, it is translated into an IsdnCargeInd,
which will be send to the user.

Unfortunately this indication is not implemented at the moment. The problem
is that I haven't understood the ASN.1 encoding of such messages :-(

-------------------------------------------------------------------------------
4 SUMMARY
=========
Well I hope that the above description gives an overview of what you can
do with the IsdnLib and how it works. For more informations refer to the
test programms in test/test*.c.

E.7.3. HISTORY, Beschreibung des zeitlichen Verlaufes

Short overwiev of the history of the IsdnLib

End 1995
	- searched for an API for using ISDN
	- found SunShine

Mar 1996
	- decided to use SunShine
	- decided to rewrite the Q.931 part of SunShine

1-Oct-1996
	- first alpha version

E.7.4. Makefile

all:
	(cd src; make all)
	(cd test; make all)

E.7.5. config, Konfiguration für make