aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/ngatm/man/unifunc.3
blob: 093d0c8979bc7f076d83b08d3da946336f8162a7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
.\"
.\" Copyright (c) 2001-2003
.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
.\" 	All rights reserved.
.\"
.\" Author: Hartmut Brandt <harti@freebsd.org>
.\"
.\" 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.
.\"
.\" $Begemot: libunimsg/man/unifunc.3,v 1.3 2004/07/08 08:21:43 brandt 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