|
|
|
|
|
Platform management discusses various functions provided as an interface to the IRAPI platform, the IRAPI timer feature, errors, tracing, and logging.
An IRAPI process must register with the system upon startup with the irRegister(3IRAPI) function. This function takes a unique process name string as an argument. The process name must not exceed IRD_MAX_APP_NAME characters in length. The process name must be the same name given with the -p option to the defService(1IRAPI) command. The irRegister(3IRAPI) function returns the message queue key of the calling process if successful. IRR_FAIL is returned if an error occurs. The RM controls send and receive messages for IRAPI processes.
A process may obtain the message queue key of another IRAPI process by calling irGetQKey(3IRAPI) with the process name of that process.
The number of channels configured in the system may be obtained with the irNumChans(3IRAPI) function. It returns the number of channels which exist that are of the type(s) specified in its argument. Two types are supported: IRD_REAL and IRD_VIRTUAL. These values may be logically ORed together to obtain a total consisting of more than one type of channel.
Channel service states
The service state of a channel can be obtained with the irServiceState(3IRAPI) function. There are several possible service states. The two most common are IRD_INACTIVE (channel is "on hook") and IRD_ACTIVE (channel is "off hook").
Library states
The IRAPI library state for a channel may be obtained with the irLibState(3IRAPI) function. This function may be used to test for an uncompleted activity that an application is performing on the channel. For example, if voice play is in progress, the library state is IRS_PLAYING. If the application has done an irAnswer(3IRAPI) and has not yet received the IRE_ANSWER_DONE event, the library is in the IRS_ANSWERING state. The many possible states that the IRAPI library may be in are described in IrSTATES(4IRAPI).
Sending messages to other processes
There are three functions described in irPostEvent(3IRAPI) which may be used to send a message to another process. One of these functions should be used instead of the old mesgsnd(3SPP) routine. The choice of which function to use is only a matter of convenience for the programmer. If the receiving process is an IRAPI process, it receives the message as an IRE_EXTERNAL event through a call to irCheck(3IRAPI) or irWCheck(3IRAPI). Otherwise, the receiving process gets an IPC message through the mesgrcv(3SPP) function.
The irPostEvent() function requires a pointer to a message buffer and the length of the buffer as arguments. The application developer must fill the irWhoTo (destination queue key) and the irChan (channel number) fields in the message buffer before calling the function.
The irPostEventC() function sends a message to whatever process owns a given channel. This function requires the channel number as an argument in addition to the message buffer and length.
The irPostEventQ() function sends a message with a message queue key. It requires the queue key as an argument in addition to the message buffer and length.
Timer management
The IRAPI provides a timer management facility with the following irTimer(3IRAPI) functions:
The irStartTimer() function starts a timer for a specific channel. If the timer expires before it is canceled, an IRE_CLOCK event is triggered for the channel. Multiple timers per channel may be started as long as they are given unique tag values.
The irCancelTimer() function cancels a channel specific timer. The same tag value used to start the timer must be used to cancel it.
The irStartPTimer() function starts a process timer for the process calling the function. If the timer expires before it is canceled, an IRE_CLOCK event with a channel ID of IRD_NULL is triggered. Multiple process level timers may be started as long as they are given unique tag values.
Timer intervals are in milliseconds but have a 10 millisecond granularity. Timers may be set to go off once or repeatedly at the specified interval on a busy system. On a lightly loaded system, an IRAPI timer can go off up to one second after it was requested.
Errors - tracing and logging
Error messages may be logged by IRAPI applications using the same logMsg interface routines provided for Data Interface Processes (DIPs). The irRegister(3IRAPI) function calls logInit(), eliminating the need for IRAPI applications to use logInit(). The db_init(), db_pr(), and db_put() functions are still available and work for printing messages to the system trace, but IRAPI processes should use the newer irTrace(3IRAPI) functions instead. The older functions may not be supported in the future.
Note:
Not all error conditions that occur within the IRAPI library are logged. The application developer must decide whether to log certain errors based on the return value of the IRAPI functions and the value of the irError variable.
The system trace facility provides a means of printing messages to a display terminal on which the trace(1IRAPI) command is being executed. Trace messages may be selectively output using process, channel, area and level parameters. There are 16 user defined areas and levels and 16 areas and levels reserved for the system. The irTrace(3IRAPI) functions support a variety of tracing operations:
irTrace(3IRAPI) and irQTrace(3IRAPI) – Channel level tracing. Messages printed with these functions appear in the system trace if the specified channel is being traced. IrQTrace(3IRAPI) is a macro that executes more quickly than irTrace(3IRAPI), but does not allow a variable number of arguments.
irTraceP(3IRAPI) and irQTraceP(3IRAPI) – Process level and all error tracing. Messages printed with these functions appear in the system trace if the process printing them is being traced. irQTraceP(3IRAPI) is a macro that executes more quickly than irTrace(3IRAPI), but does not allow a variable number of arguments.
Note:
Do not call irTrace(3IRAPI) or irQTrace(3IRAPI) with channel number of -1 (minus one). If this occurs, the trace message will always be displayed regardless of whether the process or channel is being traced.
irTrace_Put(3IRAPI) – Backward compatibility to db_put(3SPP). This function prints a message to the trace output unconditionally.
irTRACECHAN_CHK(3IRAPI) and irTRACEPROC_CHK(3IRAPI) – check tracing. These macros may be used to check to see if tracing is on for a particular channel or process before executing a block of code.
irSetTraceChan(3IRAPI), irSetTraceQkey(3IRAPI), irSetTraceArea(3IRAPI), irSetTraceLevel(3IRAPI), irSetTraceLogMode(3IRAPI), and irSetTraceDateMode(3IRAPI) – Set system tracing parameters. These functions may be used to change current values of the channel, process (by specifying the message queue key), area, level, log mode and date mode parameters of an executing trace command. (No output appears if a trace command is not running.)
The IRAPI contains many convenience functions that may be used with error and trace messages to print the symbolic names of IRAPI values.
Application Dispatch interface
The IRAPI maintains a default owner for a channel, which receives ownership of idle, in service, channels. The default owner is responsible for handling IRE_NEWCALL events on channels that it owns, determining what application should service the new call, and using irExec(3IRAPI) to invoke the application on the channel. Normally the default owner is the AD process. However, another process may change the default owner by using irChDefOwn(3IRAPI).
The AD interface allows two different applications to be assigned to a channel. The startup application is the application that is run when AD receives an IRE_NEWCALL event. The standard application is the application that is run when another IRAPI application invokes the AD process with irExec(3IRAPI) and AD receives the IRE_EXEC event. When an application gives up channel ownership with irDeinit(3IRAPI) the default owner is notified with the IRE_DEFOWN event. Normally the startup and standard applications are identical. In special cases where it is desirable to have one application gather additional information about an incoming call before the application that actually handles the call is invoked, it may be convenient to assign them as different applications.
The following code fragment illustrates how the standard AD process handles the IRAPI events involved in dispatching applications:
while (1)
{
irWCheck();
index = IRD_AD_STARTUP;
case (event_id)
{
IRE_EXEC:
index = IRD_AD_STANDARD;
irInit(cid);
IRE_NEWCALL:
iraQueryADTables(cid, index, application)
if (found)
irExec(.....);
if (not found)
log error
break;
IRE_DEFOWNER:
irInit(cid);
break;
default:
break;
}
}
The IRAPI provides several functions for access to the AD interface. These may be used to implement an alternative to the standard AD process if desired.
Initialize/add/delete AD entry in the channel and/or ANI/DNIS tables:
int iraInitADTables (int numchans, int numdnisani)
int iraInitADChannel (int numchans)
int iraInitADDnisani (int numdnisani)
int iraAddADChannel (int channel, int disp_mode,
const char *reg_file)
int iraAddADDnisani (const IRA_STR_RANGE * dnisrange,
const IRA_STR_RANGE* anirange, const char * reg_file)
int iraRemoveADChannel(int chan, int mode)
int iraRemoveADDnisani(const IRA_STR_RANGE * dnisrange,
const IRA_STR_RANGE * anirange)
Look up applications
int iraQueryADTables(channel_id cid, int mode,
AD_APPL * appl)
int iraQueryADDnisani(int channel, int mode,
const char * dnisstring, const char *anistring,
AD_APPL *appl)
Read through tables
int iraReadADChannel(int chan, int mode, AD_APPL *p_appl)
int iraReadADDnisani(AD_DNISANI_ENTRY *p_ad_dnisani_entry)
int iraRewindADDnisani()
