Lucent Technologies DEFINITY Enterprise Communications Server Release 6 CallVisor PC ASAI Instructions Manual

							ASAI Capability Primitives
Issue  3  May 1998
8-5
Identifiers
The ASAI library routinely uses a number of identifiers, defined in structures of the 
types shown. All of these structures include a field reserved for future use. The 
most common identifiers are:
nCall identifier (call_id) — Identifies a specific call.
nParty identifier (party_id) — Identifies specific parties on a call.
nOld party identifier (old_party_id) — Identifies an ECS-assigned 
identifier before two calls are merged.
nTrunk identifier (trunk_id) — Identifies a trunk.
nParty list identifier (party_ext) — Identifies a list of parties with their 
corresponding extensions.
nStation information (stn_info) — Identifies a list of calls with their 
corresponding parties and call states.
nMerge extension (merge_ext) — Identifies a list of parties with their 
corresponding extensions.
nUser to user (user_user) — Identifies information between ISDN users.
nOriginating Line Identifier (oli) — Identifies Information Indicator (II) digits 
received in the originating line information IE for the call.
nUser data — (user_data) Identifies user-supplied digits.
nUniversal Call ID (ucid)  — identifies the UCID assigned by the ECS.
call_id
typedef struct{
        char                *id_ptr;
        long                id_length;
        long                reserved;
}call_id_t;
Within the structure of type call_id_t, the parameter id_length indicates the 
number of binary bytes contained in the call identifier and id_ptr is the value of 
a pointer to an array of binary bytes that identifies the call. If call id is present id 
length must be 2. If its value is 0, the value of id_ptr is undefined. If an illegal 
value other than 0 is encountered, asai_send() will reject the message with an 
error code of C_BADPMATCH. Future releases of the ECS may change the legal 
range of values for id_length. Defensive programming practices are 
recommended.
Note that unlike null-terminated character strings such as calling_num and 
called_num, id_ptr is not a null-terminated character string. Rather, it is an 
array of bytes containing binary values. The parameter id_length indicates the 
number of binary bytes contained in the call identifier. 
						

							ASAI Capability Primitives
8-6Issue  3  May 1998 
NOTE:
call_id is not an ASCII null-terminated string but rather an array of binary 
bytes of the specified length. The length is subject to change.
party_id
typedef struct{
        char                *id_ptr;
        long                id_length;
        long                reserved;
}party_id_t;
Within party_id_t, the parameter id_length indicates the number of bytes 
contained in the party identifier, and id_ptr is the value of a pointer to the array 
of binary bytes identifying the party. The legal value for id_length is 1; if its 
value is 0, the value of id_ptr is undefined. If an illegal value other than 0 is 
encountered, asai_send() will reject the message with an error code of 
C_BADPMATCH. The legal value of id_length may change in future releases
of the ECS. Defensive programming practices are recommended.
Note that unlike null-terminated character strings such as calling_num and 
called_num, id_ptr is not a null-terminated character string. Rather, it is an 
array of binary bytes. The parameter id_length indicates the number of bytes 
contained in the call identifier.
NOTE:
party_id is not an ASCII null-terminated string but rather an array of 
binary bytes of the specified length. The length is subject to change.
old_party_id
typedef struct{
        char        *id_ptr;        
        long        which_call;
        long        id_length;
        long        reserved;
} old_party_id_t;
Within old_party_id_t, *id_ptr is a pointer to an array of binary bytes of length 
id_length that indicates an ECS-assigned party identifier before two calls are 
merged. See ‘‘party_id’’ for more information.
The parameter which_call can assume the values of C_RESULTING_CALL or 
C_OTHER_CALL and indicates whether the old party belongs to the resulting call 
or to other calls.
Note that in the structure of type party_id_t, id_ptr is not a null-terminated 
character string. 
						

							ASAI Capability Primitives
