NAME

qcc_bld, qcc_bld_setup, qcc_bld_call_proceeding, qcc_bld_connect, qcc_bld_release, qcc_bld_release_complete, qcc_bld_status, qcc_bld_status_enquiry, qcc_bld_restart, qcc_bld_restart_ack, qcc_bld_add_party, qcc_bld_add_party_ack, qcc_bld_add_party_reject, qcc_bld_drop_party, qcc_bld_drop_party_ack − build Q.2931 messages

SYNOPSIS

cc -DKERNEL -D_KERNEL [ flag ...  ] file ... 

#include <atm/types.h>
#include <atm/qcc.h>

char _depends_on[] = "drv/qcc";

mblk_t ∗qcc_bld_setup(char ∗ifname, int calltag, int vci, int forward_sdusize, int backward_sdusize, atm_addr_t ∗src_addrp, atm_addr_t ∗dst_addrp, int sap, int endpt_ref);

mblk_t ∗qcc_bld_call_proceeding(char ∗ifname, int callid, int vci, int endpt_ref);

mblk_t ∗qcc_bld_connect(char ∗ifname, int callid, int vci, int forward_sdusize, int backward_sdusize, int endpt_ref);

mblk_t ∗qcc_bld_release(char ∗ifname, int callid, int cause);

mblk_t ∗qcc_bld_release_complete(char ∗ifname, int callid, int cause);

mblk_t ∗qcc_bld_status_enquiry(char ∗ifname, int callid, int endpt_ref);

mblk_t ∗qcc_bld_status(char ∗ifname, int callid, int callstate, int cause, int endpt_ref, int endpt_state);

mblk_t ∗qcc_bld_restart(char ∗ifname, int callid, int vci, int rstall);

mblk_t ∗qcc_bld_restart_ack(char ∗ifname, int callid, int vci, int rstall);

mblk_t ∗qcc_bld_add_party(char ∗ifname, int callid, int forward_sdusize, int backward_sdusize, atm_address_t ∗src_addrp, atm_address_t ∗dst_addrp, int sap, int endpt_ref);

mblk_t ∗qcc_bld_add_party_ack(char ∗ifname, int callid, int endpt_ref);

mblk_t ∗qcc_bld_add_party_reject(char ∗ifname, int callid, int cause, int endpt_ref);

mblk_t ∗qcc_bld_drop_party(char ∗ifname, int callid, int cause, int endpt_ref);

mblk_t ∗qcc_bld_drop_party_ack(char ∗ifname, int callid, int cause, int endpt_ref);

MT-LEVEL

Safe. 

AVAILABILITY

The functionality described in this man page is available in the SUNWatma package included with the SunATM adapter board.  The -DKERNEL and -D_KERNEL flags must be included to indicate that the application should run in kernel space, and the qcc driver must be loaded (this requirement is expressed in the code using the "depends_on" line shown in the synopsis). 

DESCRIPTION

These functions build the various messages that make up the Q.2931 protocol which is used for ATM signalling.  A full description of the message format and use can be found in the ATM Forum’s User Network Interface Specification, V3.0 or V3.1. The messages built will conform to the version of the UNI Specification which is configured on the indicated interface.  The functions may be used by processes which are running in kernel space. 

In general, no error checking is performed on the data that is passed in.  Whatever data is passed in will be placed in the message that is built without examination.  The only exceptions to this are mentioned in the function descriptions. 

Two mblk_t structures are allocated and linked by each of the functions (their format is shown in the following diagram).  The pointer that is returned points to the M_PROTO block, and may then be passed downstream with the putq(9F) command. 

M_PROTO                           M_DATA

 _____________      ___________________________

--->|             |--->|     |               |     |

|  IF_Name    |    |  Q.2931 Message     |     |
|  Call_ID    |    |     |               |     |
|  Type       |    |     |               |     |
|  Error      |    |     |  Information  |     |
|  Call_Tag   |    | (9) |  Elements     | (16)|
|_____________|    |_____|_______________|_____|

The parameters passed in to each function are used to fill in the data portions of these two mblks. 

Each function requires a minimum of 2 parameters: ifname, which is a string containing the physical interface (such as sa0); and an integer, either calltag or callid, depending on the message type.  calltag is used in the setup message only; it is a reference number that is assigned by the calling application.  callid is used in all other messages; it is assigned by the lower layer and will be sent up to the user, with the calltag, in the setup_ack message. 

Other parameters for each function depend on the type of information required for each message type, and are defined in the paragraphs describing each function call. 

qcc_bld_setup() constructs a setup message containing the following Information Elements: AAL parameters, ATM user cell rate, broadband bearer capability, called party number, calling party number, quality of service parameter, and endpoint reference.  The user must pass in the forward and backward sdu sizes for the AAL parameter IE, an ATM address for the destination for the called party number IE, and one for itself for the calling party number IE (atm_address_t format is defined in the <atm/qcc.h> header file).  The value passed in the sap parameter is placed in a broadband higher layer IE. The higher layer IE indicates the sap to which received messages should be directed. If the user passes in a positive vci, a connection identifier IE will be included; if the user passes in a non-negative endpt_ref (0 is valid), an endpoint reference IE will be included. The endpoint reference IE indicates that this is a point-to-multipoint call; point-to-multipoint calls will be supported starting with the second release of SunATM software. 

