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

							Introduction to ASAI
Issue  3  May 1998
3-3
Terms and Concepts
ASAI is an interface between an adjunct and the ECS; however, a number of 
terms can be used instead of or in addition to “adjunct” and “ECS.” In this book, 
the following terms are used with the meanings shown below:
The term “application” is used only in the phrase “application program” or 
“application programmer.”
To the ECS, “application” means an adjunct entity that requests and receives 
ASAI services or capabilities. Although more than one application can reside on a 
single adjunct, the ECS is unable to distinguish between these applications. As a 
result, the adjunct and all resident applications are treated as a single application 
and these terms are used interchangeably. 
This ambiguity is avoided by restricting the use of the term “application” 
throughout this document.
The building blocks of the ASAI library are “capabilities.” Requests and indications 
are capabilities. For example, Third Party Make Call is a request for setting up a 
call; Third Party Make Call is an ASAI capability. An Event Report is an indication 
that an event has occurred; Event Report is a capability.  adjunct A PC, used to communicate with a PBX switch, in this case 
the DEFINITY ECS.
client A program that sends service requests to another program 
(generally on a different processor) called the server. Usually 
the ECS is the server and CV/PC is the client. However, this 
is not the case with adjunct routing and heartbeat requests 
where the roles interchange; for example, heartbeat requests 
and confirmation can come from both the sides at any time.
server A server is a program or machine that responds to a 
particular class of request. In this document, “server” refers to 
one of the following:
1. A program that responds to requests from another 
program (generally on a different processor) called the client. 
Usually the ECS is the server and CV/PC is the client except 
for adjunct routing and heartbeat requests where the roles 
interchange; for example, heartbeat requests and 
confirmation can come from both the sides at any time.
2. CV/LAN server is a program that allows CallVisor PC 
applications to run remotely.
library The ASAI library, provider of ASAI services.
program The application program that uses the services of the ASAI 
library, whether as a client, a server, or both. 
						

							Introduction to ASAI
3-4Issue  3  May 1998 
ASAI capabilities can be further broken down into capability “primitives” that 
perform a single task (requesting a service, responding to a request, confirming a 
request or indicating that a request has been fulfilled). A primitive is an atomic 
message passed by the library. For example, the Heartbeat capability consists of 
two primitives: C_HB_REQ and C_HB_CONF. For more details on Capability 
primitives see ‘‘ASAI Capability Manual pages’’ on page 9-21 in Chapter 9, 
‘‘Programming Manual Pages.’’
Groups of capabilities—for example, all the Third Party capabilities—are 
“Application Service Elements” (ASEs) or “capability groups.”
The term “association” is critical to understand ASAI. An association is a single 
invocation of an ASE between an adjunct and the ECS. An association is 
represented by a unique CRV/link combination. (The Glossary at the end of this 
document contains definitions of additional terms and acronyms that relate to 
ASAI.) The terms ASE instance and Single Application Object (SAO) are 
synonymous with association. An active association is one that applies to an 
existing call on the ECS or to an extension on the call.
Associations can affect a ‘‘call” or a ‘‘party” to a call (or both). A call usually has 
two or more parties (that can be identified by their ‘‘extensions” as well as by 
party_id). An extension can be three, four or five numbers that internally 
identify a station or voice/data terminal. Extension can also mean a 10-digit 
number that includes area code and a full 7-digit telephone number.
Important Note about Heartbeat
It is the responsibility of the CallVisor PC adjunct to respond to the ASAI heartbeat 
messages that are periodically sent from the ECS. This is the case for every 
CallVisor PC adjunct and for each ASAI link that is active.
The ECS sends a register message (with the operation value set to heartbeat), to 
the adjunct every two minutes. In order to respond to this request, the application 
must have previously called the function asai_set_env with server_type set 
to C_MAINT_SER for the application to be considered a maintenance server. As a 
maintenance server, the application must respond to every C_HB_REQ capability it 
receives from the ECS with a C_HB_CONF. If the adjunct fails to respond to three 
consecutive heartbeat requests from the ECS, the ECS takes down Layer 1 for 
five seconds and all active associations are aborted. If the application program 
itself has to perform the maintenance server role, great care must be taken to 
ensure that the application does not block waiting on other events which would 
cause it to miss a heartbeat request. A separate process should be used to 
perform the maintenance server role.
Beginning with Release 2.2 of the CallVisor ASAI product, an OA&M process, 
asai_hb, is available to accomplish this maintenance task. 
						

							Introduction to ASAI
