Blame - doc/asn1c-usage.html - asn1c

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