Issue  3  May 1998
8-7
trunk_id
typedef struct{
        char        *gid_ptr;
        char        *id_ptr;
        long        gid_length;
        long        id_length;
        long        direct;
        long        reserved;
} trunk_id_t;
Within trunk_id_t, gid_ptr is a pointer to an array of binary bytes indicating 
an ECS-assigned trunk group identifier of length gid_length. id_ptr is a 
pointer to an array of binary bytes indicating an ECS-assigned identifier, in the 
group identified by gid_ptr. The length of this identifier is id_length. The 
optional parameter direct can assume the values of C_NODIRET, C_INCTRK or
C_OUTTRK, the direction in which the trunk was used: no direction, incoming or 
outgoing. If this parameter is not specified, it assumes the value C_NUSE_LONG.
If the trunk group number (TGN) is less than or equal to 127, then the number 
pointed to by gid_ptr matches the TGN. Otherwise, it is 16 times the TGN,  
(divide by 16 to get TGN).
plan_type
typedef struct{
        short        addr_type;
        short        numb_plan;
}  plan_type_t;
Within plan_type_t, the parameter addr_type is a short integer that can have 
these possible values: unknown(0), international(1), national(2) and subscriber(4). 
The parameter numb_plan is also a short integer and can have these values: 
unknown(0), ISDN/telephony(1), reserved(2) and private numbering plan(9). 
Additional values for both parameters may be coded in the future.
number_id
typedef struct{
        char            *s;
        plan_type_t     type_plan;
}  number_id_t;
Within number_id_t, the s field, when not NULL, is an ASCII string that 
specifies the connected number. If s is NULL, the following field, type_plan, is 
undefined. The type_plan field is of type plan_type_t. 
						

							ASAI Capability Primitives
8-8Issue  3  May 1998 
party_ext
typedef struct{
        party_id_t      party_id;
        char            *extension;
        plan_type_t     ext_type; 
}party_ext_t;
Within party_ext_t, the parameter party_id is a structure of type
party_id_t. The extension parameter points to a null-terminated string that 
specifies the extension corresponding to the party identifier.
ext_type is a structure of type plan_type_t that supplies additional 
information about the extension field that immediately precedes it (providing 
that the extension field is not NULL).
stn_info
typedef struct{
        call_id_t            call_id;
        party_id_t           party_id;
        long                 pty_state;
        long                 reserved;
}stn_info_t;
Within stn_info_t, the call_id parameter is a structure of type
call_id_t, where id_length specifies the length of an ECS-assigned call 
identifier and id_ptr is a character string that specifies the call identifier. The 
party_id parameter points to a structure of type party_id_t, where
id_length specifies the length of an ECS-assigned party identifier and id_ptr 
points to a character string that specifies the party identifier. The pty_state 
parameter specifies the current state (busy, alert, etc.) of the corresponding party 
identifier. In stn_info the return value of the pty_state will have the same 
value as the “cause fields” in various event report messages. See Table 9-1 on 
page 9-115 in Chapter 9 for more information.
Whenever the structures of type party_id_t, call_id_t or trunk_id_t 
are used as optional parameters and the information is not supplied, id_ptr is a 
null pointer and id_length has a value of zero.
merge_ext
typedef struct{
        old_party_id_t       old_pid;
        party_id_t           party_id;
        char                 *extension;
        plan_type_t          ext_type; 
}merge_ext_t; 
						

							ASAI Capability Primitives
Issue  3  May 1998
8-9
Within merge_ext_t, the parameter old_pid is a structure of type
old_party_id_t, which provides the old party identifier (see ‘‘old_party_id’’ on 
page 8-6). 
The parameter party_id is a structure of type party_id_t that indicates an 
ECS-assigned party identifier after two calls are merged (see ‘‘party_id’’ on page 
8-6 for details).
The extension parameter points to a null-terminated string that specifies the 
extension that corresponds to the party.
ext_type is a structure of type plan_type_t that supplies additional 
information about the extension field that immediately precedes it (providing 
that the extension field is not NULL).
user_user
typdef struct {
        long       leng;
        long       protocol;
        char       *info;
} user_user_t;
The purpose of the user_user structure is to convey information between ISDN 
users. 
uudata is a structure of the type user_user_t where the leng field is an 
integer value that indicates the number of bytes of user data included in the 
request. This field is set to 0 if no user_user data is present. Currently, the ECS 
will accept up to 32 bytes of data (leng = 32). If more than 32 bytes is specified, 
an error will be returned. ASAI supports a maximum user_user data length of
32 bytes, although user_user data generated from a PRI trunk can be up to 
127 bytes in length. The DEFINITY ECS will truncate this to 32 bytes before 
forwarding it to ASAI link.
The protocol field indicates the type of information and is restricted to
C_UU_USER that indicates a user-specific protocol or C_UU_IA5, which indicates 
IA5 or ASCII characters. The info field is a pointer to an ASCII string of no more 
that 32 characters in length.
user_data
typedef struct{
long type;
long collect;
long timeout;
char *digits;
}user_code_t; 
						

							ASAI Capability Primitives
