qcc_parse(3)

NAME

qcc_parse, qcc_parse_setup, qcc_parse_call_proceeding, qcc_parse_connect, qcc_parse_release, qcc_parse_release_complete, qcc_parse_status_enquiry, qcc_parse_status, qcc_parse_restart, qcc_parse_restart_ack, qcc_parse_add_party, qcc_parse_add_party_ack, qcc_parse_add_party_reject, qcc_parse_drop_party, qcc_parse_drop_party_ack, qcc_get_hdr − parse Q.2931 messages

SYNOPSIS

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

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

int qcc_parse_setup(strbuf_t ∗datap, int ∗vcip, int ∗forward_sdusizep, int ∗backward_sdusizep, atm_addr_t ∗src_addrp, atm_addr_t ∗dst_addrp, int ∗sapp, int ∗endpt_refp);

int qcc_parse_call_proceeding(strbuf_t ∗datap, int ∗vcip, int ∗endpt_refp);

int qcc_parse_connect(strbuf_t ∗datap, int ∗vcip, int ∗forward_sdusizep, int ∗backward_sdusizep, int ∗endpt_refp);

int qcc_parse_release(strbuf_t ∗datap, int ∗causep);

int qcc_parse_release_complete(strbuf_t ∗datap, int ∗causep);

int qcc_parse_status_enquiry(strbuf_t ∗datap, int ∗endpt_refp);

int qcc_parse_status(strbuf_t ∗datap, int ∗callstatep, int ∗causep, int ∗endpt_refp, int ∗endpt_statep);

int qcc_parse_restart(strbuf_t ∗datap, int ∗vcip, int ∗rstallp);

int qcc_parse_restart_ack(strbuf_t ∗datap, int ∗vcip, int ∗rstallp);

int qcc_parse_add_party(strbuf_t ∗datap, int ∗forward_sdusize, int ∗backward_sdusize, atm_address_t ∗src_addrp, atm_address_t ∗dst_addrp, int ∗sapp, int ∗endpt_refp);

int qcc_parse_add_party_ack(strbuf_t ∗datap, int ∗endpt_refp);

int qcc_parse_add_party_reject(strbuf_t ∗datap, int ∗causep, int ∗endpt_refp);

int qcc_parse_drop_party(strbuf_t ∗datap, int ∗causep, int ∗endpt_refp);

int qcc_parse_drop_party_ack(strbuf_t ∗datap, int ∗causep, int ∗endpt_refp);

qcc_hdr_t ∗qcc_get_hdr(strbuf_t ∗ctlp);

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 parse 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. Messages conforming to both versions will be parsed. The functions may be used by processes which are running in user space.

Each function requires a minimum of 1 parameter: datap, which is a pointer to a strbuf_t buffer, or in the case of qcc_get_hdr, ctlp, which is also a pointer to a strbuf_t buffer.

datap is the data portion of a STREAMS message, corresponding to the M_DATA block of the message that is received from downstream. After receiving a message using the getmsg(2) function, the message type may be examined and an appropriate parsing routing called to extract information from the signalling message.

ctlp is the control portion of a STREAMS message, corresponding to the M_PROTO block of the message that is received from downstream. After receiving a message using the getmsg(2) function, qcc_get_hdr may be used to extract the Q.2931 header structure from the control buffer received from getmsg(2). The Q.2931 header type, qcc_hdr_t, is defined in <atm/types.h>.

Other parameters for each function depend on the type of information that is available in each message type. In all cases, certain IEs are examined in each message, as indicated below. If those IEs exist, the data that is expected from them is retrieved, but no error message is sent if they do not exist; the value of the parameter is set to -1 for any data that was expected from that particular IE. Also, IEs that are not expected are ignored. If the user wishes to ignore any of the parameters of a parse function, passing in a NULL pointer for that parameter is allowed so that space need not be allocated for the unnecessary parameter.

qcc_parse_setup() parses 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, connection identifier, broadband higher layer information, and endpoint reference. The endpoint reference IE is only included in setup messages for point-to-multipoint calls, which will be supported starting with the second release of SunATM software. The following table matches the data that is retrieved from the message with the IE from which it is parsed.

DATA RETRIEVED              INFORMATION ELEMENT
vci                         connection identifier
forward sdusize             AAL parameters
backward sdusize            AAL parameters
source address              calling party number
destination address         called party number
sap                         broadband higher layer
endpoint reference id       endpoint reference

qcc_parse_call_proceeding() parses a call proceeding message containing a connection identifier IE, which is used to set the value of vci, and an endpoint reference IE, setting the value of endpt_ref. The endpoint reference IE is only included in call proceeding messages for point-to-multipoint calls, which will be supported starting with the second release of SunATM software.

