contrib/ngatm/man/unifunc.3

   1 .\"
   2 .\" Copyright (c) 2004-2005
   3 .\"     Hartmut Brandt.
   4 .\"     All rights reserved.
   5 .\" Copyright (c) 2001-2003
   6 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   7 .\"     All rights reserved.
   8 .\"
   9 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Begemot: libunimsg/man/unifunc.3,v 1.6 2005/06/15 11:37:09 brandt_h Exp $
  33 .\"
  34 .Dd June 14, 2005
  35 .Dt UNIFUNC 3
  36 .Os
  37 .Sh NAME
  38 .Nm libngatm ,
  39 .Nm uni_decode ,
  40 .Nm uni_decode_head ,
  41 .Nm uni_decode_body ,
  42 .Nm uni_decode_ie_hdr ,
  43 .Nm uni_decode_ie_body ,
  44 .Nm uni_encode ,
  45 .Nm uni_encode_msg_hdr ,
  46 .Nm uni_encode_ie ,
  47 .Nm uni_encode_ie_hdr ,
  48 .Nm uni_check_ie ,
  49 .Nm uni_print_cref ,
  50 .Nm uni_print_msghdr ,
  51 .Nm uni_print ,
  52 .Nm uni_print_ie ,
  53 .Nm uni_initcx ,
  54 .Nm uni_print_cx
  55 .Nd "ATM signalling library - message handling functions"
  56 .Sh LIBRARY
  57 Begemot ATM signalling library
  58 .Pq libngatm, -lngatm
  59 .Sh SYNOPSIS
  60 .In netnatm/msg/unistruct.h
  61 .In netnatm/msg/unimsglib.h
  62 .Ft int
  63 .Fn uni_decode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
  64 .Ft int
  65 .Fn uni_decode_head "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
  66 .Ft int
  67 .Fn uni_decode_body "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
  68 .Ft int
  69 .Fn uni_decode_ie_hdr "enum uni_ietype *type" "struct uni_iehdr *hdr" "struct uni_msg *buf" "struct unicx *cx" "u_int *ielen"
  70 .Ft int
  71 .Fn uni_decode_ie_body "enum uni_ietype type" "union uni_ieall *ie" "struct uni_msg *buf" "u_int ielen" "struct unicx *cx"
  72 .Ft int
  73 .Fn uni_encode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
  74 .Ft int
  75 .Fn uni_encode_msg_hdr "struct uni_msg *buf" "struct uni_msghdr *hdr" "enum uni_msgtype type" "struct unicx *cx" "int *mlen"
  76 .Ft int
  77 .Fn uni_encode_ie "enum uni_ietype type" "struct uni_msg *buf" "union uni_ieall *ie" "struct unicx *cx"
  78 .Ft int
  79 .Fn uni_encode_ie_hdr "struct uni_msg *buf" "enum uni_ietype type" "struct uni_iehdr *hdr" "u_int len" "struct unicx *cx"
  80 .Ft int
  81 .Fn uni_check_ie "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx"
  82 .Ft void
  83 .Fn uni_print_cref "char *buf" "size_t buflen" "struct uni_cref *cref" "struct unicx *cx"
  84 .Ft void
  85 .Fn uni_print_msghdr "char *buf" "size_t buflen" "struct uni_msghdr *hdr" "struct unicx *cx"
  86 .Ft void
  87 .Fn uni_print "char *buf" "size_t buflen" "struct uni_all *msg" "struct unicx *cx"
  88 .Ft void
  89 .Fn uni_print_ie "char *buf" "size_t buflen" "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx"
  90 .Ft void
  91 .Fn uni_initcx "struct unicx *cx"
  92 .Ft void
  93 .Fn uni_print_cx "char *buf" "size_t buflen" "struct unicx *cx"
  94 .Sh DESCRIPTION
  95 The
  96 .Nm
  97 library handles UNI 4.0 messages.
  98 For each information element and message
  99 type the header files contain a structure definition.
 100 Additionally there
 101 are a number of help structures and a global context structure for some
 102 of the library functions.
 103 This document describes the functions that are
 104 used to handle messages.
 105 .Ss DECODING
 106 Decoding is the process of taking an octet stream containing a UNI message
 107 or IE, parsing it and filling in a message or IE structure.
 108 .Pp
 109 The function
 110 .Fn uni_decode
 111 takes a message buffer, interprets it as a UNI message and fills in the
 112 structure pointed to by
 113 .Fa msg .
 114 It also takes a context argument and may fill the error array in the context.
 115 It returns -1 if there is an error decoding the message header and
 116 -2 if there is an error decoding the message body.
 117 The function returns 0 on success.
 118 .Pp
 119 The process of decoding a message can be split up by calling
 120 .Fn uni_decode_head
 121 and
 122 .Fn uni_decode_body .
 123 The first of these functions decodes only the message header and the second
 124 one decodes only the information elements.
 125 .Fn uni_decode_head
 126 returns 0 if it could decode the message header
 127 and -1 if the message could not be decoded (bad protocol
 128 identifier, bad length or broken call reference).
 129 .Fn uni_decode_body
 130 return 0 on success and -1 for unknown message types or if any
 131 IE had an error.
 132 .Pp
 133 The function
 134 .Fn uni_decode_ie_hdr
 135 decodes the next information element header.
 136 It returns the IE type and its length
 137 in the variables pointed to by
 138 .Va type
 139 and
 140 .Va ielen
 141 and stores the decoded header in the structure pointed to by
 142 .Va hdr .
 143 The function returns 0 on success and -1 if there were not enough bytes
 144 in the buffer left for a complete IE header.
 145 .Pp
 146 The function
 147 .Fn uni_decode_ie_body
 148 decodes the body of an information element.
 149 It is passed the buffer with the message
 150 .Fa buf ,
 151 the information element type
 152 .Fa type
 153 and length
 154 .Fa ielen .
 155 The IE is stored in the union pointed to by
 156 .Fa ie .
 157 The function returns -1 on errors and 0 on success.
 158 In any case the most correct
 159 number of bytes is consumed from the input buffer.
 160 .Ss ENCODING
 161 Encoding is the process of taking a message or IE structure and producing
 162 an octet stream from it.
 163 .Pp
 164 The function
 165 .Fn uni_encode
 166 encodes a UNI message.
 167 It returns -1 if the message type is out of bounds, -3
 168 if the message type is unknown.
 169 The encoding functions for the message types
 170 can return their own error codes.
 171 The function returns 0 on success.
 172 .Pp
 173 The function
 174 .Fn uni_encode_msg_hdr
 175 encodes a message header.
 176 The variable pointed to by
 177 .Fa mlen
 178 is set to the offset of the message length field from the begin of the
 179 byte stream.
 180 This is needed because the length of the message body will
 181 be known only after all the IEs have been encoded.
 182 Then the length
 183 has to be inserted into this place.
 184 The function returns -1 if the call reference
 185 was bad and 0 on success.
 186 .Pp
 187 The function
 188 .Fn uni_encode_ie
 189 encodes one information element.
 190 The function returns 0 on success or -1
 191 on errors.
 192 The function
 193 .Fn uni_encode_ie_hdr
 194 encodes the four byte IE header.
 195 The argument
 196 .Fa len
 197 is the maximum expected length of the information element, not the real length.
 198 The function inserts a 0 in the real length field.
 199 This must be
 200 fixed up by the caller after encoding the IE contents.
 201 The function
 202 return -1 if an empty IE is to be encoded (in this case the length field will
 203 have been set to 4) or 0 otherwise.
 204 .Ss CHECKING
 205 There exists a number of function that do consistency checks on information
 206 elements.
 207 Note, that these functions do not check inter-IE consistency, but
 208 each IE by itself.
 209 .Pp
 210 The function
 211 .Fn uni_check_ie
 212 check an information element for consistency.
 213 It returns 0 if the IE seems
 214 ok, -1 otherwise.
 215 .Ss PRINTING
 216 A number of functions can be used to print decoded messages and IEs in
 217 a human readable form.
 218 This is intended mainly for debugging.
 219 Some fields of the library context are used to control how the printing is done
 220 (see
 221 .Xr unistruct 3 ) .
 222 Each of the function takes a
 223 .Fa buf
 224 and a
 225 .Fa buflen
 226 argument.
 227 The string that is generated in the buffer pointed to by
 228 .Fa buf
 229 is guaranteed to be NUL terminated.
 230 .Pp
 231 The function
 232 .Fn uni_print_cref
 233 formats a call reference taking into account special call references.
 234 The function
 235 .Fn uni_print_msg_hdr
 236 formats a message header.
 237 The functions
 238 .Fn uni_print
 239 and
 240 .Fn uni_print_ie
 241 print messages and information elements.
 242 .Ss CONTEXTS
 243 There are two functions for context handling.
 244 .Fn uni_initcx
 245 initializes a context with default values and
 246 .Fn uni_print_cx
 247 prints a context to the given buffer.
 248 .Sh SEE ALSO
 249 .Xr libngatm 3
 250 .Sh STANDARDS
 251 This implementation conforms to the applicable ITU-T
 252 recommendations and ATM Forum standards with the exception of some limitations
 253 (see the Configuration section).
 254 .Sh AUTHORS
 255 .An Hartmut Brandt Aq harti@FreeBSD.org