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

							Programming Manual Pages
Issue  3  May 1998
9-19
If no service requests have been sent by ECS or if the application has not used 
asai_set_env to register for handling them, then no service requests are 
passed to the application. Use of arg as a null pointer clears any previously set 
characteristic server value.
arg, defined below, is a pointer to a structure of type server_type_t and 
supplies the server information.
typedef struct{
        long  num_node;
        service_spec_t  *buf;
}server_type_t;
Within this structure, num_node indicates the number of structures of the type 
service_spec_t to be registered with the ASAI library and buf is a pointer to 
an array of structures of the type service_type_t, defined as follows:
typedef struct{
        long  server_type;
        char  node_id[C_NODSIZ];
}service_spec_t;
Here server_type shows which service requests will be accepted and
node_id shows where they will be accepted. Valid server types that can be put 
together with the option of selecting either one are:
C_RT_SER — Routing
C_MAINT_SER — Maintenance
The node_id selects the sources of the requests that will be serviced.
Return Value
Upon successful completion, the function returns 0. If an error occurs, the function 
returns -1.
Errors
The type of error is indicated by the error value set in asai_errno:
C_BADFD — Invalid file descriptor supplied
C_BADCHAR — Unknown or improper context for a characteristic
C_BADCHARVAL — Unknown characteristic value specified
C_SERVEX — Cluster service is being provided by another application
C_BADNODE — Node is not available 
						

							Programming Manual Pages
9-20Issue  3  May 1998 
C_SYSER — ASAI service error
C_INTR — A system call was interrupted by a signal
C_ACTIVE — Stream has active cluster instance
C_LINKDOWN — ASAI link on MAPD taken out of service by the administrator
See Also
asai_open() asai_rcv() asai_send() asai_set_env() 
						

							Programming Manual Pages
Issue  3  May 1998
9-21
ASAI Capability Manual pages 
In these manual pages, each capability is described by some or all of the following 
sections:
Name
This section names and succinctly describes the capability.
Ty p e
This section gives the capability type. Based on its use within an association, 
each capability can be classified as initiating, continuing or terminating. These 
classifications reflect the transition of the association through the states of idle, 
active and cluster terminating. All unused or uninitiated associations are said to be 
idle. The capability types are defined as follows:
In addition, this section also classifies each capability as Acknowledged or 
Unacknowledged. No additional requests can be made until the outstanding 
acknowledgement is received.
If a capability is used in an association state for which it has not been defined, the 
use of the capability is considered a protocol violation. A protocol violation in the 
case of an acknowledged capability results in a negative acknowledgment. A 
protocol violation in the case of an unacknowledged capability aborts the 
association. Initiating This type of capability starts an association that did not 
previously exist. A new sao_id (previously known as 
cluster_id) must be supplied. If an existing sao_id is 
supplied, an error will be returned.
If ECS initiates this capability, it will create an odd sao_id. 
Consequently, CV/PC developers (especially, those who 
planned to register as routing and heartbeat servers) should use 
even numbers for sao_id.
Continuing This type of capability assumes that the association already 
exists and continues to exist after the capability is sent or 
received. An existing sao_id must be supplied. If a new
 sao_id is supplied, an error will be returned.
Terminating  This type of capability assumes that the association already 
exists. However, the association will be terminated after this 
capability is processed.
It is worth noting that this processing does not happen 
instantaneously and that the application may have to deal with 
messages for this association that were queued earlier and 
have been read after the terminating capability was sent. 
						

							Programming Manual Pages
9-22Issue  3  May 1998 
Usage
This section shows the associated data structures used with the capability.
Description
This section describes the capability, including its associated parameters.
Return Value
This section gives the values returned by asai_send or asai_rcv when the 
capability is used in those functions.
Errors
See Chapter 7, ‘‘Error Messages’’ for a list of error messages with brief 
explanations of their probable causes.
Notes
This section is used to describe any exceptions, caveats or usage suggestions 
pertaining to the capability.
See Also
This section lists related capabilities and ASAI functions, as appropriate. In 
general, it describes all the other capabilities in the appropriate capability group 
and to C_EN_REP. The latter is included because Event Notification differs 
according to the release of ECS equipment in use. 
						

							Programming Manual Pages