8-10Issue  3  May 1998 
The user_data structure is used to convey the information about the DTMF 
digits to the ECS, and with the collected digits event report to convey information 
to the adjunct. The leng field is an integer value that indicates the number of 
octets (digits) of user_data included in the request. The type field indicates the 
type of information and is restricted to C_UU_IA5, which indicates IA5 or ASCII 
characters.
The digits field is a pointer to an ASCII string of no more that 32 characters in 
length.
oli
typedef struct {
char *oli_ptr;
long oli_length;
long reserved;
}oli_t;
Since the ECS does not accept any II-digits from an ASAI adjunct, CallVisor PC 
only supports receiving this IE not sending it.
The field oli_length is the length of the byte array pointed to by the field 
oli_ptr. If the IE is missing from the message or its length is zero, oli_length
is zero. In all other cases, it is the size of the array.
The field oli_ptr is a pointer to an array of binary bytes.
This substructure is included in the following ASAI event report capability 
structures:
1. Call Offered to Domain (incall_list_t)
2. Alerting (alert_list_t)
3. Connected (connect_list_t)
It is also included in the Route Request capability structure (rt_info_t). 
ucid
typedef struct {
char *id_ptr;
long id_length;
}ucid_t;
Since the ECS does not accept any UCID from an ASAI adjunct, CallVisor PC 
only supports receiving this IE not sending it.
The field id_ptr is a pointer to an array of binary bytes. 
						

							ASAI Capability Primitives
Issue  3  May 1998
8-11
The field id_length is the length of the byte array pointed to by the field 
id_ptr. If the IE is missing from the message or its length is zero, id_length is 
zero. In all other cases, it is the size of the array.
This substructure is included in the following ASAI event report capability 
structures:
1. Alerting (alert_list_t)
2. Call conferenced (conf_list_t)
3. Call initiated (initiate_list_t)
4. Call offered to Domain (incall_list_t)
5. Call connected (connect_list_t)
6. Call transferred (tran_list_t)
It is also included in the Route Request capability structure (rt_info_t). 
						

							ASAI Capability Primitives
8-12Issue  3  May 1998 
cause_value
Certain capabilities return a parameter called cause_value if a negative 
acknowledgement is sent or received. These cause_values are noted with each 
capability. In general, a cause_value is returned by the ECS and mapped to an 
ASAI cause_value. Table 8-1 lists ASAI cause_values by name, shows the  
DEFINITY ECS value, the ASAI library value, and provides a brief explanation of 
the probable cause.
Table 8-1. ASAI Library and the DEFINITY ECS Cause Values 
Cause Value 
DEFINITY 
ECS 
Va l u eASAI 
Value Description
C_ADMIN_PROGRESS CS3/46 30 Administration is in progress; 
request cannot be serviced.
*C_AGT_STATE CS3/16 23 Request to put agent in same 
state he/she is already in.
C_ANSWERING_MACHINE CS3/24 55 Answering machine detected.
*C_BAD_ADMIN CS3/41 24 ACD not provisioned or 
optioned.
*C_BAD_IE CS0/99 27 Unknown information element 
detected.
C_BEARER_CAP_UNAVAIL CS0/58 38 Bearer capability not presently 
available.
C_BEARER_SVC_NOT_IMPL CS0/65 51 Bearer service not 
implemented.
C_CALL_REJECTED CS0/21 33 Call rejected.
*C_CALLID_TERM CS3/86 8 Call is no longer in active state.
*C_CLUST_TERM CS3/87 18 Association terminated 
because service is not active.
*C_CAUSE_UNKNOWN Undefined 48 Undefined value returned from 
the ECS.
C_FACILITY_REJECTED CS0/29 56 Facility rejected.
*C_FACUNSUB CS0/50 3 Capability is implemented but 
not subscribed to by requester.
C_FEATURE_REJECTED CS3/53 31 The ECS has rejected a 
request from the adjunct.
C_INCOMPAT_DESTINATION CS0/88 39 Incompatible destination.
*C_INCOM_ST CS0/98 9 Message not compatible with 
call state.
*C_INCOM_OPT CS3/80 11 Incompatible options used to 
establish the call.
*C_INC_PASWD CS3/14 22 Invalid login password. 
						

							ASAI Capability Primitives
