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