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 − parse Q.2931 messages

SYNOPSIS

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

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

char _depends_on[] = "drv/qcc";

int qcc_parse_setup(mblk_t ∗mp, 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(mblk_t ∗mp, int ∗vcip, int ∗endpt_refp);

int qcc_parse_connect(mblk_t ∗mp, int ∗vcip, int ∗forward_sdusizep, int ∗backward_sdusizep, int ∗endpt_refp);

int qcc_parse_release(mblk_t ∗mp, int ∗causep);

int qcc_parse_release_complete(mblk_t ∗mp, int ∗causep);

int qcc_parse_status_enquiry(mblk_t ∗mp, int ∗endpt_refp);

int qcc_parse_status(mblk_t ∗mp, int ∗callstatep, int ∗causep, int ∗endpt_refp, int ∗endpt_statep);

int qcc_parse_restart(mblk_t ∗mp, int ∗vcip, int ∗rstallp);

int qcc_parse_restart_ack(mblk_t ∗mp, int ∗vcip, int ∗rstallp);

int qcc_parse_add_party(mblk_t ∗mp, int ∗forward_sdusizep, int ∗backward_sdusizep, atm_address_t ∗src_addrp, atm_address_t ∗dst_addrp, int ∗sapp, int ∗endpt_refp);

int qcc_parse_add_party_ack(mblk_t ∗mp, int ∗endpt_refp);

int qcc_parse_add_party_reject(mblk_t ∗mp, int ∗causep, int ∗endpt_refp);

int qcc_parse_drop_party(mblk_t ∗mp, int ∗causep, int ∗endpt_refp);

int qcc_parse_drop_party_ack(mblk_t ∗mp, int ∗causep, int ∗endpt_refp);

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 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 kernel space. 

Each function requires a minimum of 1 parameter: mp, which is a pointer to a mblk_t structure, and is extracted from the following structure:

M_PROTO                           M_DATA

 _____________      ___________________________

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

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

When a message is received from the q93b driver using the getq(9F) function, a pointer to the M_PROTO block shown above is returned.  However, the q93b message which is parsed is contained in the M_DATA block, so the first parameter passed to a qcc_parse function must be mp->b_cont, where mp is the pointer received by getq().  The M_PROTO block data may be examined to determine the message type, which indicates the parsing function that should be called. 

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 in 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 values 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 sever 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.  Possible cause values may be found in the header file <atm/qcc.h>.  The same parsing applies to qcc_parse_drop_party_ack(). 

RETURN VALUES

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

EXAMPLES

The following code fragment receives and parses a setup message. 

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

int            vci;
int            forward_sdusize;
int            backward_sdusize;
int            sap;
atm_addr_t     src_addr;
atm_addr_t     dst_addr;
mblk_t         ∗mp;
qcc_hdr_t      ∗hdrp;
 do {

if !(mp = getq(q)) {

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

}
hdrp = (qcc_hdr_t ∗)mp;

} while (hdrp->type != QCC_SETUP);
 qcc_parse_setup(mp->b_cont, &vci, &forward_sdusize,

&backward_sdusize, &src_addr,
&dst_addr, &sap, NULL);

printf("parse_setup: vci = 0x%x, sap = 0x%x0, vci, sap);

}

SEE ALSO

qcc_util(3), qcc_bld(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