Application programming interface for modem and ISDN processing6347093Abstract An application programming interface provides for command and data communication between a user, application or driver and a telephone data processing system which provides communication between a host computer and a telephone line. The telephone data processing system is capable of processing ISDN telephone calls as well as voice or analog-originated telephone calls. The application programming interface of the invention includes a host interface, an ISDN interface and a modem interface. The host interface receives commands and data from the user. The modem interface and ISDN interface provide commands and data communication between the host interface and the appropriate telephone call processing based on telephone call type. At the top level, the specific call type processing is transparent to the user. That is, the user need not know the type of telephone call, i.e., modem or ISDN, being processed. Claims What is claimed is: Description BACKGROUND OF THE INVENTION
TABLE 1
Host API Function Call Summary
Call Type Function Purpose
Initialization MICA_Accept ( ) Accept an incoming
call.
MICA_Close ( ) Close a data channel;
used for terminating a
call.
MICA_Connect ( ) Dial the phone
MICA_Init ( ) Initialize the boards;
should be called once
per board.
MICA_Listen ( ) Listen on a channel for
an incoming call.
MICA_Open ( ) Open a channel for lis-
tening or dialing.
MICA_Reset ( ) Reset a board; used
when a board needs to
be restarted.
Data Flow MICA_Recv ( ) Receives data (if any)
from a previously
opened channel.
MICA_Select ( ) Check a channel's
status.
MICA_Send ( ) The channel must be
opened first; sends
data out to the MICA
board set.
Control Messages MICA_GetOption ( ) Get the status of a
system option.
MICA_ProcessInt ( ) Process a MICA inter-
rupt.
MICA_SetOption ( ) Set or modify a system
option.
All of the host API function calls send parameters with each function call. Each function also returns a result code to indicate the result of the function call. Each function call will now be described in detail. The MICA_Accept call is used to accept an incoming call on a particular channel. A sample format for the call is as follows:
MICA_Accept (
intl6 channelld
)
The parameter channelId indicates the ID number of the channel on which the call is to be accepted. The possible result codes are as follows:
MICA_SUCCESS The call is accepted.
MICA_ERROR The call is rejected.
The MICA_Close function call is used to close a data channel. A sample format is as follows:
MICA_Close (
intl6 channelld
)
The parameter channelId is used to identify the channel that is to be closed. The possible result codes are as follows:
MICA_SUCCESS The channel is closed.
MICA_INVALID_CHANNEL The channel provided was not valid.
MICA_NOT_OPEN The channel was not open.
MICA_ERROR Either the ISDN or the modem board
didn't close.
The MICA_Connect function call is used to open a data channel to initiate an outgoing telephone call. A sample format for the call as follows:
MICA_Connect (
intl6 channel Id,
char *phoneNumber,
void (*callBack)(channelld, event_mask)
)
If the optional callBack routine is provided, it is executed after the connection is made. The channelId is returned with the callBack routine allowing a use of a single callBack routine with many channels. The event_mask reflects the state of the channel after the connection is made. The parameter channelId identifies the channel to be dialed. If the callBack routine is used, the channelId is provided. The parameter phoneNumber is a pointer to the phone number to be dialed. The number is in ASCII text format. The callBack parameter identifies the callback routine, and the parameter event_mask identifies the status of the channel after the connection is completed. It should be noted that prior to calling the MICA Connect function, the application must call MICA_Open. The possible result codes returned after the MICA_Connect call are as follows:
MICA_CHANNEL_NOT_OPEN The channel was not
opened.
MICA_CONNECT_NO_CHANNELS There are no available
channels.
MICA_ERROR General Error message.
MICA_INVALID_CALL_TYPE The call type was invalid.
MICA_SUCCESS Connecting.
MICA_INVALID_CHANNEL The channelld provided
was invalid.
The MICA_GetOption function call is used to get status and other information from the board set. A sample format for the MICA_GetOption call is as follows:
MICA_GetOption (
intl6 channelld,
intl6 *micaCommand,
char *returnData
)
The requested data is written into the returnData buffer. Note that this buffer should be large enough to hold the maximum size return message. The parameter board_set identifies the MICA board set on which the operation is to be performed. The micaCommand parameter identifies the command, and the returnData parameter indicates the returned data value. The possible result codes are as follows:
MICA_INVALID_COMMAND The specified command was not
recognized.
MICA_SUCCESS The command completed
successfully.
MICA_ERROR The command failed to complete.
The MICA_Init function call is used to initialize the telephone data processing system 24. For one embodiment, a sample format for the call is as follows:
MICA_Init (
mica_status_str *micaStr,
char *buffer,
intl6 buffer_len,
intl6 channels,
intl6 channellds
)
The micaStr parameter identifies the MICA status structure. The buffer parameter identifies memory allocated for MICA structures. The buffer_len parameter identifies the size of the buffer in bytes. The channels parameters identifies the number physical channels, and the channelIds parameter identifies the number of virtual channels. The possible result codes are as follows:
MICA_INIT_INSUFFICIENT_DATA Not enough information
was provided.
MICA_INIT_INSUFFICIENT_BUFFER The buffer provided was
too small.
MICA_ERROR The command failed to
complete.
MICA_SUCCESS The command completed
successfully.
Note:
the calling application is responsible for allocating sufficient space for
the MICA Status structure (for example malloc (size of
(mica_status_str))). The MICA API assumes sufficient space has been
allocated.
Note: the calling application is responsible for allocating sufficient space for the MICA Status structure (for example malloc (size of (mica_status_str))). The MICA API assumes sufficient space has been allocated. The MICA_Listen function call is used to open a data channel to receive an incoming call. An example of its format is as follows:
MICA_Listen (
intl6 channelld,
char *phoneNumber,
void (*callBack)(channelld, event mask)
)
The channelId parameter indicates the assigned channel. When used in the callBack routine, the channelId represents the channel on which the called was received. The phoneNumber parameter indicates the number to listen for; the callBack parameter indicates the routine that is to be executed when the call arrives and the parameter event_mask indicates the state of the channel after the call is accepted. Possible result codes are as follows:
MICA_SUCCESS The channel was opened successfully.
MICA_CHAN_INVALID The channel parameter was invalid.
The MICA_Open function call is used to open a data channel. A sample format for the call is as follows:
MICA_Open (
intl6 callType,
intl6 direction,
intl6 assignResource,
intl6 *error
)
The callType parameter indicates the type of call being requested, i.e., ISDN or modem. The direction parameter indicates whether the call is an inbound or outbound call. The assignResource parameter allocates the modem or ISDN channel to the identified MICA channel. This parameter is typically assigned a Boolean true/false variable. The error parameter is a pointer to a variable for error reporting. This avoids confusion between a valid channel ID and an error value. The optional callType and direction parameters are of particular use when some channels are restricted to outbound or inbound calls only. The assignResource parameter is useful when over-subscription of the channels is allowed. If the call is successful, a channelId is returned. If an error occurred, MICA_ERROR is returned. The error type is identified in the error byte. The possible values for error are:
MICA_OPEN_INVALID_TYPE The callType is invalid.
MICA_OPEN_INVALID_DIRECTION The direction was invalid.
MICA_OPEN_NO_CHANNELS No idle channels.
The MICA_ProcessInt function call is used to process an interrupt. Once an interrupt service routine or polling routine has detected that a board needs service, this routine is used to service the board. A format for the call is as follows:
MICA_ProcessInt(
intl6 intType,
intl6 callType
)
The intType parameter indicates the type of interrupt received, i.e., data or control. The callType parameter indicates the call type, i.e., ISDN or modem. The possible result codes are as follows:
MICA_SUCCESS The board(s) were successfully
serviced.
MICA_ERROR An error occurred while servicing
the boards(s).
The MICA_Recv function call is used to hand a data buffer to receive data for a specific channel. A format for the call is as follows:
MICA_Recv (
intl6 channelld,
char *dataBuffer,
intl6 bufferSize
)
The channelId parameter indicates the channel from which data is received. The dataBuffer parameter indicates the buffer in which the data is placed, and the bufferSize parameter indicates the number of bytes that can be written into the buffer. The bufferSize parameter is normally the maximum number of bytes that can be inserted into the data buffer. The return result is typically the number of bytes actually written into the data buffer. If an error occurred while data is being copied into the buffer, an error bit, typically -1, is returned. The MICA_Reset function call is used to reset the MICA board set(s). A format for the call is as follows:
MICA_Reset(
intl6 board_to_reset
)
The parameter board_to_reset indicates which board is to be reset, since more than one MICA board set can be used in the system. After this function is called, the MICA board set must be reinitialized by calling MICA_Init before any other calls can be made. The typical result codes returned after a MICA Reset call are as follows:
MICA_SUCESS The board set was successfully reset.
MICA_ERROR An error occurred while resetting
the board(s).
MICA_INVALID_NUMBER board_to_reset was set to an invalid
number.
The MICA_Select function call is used to obtain channel status information such as the connection state of a particular channel. A format for the call is as follows:
MICA_Select (
intl6 channelld,
intl6 statusMask
)
The parameter channelId identifies the channel, and statusMask is a data word which masks off unwanted information. If the statusMask is set to zero, the space available in the transmit buffer is returned in response to the function call. The returned value is either the channel status, the space available in the transmit buffer or MICA_ERROR. If the most significant bit of the returned value is set, the returned value is MICA_ERROR, not the channel status. The MICA_Send function call is used to hand a data buffer to a specific channel. A format the MICA_Send call is as follows:
MICA_Send (
intl6 channelld,
char *dataBuffer,
intl6 bytes
)
The channelId parameter identifies the channel from which data is received; the dataBuffer parameter identifies the buffer into which the data is placed; and the bytes parameter indicates the total number of bytes to be transmitted. It should be noted that data cannot be transmitted until a channel has entered the active state. Successfully connecting to a destination or accepting an incoming call causes the channel to transition to the active state. The channel's status may be verified by using the MICA Select call. The result of the MICA Send call is the number of bytes actually transmitted. If an error occurs during transmit, MICA_ERROR(-I) is returned. The MICA_SetOption call is used to send various command and control messages to the MICA telephone data processing system 24. A list of the commands that can be sent is contained in Tables 2 and 3. Table 2 lists modem mode commands, and Table 3 lists ISDN mode commands.
TABLE 2
Set Channel Option Modem Commands
Command Value(s) Description
MICA MODEM_MODE Originate/Answer Set the modem to
Originate or
Answer mode
MICA_MODEM_CALL_TONE Send Determines
whether the modem
should send
calling tone or not.
MICA_MODEM_GUARD_TONE Use Tone Should the modem
use guard
tone for
V 22N 22bis.
MICA_MODEM_FORMAT Async, LAPM, Set the modem's
MNP, ARA data transmission
format negotiation
parameters.
MICA_MODEM_AUTOD Autodetect Automatically
detect the peer's
protocol.
MICA_MODEM_AUTOD_TO 0-25.5 s Autodetect time-
out period.
MICA_MODEM_BREAK_MODE Expedited, Sets the break
Destructive processing
method for the
modem.
MICA_MODEM_BUFF_LEN 0-64 Protocol buffer
length.
MICA_MODEM_NEGOT_TO 0-25.5 s Timeout for Protocol
Negotiation.
MICA_MODEM_NEGOT_FALL_B ASCII Value The character
causing negotiation
fallback.
MICA_MODEM_COMPRESSION None, V.42bis, Compression
MNP5 method used by
the modem.
CA_MODEM_MODEM_VXX V.34bis, V.32bis, The modem standard
V.22bis to use.
MICA_MODEM_MAX_CONN_RATE 1-14 2400 * the number
specified.
MICA_MODEM_MIN_CONN_RATE 1-14 2400 * the number
specified.
MICA_MODEM_SIG_QUAL_LEVEL 1-5 The line signal
quality threshold.
MICA_MODEM_TX_LEVEL 0-15 dbm The transmit level.
MICA_MODEM_IDLE_TO 1-255 s Idle line timeout.
MICA_MODEM_FRAME_RETX 0-255 s Frame retrans-
missionlimit.
MICA_MODEM_NO_DCD_HANGUP 0-25.5 s Lost carrier hang-
up delay.
MICA_MODEM_RETRAIN_DISC 1-255 s Consecutive
retrain disconnects.
MICA_MODEM_FALL_FWD_TIMER 1-255 s 0 Disconnects.
MICA_MODEM_RDL_RESPONSE Enable Remote Diagnostic
Loopback response.
MICA_MODEM_COUNTRY_CODE 0-255 Country Location.
MICA_MODEM_MIN_ANSWER_BACK 0-255 ms Answer back time.
MICA_MODEM_CALL_TONE_GAIN 0-15 dbm Call Tone Gain.
MICA_MODEM_V.34_INFO Information bits for
V.34.
|
Same subclass Same class Consider this |
||||||||||