Issue  3  May 1998
9-23
C_3PAD (3ASAI)
Name
C_3PAD — Establish an auto-dial
Ty p e
Continuing — Acknowledged 
Usage
typedef struct{
        asai_common_t       asai_common;
        char                *called_num;
        user_user_t         uudata; 
        long                ofacility;
        char                *ofac_ext;
        long                prio_call;
        long                ack_flag;
        char                pool[C_DATSZ];
}a3pad_info_t;
Description
The client sends this capability to request the call between a third party 
domain-controlled extension and another number. A structure of type 
a3pad_info_t contains the third party call-setup parameters.
The C_3PAD capability is a continuing capability (FACility messages), created by 
C_3PDC_REQ. C_3PDC_REQ is described as an initiating capability. ECS will 
return an error if C_3PAD is used as an initiating capability, or before the 
C_3PCD_CONF is sent.
asai_common
Within this structure, the programmer sets capability to C_3PAD and 
primitive_type to C_REQUEST. The programmer also sets sao_id (also 
known as cluster_id) to identify the domain-control association.
called_num
This parameter is a pointer to a null-terminated string that specifies the called 
number. 
						

							Programming Manual Pages
9-24Issue  3  May 1998 
uudata
The purpose of the user_user information is to convey information between 
ISDN users. This information is not interpreted by ECS, but rather is carried 
transparently and delivered to the remote user. If the info field is IA5 characters 
(ASCII), the string is null-terminated.
The leng field is an integer value that indicates the number of octets of user data 
included in the request. This field is set to 0 if no user_user data is present. 
Currently, 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. (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.
ofacility
This optional parameter identifies the type of facility requested. It can be 
C_TRUNK_GROUP or C_NUSE_LONG, indicating a trunk group or facility not used. 
Note that the C_ACD_SPLIT value is not allowed since this indicates which trunk 
group should be used when dialing from the controlled station.
ofac_ext
This parameter is a pointer to a null-terminated string that identifies the trunk 
access code of the trunk group.
prio_call
This parameter is C_PRIOR_ON for a priority call or C_PRIOR_OFF for a 
nonpriority call.
ack_flag
This parameter allows the client to request acknowledgment of the auto-dial 
request. C_ACK_ON indicates that acknowledgment is expected; C_ACK_OFF 
indicates that acknowledgment is not expected. If the client sets ack_flag to 
C_ACK_OFF, an INITIATE event report instead of an acknowledgment will be 
sent.
A Third Party Domain Control association will be aborted if a Third Party Auto Dial 
request is issued for that association and the ack_flag parameter is set to 
C_ACK_OFF. 
						

							Programming Manual Pages
Issue  3  May 1998
9-25
This problem will be experienced in the following situation:
A station is monitored using the Third Party Domain Control capability. A 
Third Party Auto Dial capability is sent to the ECS to make a call from the 
monitored station to another party. The ack_flag parameter is set to 
C_ACK_OFF in the Third Party Auto Dial request to indicate that an 
acknowledgment to the C_3PAD is NOT expected from the ECS. If the 
adjunct issues a Third Party Clear Call for the Auto-Dial call, and receives 
the acknowledgment from the ECS for that request, the adjunct will then 
abort the Third Party Domain Control association due to inappropriate state 
changes.
in order to avoid this problem, you must set the ack_flag parameter to 
C_ACK_ON for every C_3PAD request.
pool
The pool parameter is a character array that provides buffer space for the ASAI 
library to store program-specific information. See the section ‘‘Pool’’ on page 8-15 
in Chapter 8, ‘‘ASAI Capability Primitives’’ for more information.
Return Value
When this capability is used in an asai_send(), the function returns a 
nonnegative value upon success and -1 on failure. A return value of 0 indicates 
that no data has been sent.
Errors
See Chapter 7, ‘‘Error Messages’’ for a list of error messages with brief 
explanations of their probable causes.
See Also
asai_send()
C_3PDC_REQ C_3PDC_CONF C_3PAD C_3PAD_CONF C_EN_REP C_3PSH
C_3PSH_CONF C_3PR C_3PR_CONF C_3PM C_3PM_CONF C_3PSD
C_3PSD_CONF C_3PCC C_3PCC_CONF C_3PRC C_3PRC_CONF C_3PSDS 
C_3PSDS_CONF 
						

							Programming Manual Pages
9-26Issue  3  May 1998 
C_3PAD_CONF (3ASAI)
Name
C_3PAD_CONF — Acknowledge an auto-dial request
Ty p e
Continuing — Unacknowledged
Usage
  typedef struct{
        asai_common_t      asai_common;
        call_id_t          call_id;
        party_id_t         party_id;
           ucid_t             ucid;         /* G3V6 */
        char               pool[C_DATSZ];
}a3pad_ack_t;
typedef struct{
        asai_common_t      asai_common;
        long               cause_value;
}a3pad_nak_t;
Description
The client receives this capability as a positive or negative acknowledgment to a 
C_3PAD_REQ request. The C_3PAD_CONF capability is always continuing and will 
not be carried in a RELease COMPlete message.
asai_common
Capability is returned as C_3PAD_CONF and primitive_type is returned as 
C_POS_ACK for a positive acknowledgment and as C_NEG_ACK for a negative 
acknowledgement. The sao_id (also known as cluster_id) specified in the 
auto-dial request is also returned.
A positive acknowledgment confirms that the C_3PAD_REQ request has been 
received and understood. Subsequent event reports will indicate the progress of 
the call.
call_id
This parameter identifies the resulting call.
party_id
This parameter indicates the identifier of the originator. 
						

							Programming Manual Pages
Issue  3  May 1998
9-27
ucid
This parameter identifies the UCID (Universal Call ID) assigned by ECS.
cause_value
This parameter can be any of the following:
C_INVALID_CRV
C_USER_BUSY
C_NOUSE_RESP
C_OUT_OF_SERV
C_NETCONJ
C_INVLDIE
C_PROTERR
C_RESUNAVL
See Table 8-1 on page 8-12 in Chapter 8 for further information on cause values.
pool
The pool parameter is a character array that provides buffer space for the ASAI 
library to store program-specific information. See ‘‘Pool’’ on page 8-15 in Chapter 
8, ‘‘ASAI Capability Primitives’’ for more information.
Return Value
When this capability is used in an asai_rcv(), the function returns the size of 
the message when successful and -1 on failure. Return value of 0 does not 
indicate an error, but that no data has been received.
Errors
See Chapter 7, ‘‘Error Messages’’ for a list of error messages with brief 
explanations of their probable causes.
See Also
asai_rcv()
C_3PANS C_3PDC_REQ C_3PDC_CONF C_3PAD C_3PAD_CONF C_EN_REP
C_3PSH C_3PSH_CONF C_3PR C_3PR_CONF C_3PM C_3PM_CONF C_3PSD 
C_3PSD_CONF C_3PCC C_3PCC_CONF C_3PRC C_3PRC_CONF 
						

							Programming Manual Pages
9-28Issue  3  May 1998 
C_3PANS (3ASAI)
Name
C_3PANS — Answer a call
Ty p e
Continuing — Acknowledged 
Usage
typedef struct{
        asai_common_t   asai_common;
        call_id_t       call_id;
        char            pool[C_DATSZ];
}a3pans_info_t;
Description
This capability allows the adjunct to request, on behalf of a station user, to 
“answer” a ringing, bridged or held call that is present at the station.   
Answering a ringing, bridged or held call means to connect a call by: 
nForcing the station off-hook, if the user is on-hook
nCutting through the call to the head or handset, if the user is off-hook 
The effect is as if the station user selected the call appearance of the alerting, 
bridged or held call and then went off-hook.
asai_common 
Within this structure, the programmer sets capability to C_3PANS and 
primitive_type to C_REQUEST. The programmer also sets sao_id (also 
known as cluster_id) to identify the association that controls the station, or 
call. 
call_id
Indicates the alerting, bridged or held call to be connected at the controlled 
station.
pool
The pool parameter is a character array that provides buffer space for the ASAI 
library to store program-specific information. See ‘‘Pool’’ on page 8-15 in Chapter 
8, ‘‘ASAI Capability Primitives’’ for more information.