qcc_create(3)

NAME

qcc_create, qcc_create_setup, qcc_create_call_proceeding, qcc_create_connect, qcc_create_connect_ack, qcc_create_release, qcc_create_release_complete, qcc_create_status, qcc_create_status_enq, qcc_create_restart, qcc_create_restart_ack, qcc_create_add_party, qcc_create_add_party_ack, qcc_create_add_party_reject, qcc_create_drop_party, qcc_create_drop_party_ack − create Q.2931 message structures

SYNOPSIS

cc [ flag ... ] file ... −latm [ library ... ]

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

int qcc_create_setup(qcc_setup_t ∗msgp, char ∗ifname, int calltag, atm_address_t ∗called_num);

int qcc_create_call_proceeding(qcc_call_proc_t ∗msgp, char ∗ifname, int callid);

int qcc_create_connect(qcc_connect_t ∗msgp, char ∗ifname, int callid);

int qcc_create_connect_ack(qcc_connect_ack_t ∗msgp, char ∗ifname, int callid);

int qcc_create_release(qcc_release_t ∗msgp, char ∗ifname, int callid, int cause);

int qcc_create_release_complete(qcc_release_complete_t ∗ msgp, char ∗ifname, int callid);

int qcc_create_status_enq(qcc_status_enq_t ∗msgp, char ∗ifname, int callid);

int qcc_create_status(qcc_status_t ∗msgp, char ∗ifname, int callid, int callstate, int cause);

int qcc_create_restart(qcc_restart_t ∗msgp, char ∗ifname, int callid, int indicator, int vci);

int qcc_create_restart_ack(qcc_restart_ack_t ∗msgp, char ∗ifname, int callid, int indicator, int vci);

int qcc_create_add_party(qcc_add_party_t ∗msgp, char ∗ifname, int callid, atm_address_t ∗called_num, int endpt_ref);

int qcc_create_add_party_ack(qcc_add_party_ack_t ∗msgp, char ∗ifname, int callid, int endpt_ref);

int qcc_create_add_party_reject(qcc_add_party_reject_t ∗ msgp, char ∗ifname, int callid, int cause, int endpt_ref);

int qcc_create_drop_party(qcc_drop_party_t ∗msgp, char ∗ifname, int callid, int cause, int endpt_ref);

