unistruct(3)

NAME

libngatm - ATM signalling library

LIBRARY

Begemot ATM signalling library (libngatm, -lngatm)

SYNOPSIS

#include <netnatm/msg/unistruct.h>
#include <netnatm/msg/unimsglib.h>

DESCRIPTION

The libngatm library handles UNI 4.0 messages. For each in

formation element and message type the header files contain a structure

definition.
Additionally there are a number of help structures and a

global context
structure for some of the library functions. This document

only
describes the common structures. For information element

and message
structures see the header files.

LIBRARY CONFIGURATION

When the library is compiled a number of constants are de

fine in the file
uni_config.h. They define certain limits. Because of the

use of these
definitions a change in any of them requires a complete re

compilation of
all library code and all code that uses the library. The

following constants are defined (they value behind the name is the de

fault value):

UNI_MAX_ERRIE (50)

When decoding information elements and analyzing them

the library
fills an array in the context with the identifiers of

IEs that had
errors. This is the size of this array.

UNI_NUM_IE_GIT (3)

A message is allowed to contain more than one General

Identifier
Transport information element. This is the maximum

supported number of these IEs.

UNI_NUM_IE_BLLI (3)

The maximum number of BLLI information elements in a

SETUP message.

UNI_NUM_IE_CALLEDSUB (2)

The maximum number of Called Subaddress information

elements in a
SETUP message.

UNI_NUM_IE_CALLINGSUB (2)

The maximum number of Calling Subaddress information

elements in a
SETUP message.

UNI_NUM_IE_TNS (4)

The maximum number of Transit Network Selection infor

mation elements in a SETUP message.

UNI_TNS_MAXLEN (4)

The maximum size of a name in the TNS IE.

UNI_UU_MAXLEN (128)

Maximum size of user data in the UU IE.

UNI_ADDR_MAXLEN (20)

Maximum address size.

UNI_SUBADDR_MAXLEN (20)

Maximum subaddress size.

UNI_NUM_IE_DTL (10)

Maximum number of DTL information elements in a SETUP

message.

UNI_DTL_MAXNUM (20)

Maximum number of identifiers in one DTL information

element.

INFORMATION ELEMENTS

Each information element structure starts with a field of

type:

struct uni_iehdr {

enum uni_coding coding; /* coding standard */
enum uni_ieact act; /* action indicator */
u_int pass:1; /* PNNI pass along re

quest */
u_int present;/* which optional ele

ments are present */

};

The coding field is the coding standard of the information

element and
may be one of UNI_CODING_ITU or UNI_CODING_NET. The action

indicator act
is used for error processing and is one of:

UNI_IEACT_CLEAR

clear call

UNI_IEACT_IGNORE

ignore IE and proceed

UNI_IEACT_REPORT

ignore IE, report and proceed

UNI_IEACT_MSG_IGNORE

ignore message

UNI_IEACT_MSG_REPORT

ignore message and report

UNI_IEACT_DEFAULT

the use action indicator flag was not set.

For information elements in PNNI message the pass fields

contains the
pass along flag from the IE header.

The present field is a bit field, which contains four common

bits
describing the current state of the information element.

The rest of the
bits are used by the information elements to indicate which

of the
optional fields of the IE are present. Most of the IE head

er files contain definitions for those bits. The common bits are:

#define UNI_IE_EMPTY 0x80000000
#define UNI_IE_PRESENT 0x40000000
#define UNI_IE_ERROR 0x20000000
#define UNI_IE_XXX 0x10000000

The flag UNI_IE_EMPTY indicates that the information element

is present,
but empty (its length is zero). This is legal for all in

formation elements. The flag UNI_IE_PRESENT indicates that the IE is

present in the
message and the flag UNI_IE_ERROR indicates that the IE had

an error.
The flag UNI_IE_XXX is currently not used.

The following macros may be used to test or change these

flags:

IE_ISPRESENT

Check whether the IE is present and not empty. Re

turns true in
this case.

IE_SETPRESENT

Set the IE to be present and not empty.

IE_ISEMPTY

Check whether the IE is present and empty. Returns

true in this
case.

IE_SETEMPTY

Set the IE to be present and empty.

IE_ISERROR

Check whether the IE is present and has an error. Re

turns true in
this case.

IE_SETERROR

Sets the IE to be present and to have an error.

IE_ISGOOD

Checks whether the IE is present, not empty and with

out error.
Returns true in this case.

For each IE type there is an enum uni_ietype definition of

the form
UNI_IE_* in uni_hdr.h.

unistruct.h contains a union uni_ieall that is the union of

all IE structures and a

struct uni_ie {

enum uni_ietype ietype;
union uni_ieall u;

};

MESSAGES

Each message structure starts with a

struct uni_msghdr {

struct uni_cref cref;
enum uni_msgact act; /* action indicator */
u_int pass:1; /* PNNI pass along re

quest */

};

The cref is the call reference:

struct uni_cref {

u_int flag;
u_int cref;

};

There are two special call references: CREF_GLOBAL and

CREF_DUMMY. The
act field is the message action indicator and has one of the

following
values:

UNI_MSGACT_CLEAR

clear call

UNI_MSGACT_IGNORE

ignore message

UNI_MSGACT_REPORT

send STATUS message

UNI_MSGACT_DEFAULT

default handling for this message type

The pass field is the pass along indicator in the case of

PNNI messages.

For each message type there is a enum uni_msgtype definition

of the form
UNI_* in uni_hdr.h. uni_struct.h contains a union_msgall

that is the
union of all message structures and a

struct uni_all {

enum uni_msgtype mtype;
union uni_msgall u;

};

CONTEXTS

The header file unimsglib.h contains a definition of a

struct uni_context
that is used to minimize the number of arguments passed to

certain functions and to avoid the use of global variables. This struc

ture has the
following public fields (all other fields are used internal

ly by the
library):

err This is an array consisting of the following struc

tures:

struct uni_ierr {

enum uni_ierr_type err; /* what error */
enum uni_ieact act; /* the action

indicator */
u_int ie:8; /* the ie type

*/
u_int man:1; /* mandatory

flag */
u_int epref:1;/* Q.2971

9.5.3.2.1 low-pri epref */

};

When decoding information elements the information

about IEs with
errors is stuffed into this array.

errcnt

The current number of IEs in err.

q2932

Enable the Q.2932.1 Generic Functional Protocol. Cur

rently only
message and IE decoding/encoding is supported. The

signalling part
is still missing.

pnni Enable PNNI extensions. Currently only message and IE

decod

ing/encoding is supported. The signalling part is

still missing.

git_hard

Do hard checking on GIT information elements.

bearer_hard

Do hard checking on Broadband Bearer IEs. This in

volves rejecting
old bearer type values.

cause_hard

Do hard checking on Cause information elements.

multiline

This is used by the printing routines. Legal values

are 0 to 4 and
give different kinds of printout.

tabsiz

The size of tabulation to use in printing. 4 is a

good value.

SEE ALSO

libunimsg(3)

STANDARDS

This implementation conforms to the applicable ITU-T recom

mendations and
ATM Forum standards with the exception of some limitations

(see the Configuration section).

AUTHORS

Hartmut Brandt <harti@freebsd.org>

BSD May 23, 2005

BSD