2 .\" Copyright (c) 2004-2005
4 .\" All rights reserved.
5 .\" Copyright (c) 2001-2003
6 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7 .\" All rights reserved.
9 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" $Begemot: libunimsg/man/unifunc.3,v 1.6 2005/06/15 11:37:09 brandt_h Exp $
42 .Nm uni_decode_ie_hdr ,
43 .Nm uni_decode_ie_body ,
45 .Nm uni_encode_msg_hdr ,
47 .Nm uni_encode_ie_hdr ,
50 .Nm uni_print_msghdr ,
55 .Nd "ATM signalling library - message handling functions"
57 Begemot ATM signalling library
60 .In netnatm/msg/unistruct.h
61 .In netnatm/msg/unimsglib.h
63 .Fn uni_decode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
65 .Fn uni_decode_head "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
67 .Fn uni_decode_body "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
69 .Fn uni_decode_ie_hdr "enum uni_ietype *type" "struct uni_iehdr *hdr" "struct uni_msg *buf" "struct unicx *cx" "u_int *ielen"
71 .Fn uni_decode_ie_body "enum uni_ietype type" "union uni_ieall *ie" "struct uni_msg *buf" "u_int ielen" "struct unicx *cx"
73 .Fn uni_encode "struct uni_msg *buf" "struct uni_all *msg" "struct unicx *cx"
75 .Fn uni_encode_msg_hdr "struct uni_msg *buf" "struct uni_msghdr *hdr" "enum uni_msgtype type" "struct unicx *cx" "int *mlen"
77 .Fn uni_encode_ie "enum uni_ietype type" "struct uni_msg *buf" "union uni_ieall *ie" "struct unicx *cx"
79 .Fn uni_encode_ie_hdr "struct uni_msg *buf" "enum uni_ietype type" "struct uni_iehdr *hdr" "u_int len" "struct unicx *cx"
81 .Fn uni_check_ie "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx"
83 .Fn uni_print_cref "char *buf" "size_t buflen" "struct uni_cref *cref" "struct unicx *cx"
85 .Fn uni_print_msghdr "char *buf" "size_t buflen" "struct uni_msghdr *hdr" "struct unicx *cx"
87 .Fn uni_print "char *buf" "size_t buflen" "struct uni_all *msg" "struct unicx *cx"
89 .Fn uni_print_ie "char *buf" "size_t buflen" "enum uni_ietype type" "union uni_ieall *ie" "struct unicx *cx"
91 .Fn uni_initcx "struct unicx *cx"
93 .Fn uni_print_cx "char *buf" "size_t buflen" "struct unicx *cx"
97 library handles UNI 4.0 messages.
98 For each information element and message
99 type the header files contain a structure definition.
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.
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.
111 takes a message buffer, interprets it as a UNI message and fills in the
112 structure pointed to by
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.
119 The process of decoding a message can be split up by calling
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.
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).
130 return 0 on success and -1 for unknown message types or if any
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
141 and stores the decoded header in the structure pointed to by
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.
147 .Fn uni_decode_ie_body
148 decodes the body of an information element.
149 It is passed the buffer with the message
151 the information element type
155 The IE is stored in the union pointed to by
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.
161 Encoding is the process of taking a message or IE structure and producing
162 an octet stream from it.
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.
174 .Fn uni_encode_msg_hdr
175 encodes a message header.
176 The variable pointed to by
178 is set to the offset of the message length field from the begin of the
180 This is needed because the length of the message body will
181 be known only after all the IEs have been encoded.
183 has to be inserted into this place.
184 The function returns -1 if the call reference
185 was bad and 0 on success.
189 encodes one information element.
190 The function returns 0 on success or -1
193 .Fn uni_encode_ie_hdr
194 encodes the four byte IE header.
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.
200 fixed up by the caller after encoding the IE contents.
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.
205 There exists a number of function that do consistency checks on information
207 Note, that these functions do not check inter-IE consistency, but
212 check an information element for consistency.
213 It returns 0 if the IE seems
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
222 Each of the function takes a
227 The string that is generated in the buffer pointed to by
229 is guaranteed to be NUL terminated.
233 formats a call reference taking into account special call references.
235 .Fn uni_print_msg_hdr
236 formats a message header.
241 print messages and information elements.
243 There are two functions for context handling.
245 initializes a context with default values and
247 prints a context to the given buffer.
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).
255 .An Hartmut Brandt Aq harti@FreeBSD.org