NAME
irPName, irGPName, irSName, irEName, irEFName, irEMName,
irAName, irSvcStName, irCName, irXName, irPrintEvent
- return symbolic names of various IRAPI constants
SYNOPSIS
#include <irapi.h>
char *irPName (int p);
char *irGPName (int p);
char *irSName (int s);
char *irEName (int e);
char *irEFName (int ef);
char *irEMName (int em);
char *irAName (int a);
char *irHName (int h);
char *irSvcStName (int ss);
char *irCName (int c);
char *irVPName (int v);
char *irXName (int x);
char *irPrintEvent (ir_event_t *evp);
int irPValue (char *pstr);
int irVPValue (char *vstr);
DESCRIPTION
These functions return character pointers to the symbolic
names of the values they are passed for the class of names
implied by the function called.
irPName - return a pointer to a channel specific
parameter name (IrPARAMETERS(4IRAPI)).
irGPName - return a pointer to a global parameter
name (IrPARAMETERS(4IRAPI)).
irSName - return a pointer to a library state name
(IrSTATES(4IRAPI)).
irEName - return a pointer to an event name
(IrEVENTS(4IRAPI)).
irEFName - return a pointer to an event flag name
(IrEVENTS(4IRAPI)).
irEMName - return a pointer to an event modifier
name (IrEVENTS(4IRAPI)).
irAName - return a pointer to an algorithm name
(IrALGORITHMS(4IRAPI)).
irHName - return a pointer to an hardware type name
(/att/include/hwrtype.h).
irSvcStName - return a pointer to a service state
name (IrDEFINES(4IRAPI)).
irCName - returns a pointer to a resource capability
name
irVPName - returns a pointer to a var param name
(IrVARPARAMS(4IRAPI)).
irXName - returns a pointer to an extension function
name (IrEXTEND(4IRAPI)).
irPrintEvent - return a pointer to a formatted
string containing all elements of an event structure
(IrEVENTS(4IRAPI)).
irPValue - return an integer corresponding to the
channel specific parameter name (IrPARAMETERS(4IRAPI)).
irVPValue - return a pointer to a character string defining
varparam name (IrVARPARAMS(4IRAPI)).
EVENT
No event results from the call to any of these functions.
RETURN
Character pointer to symbolic name of the IRAPI constant on
success.
A character pointer to a string indicating that the value is
unknown for the class implied by the function on error.
WARNING
For unknown values, the return value points to a string that
could possibly be overwritten by a call to the same or any
other irName function listed in this man page.
ERROR
These functions always return a pointer to some valid
address. irError is never modified as a result to a call to
any of these functions.
EXAMPLE
The following section describes how to extend the irXName
function to generate strings for customer defined extension
ids. The sample code in /vs/examples/IRAPI/util_fcns.c will
be referenced heavily.
All of the following code should be placed into the C files
which comprise the shared object library, aka ".so" library,
for this extension package. The /vs/examples/IRAPI/example.mk
shows how to build the util_fcns.c into such a library.
First, contact Avaya to reserve an extension
library number for your exclusive use.
Next, modify the file /att/include/irDefines.h and place a
comment next to the extension library number you are using.
For example the utility extension library number is
IRD_EXT_LIBA.
Next, modify /att/include/irExtend.h to contain the exten-
sion function identifiers you need. For example, the util-
ity extension functions are:
enum IR_EXTEND {
IRX_UTIL = IRD_EXT_LIBA,
IRX_LBOLT,
IRX_RAND,
IRX_TIME,
IRX_CTIME,
IRX_LOGMSG,
IRX_YOURLIB = IRD_EXT_LIBB,
}
Note, it is very important to change the IR_EXTEND enum in a
way that does not alter the values already present.
Next, create an array of iri_define_string structures which
map ids to names. Within the file util_fcns.c this is done
with the Iri_Extend_NamesA table:
static const struct iri_define_string Iri_Extend_NamesA[] =
{
{ IRX_UTIL, "IRX_UTIL", 0 },
{ IRX_LBOLT, "IRX_LBOLT", 0 },
{ IRX_TIME, "IRX_TIME", 0 },
{ IRX_RAND, "IRX_RAND", 0 },
{ IRX_CTIME, "IRX_CTIME", 0 },
{ 0, 0, 0 },
{ IRR_FAIL, "UNKNOWN EXTENSION FUNCTION", "" }
};
Next, create a function which calls irDefineName on this
iri_define_string structure. For the util_fcns.c function
this is done by iri_XNameA
int iri_XNameA(void *unused1, void *unused2, int id)
{
return((int)irDefineName(&Iri_Extend_NamesA[0], id));
}
The prototype of this function must be as shown above.
Within the function irSPIRegister add this function and
corresponding extension library number, iri_XNameA and
IRD_EXT_LIBA in this example, to the IRAPI dynamic switch
table Iri_Extend_Name_table.
In the util_fcns.c sample example this is accomplished with:
if (irDynSwitchAdd(Iri_Extend_Name_table, IRD_EXT_LIBA,
iri_XNameA) == IRR_FAIL) ret = IRR_FAIL;
within irSPIRegister.
The function irXName is shown below:
char *irXName( int id )
{
return((char *)irDynSwitch(Iri_Extend_Name_table,
IRD_EXT_LIB(id), (void *)0, (void *)0, id));
}
The function irDynSwitch searches the IRAPI dynamic switch
table Iri_Extend_Name_table for an entry having a val field
which matches IRD_EXT_LIB(id). For the util_fcns.c example
the value of IRD_EXT_LIB(id) for any utility extension
library is IRD_EXT_LIBA This can be seen in
/att/include/irExtend.h and /att/include/irDefines.h If a
matching entry is found then the associated function,
iri_XNameA in this example, is called:
iri_XNameA((void *)0, (void *)0, id)
The function iri_XNameA then maps id to a corresponding
string with
irDefineName(&Iri_Extend_NamesA[0], id));
and returns that string.
When the extension package is added the file
/vs/data/irSPI.libs must be modified to contain an entry
with the pathname to this extension library. The command
editSPIlibs may be used for this. For example:
editSPIlibs /usr/lib/libirUTIL.so
assuming the extension library is /usr/lib/libirUTIL.so
When an extension package is removed the corresponding entry
for the extension library must be removed. The command
editSPIlibs may be used. For example:
editSPIlibs -r /usr/lib/libirUTIL.so
A relative pathname may be used so long as LD_LIBRARY_PATH
is set appropriately at irRegister(3IRAPI) time.
SEE ALSO
irDefine(3IRAPI), irErrorStr(3IRAPI),
irExtend(3IRAPI), irRegister(3IRAPI), irSPIRegister(3IRAPI),
IrALGORITHMS(4IRAPI), IrDEFINES(4IRAPI), IrEVENTS(4IRAPI),
IrEXTEND(4IRAPI), IrPARAMETERS(4IRAPI), IrSTATES(4IRAPI),
IrVARPARAMS(4IRAPI), irSPI.libs(4IRAPI)
FILES
irStructure.h, irExtend.h, /vs/examples/IRAPI/util_fcns.c,
/vs/data/irSPI.libs
VERSION
This is version 10/24/02 of this man page.