diff options
Diffstat (limited to 'contrib/ngatm/man/unistruct.3')
| -rw-r--r-- | contrib/ngatm/man/unistruct.3 | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/contrib/ngatm/man/unistruct.3 b/contrib/ngatm/man/unistruct.3 new file mode 100644 index 0000000..86975b6 --- /dev/null +++ b/contrib/ngatm/man/unistruct.3 @@ -0,0 +1,320 @@ +.\" +.\" Copyright (c) 2001-2003 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Author: Hartmut Brandt <harti@freebsd.org> +.\" +.\" $Begemot: libunimsg/man/unistruct.3,v 1.2 2003/08/21 16:01:08 hbb Exp $ +.\" +.Dd October 30, 2003 +.Dt unistruct 3 +.Os +.Sh NAME +.Nm libngatm +.Nd "ATM signalling library" +.Sh LIBRARY +Begemot ATM signalling library +.Pq libngatm, -lngatm +.Sh SYNOPSIS +.In netnatm/msg/unistruct.h +.In netnatm/msg/unimsglib.h +.Sh DESCRIPTION +The +.Nm +library handles UNI 4.0 messages. +For each information 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. +.Ss LIBRARY CONFIGURATION +When the library is compiled a number of constants are define in the file +.Pa uni_config.h . +They define certain limits. +Because of the use of these definitions a change +in any of them requires a complete recompilation of all library code and +all code that uses the library. +The following constants are defined (they +value behind the name is the default value): +.Bl -tag -width XXXX +.It Dv UNI_MAX_ERRIE ( Li 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. +.It Dv UNI_NUM_IE_GIT ( Li 3 ) +A message is allowed to contain more than one General Identifier Transport +information element. +This is the maximum supported number of these IEs. +.It Dv UNI_NUM_IE_BLLI ( Li 3 ) +The maximum number of BLLI information elements in a SETUP message. +.It Dv UNI_NUM_IE_CALLEDSUB ( Li 2 ) +The maximum number of Called Subaddress information elements in a SETUP message. +.It Dv UNI_NUM_IE_CALLINGSUB ( Li 2 ) +The maximum number of Calling Subaddress information elements in a SETUP +message. +.It Dv UNI_NUM_IE_TNS ( Li 4 ) +The maximum number of Transit Network Selection information elements in a SETUP +message. +.It Dv UNI_TNS_MAXLEN ( Li 4 ) +The maximum size of a name in the TNS IE. +.It Dv UNI_UU_MAXLEN ( Li 128 ) +Maximum size of user data in the UU IE. +.It Dv UNI_ADDR_MAXLEN ( Li 20 ) +Maximum address size. +.It Dv UNI_SUBADDR_MAXLEN ( Li 20 ) +Maximum subaddress size. +.It Dv UNI_NUM_IE_DTL ( Li 10 ) +Maximum number of DTL information elements in a SETUP message. +.It Dv UNI_DTL_MAXNUM ( Li 20 ) +Maximum number of identifiers in one DTL information element. +.El +.Ss INFORMATION ELEMENTS +Each information element structure starts with a field of type: +.Bd -literal -offset indent +struct uni_iehdr { + enum uni_coding coding; /* coding standard */ + enum uni_ieact act; /* action indicator */ + u_int pass:1; /* PNNI pass along request */ + u_int present;/* which optional elements are present */ +}; +.Ed +.Pp +The +.Fa coding +field is the coding standard of the information element and may be one of +.Dv UNI_CODING_ITU +or +.Dv UNI_CODING_NET . +The action indicator +.Fa act +is used for error processing and is one of: +.Bl -tag -width XXXX +.It Dv UNI_IEACT_CLEAR +clear call +.It Dv UNI_IEACT_IGNORE +ignore IE and proceed +.It Dv UNI_IEACT_REPORT +ignore IE, report and proceed +.It Dv UNI_IEACT_MSG_IGNORE +ignore message +.It Dv UNI_IEACT_MSG_REPORT +ignore message and report +.It Dv UNI_IEACT_DEFAULT +the use action indicator flag was not set. +.El +.Pp +For information elements in PNNI message the +.Fa pass +fields contains the pass along flag from the IE header. +.Pp +The +.Fa 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 header files contain definitions for those bits. +The common bits are: +.Bd -literal -offset indent +#define UNI_IE_EMPTY 0x80000000 +#define UNI_IE_PRESENT 0x40000000 +#define UNI_IE_ERROR 0x20000000 +#define UNI_IE_XXX 0x10000000 +.Ed +.Pp +The flag +.Dv UNI_IE_EMPTY +indicates that the information element is present, but empty (its length is +zero). +This is legal for all information elements. +The flag +.Dv UNI_IE_PRESENT +indicates that the IE is present in the message and the flag +.Dv UNI_IE_ERROR +indicates that the IE had an error. +The flag +.Dv UNI_IE_XXX +is currently not used. +.Pp +The following macros may be used to test or change these flags: +.Bl -tag -width XXXX +.It Dv IE_ISPRESENT +Check whether the IE is present and not empty. +Returns true in this case. +.It Dv IE_SETPRESENT +Set the IE to be present and not empty. +.It Dv IE_ISEMPTY +Check whether the IE is present and empty. +Returns true in this case. +.It Dv IE_SETEMPTY +Set the IE to be present and empty. +.It Dv IE_ISERROR +Check whether the IE is present and has an error. +Returns true in this case. +.It Dv IE_SETERROR +Sets the IE to be present and to have an error. +.It Dv IE_ISGOOD +Checks whether the IE is present, not empty and without error. +Returns true in this case. +.El +.Pp +For each IE type there is an +.Vt enum uni_ietype +definition of the form +.Dv UNI_IE_* +in +.Pa uni_hdr.h . +.Pp +.Pa unistruct.h +contains a +.Vt union uni_ieall +that is the union of all IE structures and a +.Bd -literal -offset indent +struct uni_ie { + enum uni_ietype ietype; + union uni_ieall u; +}; +.Ed +.Ss MESSAGES +Each message structure starts with a +.Bd -literal -offset indent +struct uni_msghdr { + struct uni_cref cref; + enum uni_msgact act; /* action indicator */ + u_int pass:1; /* PNNI pass along request */ +}; +.Ed +.Pp +The +.Fa cref +is the call reference: +.Bd -literal -offset indent +struct uni_cref { + u_int flag; + u_int cref; +}; +.Ed +.Pp +There are two special call references: +.Dv CREF_GLOBAL +and +.Dv CREF_DUMMY . +The +.Fa act +field is the message action indicator and has one of the following values: +.Bl -tag -width XXXX +.It Dv UNI_MSGACT_CLEAR +clear call +.It Dv UNI_MSGACT_IGNORE +ignore message +.It Dv UNI_MSGACT_REPORT +send STATUS message +.It Dv UNI_MSGACT_DEFAULT +default handling for this message type +.El +.Pp +The +.Fa pass +field is the pass along indicator in the case of PNNI messages. +.Pp +For each message type there is a +.Vt enum uni_msgtype +definition of the form +.Dv UNI_* +in +.Pa uni_hdr.h . +.Pa uni_struct.h +contains a +.Vt union_msgall +that is the union of all message structures and a +.Bd -literal -offset indent +struct uni_all { + enum uni_msgtype mtype; + union uni_msgall u; +}; +.Ed +.Ss CONTEXTS +The header file +.Pa unimsglib.h +contains a definition of a +.Vt 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 structure has the following +public fields (all other fields are used internally by the library): +.Bl -tag -width XXXX +.It Fa err +This is an array consisting of the following structures: +.Bd -literal -offset indent +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 */ +}; +.Ed +When decoding information elements the information about IEs with errors is +stuffed into this array. +.It Fa errcnt +The current number of IEs in +.Fa err . +.It Fa q2932 +Enable the Q.2932.1 Generic Functional Protocol. +Currently only message +and IE decoding/encoding is supported. +The signalling part is still missing. +.It Fa pnni +Enable PNNI extensions. +Currently only message and IE decoding/encoding +is supported. +The signalling part is still missing. +.It Fa git_hard +Do hard checking on GIT information elements. +.It Fa bearer_hard +Do hard checking on Broadband Bearer IEs. +This involves rejecting old bearer +type values. +.It Fa cause_hard +Do hard checking on Cause information elements. +.It Fa multiline +This is used by the printing routines. +Legal values are 0 to 4 and give +different kinds of printout. +.It Fa tabsiz +The size of tabulation to use in printing. +4 is a good value. +.El +.Sh SEE ALSO +.Xr libunimsg 3 , +.Sh STANDARDS +This implementation conforms to the applicable ITU-T +recommendations and ATM Forum standards with the exception of some limitations +(see the Configuration section). +.Sh AUTHORS +.An Hartmut Brandt Aq harti@freebsd.org |
