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 [ flag ...  ] file ...  −latm [ library ...  ]

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

int qcc_bld_setup(strbuf_t ∗ctlp, strbuf_t ∗datap, 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);

int qcc_bld_call_proceeding(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int vci, int endpt_ref);

int qcc_bld_connect(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int vci, int forward_sdusize, int backward_sdusize, int endpt_ref);

int qcc_bld_release(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int cause);

int qcc_bld_release_complete(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int cause);

int qcc_bld_status_enquiry(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int endpt_ref);

int qcc_bld_status(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int callstate, int cause, int endpt_ref, int endpt_state);

int qcc_bld_restart(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int vci, int rstall);

int qcc_bld_restart_ack(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int vci, int rstall);

int qcc_bld_add_party(strbuf_t ∗ctlp, strbuf_t ∗datap, 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);

int qcc_bld_add_party_ack(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int endpt_ref);

int qcc_bld_add_party_reject(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int cause, int endpt_ref);

int qcc_bld_drop_party(strbuf_t ∗ctlp, strbuf_t ∗datap, char ∗ifname, int callid, int cause, int endpt_ref);

int qcc_bld_drop_party_ack(strbuf_t ∗ctlp, strbuf_t ∗datap, 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 libatm.a library, which is located in /usr/lib, must be included at compile time as indicated 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 user 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. 

Each function requires a minimum of 4 parameters: ctlp and datap, which are pointers to strbuf_t buffers; 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. 

ctlp and datap make up the control and data portions of the constructed message, corresponding to the M_PROTO and M_DATA blocks of the message that will be passed downstream.  The buffer fields in the structures which ctlp and datap point to (ctlp->buf and datap->buf) must be allocated before calling a qcc_bld∗ function; size information may be obtained using the qcc_bld_∗_datalen() functions (see qcc_len(3)).  After successful return from a qcc_bld∗ function, the message may be passed down an open stream using the putmsg(2) function, with ctlp and datap as the buffer parameters for putmsg. 

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. 

After a message has been built, the user may add IEs that are not built into the message; however, the size information returned by the qcc_len functions only includes the IEs documented here.  The user must allocate enough additional space and correct the message length value in the Q.2931 header if additional IEs are required in the message. 

qcc_bld_setup() constructs a setup message containing some or all of 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 value (0 is valid), an endpoint reference IE is 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 endpoint 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 information 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 indicates 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 cause value is passed in. Possible cause values may be found in the <atm/qcc.h> header file. 

RETURN VALUES

All functions return 0 on success and -1 on error. 

EXAMPLES

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

#include <atm/limits.h>
#include <atm/qcc.h>
 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

};
 struct strbuf  ctl, data;
char           ctlbuf[QCC_MAX_CTL_LEN];
char           databuf[QCC_MAX_DATA_LEN];
 ctl.buf = ctlbuf;
data.buf = databuf;
ctl.maxlen = QCC_MAX_CTL_LEN;
data.maxlen = QCC_MAX_DATA_LEN;
 if ((qcc_bld_setup(&ctl, &data, ifname, calltag, vci,

forward_sdusize, backward_sdusize,
&src_addr, &dst_addr, sap, -1)) < 0) {

printf("qcc_bld_setup failed\n");
exit (-1);

}
 if (putmsg(fd, &ctl, &data, 0) < 0) {

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

}

SEE ALSO

qcc_len(3), qcc_parse(3), qcc_util(3), 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 2.0  —  Last change: 30 Nov 1995