Application program interface5572675Abstract An application program interface for integrated services digital networks is implemented so that application programs can be generated independently of network protocols (Layer 1, 2; 1TR6, VN2) and independently of the respective implementation of service features. The application program interface contains for each network service an independent service program module (Telephony, FAX, Packet data, Teletex, . . . ) with a message set representing procedures as specified by standards (CCITT, ETSI, . . . ). Claims I claim: Description TECHNICAL FIELD
______________________________________
Bit 0 Telephony (3.1 kHz, 7 kHz)
Bit 1 FAX Group 3
Bit 2 FAX Group 4
Bit 3 Teletex
Bit 4 Videotex
Bit 5 Packet data
Bit 6 Bit-rate adaptation
.
. Reserved for other services.
______________________________________
Thus, corresponding message queues can be readily setup. With the aid of a release call, an associated message queue can be released. Because of the modular construction of the API, an integrated services digital network can be adapted by addition or removal of service program modules. Since, in addition, the service program modules are based on internationally standardized (if possible) procedures which are independent of the actual implementation according to, e.g., national protocols (1TR6, VN2, etc.) in the respective existing (PC) network interface ACID, each application program module can be created completely independently based solely on standardized functions. Referring now to FIG. 2 and the description below, API functions, according to an exemplary embodiment of the invention, are described in C language function calls. The naming convention for the function names are lower case letters the function name is preceded by the shortcut "api.sub.-- " FIG. 2 shows a start step 10 transitioning to a wait state 12 in which application program commands or ISDN messages from the ACID are awaited by the API. Indication of Available Messages Assuming the receipt of a start command from an application program, the application program can define a signal function during registration of it (see api.sub.-- register below). Example for a signal function:
______________________________________
void api.sub.-- signal (void)
nb.sub.-- messages++;
______________________________________
The signal function just counts the number nb of messages which are available for an application. The nb.sub.-- messages parameter is set to zero at the beginning of the application program. A nonzero value of the nb.sub.-- messages variable then indicates that a message can be received. Registration and Release of Applications Application programs are registered to the API when they start using it and they are released by the API when they cease using it. For this purpose two calls to the API are provided by the API.
______________________________________
(1.) Registration
api register
Syntax:-
char api.sub.-- register
(void sig.sub.-- function, unsigned
char acid.sub.-- id, short
inc.sub.-- call.sub.-- int, char subaddr)
Parameters:-
sig.sub.-- function
Pointer to a signal function. This
function is called by the API when
messages for this application are
available.
acid.sub.-- id
0 automatic assignment of any
ACID required
! = 0 specific ACID assignment
required.
Example:- S0- and Up0-card -
almost identical applications
both interested on voice calls
from Up0 or S0.
inc.sub.-- call.sub.-- int
incoming calls interested BITFIELD.
This value is used by the API to
route incoming calls to the
appropriate application program. If
another application is already
assigned for the required type of
incoming calls with the same
subaddress specification then the
registration fails.
0 no incoming calls interested in
(when no other application is
interested in incoming calls and
no handset is available then
arriving calls are not
answered).
Oxfff Interested in any incoming
calls
bit 0 Telephony
(3.1 kHz voice, 7 kHz
voice, speech)
bit 1 Fax Gr. 3
bit 2 Fax Gr. 4
bit 3 Teletex
bit 4 Videotex
bit 5 x.25 calls (packet data
calls)
bit 6 V.110 rate adaptation calls
bit 7-15
reserved for other
conditions
subaddr Specifies the subaddress for this
application (relevant for routing of
incoming calls).
Example:
5-8 accept calls for subaddress 5 to
8
5* accept all calls, where the
subaddress begins with 5
Return values:-
1-127 nsap.sub.-- id: Network service access point
identifier, this value is used in the
message header.
0 not used
-1 no board installed (not responding)
-2 API not responding
-3 required board can't be assigned
-4 already an application assigned for this
type of incoming calls with the same
subaddress
Description:-
This function call is used to establish the message
queuing system for this application.
One application program can handle several
NSAP-IDs, e.g., to have access to more than one
ACID.
______________________________________
Thus, as illustrated in FIG. 2, in the application program registration state 14, the network interface that the application program wants to communicate with is identified. Also identified is the type of information it wishes to receive, e.g., teletex, videotex, etc. It also has the capability to specify an application specific subaddress for routing the same information to more than one application program. As illustrated in a state 16, a specific application program function is stored to be called by the API when information of the correct type for this application program is available, i.e., to provide the "trigger" for the application program that such information is available and can be read and processed. It also provides a network service access point identifier (a number from 1-127) to be used by the application program when communicating with a particular ACID. As illustrated by states 18, 20, a message queue is created by the API for the particular end device. The queue consists of at least one input queue (InQ) and at least one output queue (OutQ).
______________________________________
(2.) Release
api release
Syntax:-
short-api.sub.-- release (char nsap.sub.-- id)
Parameters:-
nsap.sub.-- id Network service access point identifier
Return Values:-
0 Application released
1 Unknown nsap.sub.-- id
2 API not responding
Description:-
This function call to the API is used to release the
application, free the message queues and the
application id. All pending operations, calls,
messages, connections for this application are
cleared and reset. All parameters set by the
application (valid per registration or valid per
call) are reset to the default values.
______________________________________
The release call is illustrated in FIG. 2 by a state 22 which releases the application and by states 24, 26 which free the message queues and the application ID, as described above. The transition from state 24 to state 26 assumes that no other application programs are using this ISDN device. If that is not the case, a transition is made directly from state 24 back to state 12 so that the ISDN device may continue to be used by any other application programs that may happen to be using it. As described above, all pending operations are cleared and reset at all parameters reset. Message Communication Services api send (application program sends to the API which sends to the ISDN device) As shown by a state 28 in FIG. 2, after application program registration illustrated by the states 14, 16, 18, 20, a transition may be made to a state 28 in which the application program sends a message to an ISDN device. This means that the application program has a software function called to "API.sub.-- send" specifying a message and a mode. The message header contains the network service access point identifier (positive number 1-127 established during registration) and the command to be sent to the ISDN device. The mode specifies when the API should return to the application program. In the API, the message header is decoded by the API so the message can be formatted according to the appropriate communication protocol and sent to the ISDN device. The address device is mapped to the API. An exemplary embodiment is shown below.
______________________________________
Syntax:-
short api.sub.-- send (char msg.sub.-- buf, char mode)
Parameters:-
msg.sub.-- buf
pointer to the message buffer
mode The application can send a message in the
WAIT or the IMMEDIATE mode.
0 WAIT: wait until command was executed
1 immediate: immediate return to
application
Return Values:-
0 Sending of the message successful
1 Input Queue full
2 API not responding
3 Message not supported by network ACID
4 Unknown nsap.sub.-- id
5 Unknown Command
6 WAIT mode required for message
Description:
The api.sub.-- send function is used to send messages to
the API.
Validity check of messages according to capabilities
of ACID and network
api receive (application program receives from
the api which in turn received from
an ISDN device)
______________________________________
As illustrated in a state 30 in FIG. 2, the application program can receive a message (if any) from an ISDN device and will load the message into an ISDN input queue as illustrated in a state 32. A transition to a state 34 results in a call to a pointer to a signal function in order to call the API to notify it that messages for the particular application are available. After transitioning back to the wait state 12, the API moves the ISDN message from the input queue to the application program buffer as illustrated in a state 36.
______________________________________
Syntax:-
short api.sub.-- receive (char nsap.sub.-- id, char buffer)
Parameters:-
nsap.sub.-- id
Id of application, which wants to
receive a message
char buffer [MAX.sub.-- RECEIVE.sub.-- SIZE]
buffer for input message, provided by
the application
Return values:-
0 Message received
1 No message pending
2 API not responding
Description:
The api.sub.-- receive function is used to receive messages
from the API.
______________________________________
Several voice call interaction diagram examples are shown below to illustrate various API send/receive sequences which might occur using the API of the present invention according to the ECMA telephony standard message set listed in the annex.
______________________________________
Interaction Diagram
Voice Calls
Outgoing Calls
1. From application (successful)
VC.sub.-- DIAL
.fwdarw.
.rarw. VC.sub.-- RESULT (ok)
.rarw. HS.sub.-- STATUS
(`+`) (*1)
.rarw. VC.sub.-- ALERTED
(*2)
.rarw. VC.sub.-- CONNECTED
(Voice)
.rarw..fwdarw.
(*1) The handset (HS) can be also off-hook before
the VC DIAL message is being sent.
(*2) The Alert message is not necessary, it is also
possible that the first message is immediate
VC.sub.-- CONNECTED.
2. From application (engaged)
VC.sub.-- DIAL
.fwdarw.
.rarw. VC.sub.-- RESULT (ok)
.rarw. HC.sub.-- ENGAGED
(engaged.sub.-- ID)
. . . (*1)
VC.sub.-- TERMINATE
.fwdarw.
.rarw. VC.sub.-- RESULT (ok)
(*1) At this point the application program can
start some additional services, e.g.,
VC.sub.-- BOOKING.
3. From handset (successful)
.rarw. HS-STATUS ('+')
.rarw. HS.sub.-- STATUS ('1'
. . . '9')
. . . (*1)
.rarw. HS.sub.-- STATUS ('1'
. . . '9')
.rarw. VC.sub.-- ALERTED (*2)
.rarw. VC.sub.-- CONNECTED
(Voice)
.rarw..fwdarw.
(*1) The user dials several numbers
(*2) At this point the user has dialed enough
numbers and a connection could be
established.
The Alert message is not necessary, it is
also possible that the first message is
immediate VC.sub.-- CONNECTED.
4. From handset (not successful)
.rarw. HS.sub.-- STATUS ('+')
.rarw. HS.sub.-- STATUS ('1'
. . . '9')
. . . (*1)
.rarw. HS.sub.-- STATUS ('1'
. . . '9')
.rarw. VC.sub.-- ENGAGED
(engaged.sub.-- id
. . . (*2)
VC.sub.-- TERMINATE
.fwdarw.
.rarw. VC.sub.-- RESULT (ok)
(*1) User dials several numbers
(*2) At this point the application program
can start some additional services,
e.g., VC.sub.-- BOOKING.
Incoming Call
1. Handset answers call
.rarw. VC.sub.-- INCOMING.sub.-- CALL
.rarw. HS.sub.-- STATUS ('1')
.rarw. VC.sub.-- CONNECTED
(Voice)
.rarw..fwdarw.
2. Application answers call
.rarw. VC.sub.-- INCOMING.sub.-- CALL
.rarw. VC STATUS (ok)
.rarw. VC.sub.-- CONNECTED
(Voice)
.rarw..fwdarw.
______________________________________
Although the invention has been shown and described with respect to a best mode embodiment thereof, it should be understood by those skilled in the art that the foregoing and various other changes, omissions and additions in the form and detail thereof may be made therein without departing from the spirit and scope of the invention.
______________________________________
Annex
Telephony: (Voice Call)
VC Dial
VC Answer
VC Terminate
VC Alerted
VC Connected
VC Disconnected
VC Engaged
VC Incoming Call
VC Result
VC Conference
VC Drop
VC Transfer
VC Hold
VC Reconnect
VC Booking
VC Camp On
VC Divert
VC Enquire
VC Broker
VC Intrusion
VC Pickup
VC Direct Speech
Packet data as specified in X.213 (CCITT):
PD = Packet data, QOS = Quality of Service
DATA MANAGEMENT
PD SET QOS
PD GET PARENTS
CONNECTION PHASE / RELEASE PHASE
PD CONNECT REQ / DISCONNECT REQ
PD CONNECT CONF
PD CONNECT IND / DISCONNECT IND
DATA TRANSFER PHASE
PD CONNECT RESP
PD DATA REQ
PD DATA IND
PD DATA ACK REQ
PD DATA ACK IND
PD EXP DATA REQ
PD EXP DATA IND
RESET SERVICE
PD RESET REG
PD RESET CON
PD RESET IND
PD RESET RESP
RESULT MESSAGE
PD RESULT
Bit-rate adaptation as specified in V.110 (CCITT):
Global Type: V110 Modem
V110 Dial
V110 Connected
V110 Incoming Call
V110 Answer
V110 Terminate
V110 Disconnected
V110 Send
V110 Receive
V110 Parameter
V110 Result
Videotex as specified in ETSI: ETS 300079:
Basic Videotex Messages
VTX Establish
VTX Release
VTX Data
VTX Reset
VTX Set Param
VTX Read Param
VTX Set Read Param
VTX TFI
VTX TC Error
Optional Videotex Messages
VTX Channel Open
VTX Channel Close
VTX Channel Error
VTX Begin Application
VTX End Application
VTX TPD Begin
VTX TPD End
VTX DFK
VTX Escape
Global Definition for Videotex Messages
VTX ADDR
VTX Appl
VTX D UUI
VTX B CUD
VTX Cause
VTX X3 Param
Fax Group 3/4 corresponding to Packet data as specified
in X.213.
______________________________________
|
Same subclass Same class Consider this |
||||||||||
