Blame - doc/asn1c-usage.html - asn1c

blob: d7b22b0f316618435bf3058d685caa3f606aa878 [file] [log] [blame]

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