Issue  3  May 1998
3-5
The ASAI Library Functions
The functions provided by the ASAI library are:
asai_open()
asai_close()
asai_set_env()
asai_get_env()
asai_send()
asai_rcv()
asai_errval()
These functions afford access to the services defined by the full set of ASAI 
capabilities. The basic purpose of the functions is twofold: to manage the 
communication path over which ASAI capabilities are requested and 
acknowledged and to manage the exchange of information over an established 
communication path. 
						

							Introduction to ASAI
3-6Issue  3  May 1998 
Table 3-1 gives a brief description of the ASAI library functions that manage the 
communication path:
Table 3-1. ASAI Library Functions for Managing the Communication Path 
Function Description
asai_openOpens a communication path to the capability provider, 
using either a blocking or nonblocking mode of operation. 
The communication path is identified by a file descriptor.
asai_closeTerminates the communication path from the application 
process to the capability provider.
asai_set_envAllows the application process to set a characteristic of an 
opened communication path. The first characteristic to be 
set must be the destination node for service requests.
Other characteristics that can be set are the type of 
service and node on which requests for this service are to 
be received, called the service/destination pair. (This tells 
the ASAI library to place indications of the specified ASE 
from the specified node on this communication path.)
asai_get_envRequests information from the ASAI library concerning a 
characteristic of an opened communication path. 
Characteristics that can be queried are the following:
Destination node to which service requests will be sent.
Version of the ASAI library implementation. (This tells the 
application whether the features of the current ASAI 
library are sufficient for the application.)
Type of service and node that will send initiating 
indications. (This tells the application that initiating 
indications for the specified type of service and for the 
specified node will be received from ECS.) 
						

							Introduction to ASAI
Issue  3  May 1998
3-7
The other ASAI library functions are described briefly in Tables 3-2 and 3-3 below.
In general, ASAI library functions return 0 when successful and -1 on failure. 
Exceptions are noted in the manual pages in Chapter 8, ‘‘ASAI Capability 
Primitives’’ and Chapter 9, ‘‘Programming Manual Pages.’’
Table 3-2. ASAI Library Functions for Exchanging Information
Function Description
asai_sendInitiates, continues or terminates an association by 
transmitting request or confirmation primitives that identify 
specific capabilities.
asai_rcvReceives primitives that identify specific capabilities to 
initiate, continue, or terminate an association.
Table 3-3. ASAI Library Function for Handling Errors
Function Description
asai_errvalAllows the user to specify an error message, followed by 
the exiting error return value, written to stderr. 
						

							Introduction to ASAI
3-8Issue  3  May 1998 
Application Service Elements
The ASAI Application Service Elements (ASEs) support ASAI functions. ASEs, 
also referred to as ‘‘capability groups,” are the high-level building blocks from 
which specific applications are constructed. Each ASE defines a series of 
relationship interactions between a client and a server: third party call control, 
event notification, value query and so on.
Each capability provides a specific type of interaction between the client and the 
server: third party make call, third party reconnect, third party selective hold, third 
party selective listening, etc.
The client and server issue a sequence of calls to the send and receive functions 
in which capability primitives are exchanged. The capability primitives request, 
acknowledge and terminate an interaction.
Table 3-4 lists the ASAI ASEs and the capability primitives in each group.
Table 3-4. ASAI Capabilities by Capability Group (ASE)
ASE Capability Description
Third Party Call Control
C_3PAD
C_3PAD_CONF
C_3PANS
C_3PANS_CONF 
C_3PCC
C_3PCC_CONF
C_3PCE
C_3PDC_CONF
C_3PDC_REQ
C_3PDCE
C_3PM
C_3PM_CONF
C_3PMC_REQ
C_3PMC_CONF
C_3PR
C_3PR_CONFAuto Dial
Confirm Auto Dial
Answer
Confirm Answer
Clear Call
Confirm Clear Call
Call Ended
Confirm Domain Control
Domain Control
Domain Control End
Merge
Confirm Merge
Make Call
Confirm Make Call
Reconnect
Confirm Reconnect 
						

							Introduction to ASAI
