From 0b6c80c9966da081b04e14573f8c30e30bd2bb78 Mon Sep 17 00:00:00 2001 From: Hartmut Brandt Date: Mon, 3 Nov 2003 12:08:41 +0000 Subject: [PATCH] Virgin import of NgATM user part 0.91 --- contrib/ngatm/man/libngatm.3 | 72 ++++++++ contrib/ngatm/man/uniaddr.3 | 125 +++++++++++++ contrib/ngatm/man/unifunc.3 | 252 ++++++++++++++++++++++++++ contrib/ngatm/man/unistruct.3 | 320 ++++++++++++++++++++++++++++++++++ 4 files changed, 769 insertions(+) create mode 100644 contrib/ngatm/man/libngatm.3 create mode 100644 contrib/ngatm/man/uniaddr.3 create mode 100644 contrib/ngatm/man/unifunc.3 create mode 100644 contrib/ngatm/man/unistruct.3 diff --git a/contrib/ngatm/man/libngatm.3 b/contrib/ngatm/man/libngatm.3 new file mode 100644 index 000000000000..8c5941489b74 --- /dev/null +++ b/contrib/ngatm/man/libngatm.3 @@ -0,0 +1,72 @@ +.\" +.\" 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 +.\" +.\" $Begemot: libunimsg/man/libunimsg.3,v 1.2 2003/08/21 16:01:07 hbb Exp $ +.\" +.Dd October 30, 2003 +.Dt libngatm 3 +.Os +.Sh NAME +.Nm libngatm +.Nd "ATM signalling library" +.Sh LIBRARY +Begemot ATM signalling library +.Pq libngatm, -lngatm +.Sh DESCRIPTION +The Begemot UNI signalling library handles message decoding and encoding as +well as the Q.2110 and Q.2120 transport protocols and adaptation layers, and +ATM-Forum UNI 4.0 compliant signalling. +Because of this complexity the description is broken down in several man pages: +.Bl -tag -width XXXX +.It Xr unimsg 3 +Describes a data structure and functions for handling of variable sized +messages. +.It Xr unistruct 3 +describes data structures for the decoding, encoding and printing functions +in the library. +.It Xr unifunc 3 +describes the decoding, encoding and printing functions. +.\" .It Xr sscop 3 +.\" describes the SSCOP transport protocol functions. +.\" .It Xr sscfu 3 +.\" describes the SSCF at the UNI functions. +.\" .It Xr uni 3 +.\" describes the UNI 4.0 signalling functions. +.It Xr uniaddr 3 +describes address structures and handling functions. +.\" .It Xr unisap 3 +.\" describes ATM-Forum ATM-API service access point structures and +.\" handling functions. +.El +.Sh SEE ALSO +.Xr sscop 1 +.Sh STANDARDS +This implementation conforms to the applicable ITU-T +recommendations and ATM Forum standards. +.Sh AUTHORS +.An Hartmut Brandt Aq harti@freebsd.org diff --git a/contrib/ngatm/man/uniaddr.3 b/contrib/ngatm/man/uniaddr.3 new file mode 100644 index 000000000000..f80d45c723c6 --- /dev/null +++ b/contrib/ngatm/man/uniaddr.3 @@ -0,0 +1,125 @@ +.\" +.\" 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 +.\" +.\" $Begemot: libunimsg/man/uniaddr.3,v 1.2 2003/08/21 16:01:07 hbb Exp $ +.\" +.Dd October 30, 2003 +.Dt uniaddr 3 +.Os +.Sh NAME +.Nm unimsg , +.Nm uni_str2nsap , +.Nm uni_nsap2str , +.Nm uni_prefix2str , +.Nm uni_e1642nsap , +.Nm uni_nsap2e164 +.Nd "ATM signalling library - address handling" +.Sh LIBRARY +Begemot ATM signalling library +.Pq libunimsg, -lunimsg +.Sh SYNOPSIS +.In netnatm/addr.h +.Ft int +.Fn uni_str2nsap "u_char *nsap" "const char *str" +.Ft void +.Fn uni_nsap2str "char *str" "const u_char *nsap" "int dots" +.Ft void +.Fn uni_prefix2str "char *str" "const u_char *prefix" "u_int len" "int dots" +.Ft int +.Fn uni_e1642nsap "u_char *nsap" "const char *e164" +.Ft int +.Fn uni_nsap2e164 "char *e164" "const u_char *nsap" "int check" +.Sh DESCRIPTION +The UNI message library contains a number of utility functions to handle +NSAP and E.164 addresses. +.Pp +The function +.Fn uni_str2nsap +parses a string and interprets it as an NSAP address. +The string should consist of exact 40 hexadecimal digits +(upper and lower case are allowed) and any +number of dots at any position. +Any other character is illegal. +The resulting NSAP address is written to the buffer pointed to by +.Fa nsap . +This buffer should be at least 20 bytes. +On success the funtion returns 0. +If an parsing error happens -1 is returned. +.Pp +The function +.Fn uni_nsap2str +converts the NSAP address pointed to by +.Fa nsap +into a string. +For some commonly used NSAP formats (those with leading +octets 0x39, 0x45 or 0x47) dots may be inserted to make the address more +readable by passing a non-0 value in +.Fa dots . +The buffer pointed to by +.Fa str +should be large enough to hold the resulting string plus the terminating NUL. +A size of 80 byte is large enough for all cases. +.Pp +The function +.Fn uni_prefix2str +converts an NSAP prefix to a string. +The length of the NSAP prefix in bytes is passed in +.Fa len . +.Li "uni_nsap2str(str, nsap, dots)" +is equivalent to +.Li "uni_prefix2str(str, nsap, 20, dots)" . +.Pp +The function +.Fn uni_e1642nsap +converts an E.164 address given as an ASCII string to an embedded E.164 NSAP +address. +The string pointed to by +.Fa e164 +must consist of at least 1 and not more than 15 ASCII digits. +The function returns 0 on success and -1 if the E.164 address was malformed. +.Pp +The function +.Fn uni_nsap2e164 +extracts the E.164 address from an embedded E.164 NSAP address. +The argument +.Fa check +specifies whether the NSAP address should be checked for correct syntax. +If +.Fa check +is 0 the last 11 bytes of the address are ignored. If +.Fa check +is 1 the last 11 bytes except the selector byte must be zero. +If +.Fa check +is 2 the last 11 bytes must be zero. +The function returns 0 on success and -1 when the NSAP address was not an +embedded E.164 NSAP or one of the additional checks failed. +.Sh SEE ALSO +.Xr libngatm 3 , +.Sh AUTHORS +.An Hartmut Brandt Aq harti@freebsd.org diff --git a/contrib/ngatm/man/unifunc.3 b/contrib/ngatm/man/unifunc.3 new file mode 100644 index 000000000000..65f9ef939111 --- /dev/null +++ b/contrib/ngatm/man/unifunc.3 @@ -0,0 +1,252 @@ +.\" +.\" 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 +.\" +.\" $Begemot: libunimsg/man/unifunc.3,v 1.2 2003/08/21 16:01:08 hbb Exp $ +.\" +.Dd October 30, 2003 +.Dt unifunc 3 +.Os +.Sh NAME +.Nm libngatm +.Nm uni_decode +.Nm uni_decode_head +.Nm uni_decode_body +.Nm uni_decode_ie_hdr +.Nm uni_decode_ie_body +.Nm uni_encode +.Nm uni_encode_msg_hdr +.Nm uni_encode_ie +.Nm uni_encode_ie_hdr +.Nm uni_check_ie +.Nm uni_print_cref +.Nm uni_print_msghdr +.Nm uni_print +.Nm uni_print_ie +.Nm uni_initcx +.Nm uni_print_cx +.Nd "ATM signalling library - message handling functions" +.Sh LIBRARY +Begemot ATM signalling library +.Pq libngatm, -lngatm +.Sh SYNOPSIS +.In netnatm/msg/unistruct.h +.In netnatm/msg/unimsglib.h +.Ft int +.Fn uni_decode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx" +.Ft int +.Fn uni_decode_head "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx" +.Ft int +.Fn uni_decode_body "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx" +.Ft int +.Fn uni_decode_ie_hdr "enum uni_ietype *type" "struct uni_iehdr *hdr" "struct uni_msg *buf" "struct unicx *cx" "u_int *ielen" +.Ft int +.Fn uni_decode_ie_body "enum uni_ietype type" "union uni_ieall *ie" "struct uni_msg *buf" "u_int ielen" "struct unicx *cx" +.Ft int +.Fn uni_encode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx" +.Ft int +.Fn uni_encode_msg_hdr "struct uni_msg *buf" "struct uni_msghdr *hdr" "enum uni_msgtype type" "struct unicx *cx" "int *mlen" +.Ft int +.Fn uni_encode_ie "enum uni_ietype type" "struct uni_msg *buf" "union uni_ieall *ie" "struct unicx *cx" +.Ft int +.Fn uni_encode_ie_hdr "struct uni_msg *buf" "enum uni_ietype type" "struct uni_iehdr *hdr" "u_int len" "struct unicx *cx" +.Ft int +.Fn uni_check_ie "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx" +.Ft void +.Fn uni_print_cref "char *buf" "size_t buflen" "struct uni_cref *cref" "struct unicx *cx" +.Ft void +.Fn uni_print_msghdr "char *buf" "size_t buflen" "struct uni_msghdr *hdr" "struct unicx *cx" +.Ft void +.Fn uni_print "char *buf" "size_t buflen" "struct uni_all *msg" "struct unicx *cx" +.Ft void +.Fn uni_print_ie "char *buf" "size_t buflen" "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx" +.Ft void +.Fn uni_initcx "struct unicx *cx" +.Ft void +.Fn uni_print_cx "char *buf" "size_t buflen" "struct unicx *cx" +.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 describes the functions that are +used to handle messages. +.Ss 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 structure. +.Pp +The function +.Fn uni_decode +takes a message buffer, interprets it as a UNI message and fills in the +structure pointed to by +.Fa msg . +It also takes a context argument and may fill the error array in the context. +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. +.Pp +The process of decoding a message can be split up by calling +.Fn uni_decode_head +and +.Fn uni_decode_body . +The first of these functions decodes only the message header and the second +one decodes only the information elements. +.Fn 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). +.Fn uni_decode_body +return 0 on success and -1 for unknown message types or if any +IE had an error. +.Pp +The function +.Fn uni_decode_ie_hdr +decodes the next information element header. +It returns the IE type and its length +in the variables pointed to by +.Va type +and +.Va ielen +and stores the decoded header in the structure pointed to by +.Va hdr . +The function returns 0 on success and -1 if there were not enough bytes +in the buffer left for a complete IE header. +.Pp +The function +.Fn uni_decode_ie_body +decodes the body of an information element. It is passed the buffer with the +message +.Fa buf , +the information element type +.Fa type +and length +.Fa ielen . +The IE is stored in the union pointed to by +.Fa ie . +The function returns -1 on errors and 0 on success. +In any case the most correct +number of bytes is consumed from the input buffer. +.Ss ENCODING +Encoding is the process of taking a message or IE structure and producing +an octet stream from it. +.Pp +The function +.Fn uni_encode +encodes a UNI message. +It returns -1 if the message type is out of bounds, -3 +if the message type is unknown. +The encoding functions for the message types +can return their own error codes. +The function returns 0 on success. +.Pp +The function +.Fn uni_encode_msg_hdr +encodes a message header. +The variable pointed to by +.Fa 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. +.Pp +The function +.Fn uni_encode_ie +encodes one information element. +The function returns 0 on success or -1 +on errors. +The function +.Fn uni_encode_ie_hdr +encodes the four byte IE header. +The argument +.Fa 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. +.Ss CHECKING +There exists a number of function that do consistency checks on information +elements. +Note, that these functions do not check inter-IE consistency, but +each IE by itself. +.Pp +The function +.Fn uni_check_ie +check an information element for consistency. +It returns 0 if the IE seems +ok, -1 otherwise. +.Ss 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 +.Xr unistruct 3 ). +Each of the function takes a +.Fa buf +and a +.Fa buflen +argument. +The string that is generated in the buffer pointed to by +.Fa buf +is guaranteed to be NUL terminated. +.Pp +The function +.Fn uni_print_cref +formats a call reference taking into account special call references. +The function +.Fn uni_print_msg_hdr +formats a message header. +The functions +.Fn uni_print +and +.Fn uni_print_ie +print messages and information elements. +.Ss CONTEXTS +There are two functions for context handling. +.Fn uni_initcx +initializes a context with default values and +.Fn uni_print_cx +prints a context to the given buffer. +.Sh SEE ALSO +.Xr libngatm 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 diff --git a/contrib/ngatm/man/unistruct.3 b/contrib/ngatm/man/unistruct.3 new file mode 100644 index 000000000000..86975b66a249 --- /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 +.\" +.\" $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