int qcc_create_drop_party_ack(qcc_drop_party_ack_t ∗msgp, char ∗ifname, int callid, 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 create message structures representing 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 content of the created message structures 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.

After a message structure has been created, non-default Information Elements (IEs) may be added or existing IEs may be changed using the qcc_set_ie(3) function. When the message structure has been completely specified, the corresponding qcc_pack(3) function should be called to translate the message structure into the correct encoded format, contained in streams buffers which may be passed to the putmsg(2) function.

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 3 parameters: msgp, which is a pointer to the appropriate message structure type; 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.

The structure to which msgp points must be allocated by the calling user. There is a unique structure for each message type; the message structures are defined in <atm/qcctypes.h>.

Only the mandatory IEs for each message type are added to the message structure by the qcc_create call. The additional parameters to the qcc_create functions allow the user to define most of the information contained in those mandatory IEs; however, in some cases default values are assumed. Those values, as well as the additional parameters for each function, are indicated in the following paragraphs describing each function call.

qcc_create_setup() creates a setup message structure containing the following Information Elements: ATM traffic descriptor (called ATM cell rate in UNI 3.0), broadband bearer capability, called party number, and quality of service parameter. The user must pass in the destination ATM address for the called party number IE (atm_address_t format is defined in the <atm/types.h> header file). The following default values are used for the remaining Information Elements:

ATM Traffic Descriptor:

best effort; line rate is used for the forward and backward peak rates

Broadband Bearer Capability:

Bearer Class X, no indication for traffic type and timing requirements, not susceptible to clipping, and point-to-point user plane

Called Party Number:

ATM Endsystem (NSAP) address type

Quality of Service:

Forward and backward class unspecified

qcc_create_call_proceeding() creates the structure for a call proceeding message, which contains no mandatory IEs. Only the message header is filled in.

qcc_create_connect() creates the structure for a connect message, which also contains no mandatory IEs. Again, only the required header is filled in. The same is true for qcc_create_connect_ack.

qcc_create_release() creates a release message structure containing a cause IE, for which the user must pass in a cause value. The possible values can be found in the <atm/qccdefs.h> header file. By default, no diagnostic is included and the user location is assigned.

qcc_create_release_complete() creates the structure for a release complete message, which contains no madatory IEs. Only the message header is filled in.

qcc_create_status_enquiry() creates a status enquiry message structure, which contains no mandatory IEs. Only the message header is filled in.

qcc_create_status() builds a status message structure, containing two mandatory IEs: call state and cause. The user should pass in value for both the callstate and the cause; possible values may be found in the <atm/qccdefs.h> header file. In the cause IE, no diagnostic is included and the user location is assigned.

qcc_create_restart() creates a restart message structure, containing the mandatory restart indicator IE, and optionally the connection identifier IE. The user should pass in a value for the restart indicator, either RESTART_INDICATED_VC or RESTART_ALL_VCS. If a non-zero vci parameter is passed in, the connection identifier IE is also included in the message, using a default vpci of 0 and the vci parameter value.

qcc_create_add_party() constructs an add party message structure. It includes the mandatory called party number and endpoint reference IEs. The user should pass in a pointer to the called number and an endpoint reference value; for the called party number, ATM Endsystem (NSAP) address type is assumed.

qcc_create_add_party_ack() fills in an add party ack message structure with the endpoint reference IE. The endpt_ref parameter value is used.

qcc_create_add_party_reject() fills the cause and endpoint reference IEs into an add party reject structure. The user should provide the cause and endpoint reference value; possible cause values are defined in the <atm/qccdefs.h> header file. By default, no diagnostic is included and the user location is assigned in the cause IE.

qcc_create_drop_party() fills the cause and endpoint reference IEs into a drop party structure. The user should pass in the cause and endpoint reference values; possible cause values are defined in the <atm/qccdefs.h> header file. By default, no diagnostic is included and the user location is assigned in the cause IE.

qcc_create_drop_party_ack() fills in only the mandatory endpoint reference IE, requiring the endpt_ref parameter.

RETURN VALUES

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

EXAMPLES

The following code fragment creates a setup message, adds an optional AAL Parameters IE, packs the message into streams buffers, and sends it downstream.

#include <atm/limits.h>
#include <atm/qcc.h>
#include <atm/qcctypes.h>
char    ifname[QCC_MAX_IFNAME_LEN] = "sa0";
int     calltag = 0x1234;
int     forward_sdusize = 0x2378;
int     backward_sdusize = 0x2378;
qcc_msg_t          msgstruct;
qcc_setup_t        setup;
qcc_ie_t           iestruct;
qcc_aal_params_t   aal;
struct strbuf      ctl, data;
char               ctlbuf[QCC_MAX_CTL_LEN];
char               databuf[QCC_MAX_DATA_LEN];
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

};
ctl.buf = ctlbuf;
data.buf = databuf;
ctl.maxlen = QCC_MAX_CTL_LEN;
data.maxlen = QCC_MAX_DATA_LEN;
if ((qcc_create_setup(&setup, ifname,

calltag, dst_addr)) < 0) {

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

}
msgstruct.type = QCC_SETUP;
msgstruct.msg.setup = &setup;
aal.type = AAL_TYPE_5;
aal.info.aal5.forward_max = forward_sdusize;
aal.info.aal5.backward_max = backward_sdusize;
aal.info.aal5.mode = MESSAGE_MODE;
aal.info.aal5.sscs_type = SSCS_TYPE_NULL;
iestruct.type = QCC_AAL_PARAMETERS;
iestruct.ie.aal_params = &aal;
if ((qcc_set_ie(&msgstruct, &iestruct)) < 0) {

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

}
if ((qcc_pack_setup(&ctl, &data,

msgstruct.msg.setup)) < 0) {

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

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

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

}

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

Museum

Related Articles