Issue  3  May 1998
3-9
Third Party Call Control
(continued)C_3PRC
C_3PRC_CONF
C_3PREDIR
C_3PREDIR_ACK
C_3PSD
C_3PSD_CONF
C_3PSDS
C_3PSDS_CONF
C_3PSH
C_3PSH_CONF
C_3PSL_DISC
C_3PSL_DISC_ACK
C_3PSL_RECONN
C_3PSL_RECONN_ACK
C_3PSSC_CONF
C_3PSSC_REQ
C_3PTC_REQ
C_3PTC_CONFRelinquish Control
Confirm Relinquish Control
Redirect Call
Confirm redirect Call
Selective Drop
Confirm Selective Drop
Send DTMF Signals
Confirm Send DTMF 
Signals
Selective Hold
Confirm Selective Hold
Listen Disconnect
Confirm Listen Disconnect
Listen Reconnect
Confirm Listen Reconnect
Confirm Conference Call
Make Conference Call
Take Control
Confirm Take Control
Event NotificationC_EN_CAN
C_EN_CAN_CONF
C_EN_CONF
C_EN_END
C_EN_REP
C_EN_REQ
C_EN_SCN
C_EN_SCN_CONFCancel EN
Confirm Cancel
Confirm EN
End EN
EN Report
Request EN
Stop EN
Confirm Stop EN
Maintenance (Heartbeat)C_HB_CONF
C_HB_REQConfirm HB
Request HB
Request FunctionC_RF_CONF
C_RF_REQConfirm RF
Request RF
RoutingC_RT_END
C_RT_REQ
C_RT_SELEnd RT
Request RT
Select RT
Set ValueC_SV_CONF
C_SV_REQConfirm SV
Request SV
Table 3-4. ASAI Capabilities by Capability Group (ASE) — Continued
ASE Capability Description 
						

							Introduction to ASAI
3-10Issue  3  May 1998 
In addition, the ASAI library provides two types of C_ABORT capabilities, as shown 
in Table 3-5. The two ASAI abort services are referred to as user aborts and 
provider aborts.
A user abort is a program-initiated abort and a provider abort is a library-initiated 
abort. The C_ABORT capability is applicable to all ASEs. The application can 
send and receive an abort at any time. An abort is always terminating.
Value QueryC_VQ_CONF
C_VQ_REQ
C_VQ_RESPConfirm VQ
Request VQ
VQ Response
Table 3-5. ASAI Abort Capabilities
ASE Capability Description
allC_ABORT(P_ABORT) library-initiated (provider) abort
allC_ABORT(U_ABORT)  ECS-initiated (user) abort
Table 3-4. ASAI Capabilities by Capability Group (ASE) — Continued
ASE Capability Description 
						

							Introduction to ASAI
Issue  3  May 1998
3-11
ASAI Capabilities
The library functions asai_send() and asai_rcv() are used to exchange 
capabilities. Each ASAI capability is specific, performing a single task. These 
tasks are classified as initiating, continuing or terminating. The capabilities are 
also classified as acknowledged or unacknowledged.
Table 3-6 lists each capability primitive and shows how it is classified. Note that a 
number of the confirmation primitives are classified both as
‘‘unacknowledged - continuing” and ‘‘unacknowledged - terminating.” In such 
cases, the primitive is continuing when confirmation is positive and terminating 
when confirmation is negative.
Table 3-6. Classification of ASAI Capabilities 
Acknowledged Unacknowledged
Init. Cont. Term. Init. Cont. Term.
C_3PADxx
C_3PAD_CONFx
C_3PANSx
C_3PANS_CONFx
C_3PCCx
C_3PCC_CONFxx
C_3PCEx
C_3PDC_CONFxx
C_3PDC_REQx
C_3PDCEx
C_3PMx
C_3PM_CONFx
C_3PMC_CONFxx
C_3PMC_REQx
C_3PRx
C_3PR_CONFx
C_3PRCx
C_3PRC_CONFxx
C_3PREDIRxx 
						

							Introduction to ASAI
3-12Issue  3  May 1998 
C_3PREDIR_ACKxx
C_3PSDx
C_3PSD_CONFx
C_3PSDSx
C_3PSDS_CONFx
C_3PSHx
C_3PSH_CONFx
C_3PSL_DISCx
C_3PSL_DISC_ACKx
C_3PSL_RECONNx
C_3PSL_RECONN_ACKx
C_3PSSC_CONFx
C-PSSC_REQx
C_3PTC_CONFxx
C_3PTC_REQx
C_ABORTx
C_EN_CANx
C_EN_CAN_CONFxx
C_EN_CONFxx
C_EN_ENDx
C_EN_REPx
C_EN_REQx
C_EN_SCNx
C_EN_SCN_CONFx
C_HB_CONFx
C_HB_REQx
C_RF_CONFx
C_RF_REQx
Table 3-6. Classification of ASAI Capabilities  — Continued
Acknowledged Unacknowledged
Init. Cont. Term. Init. Cont. Term.