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

							ASAI Library Functions
Issue  3  May 1998
4-9
asai_get_env( )
The asai_get_env function allows you to check the version of the ASAI library, 
or retrieve your node id and server settings.
The version number of the ASAI library includes three values:  a major value, a 
minor value and a delta value. A change to a major value indicates significant 
functional change to the ASAI library; for example, addition of new capabilities. A 
change to a minor value indicates change within the existing capabilities; that is, 
an enhancement. A change to a delta value indicates a correction and does not 
represent any increased functionality. The parameters major_ver, minor_ver 
and delta_ver, respectively, represent these values.
asai_get_env also lets you check which node is handling requests from you 
and which services you are offering to the ECS. 
						

							ASAI Library Functions
4-10Issue  3  May 1998 
asai_send( )
asai_send() and asai_rcv() together are the central functions in the library.  
These two functions convey all ASAI capabilities and data across an association.
asai_send() has only three parameters:  file descriptor fd, a pointer to the 
buffer that contains the message to be sent and the length of the buffer. It is your 
responsibility to map the message to the appropriate structure (one of the 
structures contained in the union asai_info_t); otherwise, the message cannot 
be interpreted correctly on the receiving side.
For example, if you are sending a third party make call request, you map the 
message to the structure a3pmc_info_t (shown in part below).
typedef struct {
        asai_common_t   asai_common;
        char            *calling_num;
        char            *called_num;
           .
           .
           .
}a3pmc_info_t;
(All of the structures contained in asai_info_t start with asai_common_t, 
referred to as the header.) asai_common_t consists of four long data types as 
follows:
typedef struct {
        capability_t    capability;
        primitive_t     primitive_type;
        long            sao_id;
        long            reserved;
}asai_common_t;
In the case of the third party make call request, the capability is C_3PMC_REQ and 
the primitive_type is C_REQUEST.
With asai_send (), the library encodes the structure you have filled and 
forwards the result of the encoding to the ECS. With asai_rcv (), when the 
library receives a message from the ECS, it decodes the message, fills the 
necessary data into the appropriate structure and passes the structure to the 
application.
In addition to this mapping responsibility, you must also ensure that the length of 
your buffer is sufficient to contain the entire message. (If the buffer is too small, 
results are unpredictable.) 
						

							ASAI Library Functions
Issue  3  May 1998
4-11
The maximum useful size of the user buffer is size of (asai_info_t), but you 
can select a size appropriate for your application. The example below uses size of 
(asai_common_t). If you are not sure, use size of (asai_info_t).
Figure 4-6.  asai_send () Function
asai_send() returns the size of the message on success and -1 on failure. 
Technically, a return code of 0 is not an error; however, it does indicate that only 
the control portion of a message has been sent. This is probably not what you 
intended.
The sample code at the end of this chapter calls asai_send() on line 70 and on 
line 147, in Figure 4-9 on page 4-15.
if ( asai_send(fd, &mybuf, sizeof(asai_common_t)) < 0 )
{
    asai_errval(asai_send);
    exit (-asai errno);
} 
						

							ASAI Library Functions
4-12Issue  3  May 1998 
asai_rcv( )
This function reads messages from the communication path specified by fd. Like 
asai_send(), it expects a buffer and the length of the buffer to be passed to it.
Figure 4-7.  asai_rcv () Function
asai_rcv() returns the size of the buffer on success and -1 on failure. A return 
code of 0 does not indicate an error; it merely indicates that the received message 
was intended for the library and no program data is available at this time.
In the event that a received message will not fit in the buffer supplied by the 
programmer, the ASAI library returns a -1 (error) and sets asai_errno to -14 
(C_BADLNG). If a program ignores this error and simply calls the library again, an 
infinite loop is created. All application programs must check for the presence of a 
C_BADLNG error and provide a larger buffer, if it occurs. To avoid length problem, 
you can use asai_info_t.
The sample code in Figure 4-9 calls asai_rcv() on lines 75, 103 and 152.
asai_rcv_return_value = asai_rcv (fd, input_buf, BUFSIZ );
if ( asai_rcv_return_value < 0L )
{
    p = receive data from switch for node %s failed
;
    sprintf ( buf, p, node_id );
    fflush ( stdout );
    fflush ( stderr );
    asai_errval ( buf) ;
    return ( asai_errno ) ;
} 
						

							ASAI Library Functions