Issue  3  May 1998
8-13
*C_INCS_AGT_ST CS3/12 20 Agent not in compatible state.
C_INVALID_MESSAGE CS0/95 40 Invalid message, unspecified 
(backward compatibility).
*C_INVALID_CRV CS0/81 10 Invalid call identifier (sao_id 
also known as cluster_id) 
used or call does not exist.
*C_INVLDIE CS0/100 6 Value specified in parameter is 
not allowed or defined.
*C_INVLDNUM CS0/28 0 Invalid origination or 
destination address.
*C_MAND_INFO CS0/96 5 One of the required parameters 
is missing.
*C_MAXLOGIN CS3/13 21 Agent logged into maximum 
number of splits.
C_NO_TONE_CHANNEL CS0/82 54 Channel and/or tone does not 
exist (no tone connected to the 
specified call).
C_NUM_CHANGED CS0/22 34 Number changed.
*C_NETCONJ CS0/42 26 Association terminated 
because of network 
congestion.
C_NETWORK_OUT_OF_ORDER CS3/38 47 Network out of order.
C_NO_ANSWER CS3/19 43 No answer.
C_NO_CIRCUIT CS0/34 36 No circuit or channel available.
C_NO_CLASSIFIERS CS3/21 45 Classifiers not available.
*C_NOLOGIN CS3/15 13 Agent not logged into split.
C_NON_EXIST_MESSAGE CS0/97 41 Message nonexistent/not 
implemented.
*C_NORMAL CS0/16 25 Normal termination; call routed 
successfully.
C_NORMAL_UNSPECIF CS0/31 35 Normal, unspecified.
*C_NOSPLIT_MEM CS3/11 14 Agent not member of specified 
split or split number specified 
incorrectly.
C_NO_TRUNKS CS3/20 44 Trunks not available.
*C_NOUSE_RESP CS0/18 16 Originating address does not 
respond to service.
*C_NUSE_LONG none -MAX_LONG No value was returned by the 
ECS.
Table 8-1. ASAI Library and the DEFINITY ECS Cause Values  — Continued
Cause Value 
DEFINITY 
ECS 
Va l u eASAI 
Value Description 
						

							ASAI Capability Primitives
8-14Issue  3  May 1998 
*C_OUT_CALL_BARRED CS0/52 49 Outgoing call has been barred.
*C_OUT_OF_SERV CS3/27 19 Domain has been removed by 
administration.
*C_PERM_DENIED CS3/43 17 Permission checks for service 
have failed.
*C_PROTERR CS0/111 1 Capability sequence has been 
violated or underlying protocol 
error has been detected; an 
unrecognized value was 
returned by the ECS.
*C_QUEFULL CS3/22 28 Queue is full.
*C_REC_TIMER CS0/102 12 Timer expired.
C_REDIRECT CS3/30 46 Redirected.
C_REMAINS_IN_Q CS3/23 50 Call remains in queue.
C_REORDER_DENIAL CS3/42 29 Reorder/Denial.
*C_RESUNAVL CS3/40 2 Resources to fulfill service are 
not available.
*C_SER_UNIMP CS3/79 4 Noncompatible options 
selected.
*C_SERV_UNAVIL CS3/63 7 Domain or call is being 
monitored by another adjunct.
C_TEMP_FAILURE CS0/41 37 Temporary Failure.
C_TIMED_ANSWER CS3/17 52 Assumed answer based on 
internal timer.
C_UNASSIGNED_NUM CS0/1 32 Unassigned number.
C_UNSPECIFIED CS0/127 42 Unspecified.
*C_USER_BUSY CS0/17 15 Domain or call is being 
monitored by another adjunct.
C_VOICE_ENERGY_ANSWER CS3/18 53 Voice energy detected by the 
ECS.
C_COVER_BUSY CS3/26 58 Redirection cause.
C_COV_DONT_ANS CS3/28 59 Redirection cause.
C_FORWARD_ALL CS3/31 60 Redirection cause.
C_FORWARD_BUSY CS3/25 57 Redirection cause.
C_LISTEN_ONLY CS3/8 61 Single-Step Conference listen 
only
C_LISTEN_TALK CS3/9 62 Single-Step Conference 
listen-talk
Table 8-1. ASAI Library and the DEFINITY ECS Cause Values  — Continued
Cause Value 
DEFINITY 
ECS 
Va l u eASAI 
Value Description