Blame - doc/asn1c-usage.html - asn1c

blob: ded6c758337d3c4e522d2acbd8a22672d20e4806 [file] [log] [blame]

vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1
				2	<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
				3	original version by: Nikos Drakos, CBLU, University of Leeds
				4	* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
				5	* with significant contributions from:
				6	Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
				7	<HTML>
				8	<HEAD>
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	9	<TITLE>Using the Open ASN.1 Compiler</TITLE>
				10	<META NAME="description" CONTENT="Using the Open ASN.1 Compiler">
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	11	<META NAME="asn1c, ASN.1, free, compiler, BER, DER, PER, XER\">
				12
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	13
				14
				15	</HEAD>
				16
				17	<BODY >
				18
				19	<P>
				20
				21	<P>
				22
				23	<P>
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	24	<H1 ALIGN="CENTER">Using the Open ASN.1 Compiler</H1><DIV>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	25
				26	<P ALIGN="CENTER"><STRONG>Lev Walkin <vlm@lionet.info></STRONG></P>
				27	</DIV>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	28	<!-- MATH
				29	$Revision$
				30	-->
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	31
				32	<P>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	33	<BR>
				34
				35	<H2><A NAME="SECTION01000000000000000000">
				36	Contents</A>
				37	</H2>
				38	<!--Table of Contents-->
				39
				40	<UL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	41	<LI><A NAME="tex2html46"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	42	HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A>
				43	<UL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	44	<LI><A NAME="tex2html47"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	45	HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A>
				46	<UL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	47	<LI><A NAME="tex2html48"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	48	HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A>
				49	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	50	<LI><A NAME="tex2html49"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	51	HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	52	<LI><A NAME="tex2html50"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	53	HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	54	<LI><A NAME="tex2html51"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	55	HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	56	<LI><A NAME="tex2html52"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	57	HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	58	<LI><A NAME="tex2html53"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	59	HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
				60	<LI><A NAME="tex2html54"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	61	HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A>
				62	</UL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	63	<LI><A NAME="tex2html55"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	64	HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A>
				65	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	66	<LI><A NAME="tex2html56"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	67	HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	68	<LI><A NAME="tex2html57"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	69	HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	70	<LI><A NAME="tex2html58"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	71	HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	72	<LI><A NAME="tex2html59"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	73	HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
				74	<LI><A NAME="tex2html60"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	75	HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A>
				76	</UL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	77	<LI><A NAME="tex2html61"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	78	HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A>
				79	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	80	<LI><A NAME="tex2html62"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	81	HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	82	<LI><A NAME="tex2html63"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	83	HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	84	<LI><A NAME="tex2html64"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	85	HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	86	<LI><A NAME="tex2html65"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	87	HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
				88	<LI><A NAME="tex2html66"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	89	HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A>
				90	</UL>
				91	</UL>
				92	</UL><BR>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	93	<LI><A NAME="tex2html67"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	94	HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A>
				95	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	96	<LI><A NAME="tex2html68"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	97	HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	98	<LI><A NAME="tex2html69"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	99	HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A>
				100	<LI><A NAME="tex2html70"
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	101	HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	102	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	103	<LI><A NAME="tex2html71"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	104	HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	105	<LI><A NAME="tex2html72"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	106	HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A>
				107	<LI><A NAME="tex2html73"
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	108	HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from the application</A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	109	<UL>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	110	<LI><A NAME="tex2html74"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	111	HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	112	<LI><A NAME="tex2html75"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	113	HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	114	<LI><A NAME="tex2html76"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	115	HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	116	<LI><A NAME="tex2html77"
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	117	HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A>
				118	<LI><A NAME="tex2html78"
				119	HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A>
				120	<LI><A NAME="tex2html79"
				121	HREF="asn1c-usage.html#SECTION03336000000000000000">Freeing the target structure</A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	122	</UL>
				123	</UL>
				124	</UL><BR>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	125	<LI><A NAME="tex2html80"
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	126	HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
				127	</UL>
				128	<!--End of Table of Contents-->
				129
				130	<P>
				131
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	132	<P>
				133
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	134	<H1><A NAME="SECTION02000000000000000000">
				135	ASN.1 Basics</A>
				136	</H1>
				137
				138	<P>
				139
				140	<H1><A NAME="SECTION02100000000000000000">
				141	Abstract Syntax Notation: ASN.1</A>
				142	</H1>
				143
				144	<P>
				145	<I>This chapter defines some basic ASN.1 concepts and describes
				146	several most widely used types. It is by no means an authoritative
				147	or complete reference. For more complete ASN.1 description, please
				148	refer to Olivier Dubuisson's book [<A
				149	HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
				150	of standards itself [<A
				151	HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
				152
				153	<P>
				154	The Abstract Syntax Notation One is used to formally describe the
				155	semantics of data transmitted across the network. Two communicating
				156	parties may have different formats of their native data types (i.e.
				157	number of bits in the integer type), thus it is important to have
				158	a way to describe the data in a manner which is independent from the
				159	particular machine's representation. The ASN.1 specifications is used
				160	to achieve one or more of the following:
				161
				162	<P>
				163
				164	<UL>
				165	<LI>The specification expressed in the ASN.1 notation is a formal and
				166	precise way to communicate the data semantics to human readers;
				167	</LI>
				168	<LI>The ASN.1 specifications may be used as input for automatic compilers
				169	which produce the code for some target language (C, C++, Java, etc)
				170	to encode and decode the data according to some encoding rules (which
				171	are also defined by the ASN.1 standard).
				172	</LI>
				173	</UL>
				174	Consider the following example:
				175
				176	<P>
				177
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	178	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	179	Rectangle ::= SEQUENCE {
				180	height  INTEGER,
				181	width   INTEGER
				182	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	183	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	184	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	185	This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
				186	containing two integer fields. This specification may tell the reader
				187	that there is this kind of data structure and that some entity may
				188	be prepared to send or receive it. The question on <I>how</I> that
				189	entity is going to send or receive the <I>encoded data</I> is outside
				190	the scope of ASN.1. For example, this data structure may be encoded
				191	according to some encoding rules and sent to the destination using
				192	the TCP protocol. The ASN.1 specifies several ways of encoding (or
				193	''serializing'', or ''marshaling'') the data: BER, CER, DER and
				194	XER, some of them which will be described later.
				195
				196	<P>
				197	The complete specification must be wrapped in a module, which looks
				198	like this:
				199
				200	<P>
				201
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	202	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	203	UsageExampleModule1
				204	{ iso org(3) dod(6) internet(1) private(4)
				205	enterprise(1) spelio(9363) software(1)
				206	asn1c(5) docs(2) usage(1) 1 }
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	207	DEFINITIONS AUTOMATIC TAGS ::=
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	208	BEGIN
				209
				210	-- This is a comment which describes nothing.
				211	Rectangle ::= SEQUENCE {
				212	height  INTEGER,        -- Height of the rectangle
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	213	width   INTEGER         -- Width of the rectangle
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	214	}
				215
				216	END
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	217	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	218	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	219	The module header consists of module name (UsageExampleModule1), the
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	220	module object identifier ({...}), a keyword ''DEFINITIONS'', a
				221	set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
				222	ends with an ''END'' statement.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	223
				224	<P>
				225
				226	<H1><A NAME="SECTION02110000000000000000">
				227	Some of the ASN.1 Basic Types</A>
				228	</H1>
				229
				230	<P>
				231
				232	<H2><A NAME="SECTION02111000000000000000">
				233	The BOOLEAN type</A>
				234	</H2>
				235
				236	<P>
				237	The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
				238	or a similar kind of two-way choice.
				239
				240	<P>
				241
				242	<H2><A NAME="SECTION02112000000000000000">
				243	The INTEGER type</A>
				244	</H2>
				245
				246	<P>
				247	The INTEGER type is a signed natural number type without any restrictions
				248	on its size. If the automatic checking on INTEGER value bounds are
				249	necessary, the subtype constraints must be used.
				250
				251	<P>
				252
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	253	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	254	SimpleInteger ::= INTEGER
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	255
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	256	-- An integer with a very limited range
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	257	SmallPositiveInt ::= INTEGER (0..127)
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	258
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	259	-- Integer, negative
				260	NegativeInt ::= INTEGER (MIN..0)
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	261	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	262	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	263
				264	<P>
				265
				266	<H2><A NAME="SECTION02113000000000000000">
				267	The ENUMERATED type</A>
				268	</H2>
				269
				270	<P>
				271	The ENUMERATED type is semantically equivalent to the INTEGER type
				272	with some integer values explicitly named.
				273
				274	<P>
				275
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	276	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	277	FruitId ::= ENUMERATED { apple(1), orange(2) }
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	278
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	279	-- The numbers in braces are optional,
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	280	-- the enumeration can be performed
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	281	-- automatically by the compiler
				282	ComputerOSType ::= ENUMERATED {
				283	FreeBSD,          -- will be 0
				284	Windows,          -- will be 1
				285	Solaris(5),       -- will remain 5
				286	Linux,            -- will be 6
				287	MacOS             -- will be 7
				288	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	289	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	290	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	291
				292	<P>
				293
				294	<H2><A NAME="SECTION02114000000000000000">
				295	The OCTET STRING type</A>
				296	</H2>
				297
				298	<P>
				299	This type models the sequence of 8-bit bytes. This may be used to
				300	transmit some opaque data or data serialized by other types of encoders
				301	(i.e. video file, photo picture, etc).
				302
				303	<P>
				304
				305	<H2><A NAME="SECTION02115000000000000000">
				306	The OBJECT IDENTIFIER type</A>
				307	</H2>
				308
				309	<P>
				310	The OBJECT IDENTIFIER is used to represent the unique identifier of
				311	any object, starting from the very root of the registration tree.
				312	If your organization needs to uniquely identify something (a router,
				313	a room, a person, a standard, or whatever), you are encouraged to
				314	get your own identification subtree at http://www.iana.org/protocols/forms.htm.
				315
				316	<P>
				317	For example, the very first ASN.1 module in this document has the
				318	following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
				319
				320	<P>
				321
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	322	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	323	ExampleOID ::= OBJECT IDENTIFIER
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	324
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	325	usageExampleModule1-oid ExampleOID
				326	::= { 1 3 6 1 4 1 9363 1 5 2 1 1 }
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	327
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	328	-- An identifier of the Internet.
				329	internet-id OBJECT IDENTIFIER
				330	::= { iso(1) identified-organization(3)
				331	dod(6) internet(1) }
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	332	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	333	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	334	As you see, names are optional.
				335
				336	<P>
				337
				338	<H2><A NAME="SECTION02116000000000000000">
				339	The RELATIVE-OID type</A>
				340	</H2>
				341
				342	<P>
				343	The RELATIVE-OID type has the semantics of a subtree of an OBJECT
				344	IDENTIFIER. There may be no need to repeat the whole sequence of numbers
				345	from the root of the registration tree where the only thing of interest
				346	is some of the tree's subsequence.
				347
				348	<P>
				349
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	350	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	351	this-document RELATIVE-OID ::= { docs(2) usage(1) }
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	352
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	353	this-example RELATIVE-OID ::= {
				354	this-document assorted-examples(0) this-example(1) }
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	355	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	356	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	357
				358	<P>
				359
				360	<H1><A NAME="SECTION02120000000000000000">
				361	Some of the ASN.1 String Types</A>
				362	</H1>
				363
				364	<P>
				365
				366	<H2><A NAME="SECTION02121000000000000000">
				367	The IA5String type</A>
				368	</H2>
				369
				370	<P>
				371	This is essentially the ASCII, with 128 character codes available
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	372	(7 lower bits of an 8-bit byte).
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	373
				374	<P>
				375
				376	<H2><A NAME="SECTION02122000000000000000">
				377	The UTF8String type</A>
				378	</H2>
				379
				380	<P>
				381	This is the character string which encodes the full Unicode range
				382	(4 bytes) using multibyte character sequences.
				383
				384	<P>
				385
				386	<H2><A NAME="SECTION02123000000000000000">
				387	The NumericString type</A>
				388	</H2>
				389
				390	<P>
				391	This type represents the character string with the alphabet consisting
				392	of numbers (''0'' to ''9'') and a space.
				393
				394	<P>
				395
				396	<H2><A NAME="SECTION02124000000000000000">
				397	The PrintableString type</A>
				398	</H2>
				399
				400	<P>
				401	The character string with the following alphabet: space, ''<B>'</B>''
				402	(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	403	''<B>,</B>'' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	404	digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
				405	upper-case and lower-case letters (''A'' to ''Z'' and ''a''
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	406	to ''z'').
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	407
				408	<P>
				409
				410	<H2><A NAME="SECTION02125000000000000000">
				411	The VisibleString type</A>
				412	</H2>
				413
				414	<P>
				415	The character string with the alphabet which is more or less a subset
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	416	of ASCII between the space and the ''<B>~</B>''
				417	symbol (tilde).
				418
				419	<P>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	420	Alternatively, the alphabet may be described as the PrintableString
				421	alphabet presented earlier, plus the following characters: ''<B>!</B>'',
				422	''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
				423	''<B>&</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B><</B>'',
				424	''<B>></B>'', ''<B>[</B>'', ''<B>\</B>'',
				425	''<B>]</B>'', ''<B>^</B>'', ''<B>_</B>'',
				426	''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>\|</B>'',
				427	''<B>}</B>'', ''<B>~</B>''.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	428
				429	<P>
				430
				431	<H1><A NAME="SECTION02130000000000000000">
				432	ASN.1 Constructed Types</A>
				433	</H1>
				434
				435	<P>
				436
				437	<H2><A NAME="SECTION02131000000000000000">
				438	The SEQUENCE type</A>
				439	</H2>
				440
				441	<P>
				442	This is an ordered collection of other simple or constructed types.
				443	The SEQUENCE constructed type resembles the C ''struct'' statement.
				444
				445	<P>
				446
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	447	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	448	Address ::= SEQUENCE {
				449	-- The apartment number may be omitted
				450	apartmentNumber     NumericString OPTIONAL,
				451	streetName           PrintableString,
				452	cityName             PrintableString,
				453	stateName            PrintableString,
				454	-- This one may be omitted too
				455	zipNo                NumericString OPTIONAL
				456	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	457	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	458	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	459
				460	<P>
				461
				462	<H2><A NAME="SECTION02132000000000000000">
				463	The SET type</A>
				464	</H2>
				465
				466	<P>
				467	This is a collection of other simple or constructed types. Ordering
				468	is not important. The data may arrive in the order which is different
				469	from the order of specification. Data is encoded in the order not
				470	necessarily corresponding to the order of specification.
				471
				472	<P>
				473
				474	<H2><A NAME="SECTION02133000000000000000">
				475	The CHOICE type</A>
				476	</H2>
				477
				478	<P>
				479	This type is just a choice between the subtypes specified in it. The
				480	CHOICE type contains at most one of the subtypes specified, and it
				481	is always implicitly known which choice is being decoded or encoded.
				482	This one resembles the C ''union'' statement.
				483
				484	<P>
				485	The following type defines a response code, which may be either an
				486	integer code or a boolean ''true''/''false'' code.
				487
				488	<P>
				489
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	490	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	491	ResponseCode ::= CHOICE {
				492	intCode    INTEGER,
				493	boolCode   BOOLEAN
				494	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	495	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	496	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	497
				498	<P>
				499
				500	<H2><A NAME="SECTION02134000000000000000">
				501	The SEQUENCE OF type</A>
				502	</H2>
				503
				504	<P>
				505	This one is the list (array) of simple or constructed types:
				506
				507	<P>
				508
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	509	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	510	-- Example 1
				511	ManyIntegers ::= SEQUENCE OF INTEGER
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	512
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	513	-- Example 2
				514	ManyRectangles ::= SEQUENCE OF Rectangle
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	515
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	516	-- More complex example:
				517	-- an array of structures defined in place.
				518	ManyCircles ::= SEQUENCE OF SEQUENCE {
				519	radius INTEGER
				520	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	521	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	522	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	523
				524	<P>
				525
				526	<H2><A NAME="SECTION02135000000000000000">
				527	The SET OF type</A>
				528	</H2>
				529
				530	<P>
				531	The SET OF type models the bag of structures. It resembles the SEQUENCE
				532	OF type, but the order is not important: i.e. the elements may arrive
				533	in the order which is not necessarily the same as the in-memory order
				534	on the remote machines.
				535
				536	<P>
				537
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	538	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	539	-- A set of structures defined elsewhere
				540	SetOfApples :: SET OF Apple
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	541
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	542	-- Set of integers encoding the kind of a fruit
				543	FruitBag ::= SET OF ENUMERATED { apple, orange }
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	544	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	545	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	546
				547	<P>
				548
				549	<H1><A NAME="SECTION03000000000000000000">
				550	Using the ASN.1 Compiler</A>
				551	</H1>
				552
				553	<P>
				554
				555	<H1><A NAME="SECTION03100000000000000000">
				556	Introduction to the ASN.1 Compiler</A>
				557	</H1>
				558
				559	<P>
				560	The purpose of the ASN.1 compiler, of which this document is part,
				561	is to convert the ASN.1 specifications to some other target language
				562	(currently, only C is supported<A NAME="tex2html1"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	563	HREF="#foot145"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	564	language structures and surrounding maintenance code. For example,
				565	the C structure which may be created by compiler to represent the
				566	simple <I>Rectangle</I> specification defined earlier in this document,
				567	may look like this<A NAME="tex2html2"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	568	HREF="#foot404"><SUP>2.2</SUP></A>:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	569
				570	<P>
				571
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	572	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	573	typedef struct Rectangle_s {
				574	int height;
				575	int width;
				576	} Rectangle_t;
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	577	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	578	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	579	This would not be of much value for such a simple specification, so
				580	the compiler goes further and actually produces the code which fills
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	581	in this structure by parsing the opaque binary<A NAME="tex2html3"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	582	HREF="#foot152"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	583	this structure as an argument and performs structure serialization
				584	by emitting a series of bytes.
				585
				586	<P>
				587
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	588	<H1><A NAME="SECTION03200000000000000000">
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	589	Quick start</A>
				590	</H1>
				591
				592	<P>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	593	After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	594	HREF="#foot405"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
				595	HREF="#foot406"><SUP>3.2</SUP></A>:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	596
				597	<P>
				598
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	599	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	600	asn1c <I><spec.asn1></I>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	601	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	602	</BLOCKQUOTE>
				603	If several specifications contain interdependencies, all of the files
				604	must be specified altogether:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	605
				606	<P>
				607
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	608	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	609	asn1c <I><spec1.asn1> <spec2.asn1> ...</I>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	610	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	611	</BLOCKQUOTE>
				612	The compiler <B>-E</B> and <B>-EF</B> options are used for testing
				613	the parser and the semantic fixer, respectively. These options will
				614	instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
				615	is involved) ASN.1 specification as it was "understood"
				616	by the compiler. It might be useful to check whether a particular
				617	syntactic construction is properly supported by the compiler.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	618
				619	<P>
				620
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	621	<BLOCKQUOTE><PRE>
				622	asn1c <B>-EF</B> <I><spec-to-test.asn1></I>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	623	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	624	</BLOCKQUOTE>
				625	The <B>-P</B> option is used to dump the compiled output on the
				626	screen instead of creating a bunch of .c and .h files on disk in the
				627	current directory. You would probably want to start with <B>-P</B>
				628	option instead of creating a mess in your current directory. Another
				629	option, <B>-R</B>, asks compiler to only generate the files which
				630	need to be generated, and supress linking in the numerous support
				631	files.
				632
				633	<P>
				634	Print the compiled output instead of creating multiple source files:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	635
				636	<P>
				637
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	638	<BLOCKQUOTE><PRE>
				639	asn1c <B>-P</B> <I><spec-to-compile-and-print.asn1></I>
				640	</PRE>
				641	</BLOCKQUOTE>
				642
				643	<P>
				644
				645	<H1><A NAME="SECTION03300000000000000000">
				646	Using the ASN.1 Compiler</A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	647	</H1>
				648
				649	<P>
				650
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	651	<H1><A NAME="SECTION03310000000000000000">
				652	Command-line options</A>
				653	</H1>
				654
				655	<P>
				656	The <A HREF=#Table1>Table 1</A> summarizes various options affecting
				657	the compiler's behavior.
				658
				659	<P>
				660	<BR><P></P>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	661	<DIV ALIGN="CENTER"><A NAME="409"></A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	662	<TABLE>
				663	<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
				664	The list of asn1c command line options</CAPTION>
				665	<TR><TD><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
				666	<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=JUSTIFY WIDTH="3in">
				667	<TBODY>
				668	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
				669	<B>Overall Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				670	<B>Description</B></TD></TR>
				671	</TBODY><TBODY>
				672	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-E</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				673	<FONT SIZE="-1">Stop after the parsing stage and print the reconstructed ASN.1
				674	specification code to the standard output.</FONT></TD></TR>
				675	</TBODY><TBODY>
				676	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-F</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				677	<FONT SIZE="-1">Used together with -E, instructs the compiler to stop after
				678	the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
				679	specification to the standard output.</FONT></TD></TR>
				680	</TBODY><TBODY>
				681	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-P</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				682	<FONT SIZE="-1">Dump the compiled output to the standard output instead of
				683	cre- ating the target language files on disk.</FONT></TD></TR>
				684	</TBODY><TBODY>
				685	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-R</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				686	<FONT SIZE="-1">Restrict the compiler to generate only the ASN.1 tables, omit-
				687	ting the usual support code.</FONT></TD></TR>
				688	</TBODY><TBODY>
				689	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-S <I><directory></I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				690	<FONT SIZE="-1">Use the specified directory with ASN.1 skeleton files.</FONT></TD></TR>
				691	</TBODY><TBODY>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	692	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Warning Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				693	<B>Description</B></TD></TR>
				694	</TBODY><TBODY>
				695	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Werror</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				696	<FONT SIZE="-1">Treat warnings as errors; abort if any warning is produced.</FONT></TD></TR>
				697	</TBODY><TBODY>
				698	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-lexer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				699	<FONT SIZE="-1">Enable lexer debugging during the ASN.1 parsing stage.</FONT></TD></TR>
				700	</TBODY><TBODY>
				701	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-fixer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				702	<FONT SIZE="-1">Enable ASN.1 syntax tree fixer debugging during the
				703	fixing stage.</FONT></TD></TR>
				704	</TBODY><TBODY>
				705	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-compiler</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				706	<FONT SIZE="-1">Enable debugging during the actual compile time.</FONT></TD></TR>
				707	</TBODY><TBODY>
				708	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Language Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				709	<B>Description</B></TD></TR>
				710	</TBODY><TBODY>
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	711	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fall-defs-global</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	712	Normally the compiler hides the definitions (asn_DEF_xxx) of the
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	713	inner structure elements (members of SEQUENCE, SET and other types).
				714	This option makes all such definitions global. Enabling this option
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	715	may pollute the namespace by making lots of asn_DEF_xxx structures
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	716	globally visible, but will allow you to manipulate (encode and decode)
				717	the individual members of any complex ASN.1 structure.</TD></TR>
				718	</TBODY><TBODY>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	719	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fbless-SIZE</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				720	<FONT SIZE="-1">Allow SIZE() constraint for INTEGER, ENUMERATED, and other
				721	types for which this constraint is normally prohibited by the standard.
				722	This is a violation of an ASN.1 standard and compiler may fail to
				723	produce the meaningful code.</FONT></TD></TR>
				724	</TBODY><TBODY>
vlm	1111525	2004-09-17 08:35:02 +0000	[diff] [blame]	725	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fnative-types</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				726	<FONT SIZE="-1">Use the native machine's data types (int, double) whenever
				727	possible, instead of the compound ASN.1 INTEGER_t, ENUMERATED_t
				728	and REAL_t types. </FONT></TD></TR>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	729	</TBODY><TBODY>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	730	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fno-constraints</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				731	Do not generate ASN.1 subtype constraint checking code. This may make
				732	a shorter executable.</TD></TR>
				733	</TBODY><TBODY>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	734	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-funnamed-unions</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				735	<FONT SIZE="-1">Enable unnamed unions in the definitions of target language's
				736	structures.</FONT></TD></TR>
				737	</TBODY><TBODY>
				738	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-ftypes88</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				739	<FONT SIZE="-1">Use only ASN.1:1988 embedded types.</FONT></TD></TR>
				740	</TBODY><TBODY>
				741	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Output Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				742	<B>Description</B></TD></TR>
				743	</TBODY><TBODY>
				744	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-constraints</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				745	<FONT SIZE="-1">When -EF are also specified, this option forces the compiler
				746	to explain its internal understanding of subtype constraints.</FONT></TD></TR>
				747	</TBODY><TBODY>
				748	<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-lines</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
				749	<FONT SIZE="-1">Generate "- #line" comments in -E output.</FONT></TD></TR>
				750	</TBODY>
				751	</TABLE>
				752
				753	<P>
				754	</TD></TR>
				755	</TABLE>
				756	</DIV><P></P><BR>
				757
				758	<P>
				759
				760	<H1><A NAME="SECTION03320000000000000000">
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	761	Recognizing compiler output</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	762	</H1>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	763
				764	<P>
				765	After compiling, the following entities will be created in your current
				766	directory:
				767
				768	<P>
				769
				770	<UL>
				771	<LI>A set of .c and .h files, generally a single pair for each type defined
				772	in the ASN.1 specifications. These files will be named similarly to
				773	the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
				774	specification defined in the beginning of this document).
				775	</LI>
				776	<LI>A set of helper .c and .h files which contain generic encoders, decoders
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	777	and other useful routines. There will be quite a few of them, some
				778	of them even are not always necessary, but the overall amount of code
				779	after compiling will be rather small anyway.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	780	</LI>
				781	</UL>
				782	It is your responsibility to create .c file with the <I>int main()</I>
				783	routine and the Makefile (if needed). Compiler helps you with the
				784	latter by creating the Makefile.am.sample, containing the skeleton
				785	definition for the automake, should you want to use autotools.
				786
				787	<P>
				788	In other words, after compiling the Rectangle module, you have the
				789	following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
				790	<B>...</B> }, where <B>''...''</B> stands for the
				791	set of additional ''helper'' files created by the compiler. If you
				792	add the simple file with the <I>int main()</I> routine, it would even
				793	be possible to compile everything with the single instruction:
				794
				795	<P>
				796
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	797	<BLOCKQUOTE><PRE>
				798	cc -o rectangle *.c   # It could be <I>that</I> simple<A NAME="tex2html7"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	799	HREF="#foot412"><SUP>4.1</SUP></A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	800	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	801	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	802
				803	<P>
				804
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	805	<H1><A NAME="SECTION03330000000000000000">
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	806	Invoking the ASN.1 helper code from the application</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	807	</H1>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	808
				809	<P>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	810	First of all, you should to include one or more header files into
				811	your application. For our Rectangle module, including the Rectangle.h
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	812	file is enough:
				813
				814	<P>
				815
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	816	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	817	#include <Rectangle.h>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	818	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	819	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	820	The header files defines the C structure corresponding to the ASN.1
				821	definition of a rectangle and the declaration of the ASN.1 type descriptor,
				822	which is used as an argument to most of the functions provided by
				823	the ASN.1 module. For example, here is the code which frees the Rectangle_t
				824	structure:
				825
				826	<P>
				827
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	828	<BLOCKQUOTE><PRE>
				829	Rectangle_t *rect = ...;
				830
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	831	asn_DEF_Rectangle->free_struct(&asn_DEF_Rectangle,
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	832	rect, 0);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	833	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	834	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	835	This code defines a <I>rect</I> pointer which points to the Rectangle_t
				836	structure which needs to be freed. The second line invokes the generic
				837	free_struct routine created specifically for this Rectangle_t structure.
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	838	The <I>asn_DEF_Rectangle</I> is the type descriptor, which holds
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	839	a collection of generic routines to deal with the Rectangle_t structure.
				840
				841	<P>
				842	There are several generic functions available:
				843
				844	<P>
				845	<DL>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	846	<DT><STRONG>ber_decoder</STRONG></DT>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	847	<DD>This is the generic <I>restartable</I><A NAME="tex2html8"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	848	HREF="#foot239"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	849	and/or fill the target structure for you. Please refer to Section
				850	[<A HREF="#sub:Decoding-BER">Decoding-BER</A>].
				851	</DD>
				852	<DT><STRONG>der_encoder</STRONG></DT>
				853	<DD>This is the generic DER encoder (Distinguished Encoding
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	854	Rules). This encoder will take the target structure and encode it
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	855	into a series of bytes. Please refer to Section [<A HREF="#sub:Encoding-DER">Encoding-DER</A>].
				856	</DD>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	857	<DT><STRONG>xer_encoder</STRONG></DT>
				858	<DD>This is the generic XER encoder (XML Encoding Rules).
				859	This encoder will take the target structure and represent it as an
				860	XML (text) document. Please refer to Section [<A HREF="#sub:Encoding-XER">Encoding-XER</A>].
				861	</DD>
				862	<DT><STRONG>check_constraints</STRONG></DT>
				863	<DD>Check that the contents of the target structure
				864	are semantically valid and constrained to appropriate implicit or
				865	explicit subtype constraints. Please refer to Section sub:Validating-the-target.
				866	</DD>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	867	<DT><STRONG>print_struct</STRONG></DT>
				868	<DD>This function convert the contents of the passed target
				869	structure into human readable form. This form is not formal and cannot
				870	be converted back into the structure, but it may turn out to be useful
				871	for debugging or quick-n-dirty printing. Please refer to Section [<A HREF="#sub:Printing-the-target">Printing-the-target</A>].
				872	</DD>
				873	<DT><STRONG>free_struct</STRONG></DT>
				874	<DD>This is a generic disposal which frees the target structure.
				875	Please refer to Section [<A HREF="#sub:Freeing-the-target">Freeing-the-target</A>].
				876	</DD>
				877	</DL>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	878	check_constraints Check that the contents of the target structure
				879	are semantically valid and constrained to appropriate implicit or
				880	explicit subtype constraints. Please refer to Section sub:Validating-the-target.
				881
				882	<P>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	883	Each of the above function takes the type descriptor (<I>asn_DEF_...</I>)
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	884	and the target structure (<I>rect</I>, in the above example). The
				885	target structure is typically created by the generic BER decoder or
				886	by the application itself.
				887
				888	<P>
				889	Here is how the buffer can be deserialized into the structure:
				890
				891	<P>
				892
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	893	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	894	Rectangle_t *
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	895	simple_deserializer(const void *buffer, size_t buf_size) {
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	896	Rectangle_t rect = 0;    / Note this 0! */
				897	ber_dec_rval_t rval;
				898
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	899	rval = asn_DEF_Rectangle->ber_decoder(0,
				900	&asn_DEF_Rectangle,
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	901	(void **)&rect,
				902	buffer, buf_size,
				903	0);
				904
				905	if(rval<B>.code</B> == RC_OK) {
				906	return rect;          /* Decoding succeeded */
				907	} else {
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	908	/* Free partially decoded rect */
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	909	asn_DEF_Rectangle->free_struct(
				910	&asn_DEF_Rectangle, rect, 0);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	911	return 0;
				912	}
				913	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	914	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	915	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	916	The code above defines a function, <I>simple_deserializer</I>, which
				917	takes a buffer and its length and expected to return a pointer to
				918	the Rectangle_t structure. Inside, it tries to convert the bytes
				919	passed into the target structure (rect) using the generic BER decoder
				920	and returns the rect pointer afterwards. If the structure cannot be
				921	deserialized, it frees the memory which might be left allocated by
				922	the unfinished <I>ber_decoder</I> routine and returns NULL. <B>This
				923	freeing is necessary</B> because the ber_decoder is a restartable procedure,
				924	and may fail just because there is more data needs to be provided
				925	before decoding could be finalized. The code above obviously does
				926	not take into account the way the <I>ber_decoder</I> failed, so the
				927	freeing is necessary because the part of the buffer may already be
				928	decoded into the structure by the time something goes wrong.
				929
				930	<P>
				931	Restartable decoding is a little bit trickier: you need to provide
				932	the old target structure pointer (which might be already half-decoded)
				933	and react on RC_WMORE return code. This will be explained later in
				934	Section sub:Decoding-BER
				935
				936	<P>
				937
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	938	<H2><A NAME="SECTION03331000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	939	Decoding BER
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	940	</H2>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	941
				942	<P>
				943	The Basic Encoding Rules describe the basic way how the structure
				944	can be encoded and decoded. Several other encoding rules (CER, DER)
				945	define a more restrictive versions of BER, so the generic BER parser
				946	is also capable of decoding the data encoded by CER and DER encoders.
				947	The opposite is not true.
				948
				949	<P>
				950	The ASN.1 compiler provides the generic BER decoder which is implicitly
				951	capable of decoding BER, CER and DER encoded data.
				952
				953	<P>
				954	The decoder is restartable (stream-oriented), which means that in
				955	case the buffer has less data than it is expected, the decoder will
				956	process whatever it is available and ask for more data to be provided.
				957	Please note that the decoder may actually process less data than it
				958	is given in the buffer, which means that you should be able to make
				959	the next buffer contain the unprocessed part of the previous buffer.
				960
				961	<P>
				962	Suppose, you have two buffers of encoded data: 100 bytes and 200 bytes.
				963
				964	<P>
				965
				966	<UL>
				967	<LI>You may concatenate these buffers and feed the BER decoder with 300
				968	bytes of data, or
				969	</LI>
				970	<LI>You may feed it the first buffer of 100 bytes of data, realize that
				971	the ber_decoder consumed only 95 bytes from it and later feed the
				972	decoder with 205 bytes buffer which consists of 5 unprocessed bytes
				973	from the first buffer and the latter 200 bytes from the second buffer.
				974	</LI>
				975	</UL>
				976	This is not as convenient as it could be (like, the BER encoder would
				977	consume the whole 100 bytes and keep these 5 bytes in some temporary
				978	storage), but in case of stream-based processing it might actually
				979	be OK. Suggestions are welcome.
				980
				981	<P>
				982	There are two ways to invoke a BER decoder. The first one is a direct
				983	reference of the type-specific decoder. This way was shown in the
				984	previous example of <I>simple_deserializer</I> function. The second
				985	way is to invoke a <I>ber_decode</I> function, which is just a simple
				986	wrapper of the former approach into a less wordy notation:
				987
				988	<P>
				989
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	990	<BLOCKQUOTE><PRE>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	991	rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	992	buffer, buf_size);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	993	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	994	</BLOCKQUOTE>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	995	Note that the initial (asn_DEF_Rectangle->ber_decoder) reference
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	996	is gone, and also the last argument (0) is no longer necessary.
				997
				998	<P>
				999	These two ways of invocations are fully equivalent.
				1000
				1001	<P>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1002	The BER de<I>coder</I> may fail because of (<I>the following RC_...
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1003	codes are defined in ber_decoder.h</I>):
				1004
				1005	<P>
				1006
				1007	<UL>
				1008	<LI>RC_WMORE: There is more data expected than it is provided (stream
				1009	mode continuation feature);
				1010	</LI>
				1011	<LI>RC_FAIL: General failure to decode the buffer;
				1012	</LI>
				1013	<LI>... other codes may be defined as well.
				1014	</LI>
				1015	</UL>
				1016	Together with the return code (.code) the ber_dec_rval_t type contains
				1017	the number of bytes which is consumed from the buffer. In the previous
				1018	hypothetical example of two buffers (of 100 and 200 bytes), the first
				1019	call to ber_decode() would return with .code = RC_WMORE and .consumed
				1020	= 95. The .consumed field of the BER decoder return value is <B>always</B>
				1021	valid, even if the decoder succeeds or fails with any other return
				1022	code.
				1023
				1024	<P>
				1025	Please look into ber_decoder.h for the precise definition of ber_decode()
				1026	and related types.
				1027
				1028	<P>
				1029
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1030	<H2><A NAME="SECTION03332000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1031	Encoding DER
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1032	</H2>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1033
				1034	<P>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1035	The Distinguished Encoding Rules is the <I>canonical</I> variant of
				1036	BER encoding rules. The DER is best suited to encode the structures
				1037	where all the lengths are known beforehand. This is probably exactly
				1038	how you want to encode: either after a BER decoding or after a manual
				1039	fill-up, the target structure contains the data which size is implicitly
				1040	known before encoding. The DER encoding is used, for example, to encode
				1041	X.509 certificates.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1042
				1043	<P>
				1044	As with BER decoder, the DER encoder may be invoked either directly
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1045	from the ASN.1 type descriptor (asn_DEF_Rectangle) or from the stand-alone
				1046	function, which is somewhat simpler:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1047
				1048	<P>
				1049
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1050	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1051	/*
				1052	* This is a custom function which writes the
				1053	* encoded output into some FILE stream.
				1054	*/
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1055	static int
				1056	write_stream(const void buffer, size_t size, void app_key) {
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1057	FILE *ostream = app_key;
				1058	size_t wrote;
				1059
				1060	wrote = fwrite(buffer, 1, size, ostream);
				1061
				1062	return (wrote == size) ? 0 : -1;
				1063	}
				1064
				1065	/*
				1066	* This is the serializer itself,
				1067	* it supplies the DER encoder with the
				1068	* pointer to the custom output function.
				1069	*/
				1070	ssize_t
				1071	simple_serializer(FILE ostream, Rectangle_t rect) {
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1072	asn_enc_rval_t er;  /* Encoder return value */
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1073
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1074	er = der_encode(&asn_DEF_Rect, rect,
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1075	write_stream, ostream);
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1076	if(er.<B>encoded</B> == -1) {
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1077	/*
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1078	* Failed to encode the rectangle data.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1079	*/
				1080	fprintf(stderr, ''Cannot encode %s: %s\n'',
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1081	er.<B>failed_type</B>->name,
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1082	strerror(errno));
				1083	return -1;
				1084	} else {
				1085	/* Return the number of bytes */
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1086	return er.encoded;
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1087	}
				1088	}
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1089	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1090	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1091	As you see, the DER encoder does not write into some sort of buffer
				1092	or something. It just invokes the custom function (possible, multiple
				1093	times) which would save the data into appropriate storage. The optional
				1094	argument <I>app_key</I> is opaque for the DER encoder code and just
				1095	used by <I>_write_stream()</I> as the pointer to the appropriate
				1096	output stream to be used.
				1097
				1098	<P>
				1099	If the custom write function is not given (passed as 0), then the
				1100	DER encoder will essentially do the same thing (i.e., encode the data)
				1101	but no callbacks will be invoked (so the data goes nowhere). It may
				1102	prove useful to determine the size of the structure's encoding before
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1103	actually doing the encoding<A NAME="tex2html9"
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1104	HREF="#foot315"><SUP>4.3</SUP></A>.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1105
				1106	<P>
				1107	Please look into der_encoder.h for the precise definition of der_encode()
				1108	and related types.
				1109
				1110	<P>
				1111
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1112	<H2><A NAME="SECTION03333000000000000000"></A><A NAME="sub:Encoding-XER"></A><BR>
				1113	Encoding XER
				1114	</H2>
				1115
				1116	<P>
				1117	The XER stands for XML Encoding Rules, where XML, in turn, is eXtensible
				1118	Markup Language, a text-based format for information exchange. The
				1119	encoder routine API comes in two flavors: stdio-based and callback-based.
				1120	With the callback-based encoder, the encoding process is very similar
				1121	to the DER one, described in Section sub:Encoding-DER. The
				1122	following example uses the definition of write_stream() from up there.
				1123
				1124	<P>
				1125
				1126	<BLOCKQUOTE><PRE>
				1127	/*
				1128	* This procedure generates the XML document
				1129	* by invoking the XER encoder.
				1130	* NOTE: Do not copy this code verbatim!
				1131	*       If the stdio output is necessary,
				1132	*       use the xer_fprint() procedure instead.
				1133	*       See Section sub:Printing-the-target.
				1134	*/
				1135	int
				1136	print_as_XML(FILE ostream, Rectangle_t rect) {
				1137	asn_enc_rval_t er;  /* Encoder return value */
				1138
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1139	er = xer_encode(&asn_DEF_Rect, rect,
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1140	XER_F_BASIC, /* BASIC-XER or CANONICAL-XER */
				1141	write_stream, ostream);
				1142
				1143	return (er.encoded == -1) ? -1 : 0;
				1144	}
				1145	</PRE>
				1146	</BLOCKQUOTE>
				1147	Please look into xer_encoder.h for the precise definition of xer_encode()
				1148	and related types.
				1149
				1150	<P>
				1151	See Section [<A HREF="#sub:Printing-the-target">Printing-the-target</A>] for the example of stdio-based
				1152	XML encoder and other pretty-printing suggestions.
				1153
				1154	<P>
				1155
				1156	<H2><A NAME="SECTION03334000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1157	Validating the target structure
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1158	</H2>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1159
				1160	<P>
				1161	Sometimes the target structure needs to be validated. For example,
				1162	if the structure was created by the application (as opposed to being
				1163	decoded from some external source), some important information required
				1164	by the ASN.1 specification might be missing. On the other hand, the
				1165	successful decoding of the data from some external source does not
				1166	necessarily mean that the data is fully valid either. It might well
				1167	be the case that the specification describes some subtype constraints
				1168	that were not taken into account during decoding, and it would actually
				1169	be useful to perform the last check when the data is ready to be encoded
				1170	or when the data has just been decoded to ensure its validity according
				1171	to some stricter rules.
				1172
				1173	<P>
				1174	The asn_check_constraints() function checks the type for various
				1175	implicit and explicit constraints. It is recommended to use asn_check_constraints()
				1176	function after each decoding and before each encoding.
				1177
				1178	<P>
				1179	Please look into constraints.h for the precise definition of asn_check_constraints()
				1180	and related types.
				1181
				1182	<P>
				1183
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1184	<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1185	Printing the target structure
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1186	</H2>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1187
				1188	<P>
				1189	There are two ways to print the target structure: either invoke the
				1190	print_struct member of the ASN.1 type descriptor, or using the asn_fprint()
				1191	function, which is a simpler wrapper of the former:
				1192
				1193	<P>
				1194
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1195	<BLOCKQUOTE><PRE>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1196	asn_fprint(stdout, &asn_DEF_Rectangle, rect);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1197	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1198	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1199	Please look into constr_TYPE.h for the precise definition of asn_fprint()
				1200	and related types.
				1201
				1202	<P>
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1203	Another practical alternative to this custom format printing would
				1204	be to invoke XER encoder. The default BASIC-XER encoder performs reasonable
				1205	formatting for the output to be useful and human readable. To invoke
				1206	the XER decoder in a manner similar to asn_fprint(), use the xer_fprint()
				1207	call:
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1208
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1209	<P>
				1210
				1211	<BLOCKQUOTE><PRE>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1212	xer_fprint(stdout, &asn_DEF_Rectangle, rect);
vlm	763ac41	2004-09-26 13:41:45 +0000	[diff] [blame]	1213	</PRE>
				1214	</BLOCKQUOTE>
				1215	See Section sub:Encoding-XER for XML-related details.
				1216
				1217	<P>
				1218
				1219	<H2><A NAME="SECTION03336000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1220	Freeing the target structure
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1221	</H2>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1222
				1223	<P>
				1224	Freeing the structure is slightly more complex than it may seem to.
				1225	When the ASN.1 structure is freed, all the members of the structure
				1226	and their submembers etc etc are recursively freed too. But it might
				1227	not be feasible to free the structure itself. Consider the following
				1228	case:
				1229
				1230	<P>
				1231
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1232	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1233	struct my_figure {       /* The custom structure */
				1234	int flags;           /* <some custom member> */
				1235	/* The type is generated by the ASN.1 compiler */
				1236	<I>Rectangle_t rect;</I>
				1237	/* other members of the structure */
				1238	};
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1239	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1240	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1241	In this example, the application programmer defined a custom structure
				1242	with one ASN.1-derived member (rect). This member is not a reference
				1243	to the Rectangle_t, but an in-place inclusion of the Rectangle_t
				1244	structure. If the freeing is necessary, the usual procedure of freeing
				1245	everything must not be applied to the &rect pointer itself, because
				1246	it does not point to the memory block directly allocated by memory
				1247	allocation routine, but instead lies within such a block allocated
				1248	for my_figure structure.
				1249
				1250	<P>
				1251	To solve this problem, the free_struct routine has the additional
				1252	argument (besides the intuitive type descriptor and target structure
				1253	pointers), which is the flag specifying whether the outer pointer
				1254	itself must be freed (0, default) or it should be left intact (non-zero
				1255	value).
				1256
				1257	<P>
				1258
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1259	<BLOCKQUOTE><PRE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1260	/* Rectangle_t is defined within my_figure */
				1261	struct my_figure *mf = <B>...</B>;
				1262	/*
				1263	* Freeing the Rectangle_td
				1264	* without freeing the mf->rect pointer
				1265	*/
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1266	asn_DEF_Rectangle->free_struct(
				1267	&asn_DEF_Rectangle, &mf->rect, <I>1</I> /* !free */);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1268
				1269	/* Rectangle_t is a stand-alone pointer */
				1270	Rectangle_t *rect = <B>...</B>;
				1271	/*
				1272	* Freeing the Rectangle_t
				1273	* and freeing the rect pointer
				1274	*/
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1275	asn_DEF_Rectangle->free_struct(
				1276	&asn_DEF_Rectangle, rect, <I>0</I> /* free the pointer too */);
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1277	</PRE>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1278	</BLOCKQUOTE>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1279	It is safe to invoke the <I>free_struct</I> function with the target
				1280	structure pointer set to 0 (NULL), the function will do nothing.
				1281
				1282	<P>
				1283
				1284	<H2><A NAME="SECTION04000000000000000000">
				1285	Bibliography</A>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1286	</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
vlm	03eb4e1	2004-09-08 03:10:54 +0000	[diff] [blame]	1287	<DD>The OpenSource ASN.1 Compiler. http://lionet.info/asn1/
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1288	<P></P><DT><A NAME="Dub00">Dub00</A>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1289	<DD>Olivier Dubuisson - <I>ASN.1 Communication between heterogeneous
				1290	systems</I> - Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
				1291	ISBN:0-12-6333361-0.
				1292	<P></P><DT><A NAME="ITU-T_ASN.1">ITU-T/ASN.1</A>
				1293	<DD>ITU-T Study Group 17 - Languages for Telecommunication Systems http://www.itu.int/ITU-T/studygroups/com17/languages/</DL>
				1294
				1295	<P>
				1296	<BR><HR><H4>Footnotes</H4>
				1297	<DL>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1298	<DT><A NAME="foot145">... supported</A><A
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1299	HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT>
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1300	<DD>C++ is ''supported'' too, as long as an class-based approach is
				1301	not a definitive factor.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1302
				1303	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1304	<DT><A NAME="foot404">... this</A><A
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1305	HREF="asn1c-usage.html#tex2html2"><SUP>2.2</SUP></A></DT>
vlm	1111525	2004-09-17 08:35:02 +0000	[diff] [blame]	1306	<DD><I>-fnative-types</I> compiler option is used to produce basic C <I>int</I>
				1307	types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table 1</A>.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1308
				1309	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1310	<DT><A NAME="foot152">... binary</A><A
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1311	HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT>
				1312	<DD>BER, CER and DER encodings are binary. However, the XER encoding is
				1313	text (XML) based.
				1314
				1315	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1316	<DT><A NAME="foot405">...asn1c</A><A
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1317	HREF="asn1c-usage.html#tex2html4"><SUP>3.1</SUP></A></DT>
				1318	<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
				1319
				1320	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1321	<DT><A NAME="foot406">... specification</A><A
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1322	HREF="asn1c-usage.html#tex2html5"><SUP>3.2</SUP></A></DT>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1323	<DD>This is probably <B>not</B> what you want to try out right now -
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1324	read through the rest of this chapter to find out about <B>-P</B>
				1325	and <B>-R</B> options.
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1326
				1327	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1328	<DT><A NAME="foot412">...that simple</A><A
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1329	HREF="asn1c-usage.html#tex2html7"><SUP>4.1</SUP></A></DT>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1330	<DD>Provided that you've also created a .c file with the <I>int main()</I>
				1331	routine.
				1332
				1333	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1334	<DT><A NAME="foot239">...restartable</A><A
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1335	HREF="asn1c-usage.html#tex2html8"><SUP>4.2</SUP></A></DT>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1336	<DD>Restartable means that if the decoder encounters the end of the buffer,
				1337	it will fail, but may later be invoked again with the rest of the
				1338	buffer to continue decoding.
				1339
				1340	</DD>
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1341	<DT><A NAME="foot315">... encoding</A><A
vlm	fcec8e5	2004-08-23 15:12:04 +0000	[diff] [blame]	1342	HREF="asn1c-usage.html#tex2html9"><SUP>4.3</SUP></A></DT>
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1343	<DD>It is actually faster too: the encoder might skip over some computations
				1344	which aren't important for the size determination.
				1345
				1346	</DD>
				1347	</DL><BR><HR>
				1348	<ADDRESS>
				1349	Lev Walkin
vlm	4a168ae	2004-09-29 13:37:15 +0000	[diff] [blame^]	1350	2004-09-29
vlm	9ca1504	2004-08-07 06:03:15 +0000	[diff] [blame]	1351	</ADDRESS>
				1352	</BODY>
				1353	</HTML>