NAME
irSetIE, irSetIEs, irGetIE, irGetIEs - set/get an informa-
tion element
SYNOPSIS
#include <irapi.h>
int irSetIE (channel_id cid, int info_ele, int value);
int irSetIEs (channel_id cid, int info_ele, char *value);
int irGetIE (channel_id cid, int info_ele, int *value);
int irGetIEs (channel_id cid, int info_ele, char *value);
DESCRIPTION
On some trunk connections, information describing incoming
or outgoing calls is available as "information elements."
The information elements available depends on the telephony
type and the provisioning of the switch that connects to the
VIS.
Information elements are internally maintained by the IRAPI
library as a part of a call profile. The irSetIE and
irSetIEs functions set the value of an information element
in the call profile while irGetIE and irGetIEs get the value
of an information element from the call profile.
The cid is the channel identifier. The info_ele is the name
of the information element whose value is to be set or
retrieved. In irSetIE, value contains the new integer value
to which info_ele should be set. In irGetIE, value is used
by IRAPI library to return the current integer value of
info_ele.
Currently supported elements for incoming calls are IRD_ANI
(automatic number identification), IRD_DNIS (dialed number
identification service), IRD_REDIRECTING (redirecting
number), IRD_INBOUND_SERVICE (inbound service type), IRD_UUI
(user to user information) and IRD_UUI_LEN (user to user
information length).
IRD_ANI provides the Calling Party Number (CPN) which can be
either the Station ID (SID) or the ANI number depending on
the configuration of the switch (and/or the attributes asso-
ciated with a service that requests the CPN on a call-by-
call basis). IRD_DNIS provides the specific telephone
number dialed by the caller or the routing number generated
by the network when forwarding calls dialed to an 800 or 900
service number. IRD_REDIRECTING provides the number that a
caller originally dialed before it was intercepted by the
network and redirected to the VIS. IRD_INBOUND_SERVICE
provides the service type for the inbound call. The possi-
ble values are defined as SVC_* in tas_defs.h. IRD_UUI pro-
vides the User to User Information information element for
the inbound call. IRD_UUI_LEN provides the length of the
User to User Information information element.
If irSetIEs is called with info_ele set as IRD_ANI [see
IrDEFINES(4IRAPI)], the ANI information element in the call
profile will be set to the value specified in value while if
it is called with info_ele set as IRD_DNIS, the DNIS infor-
mation element in the call profile will be set to the value
specified in value. Similarly when info_ele is set to
IRD_REDIRECTING, IRD_INBOUND_SERVICE or IRD_UUI.
If irGetIEs sets info_ele to IRD_ANI, the IRD_MAX_ANI_DIGITS
address digits received during the setup of the last incom-
ing call for the cid are copied into value.
If irGetIEs sets info_ele to IRD_DNIS, the
IRD_MAX_DNIS_DIGITS address digits received during the setup
of the last incoming call for the cid are copied into value.
If irGetIEs sets info_ele to IRD_REDIRECTING, the
IRD_MAX_REDIRECT_DIGITS address digits received during the
setup of the last incoming call for the cid are copied into
value.
If irGetIEs sets info_ele to IRD_UUI, the IRD_MAX_UUI_LEN
bytes of User-to-User information received during the setup
of the last incoming call for the cid are copied into value.
The application developer must declare value to be at least
IRD_MAX_ANI_DIGITS, IRD_MAX_DNIS_DIGITS,
IRD_MAX_REDIRECT_DIGITS or IRD_MAX_UUI_LEN in length depend-
ing upon the information element required.
The irSetIE and irGetIE functions are used to set or get the
integer value for IRD_INBOUND_SERVICE or IRD_UUI_LEN.
irSetIE and irSetIEs are typically used internally by the
IRAPI library (or startup services using the converse vector
step) to set the information elements for incoming calls.
irGetIE and irGetIEs are typically used by the Application
Dispatch (AD) process or by applications after an
IRE_NEWCALL event is received to indicate that a new call
has arrived.
The information elements associated with incoming calls are
overwritten by the next incoming call and this can occur
before an application has called irDisconnect, irDeinit or
irReturn. Therefore, an application that wishes to record
the incoming information elements, such as in call data
records, must obtain the information elements before calling
irDisconnect, irDeinit or irReturn and before calling irWait
after an IRE_DISCONNECT event. The information elements for
incoming calls are undefined as soon as the incoming call is
terminated and while an outbound call is taking place.
In addition to the information elements associated with
incoming calls, there are information elements associated
with outgoing calls.
irSetIE and irGetIE may be used to modify or get the
IRD_SERVICE_TYPE information element which is of integer
type. This information element can be used to select the
service type on outbound calls. The available service types
are defined as SVC_* in tas_defs.h. The default value
IRD_INVALID can be used if there is no need to select a ser-
vice type.
irSetIE and irGetIE may be used to modify or get the
IRD_BEARER_CAP information element which is of integer type.
This information element can be used to specify the bearer
capability on outbound calls. The available bearer capabil-
ity types are defined as BEAR* in tas_defs.h. The default
value IRD_INVALID can be used if there is no need to select
a bearer capability.
irSetIEs and irGetIEs may be used to modify or get the
IRD_OUTBOUND_ANI information element which is of buffer
type. This information element can be used to set the ANI
on outbound calls. If no value is provided, a NULL string
is used by default.
Information elements associated with outbound calls must be
set before the call is initiated with irCall. These infor-
mation elements are returned to their default values when
the channel is released via irDeinit or irReturn.
Information elements are preserved across irExec(3IRAPI) and
irSubProg(3IRAPI) boundaries.
NOTE
All of the Information Elements described in this manual
page are also accesible as parameters. The corresponding
parameters are defined in IrPARAMETERS(4IRAPI) and can be
accessed using the functions defined in irParam(3IRAPI).
For the time being it is acceptable to access the informa-
tion elements either way, but future versions of the IRAPI
library may eventually phase out the use of the functions
described in this manual page (in favor of treating the
information elements like any other parameter).
EVENT
No event results from calling these functions.
RETURN VALUE
irSetIE returns IRR_OK if successful.
irGetIE returns the number of characters written to value if
successful.
IRR_FAIL is returned if an error occurs with any of the
functions.
ERROR
irError is set as follows if an error occurs:
IRER_INVALID if the cid or info_ele are invalid
IRER_SYSERROR if a system or driver call failure occurs (see
irSysError for additional information)
CAVEATS
irGetIEs puts a null string in value if the corresponding
information (ANI, DNIS, etc.) is not available for the last
call received on cid.
WARNING
Use irGetIEs and irSetIEs only with pointers to data objects
at least as large as the size requirements specified in
IrPARAMETERS(4IRAPI) otherwise memory faults may occur. For
example the following:
irSetIEs( cid, IRP_DNIS, "" );
should not be used, instead use:
irSetParamStrCnt( cid, IRP_DNIS, "", 1 );
and similarly for all other string parameters.
SEE ALSO
IrDEFINES(4IRAPI), IrPARAMETERS(4IRAPI), irParam(3IRAPI)
VERSION
This is version 8/31/00 of this man page.