diff options
Diffstat (limited to 'contrib/ngatm/man/unifunc.3')
| -rw-r--r-- | contrib/ngatm/man/unifunc.3 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/contrib/ngatm/man/unifunc.3 b/contrib/ngatm/man/unifunc.3 new file mode 100644 index 0000000..65f9ef9 --- /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 <harti@freebsd.org> +.\" +.\" $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 |
