contrib/ngatm/man/unistruct.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/unistruct.3,v 1.5 2005/06/15 11:37:12 brandt_h Exp $
  33 .\"
  34 .Dd May 23, 2005
  35 .Dt UNISTRUCT 3
  36 .Os
  37 .Sh NAME
  38 .Nm libngatm
  39 .Nd "ATM signalling library"
  40 .Sh LIBRARY
  41 Begemot ATM signalling library
  42 .Pq libngatm, -lngatm
  43 .Sh SYNOPSIS
  44 .In netnatm/msg/unistruct.h
  45 .In netnatm/msg/unimsglib.h
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 library handles UNI 4.0 messages.
  50 For each information element and message
  51 type the header files contain a structure definition.
  52 Additionally there
  53 are a number of help structures and a global context structure for some
  54 of the library functions.
  55 This document only describes the common structures.
  56 For information element and message structures see the header files.
  57 .Ss LIBRARY CONFIGURATION
  58 When the library is compiled a number of constants are define in the file
  59 .Pa uni_config.h .
  60 They define certain limits.
  61 Because of the use of these definitions a change
  62 in any of them requires a complete recompilation of all library code and
  63 all code that uses the library.
  64 The following constants are defined (they
  65 value behind the name is the default value):
  66 .Bl -tag -width XXXX
  67 .It Dv UNI_MAX_ERRIE ( Li 50 )
  68 When decoding information elements and analyzing them the library fills
  69 an array in the context with the identifiers of IEs that had errors.
  70 This is the size of this array.
  71 .It Dv UNI_NUM_IE_GIT ( Li 3 )
  72 A message is allowed to contain more than one General Identifier Transport
  73 information element.
  74 This is the maximum supported number of these IEs.
  75 .It Dv UNI_NUM_IE_BLLI ( Li 3 )
  76 The maximum number of BLLI information elements in a SETUP message.
  77 .It Dv UNI_NUM_IE_CALLEDSUB ( Li 2 )
  78 The maximum number of Called Subaddress information elements in a SETUP message.
  79 .It Dv UNI_NUM_IE_CALLINGSUB ( Li 2 )
  80 The maximum number of Calling Subaddress information elements in a SETUP
  81 message.
  82 .It Dv UNI_NUM_IE_TNS ( Li 4 )
  83 The maximum number of Transit Network Selection information elements in a SETUP
  84 message.
  85 .It Dv UNI_TNS_MAXLEN ( Li 4 )
  86 The maximum size of a name in the TNS IE.
  87 .It Dv UNI_UU_MAXLEN ( Li 128 )
  88 Maximum size of user data in the UU IE.
  89 .It Dv UNI_ADDR_MAXLEN ( Li 20 )
  90 Maximum address size.
  91 .It Dv UNI_SUBADDR_MAXLEN ( Li 20 )
  92 Maximum subaddress size.
  93 .It Dv UNI_NUM_IE_DTL ( Li 10 )
  94 Maximum number of DTL information elements in a SETUP message.
  95 .It Dv UNI_DTL_MAXNUM ( Li 20 )
  96 Maximum number of identifiers in one DTL information element.
  97 .El
  98 .Ss INFORMATION ELEMENTS
  99 Each information element structure starts with a field of type:
 100 .Bd -literal -offset indent
 101 struct uni_iehdr {
 102         enum uni_coding coding; /* coding standard */
 103         enum uni_ieact  act;    /* action indicator */
 104         u_int           pass:1; /* PNNI pass along request */
 105         u_int           present;/* which optional elements are present */
 106 };
 107 .Ed
 108 .Pp
 109 The
 110 .Fa coding
 111 field is the coding standard of the information element and may be one of
 112 .Dv UNI_CODING_ITU
 113 or
 114 .Dv UNI_CODING_NET .
 115 The action indicator
 116 .Fa act
 117 is used for error processing and is one of:
 118 .Bl -tag -width XXXX
 119 .It Dv UNI_IEACT_CLEAR
 120 clear call
 121 .It Dv UNI_IEACT_IGNORE
 122 ignore IE and proceed
 123 .It Dv UNI_IEACT_REPORT
 124 ignore IE, report and proceed
 125 .It Dv UNI_IEACT_MSG_IGNORE
 126 ignore message
 127 .It Dv UNI_IEACT_MSG_REPORT
 128 ignore message and report
 129 .It Dv UNI_IEACT_DEFAULT
 130 the use action indicator flag was not set.
 131 .El
 132 .Pp
 133 For information elements in PNNI message the
 134 .Fa pass
 135 fields contains the pass along flag from the IE header.
 136 .Pp
 137 The
 138 .Fa present
 139 field is a bit field, which contains four common bits describing the current
 140 state of the information element.
 141 The rest of the bits are used by the
 142 information elements to indicate which of the optional fields of the IE are
 143 present.
 144 Most of the IE header files contain definitions for those bits.
 145 The common bits are:
 146 .Bd -literal -offset indent
 147 #define UNI_IE_EMPTY    0x80000000
 148 #define UNI_IE_PRESENT  0x40000000
 149 #define UNI_IE_ERROR    0x20000000
 150 #define UNI_IE_XXX      0x10000000
 151 .Ed
 152 .Pp
 153 The flag
 154 .Dv UNI_IE_EMPTY
 155 indicates that the information element is present, but empty (its length is
 156 zero).
 157 This is legal for all information elements.
 158 The flag
 159 .Dv UNI_IE_PRESENT
 160 indicates that the IE is present in the message and the flag
 161 .Dv UNI_IE_ERROR
 162 indicates that the IE had an error.
 163 The flag
 164 .Dv UNI_IE_XXX
 165 is currently not used.
 166 .Pp
 167 The following macros may be used to test or change these flags:
 168 .Bl -tag -width XXXX
 169 .It Dv IE_ISPRESENT
 170 Check whether the IE is present and not empty.
 171 Returns true in this case.
 172 .It Dv IE_SETPRESENT
 173 Set the IE to be present and not empty.
 174 .It Dv IE_ISEMPTY
 175 Check whether the IE is present and empty.
 176 Returns true in this case.
 177 .It Dv IE_SETEMPTY
 178 Set the IE to be present and empty.
 179 .It Dv IE_ISERROR
 180 Check whether the IE is present and has an error.
 181 Returns true in this case.
 182 .It Dv IE_SETERROR
 183 Sets the IE to be present and to have an error.
 184 .It Dv IE_ISGOOD
 185 Checks whether the IE is present, not empty and without error.
 186 Returns true in this case.
 187 .El
 188 .Pp
 189 For each IE type there is an
 190 .Vt enum uni_ietype
 191 definition of the form
 192 .Dv UNI_IE_*
 193 in
 194 .Pa uni_hdr.h .
 195 .Pp
 196 .Pa unistruct.h
 197 contains a
 198 .Vt union uni_ieall
 199 that is the union of all IE structures and a
 200 .Bd -literal -offset indent
 201 struct uni_ie {
 202         enum uni_ietype         ietype;
 203         union uni_ieall         u;
 204 };
 205 .Ed
 206 .Ss MESSAGES
 207 Each message structure starts with a
 208 .Bd -literal -offset indent
 209 struct uni_msghdr {
 210         struct uni_cref cref;
 211         enum uni_msgact act;    /* action indicator */
 212         u_int           pass:1; /* PNNI pass along request */
 213 };
 214 .Ed
 215 .Pp
 216 The
 217 .Fa cref
 218 is the call reference:
 219 .Bd -literal -offset indent
 220 struct uni_cref {
 221         u_int   flag;
 222         u_int   cref;
 223 };
 224 .Ed
 225 .Pp
 226 There are two special call references:
 227 .Dv CREF_GLOBAL
 228 and
 229 .Dv CREF_DUMMY .
 230 The
 231 .Fa act
 232 field is the message action indicator and has one of the following values:
 233 .Bl -tag -width XXXX
 234 .It Dv UNI_MSGACT_CLEAR
 235 clear call
 236 .It Dv UNI_MSGACT_IGNORE
 237 ignore message
 238 .It Dv UNI_MSGACT_REPORT
 239 send STATUS message
 240 .It Dv UNI_MSGACT_DEFAULT
 241 default handling for this message type
 242 .El
 243 .Pp
 244 The
 245 .Fa pass
 246 field is the pass along indicator in the case of PNNI messages.
 247 .Pp
 248 For each message type there is a
 249 .Vt enum uni_msgtype
 250 definition of the form
 251 .Dv UNI_*
 252 in
 253 .Pa uni_hdr.h .
 254 .Pa uni_struct.h
 255 contains a
 256 .Vt union_msgall
 257 that is the union of all message structures and a
 258 .Bd -literal -offset indent
 259 struct uni_all {
 260         enum uni_msgtype        mtype;
 261         union uni_msgall        u;
 262 };
 263 .Ed
 264 .Ss CONTEXTS
 265 The header file
 266 .Pa unimsglib.h
 267 contains a definition of a
 268 .Vt struct uni_context
 269 that is used to minimize the number of arguments passed to certain functions
 270 and to avoid the use of global variables.
 271 This structure has the following
 272 public fields (all other fields are used internally by the library):
 273 .Bl -tag -width XXXX
 274 .It Fa err
 275 This is an array consisting of the following structures:
 276 .Bd -literal -offset indent
 277 struct uni_ierr {
 278         enum uni_ierr_type err; /* what error */
 279         enum uni_ieact  act;    /* the action indicator */
 280         u_int           ie:8;   /* the ie type */
 281         u_int           man:1;  /* mandatory flag */
 282         u_int           epref:1;/* Q.2971 9.5.3.2.1 low-pri epref */
 283 };
 284 .Ed
 285 When decoding information elements the information about IEs with errors is
 286 stuffed into this array.
 287 .It Fa errcnt
 288 The current number of IEs in
 289 .Fa err .
 290 .It Fa q2932
 291 Enable the Q.2932.1 Generic Functional Protocol.
 292 Currently only message
 293 and IE decoding/encoding is supported.
 294 The signalling part is still missing.
 295 .It Fa pnni
 296 Enable PNNI extensions.
 297 Currently only message and IE decoding/encoding
 298 is supported.
 299 The signalling part is still missing.
 300 .It Fa git_hard
 301 Do hard checking on GIT information elements.
 302 .It Fa bearer_hard
 303 Do hard checking on Broadband Bearer IEs.
 304 This involves rejecting old bearer
 305 type values.
 306 .It Fa cause_hard
 307 Do hard checking on Cause information elements.
 308 .It Fa multiline
 309 This is used by the printing routines.
 310 Legal values are 0 to 4 and give
 311 different kinds of printout.
 312 .It Fa tabsiz
 313 The size of tabulation to use in printing.
 314 4 is a good value.
 315 .El
 316 .Sh SEE ALSO
 317 .Xr libunimsg 3
 318 .Sh STANDARDS
 319 This implementation conforms to the applicable ITU-T
 320 recommendations and ATM Forum standards with the exception of some limitations
 321 (see the Configuration section).
 322 .Sh AUTHORS
 323 .An Hartmut Brandt Aq harti@FreeBSD.org