qcc_set_ie(9F)

NAME

qcc_set_ie − add or update Information Elements in a Q.2931 message structure

SYNOPSIS

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

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

char _depends_on[] = "drv/qcc";

int qcc_set_ie(qcc_msg_t ∗msgp, qcc_ie_t ∗iep);

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

This function adds a new or changes an existing Information Element in Q.2931 messages. The Q.2931 protocol 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 function may be used by processes which are running in kernel space.

A message structure should first be created using the appropriate qcc_create(9F) function call. IEs may then be added or changed using qcc_set_ie. When the message structure has been completely specified, the corresponding qcc_pack(9F) function should be called to translate the message structure into the correct encoded format, contained in mblk_t structures which may be passed to the putq(9F) 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 user should insure that the values passed in in the IE structure conform with the UNI version (3.0 or 3.1) that is running.

The function requires 2 parameters: msgp, which is a pointer to the appropriate message structure; and iep, which is a pointer to the new IE structure. The message and IE structure types are defined in the <atm/qcctypes.h> header file.

The structure to which msgp points must be allocated by the calling user. The structure pointed to by iep should have the desired values filled in to its fields, and the "valid" field should be set to 1. A value of 0 in the "valid" field indicates that the IE should not be included in the message.

The fields of each Information Element structure and their interpretations are described in the following paragraphs. Possible values for IE fields are defined in the <atm/qccdefs.h> header file.

qcc_aal_params_t
Currently, the only ATM Adaptation Layer supported on SunATM products is AAL 5. However, to allow for future changes, the aal parameters ie type consists of a field identifying the aal and a union of structures for each aal, called "info." The aal 5 structure contains 4 fields: forward_max and backward_max for the SDU sizes, mode, and sscs_type. The sscs_type is only valid in UNI 3.0; therefore, a value of 0 for sscs_type indicates that that field should not be included.

qcc_traffic_desc_t
The ATM Traffic Descriptor IE (called User Cell Rate in UNI 3.0) contains a large set of traffic parameter values. Two parameters do not have numeric values associated; they are either included or not. The are represented by two fields, best_effort and tagging, that are either set to 1 if the parameter is to be included or set to 0 if it is not. The remaining parameters all have numeric values associated with them. Since 0 is a valid value for these parameters, an additional field, params, is included in the IE structure which indicates which of these should be included in the message. Each parameter has a corresponding bit in the params field, which, when set, indicates that the parameter should be included. Flags are defined for this field in the <atm/qccdefs.h> header file.

qcc_bbc_t
The Broadband Bearer Capability IE fields correspond directly to the options for this IE. The fields are:

class           Bearer Class
type            Traffic Type
timing          Timing Requirements
clipping        Susceptibility to Clipping
userplane       User plane connection configuration

qcc_bhli_t
The Broadband High Layer Information IE structure contains 3 fields which specify the IE contents. They are type, which identifies the High Layer Information Type; infolen, which indicates the number of octets of high layer information is to be included in the message (the maximum is 8 octets), and finally an array of bytes called info which contains the information octets, called info. The octets should be placed in the first infolen elements of the array.

qcc_blli_t
The Broadband Low Layer Information IE contains 2 fields to specify the IE contents. The first, layer, is an integer which specifies which layer protocol is being specified, layer 1, 2, or 3. The second is a union, with unique structures for layer 2 and layer 3. For both layer 2 and layer 3 IEs, the protocol value will be examined and the correct coding format will be used for that protocol. Therefore, only the applicable fields from the layer structure will be used for the specified protocol type.

Layer 2 fields:

protocol     User information layer 2 protocol
mode         Mode of operation
windowsize   Window size (k)
userspec     User specified layer 2 protocol

information

Layer 3 fields:

protocol     User information layer 3 protocol
mode         Mode of operation
pktsize      Default packet size
windowsize   Packet window size
userspec     User specified layer 3 protocol

information

ipi 8-bit Initial Protocol Identifier for

ISO/IEC TR 9577

oui 24-bit organization unique identifier

for ISO/IEC TR 9577 and IEEE 802.1 SNAP

pid 16-bit protocol identifier for ISO/IEC

TR 9577 and IEEE 802.1 SNAP

qcc_call_state_t
There is only one informational field in the Call State IE structure: state, specifying the call state.

qcc_called_num_t
The Called Party Number IE structure contains a planid field, which specifies the Addressing/Numbering Plan Identification. The Type of Number is based on this value as well. There is also an address field, to specify a 20-byte address.

qcc_called_subaddr_t
The Called Party Subaddress IE structure contains a type field, which specifies the Type of Subaddress, and a 20-byte address field.

qcc_calling_num_t
In addition to the 20-byte address field, the Calling Party Number IE structure contains several fields to describe the intended interpretation of the address. They are:

planid Addressing/Numbering Plan

Identification

presentation Presentation indicator
screening Screening indicator

qcc_calling_subaddr_t
The structure for the Calling Party Subaddress IE is identical to that of the Called Party Subaddress IE.

qcc_cause_t
The Cause IE structure contains a location field and a cause field. In addition, it contains an array of 28 octets, diag, for diagnostic information. The number of diagnostic octets included in the array should be specified in the diaglen field.

qcc_conn_id_t
The Connection Identifier IE structure contains a vpci and a vci field. Note that currently, the SunATM software only supports vpci 0, although any value may be placed in the vpci field and will be encoded into the message.

qcc_qos_t
The Quality of Service IE has 3 informational fields: codingstd, specifying the Coding Standard value; and forward_class and backward_class, specifying the Forward and Backward QoS Class.

qcc_restart_ind_t
There is only one informational field in the Restart Indicator IE structure: class, whcih specifies the class of the facility to be restarted.

qcc_transit_t
The Transit Network Selection IE structure contains an array of up to four octets to specify the Carrier Identification Code value.

qcc_endpt_ref_t
The Endpoint Reference IE structure contains an endptref field, which specifies the endpoint reference value.

qcc_endpt_state_t
The Endpoint State IE structure contains a state field, which identifies the endpoint state value.

RETURN VALUES

The function returns 0 on success and -1 on error.

EXAMPLES

See the Example section of the qcc_create(9F) man page for an example using qcc_set_ie.

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