qcc_bld_call_proceeding() includes a connection identifier IE if a positive vci is passed in, and an endpoint reference IE if a non-negative endpt_ref is passed in. An endpoint reference IE should only appear if the call is a point-to-multipoint call; point-to-multipoint calls will be supported starting with the second release of SunATM software. 

qcc_bld_connect() includes an AAL parameters IE, requiring the forward_ and backward_sdusize values, a connection identifier IE if a positive vci value is passed in, and an endpoint reference IE if a non-negative endpt_ref value is passed in. An endpoint reference IE should only appear if the call is a point-to-multipoint call; point-to-multipoint calls will be supported starting with the second release of SunATM software. 

qcc_bld_release() includes a cause IE for which the user must pass in a cause value.  The possible values can be found in the <atm/qcc.h> header file.  The same is true for qcc_bld_release_ complete(). 

qcc_bld_status_enquiry() includes only an endpoint reference IE if a non-negative endpt_ref value is passed in. An endpoint reference IE should only appear if the call is a point-to-multipoint call; point-to-multipoint calls will be supported starting with the second release of SunATM software. 

qcc_bld_status() includes a call state IE, requiring the user pass in the callstate parameter; possible values can be found in the <atm/qcc.h> header file.  It also includes a cause IE; the cause value must also be passed in.  Its possible values may also be found in the <atm/qcc.h> header file. Finally, if the call is a point-to-multipoint call, endpoint reference and endpoint state IEs may also be included; they are included if a non-negative endpt_ref value is passed in. The endpt_state parameter is used in the enpoint state IE; possible party state values may be found in <atm/qcc.h>. Point-to-multipoint calls will be supported starting with the second release of SunATM software. 

qcc_bld_restart() includes a restart indicator IE, which is used to determine whether an individual call or all calls on an interface should be restarted.  If rstall is 0, only the call identified by vci should be restarted; in this case, a connection identifier IE will also be included.  If rstall is non-zero, all calls will be restarted.  The same format applies to the qcc_bld_restart_ack() function. 

qcc_bld_add_party() constructs an add party message for a point-to-multipoint call. The message constructed will contain an AAL parameters IE, which includes the forward_ and backward_sdusize parameters, a calling party number IE, which includes the value pointed to by src_addrp, a called party number IE, which includes the value pointed to by dst_addrp, a broadband higher layer interface IE, which includes the sap parameter, and an endpoint reference IE, which includes the endpt_ref parameter. The sap value in the broadband higher layer information IE is used to indicate the sap to which the message should be passed by the receiving host. 

qcc_bld_add_party_ack() constructs an add party ack message which includes an endpoint reference IE, for which the endpt_ref parameter is required. 

qcc_bld_add_party_reject() includes a cause IE, containing the cause value passed in. The possible cause values may be found in the <atm/qcc.h> header file. An endpoint reference IE is also included, which requires the endpt_ref parameter. 

qcc_bld_drop_party() constructs a drop party message. The message constructed will contain two IEs: a cause IE, which requires the cause parameter, and an endpoint reference IE, which requires the endpt_ref parameter. Possible cause values may be found in the header file <atm/qcc.h>. 

qcc_bld_drop_party_ack() contains an endpoint reference IE, requiring the endpt_ref parameter, and optionally, a cause IE. The cause IE will be included if a positive value is passed in in the cause parameter. Possible cause values may be found in the <atm/qcc.h> header file. 

RETURN VALUES

All functions return a pointer to an mblk_t.  If the function is not successful, the pointer will be NULL. 

EXAMPLES

The following code fragment builds a setup message and sends it downstream. 

#include <sys/stream.h>
#include <atm/qcc.h>
#include <atm/limits.h>
 char    _depends_on[] = "drv/qcc";
 void
send_setup(queue_t ∗q);
{

mblk_t  ∗mp;
char    ifname[QCC_MAX_IFNAME_LEN] = "sa0";
int     calltag = 0x1234;
int     vci = 0x100;
int     forward_sdusize = 0x2378;
int     backward_sdusize = 0x2378;
int     sap = 0x100;
 atm_addr_t     src_addr = {

0x45, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x0f, 0x00, 0x00, 0x00, 0x00,
0x08, 0x00, 0x20, 0x1a, 0xe1, 0x53, 0x00

};
 atm_addr_t     dst_addr = {

0x45, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x0f, 0x00, 0x00, 0x00, 0x00,
0x08, 0x00, 0x20, 0x1a, 0xb6, 0xb9, 0x00

};
 mp = qcc_bld_setup(ifname, calltag, vci,

forward_sdusize, backward_sdusize,
&src_addr, &dst_addr, sap, -1);

 if (putq(q, mp) < 0) {

perror("putq");
exit (-1);

}

}

SEE ALSO

qcc_util(3), qcc_parse(9F), q93b(7)

"ATM User-Network Interface Specification, V3.0," ATM Forum. 

NOTES

This API is an interim solution until the ATM Forum has standardized an API.  At that time, Sun will implement that API, and support for the Q.2931 Call Control library may not be continued. 

SunOS ATM_2.0  —  Last change: 30 Nov 1995