unifunc(3)

NAME

libngatm, uni_decode, uni_decode_head, uni_decode_body, uni_decode_ie_hdr, uni_decode_ie_body, uni_encode,

uni_encode_msg_hdr,
uni_encode_ie, uni_encode_ie_hdr, uni_check_ie,

uni_print_cref,
uni_print_msghdr, uni_print, uni_print_ie, uni_initcx,

uni_print_cx - ATM
signalling library - message handling functions

LIBRARY

Begemot ATM signalling library (libngatm, -lngatm)

SYNOPSIS

#include <netnatm/msg/unistruct.h>
#include <netnatm/msg/unimsglib.h>
int
uni_decode(struct  uni_msg *buf, struct uni_all *msg, struct
unicx *cx);
int
uni_decode_head(struct uni_msg *buf, struct uni_all *msg,
        struct unicx *cx);
int
uni_decode_body(struct uni_msg *buf, struct uni_all *msg,
        struct unicx *cx);
int
uni_decode_ie_hdr(enum uni_ietype  *type,  struct  uni_iehdr
*hdr,
        struct   uni_msg   *buf,  struct  unicx  *cx,  u_int
*ielen);
int
uni_decode_ie_body(enum  uni_ietype  type,  union  uni_ieall
*ie,
        struct uni_msg *buf, u_int ielen, struct unicx *cx);
int
uni_encode(struct uni_msg *buf, struct uni_all *msg,  struct
unicx *cx);
int
uni_encode_msg_hdr(struct  uni_msg  *buf,  struct uni_msghdr
*hdr,
        enum uni_msgtype type, struct unicx *cx, int *mlen);
int
uni_encode_ie(enum uni_ietype type, struct uni_msg *buf,
        union uni_ieall *ie, struct unicx *cx);
int
uni_encode_ie_hdr(struct uni_msg *buf, enum uni_ietype type,
        struct uni_iehdr *hdr, u_int len, struct unicx *cx);
int
uni_check_ie(enum uni_ietype type, union uni_ieall *ie,
        struct unicx *cx);
void
uni_print_cref(char  *buf,  size_t  buflen,  struct uni_cref
*cref,
        struct unicx *cx);
void
uni_print_msghdr(char *buf, size_t buflen, struct uni_msghdr
*hdr,
        struct unicx *cx);
void
uni_print(char *buf, size_t buflen, struct uni_all *msg,
        struct unicx *cx);
void
uni_print_ie(char *buf, size_t buflen, enum uni_ietype type,
        union uni_ieall *ie, struct unicx *cx);
void
uni_initcx(struct unicx *cx);
void
uni_print_cx(char *buf, size_t buflen, struct unicx *cx);

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

describes the
functions that are used to handle messages.

DECODING

Decoding is the process of taking an octet stream containing

a UNI message or IE, parsing it and filling in a message or IE struc

ture.

The function uni_decode() takes a message buffer, interprets

it as a UNI
message and fills in the structure pointed to by msg. It

also takes a
context argument and may fill the error array in the con

text. It returns
-1 if there is an error decoding the message header and -2

if there is an
error decoding the message body. The function returns 0 on

success.

The process of decoding a message can be split up by calling
uni_decode_head() and uni_decode_body(). The first of these

functions
decodes only the message header and the second one decodes

only the
information elements. uni_decode_head() returns 0 if it

could decode the
message header and -1 if the message could not be decoded

(bad protocol
identifier, bad length or broken call reference).

uni_decode_body()
return 0 on success and -1 for unknown message types or if

any IE had an
error.

The function uni_decode_ie_hdr() decodes the next informa

tion element
header. It returns the IE type and its length in the vari

ables pointed
to by type and ielen and stores the decoded header in the

structure
pointed to by hdr. The function returns 0 on success and -1

if there
were not enough bytes in the buffer left for a complete IE

header.

The function uni_decode_ie_body() decodes the body of an in

formation element. It is passed the buffer with the message buf, the in

formation element type type and length ielen. The IE is stored in the

union pointed
to by ie. The function returns -1 on errors and 0 on suc

cess. In any
case the most correct number of bytes is consumed from the

input buffer.

ENCODING

Encoding is the process of taking a message or IE structure

and producing
an octet stream from it.

The function uni_encode() encodes a UNI message. It returns

-1 if the
message type is out of bounds, -3 if the message type is un

known. The
encoding functions for the message types can return their

own error
codes. The function returns 0 on success.

The function uni_encode_msg_hdr() encodes a message header.

The variable
pointed to by mlen is set to the offset of the message

length field from
the begin of the byte stream. This is needed because the

length of the
message body will be known only after all the IEs have been

encoded.
Then the length has to be inserted into this place. The

function returns
-1 if the call reference was bad and 0 on success.

The function uni_encode_ie() encodes one information ele

ment. The function returns 0 on success or -1 on errors. The function
uni_encode_ie_hdr() encodes the four byte IE header. The

argument len is
the maximum expected length of the information element, not

the real
length. The function inserts a 0 in the real length field.

This must be
fixed up by the caller after encoding the IE contents. The

function
return -1 if an empty IE is to be encoded (in this case the

length field
will have been set to 4) or 0 otherwise.

CHECKING

There exists a number of function that do consistency checks

on information elements. Note, that these functions do not check in

ter-IE consistency, but each IE by itself.

The function uni_check_ie() check an information element for

consistency.
It returns 0 if the IE seems ok, -1 otherwise.

PRINTING

A number of functions can be used to print decoded messages

and IEs in a
human readable form. This is intended mainly for debugging.

Some fields
of the library context are used to control how the printing

is done (see
unistruct(3) ). Each of the function takes a buf and a

buflen argument.
The string that is generated in the buffer pointed to by buf

is guaranteed to be NUL terminated.

The function uni_print_cref() formats a call reference tak

ing into
account special call references. The function

uni_print_msg_hdr() formats a message header. The functions uni_print() and

uni_print_ie()
print messages and information elements.

CONTEXTS

There are two functions for context handling. uni_initcx()

initializes a
context with default values and uni_print_cx() prints a con

text to the
given buffer.

SEE ALSO

libngatm(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