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
57Begemot 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
95The
96.Nm
97library handles UNI 4.0 messages.
98For each information element and message
99type the header files contain a structure definition.
100Additionally there
101are a number of help structures and a global context structure for some
102of the library functions.
103This document describes the functions that are
104used to handle messages.
105.Ss DECODING
106Decoding is the process of taking an octet stream containing a UNI message
107or IE, parsing it and filling in a message or IE structure.
108.Pp
109The function
110.Fn uni_decode
111takes a message buffer, interprets it as a UNI message and fills in the
112structure pointed to by
113.Fa msg .
114It also takes a context argument and may fill the error array in the context.
115It returns -1 if there is an error decoding the message header and
116-2 if there is an error decoding the message body.
117The function returns 0 on success.
118.Pp
119The process of decoding a message can be split up by calling
120.Fn uni_decode_head
121and
122.Fn uni_decode_body .
123The first of these functions decodes only the message header and the second
124one decodes only the information elements.
125.Fn uni_decode_head
126returns 0 if it could decode the message header
127and -1 if the message could not be decoded (bad protocol
128identifier, bad length or broken call reference).
129.Fn uni_decode_body
130return 0 on success and -1 for unknown message types or if any
131IE had an error.
132.Pp
133The function
134.Fn uni_decode_ie_hdr
135decodes the next information element header.
136It returns the IE type and its length
137in the variables pointed to by
138.Va type
139and
140.Va ielen
141and stores the decoded header in the structure pointed to by
142.Va hdr .
143The function returns 0 on success and -1 if there were not enough bytes
144in the buffer left for a complete IE header.
145.Pp
146The function
147.Fn uni_decode_ie_body
148decodes the body of an information element.
149It is passed the buffer with the message
150.Fa buf ,
151the information element type
152.Fa type
153and length
154.Fa ielen .
155The IE is stored in the union pointed to by
156.Fa ie .
157The function returns -1 on errors and 0 on success.
158In any case the most correct
159number of bytes is consumed from the input buffer.
160.Ss ENCODING
161Encoding is the process of taking a message or IE structure and producing
162an octet stream from it.
163.Pp
164The function
165.Fn uni_encode
166encodes a UNI message.
167It returns -1 if the message type is out of bounds, -3
168if the message type is unknown.
169The encoding functions for the message types
170can return their own error codes.
171The function returns 0 on success.
172.Pp
173The function
174.Fn uni_encode_msg_hdr
175encodes a message header.
176The variable pointed to by
177.Fa mlen
178is set to the offset of the message length field from the begin of the
179byte stream.
180This is needed because the length of the message body will
181be known only after all the IEs have been encoded.
182Then the length
183has to be inserted into this place.
184The function returns -1 if the call reference
185was bad and 0 on success.
186.Pp
187The function
188.Fn uni_encode_ie
189encodes one information element.
190The function returns 0 on success or -1
191on errors.
192The function
193.Fn uni_encode_ie_hdr
194encodes the four byte IE header.
195The argument
196.Fa len
197is the maximum expected length of the information element, not the real length.
198The function inserts a 0 in the real length field.
199This must be
200fixed up by the caller after encoding the IE contents.
201The function
202return -1 if an empty IE is to be encoded (in this case the length field will
203have been set to 4) or 0 otherwise.
204.Ss CHECKING
205There exists a number of function that do consistency checks on information
206elements.
207Note, that these functions do not check inter-IE consistency, but
208each IE by itself.
209.Pp
210The function
211.Fn uni_check_ie
212check an information element for consistency.
213It returns 0 if the IE seems
214ok, -1 otherwise.
215.Ss PRINTING
216A number of functions can be used to print decoded messages and IEs in
217a human readable form.
218This is intended mainly for debugging.
219Some fields of the library context are used to control how the printing is done
220(see
221.Xr unistruct 3 ) .
222Each of the function takes a
223.Fa buf
224and a
225.Fa buflen
226argument.
227The string that is generated in the buffer pointed to by
228.Fa buf
229is guaranteed to be NUL terminated.
230.Pp
231The function
232.Fn uni_print_cref
233formats a call reference taking into account special call references.
234The function
235.Fn uni_print_msg_hdr
236formats a message header.
237The functions
238.Fn uni_print
239and
240.Fn uni_print_ie
241print messages and information elements.
242.Ss CONTEXTS
243There are two functions for context handling.
244.Fn uni_initcx
245initializes a context with default values and
246.Fn uni_print_cx
247prints a context to the given buffer.
248.Sh SEE ALSO
249.Xr libngatm 3
250.Sh STANDARDS
251This implementation conforms to the applicable ITU-T
252recommendations and ATM Forum standards with the exception of some limitations
253(see the Configuration section).
254.Sh AUTHORS
| 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
57Begemot 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
95The
96.Nm
97library handles UNI 4.0 messages.
98For each information element and message
99type the header files contain a structure definition.
100Additionally there
101are a number of help structures and a global context structure for some
102of the library functions.
103This document describes the functions that are
104used to handle messages.
105.Ss DECODING
106Decoding is the process of taking an octet stream containing a UNI message
107or IE, parsing it and filling in a message or IE structure.
108.Pp
109The function
110.Fn uni_decode
111takes a message buffer, interprets it as a UNI message and fills in the
112structure pointed to by
113.Fa msg .
114It also takes a context argument and may fill the error array in the context.
115It returns -1 if there is an error decoding the message header and
116-2 if there is an error decoding the message body.
117The function returns 0 on success.
118.Pp
119The process of decoding a message can be split up by calling
120.Fn uni_decode_head
121and
122.Fn uni_decode_body .
123The first of these functions decodes only the message header and the second
124one decodes only the information elements.
125.Fn uni_decode_head
126returns 0 if it could decode the message header
127and -1 if the message could not be decoded (bad protocol
128identifier, bad length or broken call reference).
129.Fn uni_decode_body
130return 0 on success and -1 for unknown message types or if any
131IE had an error.
132.Pp
133The function
134.Fn uni_decode_ie_hdr
135decodes the next information element header.
136It returns the IE type and its length
137in the variables pointed to by
138.Va type
139and
140.Va ielen
141and stores the decoded header in the structure pointed to by
142.Va hdr .
143The function returns 0 on success and -1 if there were not enough bytes
144in the buffer left for a complete IE header.
145.Pp
146The function
147.Fn uni_decode_ie_body
148decodes the body of an information element.
149It is passed the buffer with the message
150.Fa buf ,
151the information element type
152.Fa type
153and length
154.Fa ielen .
155The IE is stored in the union pointed to by
156.Fa ie .
157The function returns -1 on errors and 0 on success.
158In any case the most correct
159number of bytes is consumed from the input buffer.
160.Ss ENCODING
161Encoding is the process of taking a message or IE structure and producing
162an octet stream from it.
163.Pp
164The function
165.Fn uni_encode
166encodes a UNI message.
167It returns -1 if the message type is out of bounds, -3
168if the message type is unknown.
169The encoding functions for the message types
170can return their own error codes.
171The function returns 0 on success.
172.Pp
173The function
174.Fn uni_encode_msg_hdr
175encodes a message header.
176The variable pointed to by
177.Fa mlen
178is set to the offset of the message length field from the begin of the
179byte stream.
180This is needed because the length of the message body will
181be known only after all the IEs have been encoded.
182Then the length
183has to be inserted into this place.
184The function returns -1 if the call reference
185was bad and 0 on success.
186.Pp
187The function
188.Fn uni_encode_ie
189encodes one information element.
190The function returns 0 on success or -1
191on errors.
192The function
193.Fn uni_encode_ie_hdr
194encodes the four byte IE header.
195The argument
196.Fa len
197is the maximum expected length of the information element, not the real length.
198The function inserts a 0 in the real length field.
199This must be
200fixed up by the caller after encoding the IE contents.
201The function
202return -1 if an empty IE is to be encoded (in this case the length field will
203have been set to 4) or 0 otherwise.
204.Ss CHECKING
205There exists a number of function that do consistency checks on information
206elements.
207Note, that these functions do not check inter-IE consistency, but
208each IE by itself.
209.Pp
210The function
211.Fn uni_check_ie
212check an information element for consistency.
213It returns 0 if the IE seems
214ok, -1 otherwise.
215.Ss PRINTING
216A number of functions can be used to print decoded messages and IEs in
217a human readable form.
218This is intended mainly for debugging.
219Some fields of the library context are used to control how the printing is done
220(see
221.Xr unistruct 3 ) .
222Each of the function takes a
223.Fa buf
224and a
225.Fa buflen
226argument.
227The string that is generated in the buffer pointed to by
228.Fa buf
229is guaranteed to be NUL terminated.
230.Pp
231The function
232.Fn uni_print_cref
233formats a call reference taking into account special call references.
234The function
235.Fn uni_print_msg_hdr
236formats a message header.
237The functions
238.Fn uni_print
239and
240.Fn uni_print_ie
241print messages and information elements.
242.Ss CONTEXTS
243There are two functions for context handling.
244.Fn uni_initcx
245initializes a context with default values and
246.Fn uni_print_cx
247prints a context to the given buffer.
248.Sh SEE ALSO
249.Xr libngatm 3
250.Sh STANDARDS
251This implementation conforms to the applicable ITU-T
252recommendations and ATM Forum standards with the exception of some limitations
253(see the Configuration section).
254.Sh AUTHORS
|