qcc_parse_connect() parses a connect message containing an AAL parameters IE, setting the forward and backward sdusize values, a connection identifier IE, setting the value of vci, and an endpoint reference IE, setting the value of endpt_ref. The endpoint reference IE is only included in connect messages for point-to-multipoint calls, which will be supported starting with the second release of SunATM software.

qcc_parse_release() parses a cause IE, setting the cause value. A listing of the possible values can be found in the <atm/qcc.h> header file. The same is true for qcc_parse_release_complete.

qcc_parse_status_enquiry() parses a status enquiry message containing an endpoint reference IE, setting the value of endpt_ref. The endpoint reference IE is only included when enquiring about a party state in a point-to-multipoint call. Point-to-multipoint calls will be supported starting with the second release of SunATM software.

qcc_parse_status() parses a status message. The IEs that are parsed are call state, cause, endpoint reference, and endpoint state. The call state and cause IEs are used to set the value of the parameters callstate and cause; possible values for both parameters may be found in the <atm/qcc.h> header file. The endpoint reference and endpoint state IEs will be used to set the values of the endpt_ref and endpt_state parameters; they are included if an enquiry is made about a party state in a point-to-multipoint call or to report an error condition in a point-to-multipoint call. Point-to-multipoint calls will be supported starting with the second release of SunATM software.

qcc_parse_restart() parses a restart message containing two possible IEs: connection identifier and restart indicator. The restart indicator IE is used to set the value of rstall; this parameter indicates whether a particular vci or all vcis are to be restarted (rstall = 1 implies all vcis, rstall = 0 implies a particular vci). The connection identifier identifies the particular vci. In this case, the value of the parameter vci is set to 0 if there is no connection identifier IE in the message. The same format applies to the qcc_parse_restart_ack() function.

qcc_parse_add_party() parses an add party message containing several possible IEs. They include AAL parameters, calling party number, called party number, broadband higher layer information, and endpoint reference. The following table matches the data that is retrieved from the message with the IE from which it is parsed.

DATA RETRIEVED              INFORMATION ELEMENT
forward sdusize             AAL parameters
backward sdusize            AAL parameters
source address              calling party number
destination address         called party number
sap                         broadband higher layer
endpoint reference id       endpoint reference

qcc_parse_add_party_ack() extracts an endpoint reference value from the endpoint reference IE in an add party ack message.

qcc_parse_add_party_reject() parses an add party reject message possibly containing a cause IE, from which it extracts the cause value, and an endpoint reference IE, from which it extracts the endpoint reference value. Possible cause values may be found in the header file <atm/qcc.h>.

qcc_parse_drop_party() extracts an endpoint reference value and a cause value from those respective IEs in a drop party message. The same is true for qcc_parse_drop_party_ack().

qcc_get_hdr() extracts the Q.2931 header from the control buffer received in getmsg(2). A pointer to this buffer, ctlp, is passed in to the function, and a pointer to the header of type qcc_hdr_t is returned on success. On failure, a null pointer is returned.

RETURN VALUES

All functions, with the exception of qcc_get_hdr, return 0 on success and -1 on error. The return values for qcc_get_hdr are described above.

EXAMPLES

The following code fragment receives and parses a setup message.

#include <atm/types.h>
#include <atm/qcc.h>
#include <atm/limits.h>
void
wait_for_setup(int fd);
{

int            vci;
int            forward_sdusize;
int            backward_sdusize;
int            sap;
int            flags = 0;
atm_addr_t     src_addr;
atm_addr_t     dst_addr;
qcc_hdr_t      ∗hdrp;
struct strbuf ctl, data;
char           ctlbuf[QCC_MAX_CTL_LEN];
char           databuf[QCC_MAX_DATA_LEN];
ctl.buf = ctlbuf;
data.buf = databuf;
ctl.len = data.len = 0;
ctl.maxlen = QCC_MAX_CTL_LEN;
data.maxlen = QCC_MAX_DATA_LEN;
if (getmsg(fd, &ctl, &data, &flags) < 0) {

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

}
hdrp = qcc_get_hdr(&ctl);
if ((hdrp) && (hdrp->type == QCC_SETUP)) {

if ((qcc_parse_setup(&data, &vci, &forward_sdusize,

&backward_sdusize, &src_addr,
&dst_addr, &sap, NULL)) < 0) {

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

}
printf("parse_setup: vci = 0x%x, sap = 0x%x\n",

vci, sap);

}

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

Museum

Related Articles