Issue  3  May 1998
4-13
asai_close( )
You may never have to use asai_close(). However, the UNIX system imposes 
a limit on the number of files that can be open at one time. If your application 
opens a large number of files, you may have to call asai_close() to close 
specific communication paths. asai_close() closes the communication path 
identified by fd. It returns 0 on success and -1 on failure.
You may also want to write a function to close your application under certain 
conditions, for example to stop the system from hanging on an asai_rcv() if the 
ECS fails to return the expected response. Figure 4-8 shows asai_close().
Figure 4-8. Closing the Communication Path
void appy_close ()
{
    extern int fd;
    extern char pathname[];
    char buf[C_MESIZE];
    char *p;
    if ( asai_close(fd) < 0 )
    {
p = close of ASAI communication path %s failed
;
sprintf ( buf, p, pathname );
  asai_errval (buf );
fflush ( stdout );
fflush ( stderr );
    }
    return; 
						

							ASAI Library Functions
4-14Issue  3  May 1998 
Sample Code
The sample code reproduced here tests the Event Notification capabilities.
First the program determines whether the domain type is an ACD split or a call 
vector. Then it requests appropriate event reports.
The C_EN_REQ capability is sent on lines 65-74 in Figure 4-9. If an abort capability 
is received (lines 75 to 91) the program exits. Similarly, if 
C_EN_CONF is received with a negative acknowledgement (lines 92 to 98), as 
shown in Figure 4-9, the program exits. Otherwise, an event report is received. 
The request is cancelled by sending the C_EN_CAN capability. 
						

							ASAI Library Functions
Issue  3  May 1998
4-15
Figure 4-9. Sample Code — Testing the Event Notification Capabilities
  1   /*
    2    * :set tabstop=4 shiftwidth=4
    3    *
    4    * usage: entest  acd|vec  []
    5    *     entest signal01 acd 9999
    6    *               # receive reports from acd domain
    7    *     entest signal01 vec 9999 10
    8    *               # receive 10 reports from vector domain
    9    */
   10   
   11   #include 
   12   #include 
   13   #include 
   14   #include 
   15   #include 
   16   #include 
   17   
   18   extern char *caps[];
   19   extern char *typs[];
   20   extern char *causes[];
   21   extern char *modes[];
   22   extern char *names[];
   23   
   24   main(argc, argv)
   25      char *argv[];
   26   {
   27      int fd, cnt;
   28      en_buf_t en;
   29      asai_info_t rsp;
   30   
   31      if (argc < 4)
   32      {
   33      usage:
   34         fprintf(stderr, usage: %s  acd|vec  \
   35                []
,argv[0]);
   36         exit(1);
   37      }
   38      if (strcmp(argv[2], acd) == 0)
   39      {
   40         en.acd_grp_info.domain_type = C_ACD_GROUP;
   41         en.acd_grp_info.domain_ext = argv[3];
   42      }
   43      else if (strcmp(argv[2], vec) == 0)
   44      {
   45         en.cv_info.domain_type = C_CALL_VECTOR; 
						

							ASAI Library Functions
4-16Issue  3  May 1998 
Figure 4-9.  Sample Code — Testing the Event Notification Capabilities — Continued
  46         en.cv_info.domain_ext = argv[3];
   47      }
   48      else
   49      {
   50         goto usage;
   51      }
   52      if ((fd = asai_open(/dev/asai/asai, 0)) < 0)
   53      {
   54         asai_errval(asai_open(dev/asai/asai) failed:);
   55         exit(-asai_errno);
   56      }
   57      if (asai_set_env(fd, C_NODE_ID, argv[1]) < 0)
   58      {
   59         asai_errval(asai_set_env(C_NODE_ID) failed:);
   60         exit(-asai_errno);
   61      }
   62   
   63   
   64      cnt = argc == 5 ? strtol(argv[4], 0, 0) : 1;
   65      en.en_common.asai_common.capability = C_EN_REQ;
   66      en.en_common.asai_common.primitive_type = C_REQUEST;
   67      en.en_common.asai_common.sao_id = 0;
   68   
   69      printf(Sent: C_EN_REQ (C_REQUEST) on clid 0
);
   70      if (asai_send(fd, &en, sizeof(en))
						

							ASAI Library Functions
Issue  3  May 1998
4-17
Figure 4-9.  Sample Code — Testing the Event Notification Capabilities — Continued
  91      }
   92      else if (rsp.asai_common.capability==C_EN_CONF &&
   93          rsp.asai_common.primitive_type==C_NEG_ACK)
   94      {
   95         printf(	cause:%s
, \
   96            causes[rsp.en_rsp.en_nak.cause_value]);
   97         exit(2);
   98      }
   99      printf(
);
  100   
  101      for (;cnt--;)
  102      {
  103         if (asai_rcv(fd, &rsp, sizeof(rsp))
						

							ASAI Library Functions
4-18Issue  3  May 1998 
Figure 4-9.  Sample Code — Testing the Event Notification Capabilities — Continued
  136            break;
  137         default:
  138            printf(	Unexpected capability \
  139                           causes abort!
);
  140            exit(4);
  141         }
  142      }
  143   
  144      en.en_common.asai_common.capability = C_EN_CAN;
  145   
  146      printf(Sent: C_EN_CAN (C_REQUEST) on clid 0
);
  147      if (asai_send(fd, &en, sizeof(asai_common_t))