diff options
| author | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
|---|---|---|
| committer | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
| commit | 84adefa331c4159d432d22840663c38f155cd4c1 (patch) | |
| tree | bff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/asn1/doc/src | |
| download | otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2 otp-84adefa331c4159d432d22840663c38f155cd4c1.zip | |
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/asn1/doc/src')
23 files changed, 7646 insertions, 0 deletions
diff --git a/lib/asn1/doc/src/Makefile b/lib/asn1/doc/src/Makefile new file mode 100644 index 0000000000..be8755f0ff --- /dev/null +++ b/lib/asn1/doc/src/Makefile @@ -0,0 +1,223 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1997-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(ASN1_VSN) +APPLICATION=asn1 + + +# ---------------------------------------------------- +# Include dependency +# ---------------------------------------------------- + +ifndef DOCSUPPORT +include make.dep +endif + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = asn1ct.xml \ + asn1rt.xml + +GEN_XML = \ + asn1_spec.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml + +XML_HTML_FILE = \ + notes_history.xml + +XML_CHAPTER_FILES = \ + asn1_ug.xml \ + asn1_spec.xml \ + notes.xml + +BOOK_FILES = book.xml + +XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \ + $(GEN_XML) $(XML_PART_FILES) $(XML_CHAPTER_FILES) + +GIF_FILES = \ + exclusive_Win_But.gif \ + selective_Window2.gif \ + selective_TypeList.gif + +# ---------------------------------------------------- + +ASN1_FILES = \ + Seq.asn \ + Seq.asn1config + +INFO_FILE = ../../info +EXTRA_FILES = \ + $(DEFAULT_HTML_FILES) \ + $(ASN1_FILES) \ + $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +ifdef DOCSUPPORT + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +else + +TEX_FILES_BOOK = \ + $(BOOK_FILES:%.xml=%.tex) \ + $(BOOK_FILES:%.xml=%.sgml) part.tex +TEX_FILES_REF_MAN = $(XML_REF3_FILES:%.xml=%.tex) \ + $(XML_APPLICATION_FILES:%.xml=%.tex) +TEX_FILES_USERS_GUIDE = \ + $(XML_CHAPTER_FILES:%.xml=%.tex) + +TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf +TOP_PS_FILE = $(APPLICATION)-$(VSN).ps + +$(TOP_PDF_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@ + +$(TOP_PS_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@ + +endif + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +ifdef DOCSUPPORT + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f $(GEN_XML) errs core *~ + +else + +ifeq ($(DOCTYPE),pdf) +docs: pdf +else +ifeq ($(DOCTYPE),ps) +docs: ps +else +docs: html gifs man +endif +endif + +pdf: $(TOP_PDF_FILE) + +ps: $(TOP_PS_FILE) + +html: $(HTML_FILES) + +clean clean_docs clean_tex: + rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK) + rm -f $(HTML_FILES) $(MAN3_FILES) + rm -f $(TOP_PDF_FILE) $(TOP_PS_FILE) + rm -f errs core *~ $(LATEX_CLEAN) + +endif + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +ifdef DOCSUPPORT + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + +else + +ifeq ($(DOCTYPE),pdf) +release_docs_spec: pdf + $(INSTALL_DIR) $(RELEASE_PATH)/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf +else +ifeq ($(DOCTYPE),ps) +release_docs_spec: ps + $(INSTALL_DIR) $(RELEASE_PATH)/ps + $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps +else +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \ + $(HTML_APPHISTORY) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 +endif +endif + +endif + +release_spec: + + + diff --git a/lib/asn1/doc/src/Seq.asn b/lib/asn1/doc/src/Seq.asn new file mode 100644 index 0000000000..2f2c48cf02 --- /dev/null +++ b/lib/asn1/doc/src/Seq.asn @@ -0,0 +1,37 @@ +GUI DEFINITIONS AUTOMATIC TAGS ::= + +BEGIN + +Action ::= SEQUENCE + { + number INTEGER DEFAULT 15, + handle [0] Handle DEFAULT {number 12, on TRUE} + } + +Key ::= [11] EXPLICIT Button +Handle ::= [12] Key +Button ::= SEQUENCE + { + number INTEGER, + on BOOLEAN + } + +Window ::= CHOICE + { + vsn INTEGER, + status E + } + +Status ::= SEQUENCE + { + state INTEGER, + buttonList SEQUENCE OF Button, + enabled BOOLEAN OPTIONAL, + actions CHOICE { + possibleActions SEQUENCE OF Action, + noOfActions INTEGER + } + } + + +END diff --git a/lib/asn1/doc/src/Seq.asn1config b/lib/asn1/doc/src/Seq.asn1config new file mode 100644 index 0000000000..571cf4cd32 --- /dev/null +++ b/lib/asn1/doc/src/Seq.asn1config @@ -0,0 +1,3 @@ +{exclusive_decode,{'GUI', + [{decode_Window_exclusive,['Window',[{status,[{buttonList,parts},{actions,undecoded}]}]]}, + {decode_Button_exclusive,['Button',[{number,undecoded}]]}]}}. diff --git a/lib/asn1/doc/src/asn1_spec.xmlsrc b/lib/asn1/doc/src/asn1_spec.xmlsrc new file mode 100644 index 0000000000..8d61834da8 --- /dev/null +++ b/lib/asn1/doc/src/asn1_spec.xmlsrc @@ -0,0 +1,824 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Specialized Decodes</title> + <prepared>EAB/UAB/UKH/KD Bertil Karlsson</prepared> + <docno></docno> + <date>2003-04-24</date> + <rev>D</rev> + <file>asn1_spec.xml</file> + </header> + <marker id="SpecializedDecodes"></marker> + <p>When performance is of highest priority and one is interested in + a limited part of the ASN.1 encoded message, before one decide what + to do with the rest of it, one may want to decode only this small + part. The situation may be a server that has to decide to which + addressee it will send a message. The addressee may be interested in + the entire message, but the server may be a bottleneck that one want + to spare any unnecessary load. Instead of making two <em>complete decodes</em> (the normal case of decode), one in the server and one + in the addressee, it is only necessary to make one <em>specialized decode</em>(in the server) and another complete decode(in the + addressee). The following specialized decodes <em>exclusive decode</em> and <em>selected decode</em> support to solve this and + similar problems. + </p> + <p>So far this functionality is only provided when using the + optimized BER_BIN version, that is when compiling with the + options <c>ber_bin</c> and <c>optimize</c>. It does also work + using the <c>driver</c> option. We have no intent to make this + available on the default BER version, but maybe in the PER_BIN + version (<c>per_bin</c>). + </p> + + <section> + <title>Exclusive Decode</title> + <p>The basic idea with exclusive + decode is that you specify which parts of the message you want to + exclude from being decoded. These parts remain encoded and are + returned in the value structure as binaries. They may be decoded + in turn by passing them to a certain <c>decode_part/2</c> + function. The performance gain is high when the message is large + and you can do an exclusive decode and later on one or several + decodes of the parts or a second complete decode instead of two or + more complete decodes. + </p> + + <section> + <title>How To Make It Work</title> + <p>In order to make exclusive decode work you have to do the + following: + </p> + <list type="bulleted"> + <item>First,decide the name of the function for the exclusive + decode.</item> + <item>Second, write instructions that must consist of the name + of the exclusive decode function, the name of the ASN.1 + specification and a notation that tells which parts of the + message structure will be excluded from decode. These + instructions shall be included in a configuration + file. </item> + <item>Third, compile with the additional option + <c>asn1config</c>. The compiler searches for a configuration + file with the same name as the ASN.1 spec but with the + extension .asn1config. This configuration file is not the same + as used for compilation of a set of files. See section + <seealso marker="#UndecodedPart">Writing an Exclusive Decode Instruction.</seealso></item> + </list> + </section> + + <section> + <title>User Interface</title> + <p>The run-time user interface for exclusive decode consists of + two different functions. First, the function for an exclusive + decode, whose name the user decides in the configuration + file. Second, the compiler generates a <c>decode_part/2</c> + function when exclusive decode is chosen. This function decodes + the parts that were left undecoded during the exclusive + decode. Both functions are described below. + </p> + <p>If the exclusive decode function has for example got the name + <c>decode_exclusive</c> and an ASN.1 encoded message + <c>Bin</c> shall be exclusive decoded, the call is:</p> + <pre> +{ok,Excl_Message} = 'MyModule':decode_exclusive(Bin) </pre> + <marker id="UndecodedPart"></marker> + <p>The result <c>Excl_Message</c> has the same structure as an + complete decode would have, except for the parts of the top-type + that were not decoded. The undecoded parts will be on their place + in the structure on the format <c>{Type_Key,Undecoded_Value}</c>. + </p> + <p>Each undecoded part that shall be decoded must be fed into the <c>decode_part/2</c> function,like:</p> + <pre> +{ok,Part_Message} = 'MyModule':decode_part(Type_Key,Undecoded_Value) </pre> + </section> + + <section> + <marker id="Exclusive Instruction"></marker> + <title>Writing an Exclusive Decode Instruction</title> + <p>This instruction is written in the configuration file on the + format:</p> + <pre> + +Exclusive_Decode_Instruction = {exclusive_decode,{Module_Name,Decode_Instructions}}. + +Module_Name = atom() + +Decode_Instructions = [Decode_Instruction]+ + +Decode_Instruction = {Exclusive_Decode_Function_Name,Type_List} + +Exclusive_Decode_Function_Name = atom() + +Type_List = [Top_Type,Element_List] + +Element_List = [Element]+ + +Element = {Name,parts} | + {Name,undecoded} | + {Name,Element_List} + +Top_Type = atom() + +Name = atom() + </pre> + <p>Observe that the instruction must be a valid Erlang term ended + by a dot. + </p> + <p>In the <c>Type_List</c> the "path" from the top type to each + undecoded sub-components is described. The top type of the path is + an atom, the name of it. The action on each component/type that + follows will be described by one of <c>{Name,parts}, {Name,undecoded}, {Name,Element_List}</c></p> + <p>The use and effect of the actions are: + </p> + <list type="bulleted"> + <item><c>{Name,undecoded}</c> Tells that the element will be + left undecoded during the exclusive decode. The type of Name may + be any ASN.1 type. The value of element Name will be returned as a + tuple,as mentioned <seealso marker="#UndecodedPart">above</seealso>, in the value structure of the top type.</item> + <item><c>{Name,parts}</c> The type of Name may be one of + SEQUENCE OF or SET OF. The action implies that the different + components of Name will be left undecoded. The value of Name + will be returned as a tuple, as <seealso marker="#UndecodedPart">above </seealso>, where the second element is a list of + binaries. That is because the representation of a SEQUENCE OF/ + SET OF in Erlang is a list of its internal type. Any of the + elements of this list or the entire list can be decoded by the + <c>decode_part</c> function.</item> + <item><c>{Name,Element_List}</c>This action is used when one or + more of the sub-types of Name will be exclusive decoded.</item> + </list> + <p>Name in the actions above may be a component name of a + SEQUENCE or a SET or a name of an alternative in a CHOICE. + </p> + </section> + + <section> + <title>Example</title> + <p>In the examples below we use the definitions from the following ASN.1 spec:</p> + <marker id="Asn1spec"></marker> + <codeinclude file="Seq.asn" tag="" type="none"></codeinclude> + <p>If <c>Button</c> is a top type and we want to exclude + component <c>number</c> from decode the Type_List in the + instruction in the configuration file will be + <c>['Button',[{number,undecoded}]]</c>. If we call the decode + function <c>decode_Button_exclusive</c> the Decode_Instruction + will be + <c>{decode_Button_exclusive,['Button',[{number,undecoded}]]}</c>. + </p> + <p>We also have another top type <c>Window</c> whose sub + component actions in type <c>Status</c> and the parts of component + <c>buttonList</c> shall be left undecoded. For this type we name + the function <c>decode__Window_exclusive</c>. The whole + Exclusive_Decode_Instruction configuration is as follows: </p> + <codeinclude file="Seq.asn1config" tag="" type="none"></codeinclude> + <p></p> + <image file="exclusive_Win_But.gif"> + <icaption>Figure symbolizes the bytes of a Window:status message. The components buttonList and actions are excluded from decode. Only state and enabled are decoded when decode__Window_exclusive is called. </icaption> + </image> + <p></p> + <p>Compiling GUI.asn including the configuration file is done like:</p> + <pre> +unix> erlc -bber_bin +optimize +asn1config GUI.asn + +erlang> asn1ct:compile('GUI',[ber_bin,optimize,asn1config]). </pre> + <p>The module can be used like:</p> + <pre> + +1> Button_Msg = {'Button',123,true}. +{'Button',123,true} +2> {ok,Button_Bytes} = 'GUI':encode('Button',Button_Msg). +{ok,[<<48>>, + [6], + [<<128>>, + [1], + 123], + [<<129>>, + [1], + 255]]} +3> {ok,Exclusive_Msg_Button} = 'GUI':decode_Button_exclusive(list_to_binary(Button_Bytes)). +{ok,{'Button',{'Button_number',<<28,1,123>>}, + true}} +4> 'GUI':decode_part('Button_number',<<128,1,123>>). +{ok,123} +5> Window_Msg = +{'Window',{status,{'Status',35, + [{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}], + false, + {possibleActions,[{'Action',16,{'Button',17,true}}]}}}}. +{'Window',{status,{'Status',35, + [{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}], + false, + {possibleActions,[{'Action',16,{'Button',17,true}}]}}}} +6> {ok,Window_Bytes}='GUI':encode('Window',Window_Msg). +{ok,[<<161>>, + [127], + [<<128>>, ... + + +8> {ok,{status,{'Status',Int,{Type_Key_SeqOf,Val_SEQOF}, +BoolOpt,{Type_Key_Choice,Val_Choice}}}}= +'GUI':decode_Window_status_exclusive(list_to_binary(Window_Bytes)). +{ok,{status,{'Status',35, + {'Status_buttonList',[<<48,6,128,1,3,129,1,255>>, + <<48,6,128,1,4,129,1,0>>, + <<48,6,128,1,5,129,1,255>>, + <<48,6,128,1,6,129,1,255>>, + <<48,6,128,1,7,129,1,0>>, + <<48,6,128,1,8,129,1,255>>, + <<48,6,128,1,9,129,1,255>>, + <<48,6,128,1,10,129,1,0>>, + <<48,6,128,1,11,129,1,255>>, + <<48,6,128,1,12,129,1,255>>, + <<48,6,128,1,13,129,1,0>>, + <<48,6,128,1,14,129,1,255>>]}, + false, + {'Status_actions', +<<163,21,160,19,48,17,2,1,16,160,12,172,10,171,8,48,6,128,1,...>>}}}} +10> 'GUI':decode_part(Type_Key_SeqOf,Val_SEQOF). +{ok,[{'Button',3,true}, + {'Button',4,false}, + {'Button',5,true}, + {'Button',6,true}, + {'Button',7,false}, + {'Button',8,true}, + {'Button',9,true}, + {'Button',10,false}, + {'Button',11,true}, + {'Button',12,true}, + {'Button',13,false}, + {'Button',14,true}]} +11> 'GUI':decode_part(Type_Key_SeqOf,hd(Val_SEQOF)). +{ok,{'Button',3,true}} +12> 'GUI':decode_part(Type_Key_Choice,Val_Choice). +{ok,{possibleActions,[{'Action',16,{'Button',17,true}}]}} + </pre> + </section> + </section> + + <section> + <title>Selective Decode</title> + <p>This specialized decode decodes one single subtype of a + constructed value. It is the fastest method to extract one sub + value. The typical use of this decode is when one want to + inspect, for instance a version number,to be able to decide what + to do with the entire value. The result is returned as + <c>{ok,Value}</c> or <c>{error,Reason}</c>. + </p> + + <section> + <title>How To Make It Work</title> + <p>The following steps are necessary: + </p> + <list type="bulleted"> + <item>Write instructions in the configuration + file. Including the name of a user function, the name of the ASN.1 + specification and a notation that tells which part of the type + will be decoded. </item> + <item>Compile with the additional option + <c>asn1config</c>. The compiler searches for a configuration file + with the same name as the ASN.1 spec but with the extension + .asn1config. In the same file you can provide configuration specs + for exclusive decode as well. The generated Erlang module has the + usual functionality for encode/decode preserved and the + specialized decode functionality added. </item> + </list> + </section> + + <section> + <title>User Interface</title> + <p>The only new user interface function is the one provided by the + user in the configuration file. You can invoke that function by + the <c>ModuleName:FunctionName</c> notation. + </p> + <p>So, if you have the following spec + <c>{selective_decode,{'ModuleName',[{selected_decode_Window,TypeList}]}}</c> + in the con-fig file, you do the selective decode by + <c>{ok,Result}='ModuleName':selected_decode_Window(EncodedBinary).</c></p> + </section> + + <section> + <marker id="Selective Instruction"></marker> + <title>Writing a Selective Decode Instruction</title> + <p>It is possible to describe one or many selective decode + functions in a configuration file, you have to use the following + notation:</p> + <pre> +Selective_Decode_Instruction = {selective_decode,{Module_Name,Decode_Instructions}}. + +Module_Name = atom() + +Decode_Instructions = [Decode_Instruction]+ + +Decode_Instruction = {Selective_Decode_Function_Name,Type_List} + +Selective_Decode_Function_Name = atom() + +Type_List = [Top_Type|Element_List] + +Element_List = Name|List_Selector + +Name = atom() + +List_Selector = [integer()] </pre> + <p>Observe that the instruction must be a valid Erlang term ended + by a dot. + </p> + <p>The <c>Module_Name</c> is the same as the name of the ASN.1 + spec, but without the extension. A <c>Decode_Instruction</c> is + a tuple with your chosen function name and the components from + the top type that leads to the single type you want to + decode. Notice that you have to choose a name of your function + that will not be the same as any of the generated functions. The + first element of the <c>Type_List</c> is the top type of the + encoded message. In the <c>Element_List</c> it is followed by + each of the component names that leads to selected type. Each of + the names in the <c>Element_List</c> must be constructed types + except the last name, which can be any type. + </p> + <p>The List_Selector makes it possible to choose one of the + encoded components in a SEQUENCE OF/ SET OF. It is also possible + to go further in that component and pick a sub type of that to + decode. So in the <c>Type_List</c>: <c>['Window',status,buttonList,[1],number]</c> the + component <c>buttonList</c> has to be a SEQUENCE OF or SET OF type. In + this example component <c>number</c> of the first of the encoded + elements in the SEQUENCE OF <c>buttonList</c> is selected. This apply on + the ASN.1 spec <seealso marker="#Asn1spec">above</seealso>. + </p> + </section> + + <section> + <title>Another Example</title> + <p>In this example we use the same ASN.1 spec as <seealso marker="#Asn1spec">above</seealso>. A valid selective decode + instruction is:</p> + <pre> +{selective_decode, + {'GUI', + [{selected_decode_Window1, + ['Window',status,buttonList, + [1], + number]}, + {selected_decode_Action, + ['Action',handle,number]}, + {selected_decode_Window2, + ['Window', + status, + actions, + possibleActions, + [1], + handle,number]}]}}. + </pre> + <p>The first <c>Decode_Instruction</c>, + <c>{selected_decode_Window1,['Window',status,buttonList,[1],number]}</c> + is commented in the previous section. The instruction + <c>{selected_decode_Action,['Action',handle,number]}</c> picks + the component <c>number</c> in the <c>handle</c> component of the type + <c>Action</c>. If we have the value <c>ValAction = {'Action',17,{'Button',4711,false}}</c> the internal value 4711 + should be picked by <c>selected_decode_Action</c>. In an Erlang + terminal it looks like:</p> + <pre> +ValAction = {'Action',17,{'Button',4711,false}}. +{'Action',17,{'Button',4711,false}} +7> {ok,Bytes}='GUI':encode('Action',ValAction). +... +8> BinBytes = list_to_binary(Bytes). +<<48,18,2,1,17,160,13,172,11,171,9,48,7,128,2,18,103,129,1,0>> +9> 'GUI':selected_decode_Action(BinBytes). +{ok,4711} +10> </pre> + <p>The third instruction, + <c>['Window',status,actions,possibleActions,[1],handle,number]</c>, + which is a little more complicated,</p> + <list type="bulleted"> + <item>starts with type <em>Window</em>. </item> + <item>Picks component <em>status</em> of <c>Window</c> that is + of type <c>Status</c>.</item> + <item>Then takes component <em>actions</em> of type + <c>Status</c>.</item> + <item>Then <em>possibleActions</em> of the internal defined + CHOICE type.</item> + <item>Thereafter it goes into the first component of the + SEQUENCE OF by <em>[1]</em>. That component is of type + <c>Action</c>.</item> + <item>The instruction next picks component + <em>handle</em>.</item> + <item>And finally component <em>number</em> of the type + <c>Button</c>.</item> + </list> + <p>The following figures shows which components are in the + TypeList + <c>['Window',status,actions,possibleActions,[1],handle,number]</c>. And + which part of a message that will be decoded by + selected_decode_Window2. + </p> + <p></p> + <image file="selective_TypeList.gif"> + <icaption>The elements specified in the config file for selective decode of a sub-value in a Window message</icaption> + </image> + <p></p> + <image file="selective_Window2.gif"> + <icaption>Figure symbolizes the bytes of a Window:status message. Only the marked element is decoded when selected_decode_Window2 is called. </icaption> + </image> + <p>With the following example you can examine that both + <c>selected_decode_Window2</c> and + <c>selected_decode_Window1</c> decodes the intended sub-value + of the value <c>Val</c></p> + <pre> +1> Val = {'Window',{status,{'Status',12, + [{'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}], + true, + {possibleActions,[{'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}]}}}} +2> {ok,Bytes}='GUI':encode('Window',Val). +... +3> Bin = list_to_binary(Bytes). +<<161,101,128,1,12,161,32,48,6,128,1,13,129,1,255,48,6,128,1,14,129,1,0,48,6,128,1,15,129,...>> +4> 'GUI':selected_decode_Window1(Bin). +{ok,13} +5> 'GUI':selected_decode_Window2(Bin). +{ok,18} </pre> + <p>Observe that the value feed into the selective decode + functions must be a binary. + </p> + </section> + </section> + + <section> + <title>Performance</title> + <p>To give an indication on the possible performance gain using + the specialized decodes, some measures have been performed. The + relative figures in the outcome between selective, exclusive and + complete decode (the normal case) depends on the structure of + the type, the size of the message and on what level the + selective and exclusive decodes are specified. + </p> + + <section> + <title>ASN.1 Specifications, Messages and Configuration</title> + <p>The specs <seealso marker="#Asn1spec">GUI</seealso> and + <url href="http://www.itu.int/ITU-T/asn1/database/itu-t/h/h248/2002/MEDIA-GATEWAY-CONTROL.html">MEDIA-GATEWAY-CONTROL</url> + was used in the test. + </p> + <p>For the GUI spec the configuration looked like:</p> + <pre> +{selective_decode, + {'GUI', + [{selected_decode_Window1, + ['Window', + status,buttonList, + [1], + number]}, + {selected_decode_Window2, + ['Window', + status, + actions, + possibleActions, + [1], + handle,number]}]}}. + {exclusive_decode, + {'GUI', + [{decode_Window_status_exclusive, + ['Window', + [{status, + [{buttonList,parts}, + {actions,undecoded}]}]]}]}}. + </pre> + <p>The MEDIA-GATEWAY-CONTROL configuration was:</p> + <pre> +{exclusive_decode, + {'MEDIA-GATEWAY-CONTROL', + [{decode_MegacoMessage_exclusive, + ['MegacoMessage', + [{authHeader,undecoded}, + {mess, + [{mId,undecoded}, + {messageBody,undecoded}]}]]}]}}. +{selective_decode, + {'MEDIA-GATEWAY-CONTROL', + [{decode_MegacoMessage_selective, + ['MegacoMessage',mess,version]}]}}. + </pre> + <p>The corresponding values were:</p> + <pre> +{'Window',{status,{'Status',12, + [{'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}, + {'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}, + {'Button',13,true}, + {'Button',14,false}, + {'Button',15,true}, + {'Button',16,false}], + true, + {possibleActions, + [{'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}, + {'Action',17,{'Button',18,false}}, + {'Action',19,{'Button',20,true}}, + {'Action',21,{'Button',22,false}}]}}}} + + +{'MegacoMessage',asn1_NOVALUE, + {'Message',1, + {ip4Address, + {'IP4Address',[125,125,125,111],55555}}, + {transactions, + [{transactionReply, + {'TransactionReply',50007,asn1_NOVALUE, + {actionReplies, + [{'ActionReply',0,asn1_NOVALUE,asn1_NOVALUE, + [{auditValueReply,{auditResult,{'AuditResult', + {'TerminationID',[],[255,255,255]}, + [{mediaDescriptor, + {'MediaDescriptor',asn1_NOVALUE, + {multiStream, + [{'StreamDescriptor',1, + {'StreamParms', + {'LocalControlDescriptor', + sendRecv, + asn1_NOVALUE, + asn1_NOVALUE, + [{'PropertyParm', + [0,11,0,7], + [[52,48]], + asn1_NOVALUE}]}, + {'LocalRemoteDescriptor', + [[{'PropertyParm', + [0,0,176,1], + [[48]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,8], + [[73,78,32,73,80,52,32,49,50,53,46,49, + 50,53,46,49,50,53,46,49,49,49]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,15], + [[97,117,100,105,111,32,49,49,49,49,32, + 82,84,80,47,65,86,80,32,32,52]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,12], + [[112,116,105,109,101,58,51,48]], + asn1_NOVALUE}]]}, + {'LocalRemoteDescriptor', + [[{'PropertyParm', + [0,0,176,1], + [[48]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,8], + [[73,78,32,73,80,52,32,49,50,52,46,49,50, + 52,46,49,50,52,46,50,50,50]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,15], + [[97,117,100,105,111,32,50,50,50,50,32,82, + 84,80,47,65,86,80,32,32,52]], + asn1_NOVALUE}, + {'PropertyParm', + [0,0,176,12], + [[112,116,105,109,101,58,51,48]], + asn1_NOVALUE}]]}}}]}}}, + {packagesDescriptor, + [{'PackagesItem',[0,11],1}, + {'PackagesItem',[0,11],1}]}, + {statisticsDescriptor, + [{'StatisticsParameter',[0,12,0,4],[[49,50,48,48]]}, + {'StatisticsParameter',[0,11,0,2],[[54,50,51,48,48]]}, + {'StatisticsParameter',[0,12,0,5],[[55,48,48]]}, + {'StatisticsParameter',[0,11,0,3],[[52,53,49,48,48]]}, + {'StatisticsParameter',[0,12,0,6],[[48,46,50]]}, + {'StatisticsParameter',[0,12,0,7],[[50,48]]}, + {'StatisticsParameter',[0,12,0,8],[[52,48]]}]}]}}}]}]}}}]}}} + </pre> + <p>The size of the encoded values was 458 bytes for GUI and 464 + bytes for MEDIA-GATEWAY-CONTROL. + </p> + </section> + + <section> + <title>Results</title> + <p>The ASN.1 specs in the test are compiled with the options + <c>ber_bin, optimize, driver</c> and <c>asn1config</c>. If the + <c>driver</c> option had been omitted there should have been + higher values for <c>decode</c> and <c>decode_part</c>. + </p> + <p>The test program runs 10000 decodes on the value, resulting + in a printout with the elapsed time in microseconds for the + total number of decodes. + </p> + <table> + <row> + <cell align="left" valign="top"><em>Function</em></cell> + <cell align="left" valign="top"><em>Time</em>(microseconds)</cell> + <cell align="left" valign="top"><em>Kind of Decode</em></cell> + <cell align="left" valign="top"><em>ASN.1 spec</em></cell> + <cell align="left" valign="top"><em>% of time vs. complete decode</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_MegacoMessage_selective/1</c></cell> + <cell align="left" valign="middle"><c>374045</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>8.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_MegacoMessage_exclusive/1</c></cell> + <cell align="left" valign="middle"><c>621107</c></cell> + <cell align="left" valign="middle"><c>exclusive</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>13.8</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>4507457</c></cell> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selected_decode_Window1/1</c></cell> + <cell align="left" valign="middle"><c>449585</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>7.6</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selected_decode_Window2/1</c></cell> + <cell align="left" valign="middle"><c>890666</c></cell> + <cell align="left" valign="middle"><c>selective</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>15.1</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode_Window_status_exclusive/1</c></cell> + <cell align="left" valign="middle"><c>1251878</c></cell> + <cell align="left" valign="middle"><c>exclusive</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>21.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>5889197</c></cell> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <tcaption>Results of complete, exclusive and selective decode</tcaption> + </table> + <p>Another interesting question is what the relation is between + a complete decode, an exclusive decode followed by + <c>decode_part</c> of the excluded parts and a selective decode + followed by a complete decode. Some situations may be compared to + this simulation, e.g. inspect a sub-value and later on look at + the entire value. The following table shows figures from this + test. The number of loops and time unit is the same as in the + previous test. + </p> + <table> + <row> + <cell align="left" valign="top"><em>Actions</em></cell> + <cell align="left" valign="top"><em>Function</em> </cell> + <cell align="left" valign="top"><em>Time</em>(microseconds)</cell> + <cell align="left" valign="top"><em>ASN.1 spec</em></cell> + <cell align="left" valign="top"><em>% of time vs. complete decode</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>4507457</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>decode_­MegacoMessage_­selective/1</c></cell> + <cell align="left" valign="middle"><c>4881502</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>108.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>exclusive and decode_part</c></cell> + <cell align="left" valign="middle"><c>decode_­MegacoMessage_­exclusive/1</c></cell> + <cell align="left" valign="middle"><c>5481034</c></cell> + <cell align="left" valign="middle"><c>MEDIA-GATEWAY-CONTROL</c></cell> + <cell align="left" valign="middle"><em>112.3</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>complete</c></cell> + <cell align="left" valign="middle"><c>decode/2</c></cell> + <cell align="left" valign="middle"><c>5889197</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>100</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>selected_­decode_­Window1/1</c></cell> + <cell align="left" valign="middle"><c>6337636</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>107.6</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>selective and complete</c></cell> + <cell align="left" valign="middle"><c>selected_­decode_­Window2/1</c></cell> + <cell align="left" valign="middle"><c>6795319</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>115.4</em></cell> + </row> + <row> + <cell align="left" valign="middle"><c>exclusive and decode_part</c></cell> + <cell align="left" valign="middle"><c>decode_­Window_­status_­exclusive/1</c></cell> + <cell align="left" valign="middle"><c>6249200</c></cell> + <cell align="left" valign="middle"><c>GUI</c></cell> + <cell align="left" valign="middle"><em>106.1</em></cell> + </row> + <tcaption>Results of complete, exclusive + decode_part and selective + complete decodes</tcaption> + </table> + <p>Other ASN.1 types and values can differ much from these + figures. Therefore it is important that you, in every case where + you intend to use either of these decodes, perform some tests + that shows if you will benefit your purpose. + </p> + </section> + + <section> + <title>Comments</title> + <p>Generally speaking the gain of selective and exclusive decode + in advance of complete decode is greater the bigger value and the + less deep in the structure you have to decode. One should also + prefer selective decode instead of exclusive decode if you are + interested in just one single sub-value.</p> + <p>Another observation is that the exclusive decode followed by + decode_part decodes is very attractive if the parts will be sent + to different servers for decoding or if one in some cases not is + interested in all parts.</p> + <p>The fastest selective decode are when the decoded type is a + primitive type and not so deep in the structure of the top + type. The <c>selected_decode_Window2</c> decodes a big constructed + value, which explains why this operation is relatively slow.</p> + <p>It may vary from case to case which combination of + selective/complete decode or exclusive/part decode is the fastest.</p> + </section> + </section> +</chapter> + diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml new file mode 100644 index 0000000000..f2cd073ec8 --- /dev/null +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -0,0 +1,1981 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Asn1</title> + <prepared>ETX/DN/SP Kenneth. Lundin</prepared> + <docno></docno> + <date>1999-03-25</date> + <rev>D</rev> + <file>asn1_ug.xml</file> + </header> + + <section> + <title>Introduction</title> + + <section> + <title>Features</title> + <p>The Asn1 application provides: + </p> + <list type="bulleted"> + <item>An ASN.1 compiler for Erlang, which generates encode and + decode functions to be used by Erlang programs sending and + receiving ASN.1 specified data.</item> + <item>Run-time functions used by the generated code.</item> + <item>Encoding rules supported are <em>BER</em>, the + specialized BER version <em>DER</em> and the basic form of + aligned and unaligned variants of <em>PER</em>.</item> + </list> + </section> + + <section> + <title>Overview</title> + <p>ASN.1 (Abstract Syntax Notation 1) defines the abstract + syntax of information. The purpose of ASN.1 is to have + a platform independent language to express types using a + standardized set of rules for the transformation of values of + a defined type, into a stream of bytes. This stream of bytes + can then be sent on a communication channel set up by the + lower layers in the stack of communication protocols e.g. + TCP/IP or encapsulated within UDP packets. This way, two + different applications written in two completely different + programming languages running on different computers with + different internal representation of data can exchange + instances of structured data types (instead of exchanging + bytes or bits). This makes programming faster and easier since no code + has to be written to process the transport format of the + data. + </p> + <p>To write a network application which processes ASN.1 encoded + messages, it is prudent and sometimes essential to have a set + of off-line development tools such as an ASN.1 compiler which + can generate the encode and decode logic for the specific ASN.1 + data types. It is also necessary to combine this with some + general language-specific runtime support for ASN.1 encoding and + decoding. + </p> + <p>The ASN.1 compiler must be directed towards a target language + or a set of closely related languages. This manual describes a + compiler which is directed towards the functional language + Erlang. In order to use this compiler, familiarity with the + language Erlang is essential. Therefore, the runtime support for ASN.1 is + also closely related to the language Erlang and + consist of a number of functions, which the + compiler uses. The types in ASN.1 and how to represent + values of those types in Erlang are described in this manual. + </p> + <p>The following document is structured so that the first part describes + how to use ASN.1 compiler, and then there are descriptions of all + the primitive and constructed ASN.1 types and their representation + in Erlang, + </p> + </section> + + <section> + <title>Prerequisites</title> + <p>It is assumed that the reader is familiar with the ASN.1 notation + as documented in the standard definition [<cite id="X.680"></cite>] which is + the primary text. It may also be helpful, but not necessary, + to read the standard definitions + [<cite id="X.681"></cite>] [<cite id="X.682"></cite>] [<cite id="X.683"></cite>] + [<cite id="X.690"></cite>] [<cite id="X.691"></cite>]. </p> + <p>A very good book explaining those reference texts is + [<cite id="DUBUISSON"></cite>], free to download at + <url href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html </url>. + </p> + <p>Knowledge of Erlang programming is also essential and reading the book + <em>Concurrent Programming in ERLANG</em>, + [<cite id="erlbook2"></cite>], is recommended. Part 1 of this is available on the web in + <url href="http://www.erlang.org/download/erlang-book-part1.pdf">PDF</url> format. + </p> + </section> + + <section> + <title>Capability</title> + <p>This application covers all features of ASN.1 up to the 1997 + edition of the specification. In the 2002 edition some new + extensions came up of which there are support only for some of + them. ECN (Cncoding Control Notation) and XML notation are still + unsupported. Though, the other features of 2002 edition are + fully or partly supported as shown below:</p> + <list type="bulleted"> + <item> + <p>Decimal notation (e.g., "1.5e3") for REAL values. The + NR1, NR2 and NR3 formats as explained in ISO6093 are + supported.</p> + </item> + <item> + <p>The RELATIVE-OID type for relative object identifiers are + fully supported.</p> + </item> + <item> + <p>The subtype constraint (CONTAINING/ENCODED BY) to + constrain the content of an octet string or a bit string is + parsed when compiling, but no further action is taken. This + constraint is not a PER-visible constraint.</p> + </item> + <item> + <p>The subtype constraint by regular expressions (PATTERN) for character string types is parsed when compiling, but no further action is taken. This constraint is not a PER-visible constraint.</p> + </item> + <item> + <p>Multiple-line comments as in C, <c>/* ... */</c>, are + supported.</p> + </item> + </list> + <p>It should also be added here that the encoding formats + supported are <em>BER</em>, <em>DER</em>, <em>PER aligned + basic</em> variant and <em>PER unaligned basic</em> variant.</p> + </section> + + </section> + + <section> + <title>Getting Started with Asn1</title> + + <section> + <title>A First Example</title> + <p>The following example demonstrates the basic functionality used to run + the Erlang ASN.1 compiler.</p> + <p>First, create a file called <c>People.asn</c> containing the following:</p> + <pre> +People DEFINITIONS IMPLICIT TAGS ::= + +BEGIN +EXPORTS Person; + +Person ::= [PRIVATE 19] SEQUENCE { + name PrintableString, + location INTEGER {home(0),field(1),roving(2)}, + age INTEGER OPTIONAL } +END </pre> + <p>This file (<c>people.asn</c>) must be compiled before it can be + used. + The ASN.1 compiler checks that the syntax is correct and that the + text represents proper ASN.1 code before generating an abstract + syntax tree. The code-generator then uses the abstract syntax + tree in order to generate code. + </p> + <p>The generated Erlang files will be placed in the current directory or + in the directory specified with the <c>{outdir,Dir}</c> option. + The following shows how the compiler + can be called from the Erlang shell:</p> + <pre> +1><input>asn1ct:compile("People",[ber_bin]).</input> +Erlang ASN.1 compiling "People.asn" +--{generated,"People.asn1db"}-- +--{generated,"People.hrl"}-- +--{generated,"People.erl"}-- +ok +2> </pre> + <p>The ASN.1 module People is now accepted and the abstract syntax tree + is saved in the <c>People.asn1db</c> file, the + generated Erlang code is compiled using the Erlang compiler and + loaded into the Erlang runtime system. Now there is a user interface + of encode/2 and decode/2 in the module People, which is invoked by: + <br></br> +<c><![CDATA['People':encode(<Type name>,<Value>),]]></c> <br></br> + + or <br></br> +<c><![CDATA['People':decode(<Type name>,<Value>),]]></c> <br></br> + + Alternatively one can use the <c><![CDATA[asn1rt:encode(<Module name> ,<Type name>,<Value>)]]></c> and <c><![CDATA[asn1rt:decode(< Module name>,<Type name>,<Value>)]]></c> calls. + However, they are not as efficient as the previous methods since they + result in an additional <c>apply/3</c> call.</p> + <p>Assume there is a network + application which receives instances of the ASN.1 defined + type Person, modifies and sends them back again:</p> + <code type="none"> +receive + {Port,{data,Bytes}} -> + case 'People':decode('Person',Bytes) of + {ok,P} -> + {ok,Answer} = 'People':encode('Person',mk_answer(P)), + Port ! {self(),{command,Answer}}; + {error,Reason} -> + exit({error,Reason}) + end + end, </code> + <p>In the example above, a series of bytes is received from an + external source and the bytes are then decoded into a valid + Erlang term. This was achieved with the call + <c>'People':decode('Person',Bytes)</c> which returned + an Erlang value of the ASN.1 type <c>Person</c>. Then an answer was + constructed and encoded using + <c>'People':encode('Person',Answer)</c> which takes an + instance of a defined ASN.1 type and transforms it to a + (possibly) nested list of bytes according to the BER or PER + encoding-rules. + <br></br> +The encoder and the decoder can also be run from + the shell. The following dialogue with the shell illustrates + how the functions + <c>asn1rt:encode/3</c> and <c>asn1rt:decode/3</c> are used.</p> + <pre> +2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input> +{'Person',"Some Name",roving,50} +3> <input>{ok,Bytes} = asn1rt:encode('People','Person',Rockstar).</input> +{ok,[<<243>>, + [17], + [19,9,"Some Name"], + [2,1,[2]], + [2,1,"2"]]} +4> <input>Bin = list_to_binary(Bytes).</input> +<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,2,1,50>> +5> <input>{ok,Person} = asn1rt:decode('People','Person',Bin).</input> +{ok,{'Person',"Some Name",roving,50}} +6> </pre> + <p>Notice that the result from <c>encode</c> is a nested list which + must be turned into a binary before the call to <c>decode</c>. A + binary is necessary as input to decode since the module was compiled + with the <c>ber_bin</c> option + The reason for returning a nested list is that it is faster to produce + and the <c>list_to_binary</c> operation is + performed automatically when the list is sent via the Erlang port mechanism.</p> + </section> + + <section> + <title>Module dependencies</title> + <p>It is common that asn1 modules import defined types, values and + other entities from another asn1 module.</p> + <p>Earlier versions of the asn1 compiler required that modules that + were imported from had to be compiled before the module that + imported. This caused problems when asn1 modules had circular + dependencies.</p> + <p>Now are referenced modules parsed when the compiler finds an + entity that is imported. There will not be any code generated for + the referenced module. However, the compiled module rely on + that the referenced modules also will be compiled.</p> + </section> + </section> + + <section> + <title>The Asn1 Application User Interface</title> + <p>The Asn1 application provides two separate user interfaces:</p> + <list type="bulleted"> + <item> + <p>The module <c>asn1ct</c> which provides the compile-time functions + (including the compiler).</p> + </item> + <item> + <p>The module <c>asn1rt</c> which provides the run-time functions. + However, it is preferable to use the generated <c>encode/2</c> and + <c>decode/2</c> functions in each module, ie. + Module:encode(Type,Value), in favor of the <c>asn1rt</c> + interface.</p> + </item> + </list> + <p>The reason for the division of the interface into compile-time + and run-time + is that only run-time modules (<c>asn1rt*</c>) need to be loaded in + an embedded system. + </p> + + <section> + <title>Compile-time Functions</title> + <p>The ASN.1 compiler can be invoked directly from the command-line + by means of the <c>erlc</c> program. This is convenient when compiling + many ASN.1 files from the command-line or when using Makefiles. + Here are some examples of how the <c>erlc</c> command can be used to invoke the + ASN.1 compiler:</p> + <pre> +erlc Person.asn +erlc -bper_bin Person.asn +erlc -bber_bin +optimize ../Example.asn +erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn </pre> + <p>The useful options for the ASN.1 compiler are:</p> + <taglist> + <tag><c>-b[ber | per | ber_bin | per_bin | uper_bin]</c></tag> + <item> + <p>Choice of encoding rules, if omitted <c>ber</c> is the + default. The <c>ber_bin</c> and <c>per_bin</c> options + allows for optimizations and are therefore recommended + instaed of the <c>ber</c> and <c>per</c> options.</p> + </item> + <tag><c>-o OutDirectory</c></tag> + <item> + <p>Where to put the generated files, default is the current + directory.</p> + </item> + <tag><c>-I IncludeDir</c></tag> + <item> + <p>Where to search for <c>.asn1db</c> files and asn1 + source specs in order to resolve references to other + modules. This option can be repeated many times if there + are several places to search in. The compiler will always + search the current directory first.</p> + </item> + <tag><c>+compact_bit_string</c></tag> + <item> + <p>Gives the user the option to use a compact format of the BIT + STRING type to save memory space, typing space and + increase encode/decode performance, for details see + <seealso marker="#BIT STRING">BIT STRING </seealso>type section.</p> + </item> + <tag><c>+der</c></tag> + <item> + <p>DER encoding rule. Only when using <c>-ber</c> or + <c>-ber_bin</c> option.</p> + </item> + <tag><c>+optimize</c></tag> + <item> + <p>This flag has effect only when used together with one of + <c>per_bin</c> or <c>ber_bin</c> flags. It gives time optimized + code in the generated modules and it uses another runtime module. + In the <c>per_bin</c> case a linked-in driver is used. The + result from an encode is a binary.</p> + <p><em>When this flag is used you cannot use the old format</em><c>{TypeName,Value}</c> when you encode values. Since it is + an unnecessary construct it has been removed in favor of + performance. It + is neither admitted to construct SEQUENCE or SET component values + with the format <c>{ComponentName,Value}</c> since it also is + unnecessary. The only case were it is necessary is in a CHOICE, + were you have to pass values to the right component by specifying + <c>{ComponentName,Value}</c>. See also about + <seealso marker="#TypeNameValue">{Typename,Value}</seealso> below + and in the sections for each type.</p> + </item> + <tag><c>+driver</c></tag> + <item> + <p>Together with the flags <c>ber_bin</c> and <c>optimize</c> + you choose to use a linked in driver for considerable faster + decode.</p> + </item> + <tag><c>+asn1config</c></tag> + <item> + <p>This functionality works together with the flags + <c>ber_bin</c> and <c>optimize</c>. You enables the + specialized decodes, see the <seealso marker="asn1_spec">Specialized Decode</seealso> chapter. + </p> + </item> + <tag><c>+undec_rest</c></tag> + <item> + <p>A buffer that holds a message, being decoded may + also have some following bytes. Now it is possible to get + those following bytes returned together with the decoded + value. If an asn1 spec is compiled with this option a tuple + <c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a + list or a binary. Earlier versions of the compiler ignored + those following bytes.</p> + </item> + <tag><c>{inline,OutputName}</c></tag> + <item> + <p>Compiling with this option gives one output module + containing all asn1 run-time functionality. The asn1 specs + are provided in a target module <c>Module.set.asn</c> as + described in the <seealso marker="asn1ct#asn1set">reference manual</seealso>. The name of the resulting module + containing generated encode/decode functions and inlined + run-time functions will be <c>OutputName.erl</c>. The + merging/inlining of code is done by the <c>igor</c> module + of <c>syntax_tools</c>. By default the functions generated + from the first asn1 spec in the <c>.set.asn</c> are + exported, unless a <c>{export,[atom()]}</c> or + <c>{export_all,true}</c> option are provided. The list of + atoms are names of choosen asn1 specs from the + <c>.set.asn</c> file. See further examples of usage <seealso marker="#inlineExamples">below</seealso></p> + </item> + <tag><c>+'Any Erlc Option'</c></tag> + <item> + <p>You may add any option to the Erlang compiler when + compiling the generated Erlang files. Any option + unrecognised by the asn1 compiler will be passed to the + Erlang compiler.</p> + </item> + </taglist> + <p>For a complete description of <c>erlc</c> see Erts Reference Manual.</p> + <p>For preferred option use see <seealso marker="#preferred option use">Preferred Option Use</seealso> section.</p> + <p>The compiler and other compile-time functions can also be invoked from + the Erlang shell. Below follows a brief + description of the primary functions, for a + complete description of each function see + <seealso marker="asn1ct">the Asn1 Reference Manual</seealso>, the + <c>asn1ct</c> module.</p> + <p>The compiler is invoked by using <c>asn1ct:compile/1</c> with + default options, or <c>asn1ct:compile/2</c> if explicit options + are given. + Example:</p> + <pre> +asn1ct:compile("H323-MESSAGES.asn1"). </pre> + <p>which equals:</p> + <pre> +asn1ct:compile("H323-MESSAGES.asn1",[ber]). </pre> + <p>If one wants PER encoding with optimizations:</p> + <pre> +asn1ct:compile("H323-MESSAGES.asn1",[per_bin,optimize]). </pre> + <p>The generic encode and decode functions can be invoked like this:</p> + <pre> +asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}). +asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre> + <p>Or, preferable like:</p> + <pre> +'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}). +'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre> + </section> + + <section> + <marker id="preferred option use"></marker> + <title>Preferred Option Use</title> + <p> + It may not be obvious which compile options best fit a + situation. This section describes the format of the result of + encode and decode. It also gives some performance statistics + when using certain options. Finally there is a recommendation + which option combinations should be used. + </p> + <p> + The default option is <c>ber</c>. It is the same backend as + <c>ber_bin</c> except that the result of encode is transformed + to a flat list. Below is a table that gives the different + formats of input and output of encode and decode using the + <em>allowed combinations</em> of coding and optimization + options: (EAVF stands for how ASN1 values are represented in + Erlang which is described in the <seealso + marker="#ASN1Types">ASN1 Types chapter</seealso>) + </p> + <table> + <row> + <cell align="left" valign="middle"><em>Encoding Rule</em></cell> + <cell align="left" valign="middle"><em>Compile options, allowed combinations</em></cell> + <cell align="left" valign="middle"><em>encode input</em></cell> + <cell align="left" valign="middle"><em>encode output</em></cell> + <cell align="left" valign="middle"><em>decode input</em></cell> + <cell align="left" valign="middle"><em>decode output</em></cell> + </row> + <row> + <cell align="left" valign="middle">BER</cell> + <cell align="left" valign="middle">[ber] (default)</cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">flat list</cell> + <cell align="left" valign="middle">flat list / binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">BER</cell> + <cell align="left" valign="middle">[ber_bin]</cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">BER</cell> + <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">BER</cell> + <cell align="left" valign="middle"><em>[ber_bin, optimize, driver]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">iolist / binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">PER aligned variant</cell> + <cell align="left" valign="middle">[per]</cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">flat list</cell> + <cell align="left" valign="middle">flat list</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">PER aligned variant</cell> + <cell align="left" valign="middle"><em>[per_bin]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist / binary</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">PER aligned variant</cell> + <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">PER unaligned variant</cell> + <cell align="left" valign="middle"><em>[uper_bin]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + + <row> + <cell align="left" valign="middle">DER</cell> + <cell align="left" valign="middle">[(ber), der]</cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">flat list</cell> + <cell align="left" valign="middle">flat list / binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">DER</cell> + <cell align="left" valign="middle">[ber_bin, der]</cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">DER</cell> + <cell align="left" valign="middle"><em>[ber_bin, optimize, der]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + <row> + <cell align="left" valign="middle">DER</cell> + <cell align="left" valign="middle"><em>[ber_bin, optimize, driver, der]</em></cell> + <cell align="left" valign="middle">EAVF</cell> + <cell align="left" valign="middle">iolist</cell> + <cell align="left" valign="middle">binary</cell> + <cell align="left" valign="middle">EAVF</cell> + </row> + + + <tcaption>The output / input formats for different combinations of compile options.</tcaption> + </table> + <p> + Encode / decode speed comparison in one user case for the above + alternatives (except <c>DER</c>) is showed in the table below. The + <c>DER</c> alternatives are slower than their corresponding + <c>BER</c> alternative. + </p> + + <table> + <row> + <cell align="left" valign="middle"><em>compile options</em></cell> + <cell align="left" valign="middle"><em>encode time</em></cell> + <cell align="left" valign="middle"><em>decode time</em></cell> + </row> + <row> + <cell align="left" valign="middle">[ber]</cell> + <cell align="left" valign="middle">120</cell> + <cell align="left" valign="middle">162</cell> + </row> + <row> + <cell align="left" valign="middle">[ber_bin]</cell> + <cell align="left" valign="middle">124</cell> + <cell align="left" valign="middle">154</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell> + <cell align="left" valign="middle">50</cell> + <cell align="left" valign="middle">78</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize, driver]</em></cell> + <cell align="left" valign="middle">50</cell> + <cell align="left" valign="middle">62</cell> + </row> + <row> + <cell align="left" valign="middle">[per]</cell> + <cell align="left" valign="middle">141</cell> + <cell align="left" valign="middle">133</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[per_bin]</em></cell> + <cell align="left" valign="middle">125</cell> + <cell align="left" valign="middle">123</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell> + <cell align="left" valign="middle">77</cell> + <cell align="left" valign="middle">72</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[uper_bin]</em></cell> + <cell align="left" valign="middle">97</cell> + <cell align="left" valign="middle">104</cell> + </row> + <tcaption> + One example of difference in speed for the compile option alternatives. + </tcaption> + </table> + + <p> + The sole compile options <c>ber</c>, <c>ber_bin</c> and <c>per</c> + are kept for backwards compatibility and should not be used in + new code. + </p> + <p> + You are strongly recommended to use the appropriate alternative + of the bold typed options. The <c>optimize</c> and + <c>driver</c> options does not affect the encode or decode + result, just the time spent in run-time. When <c>ber_bin</c> and + <c>driver</c> or <c>per_bin, optimize</c> and <c>driver</c> is + combined the C-code driver is used in choosen parts of encode / + decode procedure. + </p> + <table> + <row> + <cell align="left" valign="middle"><em>Compile options, allowed combinations</em></cell> + <cell align="left" valign="middle"><em>use of linked-in driver</em></cell> + </row> + <row> + <cell align="left" valign="middle">[ber]</cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle">[ber_bin]</cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize, driver]</em></cell> + <cell align="left" valign="middle">yes</cell> + </row> + <row> + <cell align="left" valign="middle">[per]</cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[per_bin]</em></cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell> + <cell align="left" valign="middle">yes</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[uper_bin]</em></cell> + <cell align="left" valign="middle">no</cell> + </row> + + <row> + <cell align="left" valign="middle">[(ber), der]</cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle">[ber_bin, der]</cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize, der]</em></cell> + <cell align="left" valign="middle">no</cell> + </row> + <row> + <cell align="left" valign="middle"><em>[ber_bin, optimize, driver, der]</em></cell> + <cell align="left" valign="middle">yes</cell> + </row> + + + <tcaption>When the ASN1 linked-in driver is used.</tcaption> + </table> + + </section> + <section> + <title>Run-time Functions</title> + <p>A brief description of the major functions is given here. For a + complete description of each function see + <seealso marker="asn1rt"> the Asn1 Reference Manual</seealso>, the <c>asn1rt</c> module.</p> + <p>The generic run-time encode and decode functions can be invoked as below:</p> + <pre> +asn1rt:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}). +asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre> + <p>Or, preferable like:</p> + <pre> +'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}). +'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre> + <p>The asn1 linked-in driver is enabled in two occasions: encoding of + asn1 values when the asn1 spec is compiled with <c>per_bin</c> and + <c>optimize</c> or decode of encoded asn1 values when the asn1 spec is + compiled with <c>ber_bin</c>, <c>optimize</c> and <c>driver</c>. In + those cases the driver will be loaded automatically at the first call + to <c>encode</c>/<c>decode</c>. If one doesn't want the performance + overhead of the driver being loaded at the first call it is possible + to load the driver separately by <c>asn1rt:load_driver()</c>. </p> + <p>By invoking the function <c>info/0</c> in a generated module, one + gets information about which compiler options were used.</p> + </section> + + <section> + <title>Errors</title> + <p>Errors detected at + compile time appear on the screen together with + a line number indicating where in the source file the error + was detected. If no errors are found, an Erlang ASN.1 module will + be created as default.</p> + <p>The run-time encoders and decoders (in the <c>asn1rt</c> module) do + execute within a catch and returns <c>{ok, Data}</c> or + <c>{error, {asn1, Description}}</c> where + <c>Description</c> is + an Erlang term describing the error. </p> + </section> + </section> + + <section> + <marker id="inlineExamples"></marker> + <title>Multi File Compilation</title> + <p>There are various reasons for using a multi file compilation:</p> + <list type="bulleted"> + <item>You want to choose name for the generated module by + any reason. Maybe you need to compile the same specs for + different encoding/decoding standards.</item> + <item>You want only one resulting module.</item> + <item>If it is crucial to have a minimal system. Using + <c>{inline,OutputModule}</c> includes all necessary run-time + functions of the asn1 application, but skips those modules not + used.</item> + <item>Upgrading issues: Even if you upgrade your Erlang system + you may want to continue running the old asn1 run-time + functionality.</item> + <item>Performance issues: If you have an asn1 system with a lot + of cross references you may gain in performance. Meassurements + must be done for each case.</item> + </list> + <p>You may choose either the plain multi file compilation that just + merges the choosen asn1 specs or the <c>{inline,OutputModule}</c> + that also includes the used asn1 run-time functionality.</p> + <p>For both cases you need to specify which asn1 specs you will + compile in a module that must have the extension + <c>.set.asn</c>. You chose name of the module and provide the + names of the asn1 specs. For instance, if you have the specs + <c>File1.asn</c>, <c>File2.asn</c> and <c>File3.asn</c> your + module <c>MyModule.set.asn</c> will look like:</p> + <pre> +File1.asn +File2.asn +File3.asn </pre> + <p>If you compile with:</p> + <code type="none"> +~> erlc MyModule.set.asn </code> + <p>the result will be one merged module <c>MyModule.erl</c> with + the generated code from the three asn1 specs. But if you compile + with:</p> + <code type="none"> +~> erlc +"{inline,'OutputModule'}" MyModule.set.asn </code> + <p>the result will be a module <c>OutputModule.erl</c> that + contains all encode/decode functions for the three asn1 specs and + all used functions from the asn1 run-time modules, in this case + <c>asn1rt_ber_bin</c>. In the former case all encode/decode + functions are exported but in the latter only the encode/decode + functions of the first spec in the <c>.set.asn</c>, i.e. those + from <c>File1.asn</c>. + </p> + </section> + + <section> + <marker id="ASN1Types"></marker> + <title>The ASN.1 Types</title> + <p>This section describes the ASN.1 types including their + functionality, purpose and how values are assigned in Erlang. + </p> + <p>ASN.1 has both primitive and constructed types:</p> + <p></p> + <table> + <row> + <cell align="left" valign="middle"><em>Primitive types</em></cell> + <cell align="left" valign="middle"><em>Constructed types</em></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#BOOLEAN">BOOLEAN</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#SEQUENCE">SEQUENCE</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#INTEGER">INTEGER</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#SET">SET</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#REAL">REAL</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#CHOICE">CHOICE</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#NULL">NULL</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#SOF">SET OF and SEQUENCE OF</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#ENUMERATED">ENUMERATED</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#ANY">ANY</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#BIT STRING">BIT STRING</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#ANY">ANY DEFINED BY</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#OCTET STRING">OCTET STRING</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EXTERNAL</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#Character Strings">Character Strings</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EMBEDDED PDV</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#OBJECT IDENTIFIER">OBJECT IDENTIFIER</seealso></cell> + <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">CHARACTER STRING</seealso></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#Object Descriptor">Object Descriptor</seealso></cell> + <cell align="left" valign="middle"></cell> + </row> + <row> + <cell align="left" valign="middle"><seealso marker="#The TIME types">The TIME types</seealso></cell> + <cell align="left" valign="middle"></cell> + </row> + <tcaption>The supported ASN.1 types</tcaption> + </table> + <marker id="TypeNameValue"></marker> + <note> + <p>Values of each ASN.1 type has its own representation in Erlang + described in the following subsections. Users shall provide + these values for encoding according to the representation, as + in the example below.</p> + </note> + <pre> +Operational ::= BOOLEAN --ASN.1 definition </pre> + <p>In Erlang code it may look like:</p> + <pre> +Val = true, +{ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val), </pre> + <p>For historical reasons it is also possible to assign ASN.1 values + in Erlang using a tuple notation + with type and value as this</p> + <pre> +Val = {'Operational',true} </pre> + <warning> + <marker id="warning"></marker> + <p>The tuple notation, <c>{Typename, Value}</c> is only kept + because of backward compatibility and may be withdrawn in a + future release. If the notation is used the <c>Typename</c> + element must be spelled correctly, otherwise a run-time error + will occur. + </p> + <p>If the ASN.1 module is compiled with the flags + <c>per_bin</c> or <c>ber_bin</c> and <c>optimize</c> it is not + allowed to use the tuple notation. That possibility has been + removed due to performance reasons. Neither is it allowed to + use the <c>{ComponentName,Value}</c> notation in case of a + SEQUENCE or SET type.</p> + </warning> + <p>Below follows a description of how + values of each type can be represented in Erlang. + </p> + + <section> + <marker id="BOOLEAN"></marker> + <title>BOOLEAN</title> + <p>Booleans in ASN.1 express values that can be either + TRUE or FALSE. + The meanings assigned to TRUE or FALSE is beyond the scope + of this text. <br></br> + + In ASN.1 it is possible to have:</p> + <pre> +Operational ::= BOOLEAN + </pre> + <p>Assigning a value to the type Operational in Erlang is possible by + using the following Erlang code:</p> + <code type="erl"> +Myvar1 = true, + </code> + <p>Thus, in Erlang the atoms <c>true</c> and <c>false</c> are used + to encode a boolean value.</p> + </section> + + <section> + <marker id="INTEGER"></marker> + <title>INTEGER</title> + <p>ASN.1 itself specifies indefinitely large integers, and the Erlang + systems with versions 4.3 and higher, support very large + integers, in practice indefinitely large integers.</p> + <p>The concept of sub-typing can be applied to integers as well + as to other ASN.1 types. The details of sub-typing are not + explained here, for further info see [<cite id="X.680"></cite>]. A variety + of syntaxes are allowed when defining a type as an integer:</p> + <pre> +T1 ::= INTEGER +T2 ::= INTEGER (-2..7) +T3 ::= INTEGER (0..MAX) +T4 ::= INTEGER (0<..MAX) +T5 ::= INTEGER (MIN<..-99) +T6 ::= INTEGER {red(0),blue(1),white(2)} + </pre> + <p>The Erlang representation of an ASN.1 INTEGER is an integer or + an atom if a so called \011<c>Named NumberList</c> (see T6 above) + is specified.</p> + <p>Below is an example of Erlang code which assigns values for the + above types: </p> + <pre> +T1value = 0, +T2value = 6, +T6value1 = blue, +T6value2 = 0, +T6value3 = white + </pre> + <p>The Erlang variables above are now bound to valid instances of + ASN.1 defined types. This style of value can be passed directly + to the encoder for transformation into a series of bytes.</p> + <p>The decoder will return an atom if the value corresponds to a + symbol in the Named NumberList.</p> + </section> + + <section> + <marker id="REAL"></marker> + <title>REAL</title> + <p>In this version reals are not implemented. When they are, + the following + ASN.1 type is used:</p> + <pre> +R1 ::= REAL + </pre> + <p>Can be assigned a value in Erlang as:</p> + <pre> +R1value1 = 2.14, +R1value2 = {256,10,-2}, + </pre> + <p>In the last line note that the tuple {256,10,-2} is the real number + 2.56 in a special notation, which will encode faster than simply + stating the number as 2.56. The arity three tuple is + <c>{Mantissa,Base,Exponent}</c> i.e. Mantissa * Base^Exponent.</p> + </section> + + <section> + <marker id="NULL"></marker> + <title>NULL</title> + <p>Null is suitable in cases where supply and recognition of a value + is important but the actual value is not.</p> + <pre> +Notype ::= NULL + </pre> + <p>The NULL type can be assigned in Erlang:</p> + <pre> +N1 = 'NULL', + </pre> + <p>The actual value is the quoted atom 'NULL'.</p> + </section> + + <section> + <marker id="ENUMERATED"></marker> + <title>ENUMERATED</title> + <p>The enumerated type can be used, when the value we wish to + describe, may only take one of a set of predefined values.</p> + <pre> +DaysOfTheWeek ::= ENUMERATED { sunday(1),monday(2),tuesday(3), +\011wednesday(4),thursday(5),friday(6),saturday(7) } + </pre> + <p>For example to assign a weekday value in Erlang use the same atom + as in the <c>Enumerations</c> of the type definition:</p> + <pre> +Day1 = saturday, + </pre> + <p>The enumerated type is very similar to an integer type, when + defined with a set of predefined values. An enumerated type + differs from an integer in that it may only have specified + values, whereas an integer can also have any other value.</p> + </section> + + <section> + <marker id="BIT STRING"></marker> + <title>BIT STRING </title> + <p>The BIT STRING type can be used to model information which + is made up of arbitrary length series of bits. It is intended + to be used for a selection of flags, not for binary files. <br></br> + + In ASN.1 BIT STRING definitions may look like: + </p> + <pre> +Bits1 ::= BIT STRING +Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)} + </pre> + <p>There are four different notations available for representation of + BIT STRING values in Erlang and as input to the encode functions.</p> + <list type="ordered"> + <item>A list of binary digits (0 or 1).</item> + <item>A hexadecimal number (or an integer). This format should be + avoided, since it is easy to misinterpret a <c>BIT STRING</c> + value in this format. This format may be withdrawn in a future + release.</item> + <item>A list of atoms corresponding to atoms in the <c>NamedBitList</c> + in the BIT STRING definition.</item> + <item>As <c>{Unused,Binary}</c> where <c>Unused</c> denotes how + many trailing zero-bits 0 to 7 that are unused in the least + significant byte in <c>Binary</c>. This notation is only + available when the ASN.1 files have been compiled with the + <em>+compact_bit_string</em> flag in the option list. In + this case it is possible to use all kinds of notation when + encoding. But the result when decoding is always in the + compact form. The benefit from this notation is a more + compact notation when one has large BIT STRINGs. The + encode/decode performance is also much better in the case of + large BIT STRINGs. </item> + </list> + <note> + <p>Note that it is advised not to use the integer format of a + BIT STRING, see the second point above.</p> + </note> + <pre> +Bits1Val1 = [0,1,0,1,1], +Bits1Val2 = 16#1A, +Bits1Val3 = {3,<<0:1,1:1,0:1,1:1,1:1,0:3>>} + </pre> + <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c> and <c>Bits1Val3</c> + denote the same value.</p> + <pre> +Bits2Val1 = [gnu,punk], +Bits2Val2 = 2#1110, +Bits2Val3 = [bar,gnu,gnome], +Bits2Val4 = [0,1,1,1] + </pre> + <p>The above <c>Bits2Val2</c>, <c>Bits2Val3</c> and <c>Bits2Val4</c> + also all denote the same value.</p> + <p><c>Bits2Val1</c> is assigned symbolic values. The assignment means + that the bits corresponding to <c>gnu</c> and <c>punk</c> i.e. bits + 2 and 14 are set to 1 and the rest set to 0. The symbolic values + appear as a list of values. If a named value appears, which is not + specified in the type definition, a run-time error will occur.</p> + <p>The compact notation equivalent to the empty BIT STRING is + <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is <c>[]</c> or + <c>0</c>.</p> + <p>BIT STRINGS may also be sub-typed with for example a SIZE + specification:</p> + <pre> +Bits3 ::= BIT STRING (SIZE(0..31)) </pre> + <p>This means that no bit higher than 31 can ever be set.</p> + </section> + + <section> + <marker id="OCTET STRING"></marker> + <title>OCTET STRING</title> + <p>The OCTET STRING is the simplest of all ASN.1 types The OCTET STRING + only moves or transfers e.g. binary files or other unstructured + information complying to two rules. + Firstly, the bytes consist of octets and secondly, encoding is + not required.</p> + <p>It is possible to have the following ASN.1 type definitions:</p> + <pre> +O1 ::= OCTET STRING +O2 ::= OCTET STRING (SIZE(28)) </pre> + <p>With the following example assignments in Erlang:</p> + <pre> +O1Val = [17,13,19,20,0,0,255,254], +O2Val = "must be exactly 28 chars....", </pre> + <p>Observe that <c>O1Val</c> is assigned a series of numbers between 0 + and 255 i.e. octets. + <c>O2Val</c> is assigned using the string notation. + </p> + </section> + + <section> + <marker id="Character Strings"></marker> + <title>Character Strings</title> + <p>ASN.1 supports a wide variety of character sets. The main difference + between OCTET STRINGS and the Character strings is that OCTET + STRINGS have no imposed semantics on the bytes delivered.</p> + <p>However, when using for instance the IA5String (which closely + resembles ASCII) the byte 65 (in decimal + notation) <em>means</em> the character 'A'. + </p> + <p>For example, if a defined type is to be a VideotexString and + an octet is received with the unsigned integer value X, then + the octet should be interpreted as specified in the standard + ITU-T T.100,T.101. + </p> + <p>The ASN.1 to Erlang compiler + will not determine the correct interpretation of each BER + (Basic Encoding Rules) string octet value with different + Character strings. Interpretation of octets is the + responsibility of the application. Therefore, from the BER + string point of view, octets appear to be very similar to + character strings and are compiled in the same way. + </p> + <p>It should be noted that when PER (Packed Encoding Rules) is + used, there is a significant difference in the encoding scheme + between OCTET STRINGS and other strings. The constraints + specified for a type are especially important for PER, where + they affect the encoding. + </p> + <p>Please note that <em>all</em> the Character strings are + supported and it is possible to use the following ASN.1 type + definitions:</p> + <pre> +Digs ::= NumericString (SIZE(1..3)) +TextFile ::= IA5String (SIZE(0..64000)) </pre> + <p>and the following Erlang assignments:</p> + <pre> +DigsVal1 = "456", +DigsVal2 = "123", +TextFileVal1 = "abc...xyz...", +TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] </pre> + <p>The Erlang representation for "BMPString" and + "UniversalString" is either a list of ASCII values or a list + of quadruples. The quadruple representation associates to the + Unicode standard representation of characters. The ASCII + characters are all represented by quadruples beginning with + three zeros like {0,0,0,65} for the 'A' character. When + decoding a value for these strings the result is a list of + quadruples, or integers when the value is an ASCII character. + The following example shows how it works:</p> + <p>In a file <c>PrimStrings.asn1</c> the type <c>BMP</c> is defined as + <br></br> +<c>BMP ::= BMPString</c> then using BER encoding (<c>ber_bin</c> + option)the input/output format will be:</p> + <pre> +1> <input>{ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).</input> +{ok,[30,4,"55-8"]} +2> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes1)).</input> +{ok,[{0,0,53,53},{0,0,45,56}]} +3> <input>{ok,Bytes2} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,0,65}]).</input> +{ok,[30,4,[53,53,0,65]]} +4> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes2)).</input> +{ok,[{0,0,53,53},65]} +5> <input>{ok,Bytes3} = asn1rt:encode('PrimStrings','BMP',"BMP string").</input> +{ok,[30,20,[0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103]]} +6> <input>asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes3)).</input> +{ok,"BMP string"} </pre> + <p>The UTF8String is represented in Erlang as a list of integers, + where each integer represents the unicode value of one + character. When a value shall be encoded one first has to + transform it to a UTF8 encoded binary, then it can be encoded by + asn1. When decoding the result is a UTF8 encoded binary, which + may be transformed to an integer list. The transformation + functions, <c>utf8_binary_to_list</c> and + <c>utf8_list_to_binary</c>, are in the <c>asn1rt</c> module. In + the example below we assume an asn1 definition <c>UTF ::= UTF8String</c> in a module <c>UTF.asn</c>:</p> + <pre> +1> <input>asn1ct:compile('UTF',[ber_bin]).</input> +Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn" +Compiler Options: [ber_bin] +--{generated,"UTF.asn1db"}-- +--{generated,"UTF.erl"}-- +ok +2> <input>UTF8Val1 = "hello".</input> +"hello" +3> <input>{ok,UTF8bin1} = asn1rt:utf8_list_to_binary(UTF8Val1).</input> +{ok,<<104,101,108,108,111>>} +4> <input>{ok,B}='UTF':encode('UTF',UTF8bin1).</input> +{ok,[12, + 5, + <<104,101,108,108,111>>]} +5> <input>Bin = list_to_binary(B).</input> +<<12,5,104,101,108,108,111>> +6> <input>{ok,UTF8bin1}='UTF':decode('UTF',Bin).</input> +{ok,<<104,101,108,108,111>>} +7> <input>asn1rt:utf8_binary_to_list(UTF8bin1).</input> +{ok,"hello"} +8> <input>UTF8Val2 = [16#00,16#100,16#ffff,16#ffffff].</input> +[0,256,65535,16777215] +9> <input>{ok,UTF8bin2} = asn1rt:utf8_list_to_binary(UTF8Val2).</input> +{ok,<<0,196,128,239,191,191,248,191,191,191,191>>} +10> <input>{ok,B2} = 'UTF':encode('UTF',UTF8bin2).</input> +{ok,[12, + 11, + <<0,196,128,239,191,191,248,191,191,191,191>>]} +11> <input>Bin2 = list_to_binary(B2).</input> +<<12,11,0,196,128,239,191,191,248,191,191,191,191>> +12> <input>{ok,UTF8bin2} = 'UTF':decode('UTF',Bin2).</input> +{ok,<<0,196,128,239,191,191,248,191,191,191,191>>} +13> <input>asn1rt:utf8_binary_to_list(UTF8bin2).</input> +{ok,[0,256,65535,16777215]} +14> </pre> + </section> + + <section> + <marker id="OBJECT IDENTIFIER"></marker> + <title>OBJECT IDENTIFIER</title> + <p>The OBJECT IDENTIFIER is used whenever a unique identity is required. + An ASN.1 module, a transfer syntax, etc. is identified with an + OBJECT IDENTIFIER. Assume the example below:</p> + <pre> +Oid ::= OBJECT IDENTIFIER + </pre> + <p>Therefore, the example below is a valid Erlang instance of the + type 'Oid'.</p> + <pre> +OidVal1 = {1,2,55}, + </pre> + <p>The OBJECT IDENTIFIER value is simply a tuple with the + consecutive values which must be integers. + </p> + <p>The first value is limited to the values 0, 1 or 2 and the + second value must be in the range 0..39 when the first value + is 0 or 1. + </p> + <p>The OBJECT IDENTIFIER is a very important type and it is + widely used within different standards to uniquely identify + various objects. In [<cite id="DUBUISSON"></cite>], there is an + easy-to-understand description of the usage of + OBJECT IDENTIFIER.</p> + <p></p> + </section> + + <section> + <marker id="Object Descriptor"></marker> + <title>Object Descriptor</title> + <p>Values of this type can be assigned a value as an ordinary string i.e. <br></br> + + "This is the value of an Object descriptor"</p> + </section> + + <section> + <marker id="The TIME types"></marker> + <title>The TIME Types</title> + <p>Two different time types are defined within ASN.1, Generalized + Time and UTC (Universal Time Coordinated), both are assigned a + value as an ordinary string within double quotes i.e. + "19820102070533.8".</p> + <p>In case of DER encoding the compiler does not check the validity + of the time values. The DER requirements upon those strings is + regarded as a matter for the application to fulfill.</p> + </section> + + <section> + <marker id="SEQUENCE"></marker> + <title>SEQUENCE</title> + <p>The structured types of ASN.1 are constructed from other types + in a manner similar to the concepts of array and struct in C. + <br></br> + A SEQUENCE in ASN.1 is + comparable with a struct in C and a record in Erlang. + A SEQUENCE may be defined as:</p> + <pre> +Pdu ::= SEQUENCE { + a INTEGER, + b REAL, + c OBJECT IDENTIFIER, + d NULL } </pre> + <p>This is a 4-component structure called 'Pdu'. The major format + for representation of SEQUENCE in Erlang is the record format. + For each SEQUENCE and <c>SET</c> in an ASN.1 module an Erlang + record declaration is generated. For <c>Pdu</c> above, a record + like this is defined:</p> + <pre> +-record('Pdu',{a, b, c, d}). </pre> + <p>The record declarations for a module <c>M</c> are placed in a + separate <c>M.hrl</c> file.</p> + <p>Values can be assigned in Erlang as shown below:</p> + <pre> +MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre> + <p>It is also possible to specify the value for each component in + a SEQUENCE or a SET as <c>{ComponentName,Value}</c>. It is not + recommended and is not supported if the flags <c>per_bin</c> or + <c>ber_bin</c> and <c>optimize</c> were used when the module was + compiled.</p> + <p>The decode functions will return a record as result when decoding + a <c>SEQUENCE</c> or a <c>SET</c>. + <marker id="DEFAULT"></marker> +</p> + <p>A <c>SEQUENCE</c> and a <c>SET</c> may contain a component with a + <c>DEFAULT</c> key word followed by the actual value that is the + default value. In case of BER encoding it is optional to encode the + value if it equals the default value. If the application uses the + atom asn1_DEFAULT as value or if the value is a primitive value + that equals the default value the encoding omits the bytes for + this value, which is more efficient and it results in fever + bytes to send to the receiving application.</p> + <p>For instance, if the following types exists in a file "File.asn":</p> + <pre> +Seq1 ::= SEQUENCE { +\011a INTEGER DEFAULT 1, +\011b Seq2 DEFAULT {aa TRUE, bb 15} +} + +Seq2 ::= SEQUENCE { +\011aa BOOLEAN, +\011bb INTEGER +} + </pre> + <p>Some values and the corresponding encoding in an Erlang terminal + is shown below:</p> + <pre> +1> <input>asn1ct:compile('File').</input> +Erlang ASN.1 version "1.3.2" compiling "File.asn1" +Compiler Options: [] +--{generated,"File.asn1db"}-- +--{generated,"File.hrl"}-- +--{generated,"File.erl"}-- +ok +2> <input>'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</input> +{ok,["0",[0],[[],[]]]} +3> <input>lists:flatten(["0",[0],[[],[]]]).</input> +[48,0] +4> <input>'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</input> +{ok,["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]} +5> <input>lists:flatten(["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]).</input> +[48,8,161,6,128,1,255,129,1,15] +6> </pre> + <p>The result after command line 3, in the example above,shows that the + encoder omits the encoding of default values when they are specific + by asn1_DEFAULT. Line 5 shows that even primitive values that equals + the default value are detected and not encoded. But the constructed + value of component <c>b</c> in <c>Seq1</c> is not recognized as the + default value. Checking of default values in <c>BER</c> is not done + in case of complex values, because it would be to expensive. + <marker id="DEFAULT DER"></marker> +</p> + <p>But, the DER encoding format has stronger requirements regarding + default\011values both for SET and SEQUENCE. A more elaborate and time + expensive check of default values will take place. The following is + an example with the same types and values as above but with der + encoding format.</p> + <pre> +1> <input>asn1ct:compile('File',[der]).</input> +Erlang ASN.1 version "1.3.2" compiling "File.asn1" +Compiler Options: [der] +--{generated,"File.asn1db"}-- +--{generated,"File.hrl"}-- +--{generated,"File.erl"}-- +ok +2> <input>'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</input> +{ok,["0",[0],[[],[]]]} +3> <input>lists:flatten(["0",[0],[[],[]]]).</input> +[48,0] +4> <input>'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).</input> +{ok,["0",[0],[[],[]]]} +5> <input>lists:flatten(["0",[0],[[],[]]]).</input> +[48,0] +6> + </pre> + <p>Line 5 shows that even values of constructed types is checked and if + it equals the default value it will not be encoded.</p> + </section> + + <section> + <marker id="SET"></marker> + <title>SET</title> + <p>The SET type is an unusual construct and normally the SEQUENCE + type is more appropriate to use. Set is also inefficient compared with SEQUENCE, as the components can be in any order. Hence, it must be possible + to distinguish every component in 'SET', both when + encoding and decoding a value of a type defined to be a SET. + The tags of all components must be different from each other + in order to be easily recognizable.</p> + <p>A SET may be defined as:</p> + <pre> +Pdu2 ::= SET { + a INTEGER, + b BOOLEAN, + c ENUMERATED {on(0),off(1)} } </pre> + <p>A SET is represented as an Erlang record. + For each SEQUENCE and <c>SET</c> in + an ASN.1 module an Erlang record declaration is generated. For + <c>Pdu2</c> above a record is defined like this:</p> + <pre> +-record('Pdu2',{a, b, c}). </pre> + <p>The record declarations for a module <c>M</c> are placed in a + separate <c>M.hrl</c> file.</p> + <p>Values can be assigned in Erlang as demonstrated below:</p> + <pre> +V = #'Pdu2'{a=44,b=false,c=off}. </pre> + <p>The decode functions will return a record as result when decoding + a SET. + </p> + <p>The difference between SET and SEQUENCE is that the order of + the components (in the BER encoded format) is undefined for SET + and defined as the lexical order from the ASN.1 definition for + SEQUENCE. The ASN.1 compiler for Erlang will always encode a + SET in the lexical order. The decode routines can handle SET + components encoded in any order but will always return the + result as a record. Since all components of the SET must be + distinguishable both in the encoding phase as well as the + decoding phase the following type is not allowed in a module + with EXPLICIT or IMPLICIT as tag-default :</p> + <p></p> + <pre> +Bad ::= SET {i INTEGER, + j INTEGER } </pre> + <p>The ASN.1 to Erlang compiler rejects the above type. We + shall not explain the concept of tag further here, we refer to + [<cite id="X.680"></cite>]. + </p> + <p>Encoding of a SET with components with DEFAULT values behaves + similar as a SEQUENCE, <seealso marker="#DEFAULT">see above</seealso>. The DER encoding format restrictions on DEFAULT + values is the same for SET as for SEQUENCE, and is supported by + the compiler, <seealso marker="#DEFAULT DER">see above</seealso>.</p> + <p>Moreover, in DER the elements of a SET will be sorted. If a + component is an untagged choice the sorting have to take place + in run-time. This fact emphasizes the following recommendation + if DER encoding format is used.</p> + <p>The concept of SET is an unusual + construct and one cannot think of one single application + where the set type is essential. (Imagine if someone + "invented'' the shuffled array in 'C') People tend to think + that 'SET' sounds nicer and more mathematical than 'SEQUENCE' + and hence use it when 'SEQUENCE' would have been more + appropriate. It is also most inefficient, since every correct + implementation of SET must always be prepared to accept the + components in any order. So, if possible use SEQUENCE instead + of SET.</p> + </section> + + <section> + <title>Notes about Extendability for SEQUENCE and SET</title> + <p>When a SEQUENCE or SET contains an extension marker and + extension components like this:</p> + <pre> +SExt ::= SEQUENCE { + a INTEGER, + ..., + b BOOLEAN } + </pre> + <p>It means that the type may get more components in newer + versions of the ASN.1 spec. In this case it has got a new + component <c>b</c>. Thus, incoming messages that will be decoded + may have more or fever components than this one. + </p> + <p>The component <c>b</c> will be treated as + an original component when encoding a message. In this case, as + it is not an optional element, it must be encoded. + </p> + <p>During decoding the <c>b</c> field of the record will get the decoded + value of the <c>b</c> + component if present and otherwise the value <c>asn1_NOVALUE</c>.</p> + </section> + + <section> + <marker id="CHOICE"></marker> + <title>CHOICE</title> + <p>The CHOICE type is a space saver and is similar to the concept of a + 'union' in the C-language. As with the previous SET-type, the + tags of all components of a CHOICE need to be distinct. If + AUTOMATIC TAGS are defined for the module (which is + preferable) the tags can be omitted completely in the ASN.1 + specification of a CHOICE. + </p> + <p>Assume:</p> + <pre> +T ::= CHOICE { + x [0] REAL, + y [1] INTEGER, + z [2] OBJECT IDENTIFIER } + </pre> + <p>It is then possible to assign values:</p> + <pre> +TVal1 = {y,17}, +TVal2 = {z,{0,1,2}}, + </pre> + <p>A CHOICE value is always represented as the tuple + <c>{ChoiceAlternative, Val}</c> where <c>ChoiceAlternative</c> + is an atom denoting the selected choice + alternative. + </p> + <p>It is also allowed to have a CHOICE type tagged as follow:</p> + <p></p> + <pre> +C ::= [PRIVATE 111] CHOICE { + C1, + C2 } + +C1 ::= CHOICE { + a [0] INTEGER, + b [1] BOOLEAN } + +C2 ::= CHOICE { + c [2] INTEGER, + d [3] OCTET STRING } </pre> + <p>In this case, the top type C appears to have no tags at all in + its components, however, both C1 and C2 are also defined as + CHOICE types and they have distinct tags among themselves. + Hence, the above type C is both legal and allowed. + </p> + + <section> + <title>Extendable CHOICE</title> + <p>When a CHOICE contains an extension marker and the decoder detects + an unknown alternative of the CHIOCE the value is represented as:</p> + <pre> +\011 {asn1_ExtAlt, BytesForOpenType} + </pre> + <p>Where <c>BytesForOpenType</c> is a list of bytes constituting the + encoding of the "unknown" CHOICE alternative. </p> + </section> + </section> + + <section> + <marker id="SOF"></marker> + <title>SET OF and SEQUENCE OF</title> + <p>The SET OF and SEQUENCE OF types correspond to the concept of an array + found in several programming languages. The Erlang syntax for + both of these types is straight forward. For example:</p> + <pre> +Arr1 ::= SET SIZE (5) OF INTEGER (4..9) +Arr2 ::= SEQUENCE OF OCTET STRING </pre> + <p>We may have the following in Erlang:</p> + <pre> +Arr1Val = [4,5,6,7,8], +Arr2Val = ["abc",[14,34,54],"Octets"], </pre> + <p>Please note that the definition of the SET OF type implies that + the order of the components is undefined, but in practice there is + no difference between SET OF and SEQUENCE OF. The ASN.1 compiler + for Erlang does not randomize the order of the SET OF components + before encoding.</p> + <p>However, in case of a value of the type <c>SET OF</c>, the DER + encoding format requires the elements to be sent in ascending + order of their encoding, which implies an expensive sorting + procedure in run-time. Therefore it is strongly recommended to + use <c>SEQUENCE OF</c> instead of <c>SET OF</c> if it is possible.</p> + </section> + + <section> + <marker id="ANY"></marker> + <title>ANY and ANY DEFINED BY</title> + <p>The types <c>ANY</c> and <c>ANY DEFINED BY</c> have been removed + from the standard since 1994. It is recommended not to use + these types any more. They may, however, exist in some old ASN.1 + modules. + The idea with this type was to leave a "hole" in a definition where + one could put unspecified data of any kind, even non ASN.1 data.</p> + <p>A value of this type is encoded as an <c>open type</c>.</p> + <p>Instead of <c>ANY</c>/<c>ANY DEFINED BY</c> one should use + <c>information object class</c>, <c>table constraints</c> and + <c>parameterization</c>. In particular the construct + <c>TYPE-IDENTIFIER.@Type</c> accomplish the same as the + deprecated <c>ANY</c>.</p> + <p>See also <seealso marker="#Information Object">Information object</seealso></p> + </section> + + <section> + <marker id="NegotiationTypes"></marker> + <title>EXTERNAL, EMBEDDED PDV and CHARACTER STRING</title> + <p>These types are used in presentation layer negotiation. They are + encoded according to their associated type, see [<cite id="X.680"></cite>].</p> + <p>The <c>EXTERNAL</c> type had a slightly different associated type + before 1994. [<cite id="X.691"></cite>] states that encoding shall follow + the older associate type. Therefore does generated encode/decode + functions convert values of the newer format to the older format + before encoding. This implies that it is allowed to use + <c>EXTERNAL</c> type values of either format for encoding. Decoded + values are always returned on the newer format.</p> + </section> + + <section> + <title>Embedded Named Types</title> + <p>The structured types previously described may very well have other named types + as their components. The general syntax to assign a value to the component C + of a named ASN.1 type T in Erlang is the record syntax + <c>#'T'{'C'=Value}</c>. + Where <c>Value</c> may be a value of yet another type T2.</p> + <p>For example:</p> + <pre> +B ::= SEQUENCE { + a Arr1, + b [0] T } + +Arr1 ::= SET SIZE (5) OF INTEGER (4..9) + +T ::= CHOICE { + x [0] REAL, + y [1] INTEGER, + z [2] OBJECT IDENTIFIER } </pre> + <p>The above example can be assigned like this in Erlang:</p> + <pre> +V2 = #'B'{a=[4,5,6,7,8], b={x,7.77}}. + </pre> + </section> + </section> + + <section> + <title>Naming of Records in .hrl Files</title> + <p>When an asn1 specification is compiled all defined types of + type SET or SEQUENCE will result in a corresponding record in the + generated hrl file. This is because the values for SET/SEQUENCE + as mentioned in sections above are represented as records.</p> + <p>Though there are some special cases of this functionality that + are presented below.</p> + + <section> + <title>Embedded Structured Types</title> + <p>It is also possible in ASN.1 to have components that are themselves + structured types. + For example, it is possible to have:</p> + <pre> +Emb ::= SEQUENCE { + a SEQUENCE OF OCTET STRING, + b SET { + a [0] INTEGER, + b [1] INTEGER DEFAULT 66}, + c CHOICE { + a INTEGER, + b FooType } } + +FooType ::= [3] VisibleString </pre> + <p>The following records are generated because of the type <c>Emb</c>:</p> + <pre> +-record('Emb,{a, b, c}). +-record('Emb_b',{a, b = asn1_DEFAULT}). % the embedded SET type + </pre> + <p>Values of the <c>Emb</c> type can be assigned like this:</p> + <code type="none"> +V = #'Emb'{a=["qqqq",[1,2,255]], + b = #'Emb_b'{a=99}, + c ={b,"Can you see this"}}. + </code> + <p>For an embedded type of type SEQUENCE/SET in a SEQUENCE/SET + the record name is extended with an underscore and the component + name. If the embedded structure is deeper with SEQUENCE, SET or + CHOICE types in the line, each component-/alternative-name will + be added to the recordname.</p> + <p>For example:</p> + <pre> +Seq ::= SEQUENCE{ + a\011CHOICE{ +\011b SEQUENCE { +\011 c INTEGER +\011 } +\011} +} </pre> + <p>will result in the following record:</p> + <pre> +-record('Seq_a_b',{c}). </pre> + <p>If the structured type has a component with an embedded + SEQUENCE OF/SET OF which embedded type in turn is a + SEQUENCE/SET it will give a record with the SEQOF/SETOF + addition as in the following example:</p> + <pre> +Seq ::= SEQUENCE { + a SEQUENCE OF SEQUENCE { +\011 b + } + c SET OF SEQUENCE { +\011 d + } +} </pre> + <p>This results in the records:</p> + <pre> +-record('Seq_a_SEQOF'{b}). +-record('Seq_c_SETOF'{d}). </pre> + <p>A parameterized type should be considered as an embedded + type. Each time a such type is referenced an instance of it is + defined. Thus in the following example a record with name + <c>'Seq_b'</c> is generated in the .hrl file and used to hold + values.</p> + <pre> +Seq ::= SEQUENCE { + b PType{INTEGER} +} + +PType{T} ::= SEQUENCE{ + id T +} </pre> + </section> + + <section> + <title>Recursive Types</title> + <p>Types may refer to themselves. Suppose:</p> + <pre> +Rec ::= CHOICE { + nothing [0] NULL, + something SEQUENCE { + a INTEGER, + b OCTET STRING, + c Rec }} </pre> + <p>This type is recursive; that is, it refers to itself. This is allowed + in ASN.1 and the ASN.1-to-Erlang compiler supports this recursive + type. A value for this type is assigned in Erlang as shown below:</p> + <pre> +V = {something,#'Rec_something'{a = 77, + b = "some octets here", + c = {nothing,'NULL'}}}. </pre> + </section> + </section> + + <section> + <title>ASN.1 Values</title> + <p>Values can be assigned to ASN.1 type within the ASN.1 code + itself, as opposed to the actions taken in the previous chapter where + a value was assigned to an ASN.1 type in Erlang. The full value + syntax of ASN.1 is supported and [X.680] describes in detail how + to assign values in ASN.1. Below is a short example:</p> + <pre> +TT ::= SEQUENCE { + a INTEGER, + b SET OF OCTET STRING } + +tt TT ::= {a 77,b {"kalle","kula"}} </pre> + <p>The value defined here could be used in several ways. + Firstly, it could be used as the value in some DEFAULT component:</p> + <pre> +SS ::= SET { + s [0] OBJECT IDENTIFIER, + val TT DEFAULT tt } </pre> + <p>It could also be used from inside an Erlang program. If the above ASN.1 + code was defined in ASN.1 module <c>Values</c>, then the ASN.1 value + <c>tt</c> can be reached from Erlang as + a function call to <c>'Values':tt()</c> as in the example below.</p> + <pre> +1> <input>Val = 'Values':tt().</input> +{'TT',77,["kalle","kula"]} +2> <input>{ok,Bytes} = 'Values':encode('TT',Val).</input> +{ok,["0", + [18], + [[[128],[1],"M"],["\\241","\\r",[[[4],[5],"kalle"],[[4],[4],"kula"]]]]]} +3> <input>FlatBytes = lists:flatten(Bytes).</input> +[48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,107,117,108,97] +4> <input>'Values':decode('TT',FlatBytes).</input> +{ok,{'TT',77,["kalle","kula"]}} +5> + </pre> + <p>The above example shows that a function is generated by the compiler + that returns a valid Erlang representation of the value, even though + the value is of a complex type.</p> + <p>Furthermore, there is a macro generated for each value in the .hrl + file. So, the defined value <c>tt</c> can also be extracted by + <c>?tt</c> in application code.</p> + </section> + + <section> + <title>Macros</title> + <p>MACRO is not supported as the the type is no longer part of the + ASN.1 standard.</p> + </section> + + <section> + <marker id="Information Object"></marker> + <title>ASN.1 Information Objects (X.681)</title> + <p>Information Object Classes, Information Objects and Information + Object Sets, (in the following called classes, objects and + object sets respectively), are defined in the standard + definition [<cite id="X.681"></cite>]. In the following only a brief + explanation is given. </p> + <p>These constructs makes it possible to define open types, + i.e. values of that type can be of any ASN.1 type. It is also + possible to define relationships between different types and + values, since classes can hold types, values, objects, object + sets and other classes in its fields. + An Information Object Class may be defined in ASN.1 as:</p> + <pre> +GENERAL-PROCEDURE ::= CLASS { + &Message, + &Reply OPTIONAL, + &Error OPTIONAL, + &id PrintableString UNIQUE +} +WITH SYNTAX { + NEW MESSAGE &Message + [REPLY &Reply] + [ERROR &Error] + ADDRESS &id +} </pre> + <p>An object is an instance of a class and an object set is a set + containing objects of one specified class. A definition may look like + below.</p> + <p>The object <c>object1</c> is an instance of the CLASS + GENERAL-PROCEDURE and has one type field and one fixed type value + field. The object <c>object2</c> also has an OPTIONAL field ERROR, + which is a type field.</p> + <pre> +object1 GENERAL-PROCEDURE ::= { + NEW MESSAGE PrintableString + ADDRESS "home" +} + +object2 GENERAL-PROCEDURE ::= { + NEW MESSAGE INTEGER + ERROR INTEGER + ADDRESS "remote" +} </pre> + <p>The field ADDRESS is a UNIQUE field. Objects in an object set must + have unique values in their UNIQUE field, as in GENERAL-PROCEDURES: </p> + <pre> +GENERAL-PROCEDURES GENERAL-PROCEDURE ::= { + object1 | object2} </pre> + <p>One can not encode a class, object or object set, only referring to + it when defining other ASN.1 entities. Typically one refers to a + class and to object sets by table constraints and component + relation constraints [<cite id="X.682"></cite>] in ASN.1 types, as in: </p> + <pre> +StartMessage ::= SEQUENCE { + msgId GENERAL-PROCEDURE.&id ({GENERAL-PROCEDURES}), + content GENERAL-PROCEDURE.&Message\011({GENERAL-PROCEDURES}{@msgId}), + } </pre> + <p>In the type <c>StartMessage</c> the constraint following the + <c>content</c> field tells that in a value of type + <c>StartMessage</c> the value in the <c>content</c> field must + come from the same object that is choosen by the <c>msgId</c> + field.</p> + <p>So, the value <c>#'StartMessage'{msgId="home",content="Any Printable String"}</c> is legal to encode as a StartMessage + value, while the value <c>#'StartMessage'{msgId="remote", content="Some String"}</c> is illegal since the constraint + in StartMessage tells that when you have choosen a value from a + specific object in the object set GENERAL-PROCEDURES in the + msgId field you have to choose a value from that same object in + the content field too. In this second case it should have been + any INTEGER value.</p> + <p><c>StartMessage</c> can in the <c>content</c> field be + encoded with a value of any type that an object in the + <c>GENERAL-PROCEDURES</c> object set has in its <c>NEW MESSAGE</c> field. This field refers to a type field + <c><![CDATA[&Message]]></c> in the class. The <c>msgId</c> field is always + encoded as a PrintableString, since the field refers to a fixed type + in the class.</p> + </section> + + <section> + <title>Parameterization (X.683)</title> + <p>Parameterization, which is defined in the standard [<cite id="X.683"></cite>], can be used when defining types, values, value + sets, information object classes, information objects or + information object sets. + A part of a definition can be supplied as a parameter. For + instance, if a Type is used in a definition with certain + purpose, one want the typename to express the intention. This + can be done with parameterization.</p> + <p>When many types (or an other ASN.1 entity) only differs in some + minor cases, but the structure of the types are similar, only + one general type can be defined and the differences may be supplied + through parameters. </p> + <p>One example of use of parameterization is:</p> + <pre> +General{Type} ::= SEQUENCE +{ + number INTEGER, + string Type +} + +T1 ::= General{PrintableString} + +T2 ::= General{BIT STRING} + </pre> + <p>An example of a value that can be encoded as type T1 is {12,"hello"}.</p> + <p>Observe that the compiler not generates encode/decode functions for + parameterized types, only for the instances of the parameterized + types. So, if a file contains the types General{}, T1 and T2 above, + encode/decode functions will only be generated for T1 and T2. + </p> + </section> + + <section> + <title>Tags</title> + <p>Every built-in ASN.1 type, except CHOICE and ANY have a universal tag. + This is a unique number that clearly identifies the type. <br></br> + + It is essential for all users of ASN.1 to + understand all the details about tags.</p> + <p>Tags are implicitly encoded in the BER encoding as shown below, but + are hardly not accounted for in the PER encoding. In PER tags are + used for instance to sort the components of a SET.</p> + <p>There are four different types of tags.</p> + <taglist> + <tag><em>universal</em></tag> + <item> + <p>For types whose meaning is the same in all + applications. Such as integers, sequences and so on; that is, all the built in + types.</p> + </item> + <tag><em>application</em></tag> + <item> + <p>For application specific types for example, the types in + X.400 Message handling service have this sort of tag.</p> + </item> + <tag><em>private</em></tag> + <item> + <p>For your own private types.</p> + </item> + <tag><em>context</em></tag> + <item> + <p>This is used to distinguish otherwise indistinguishable + types in a specific context. For example, if we have two + components of a + CHOICE type that are both <c>INTEGER</c> values, there is no + way for the decoder to + decipher which component was actually chosen, since both + components will be + tagged as <c>INTEGER</c>. When this or similar situations occur, + one or both of the components should be given a context specific + to resolve the ambiguity.</p> + </item> + </taglist> + <p>The tag in the case of the 'Apdu' type [PRIVATE 1] is encoded to a + sequence of bytes making it possible for a + decoder to look at the (initial) bytes that arrive and determine + whether the rest of the bytes must be of the type associated + with that particular sequence of bytes. This means that each + tag must be uniquely associated with <em>only</em> one ASN.1 + type. + </p> + <p>Immediately following the tag is a sequence of bytes + informing the decoder of the length of the instance. This is + sometimes referred to as TLV (Tag length value) encoding. + Hence, the structure of a BER encoded series of bytes is as shown in the table below.</p> + <p></p> + <table> + <row> + <cell align="left" valign="middle">Tag</cell> + <cell align="left" valign="middle">Len</cell> + <cell align="left" valign="middle">Value</cell> + </row> + <tcaption>Structure of a BER encoded series of bytes</tcaption> + </table> + </section> + + <section> + <title>Encoding Rules</title> + <p>When the first recommendation on ASN.1 was released 1988 it was + accompanied with the Basic Encoding Rules, BER, as the only + alternative for encoding. + BER is a somewhat verbose protocol. It adopts a so-called TLV (type, + length, value) approach to encoding in which every element of the + encoding carries some type information, some length information and + then the value of that element. Where the element is itself + structured, then the Value part of the element is itself a series of + embedded TLV components, to whatever depth is necessary. In summary, + BER is not a compact encoding but is relatively fast and easy to + produce.</p> + <p>The DER (Distinguished Encoding Rule) encoding format was included in + the standard in 1994. It is a specialized form of BER, which gives + the encoder the option to encode some entities differently. For + instance, is the value for TRUE any octet with any bit set to one. But, + DER does not leave any such choices. The value for TRUE in the DER + case is encoded as the octet <c>11111111</c>. So, the same value + encoded by two different DER encoders must result in the same bit + stream.</p> + <p>A more compact encoding is achieved with the Packed Encoding + Rules PER which was introduced together with the revised + recommendation in 1994. PER takes a rather different approach from + that taken by BER. The first difference is that the tag part in + the TLV is omitted from the encodings, and any tags in the + notation are not encoded. The potential ambiguities are resolved + as follows:</p> + <list type="bulleted"> + <item> + <p>A CHOICE is encoded by first encoding a choice index which + identifies the chosen + alternative by its position in the notation.</p> + </item> + <item> + <p>The elements of a SEQUENCE are transmitted in textual + order. OPTIONAL or DEFAULT elements are preceded by a bit map + to identify which elements are present. After sorting the + elements of a SET in the "canonical tag order" as defined in + X.680 8.6 they are treated as a SEQUENCE regarding OPTIONAL + and DEFAULT elements. A SET is transferred in the sorted + order.</p> + </item> + </list> + <p>A second difference is that PER takes full account of the sub-typing + information in that the encoded bytes are affected by the constraints. + The BER encoded bytes are unaffected by the constraints. + PER uses the sub-typing information to for example omit length fields + whenever possible. </p> + <p>The run-time functions, sometimes take the constraints into account + both for BER and PER. For instance are SIZE constrained strings checked.</p> + <p>There are two variants of PER, <em>aligned</em> and <em>unaligned</em>. + In summary, PER results in compact encodings which require much more + computation to produce than BER. + </p> + </section> +</chapter> + diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml new file mode 100644 index 0000000000..9c04956e86 --- /dev/null +++ b/lib/asn1/doc/src/asn1ct.xml @@ -0,0 +1,379 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>asn1ct</title> + <prepared>Kenneth Lundin</prepared> + <responsible>Kenneth Lundin</responsible> + <docno>1</docno> + <approved>Kenneth Lundin</approved> + <checked></checked> + <date>97-10-14</date> + <rev>A</rev> + <file>asn1.sgml</file> + </header> + <module>asn1ct</module> + <modulesummary>ASN.1 compiler and compile-time support functions</modulesummary> + <description> + <p>The ASN.1 compiler takes an ASN.1 module as input and generates a + corresponding Erlang module which can encode and decode the data-types + specified. Alternatively the compiler takes a specification module + (se below) specifying all input modules and generates one module with + encode/decode functions. There are also some generic functions which + can be used in during development of applications which handles ASN.1 + data (encoded as BER or PER).</p> + </description> + <funcs> + <func> + <name>compile(Asn1module) -> ok | {error,Reason}</name> + <name>compile(Asn1module , Options) -> ok | {error,Reason}</name> + <fsummary>Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER.</fsummary> + <type> + <v>Asn1module = atom() | string()</v> + <v>Options = [Option| OldOption]</v> + <v>Option = ber_bin | per_bin | uper_bin | der | compact_bit_string | + noobj | {n2n,EnumTypeName} |{outdir,Dir} | {i,IncludeDir} | optimize | + driver | asn1config | undec_rest | {inline,OutputName} | inline</v> + <v>OldOption = ber | per</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Compiles the ASN.1 module <c>Asn1module</c> and generates an + Erlang module <c>Asn1module.erl</c> with encode and decode + functions for the types defined in <c>Asn1module</c>. For each + ASN.1 value defined in the module an Erlang function which + returns the value in Erlang representation is generated.</p> + <p>If <c>Asn1module</c> is a filename without extension first + <c>".asn1"</c> is assumed, then <c>".asn"</c> and finally + <c>".py"</c> (to be compatible with the old ASN.1 compiler). + Of course <c>Asn1module</c> can be a full pathname (relative or + absolute) including filename with (or without) extension. + <marker id="asn1set"></marker> +</p> + <p>If one wishes to compile a set of Asn1 modules into one + Erlang file with encode/decode functions one has to list all + involved files in a configuration file. This configuration + file must have a double extension ".set.asn", (".asn" can + alternatively be ".asn1" or ".py"). The input files' names + must be listed, within quotation marks (""), one at each row + in the file. If the input files are <c>File1.asn</c>, + <c>File2.asn</c> and <c>File3.asn</c> the configuration file + shall look like:</p> + <pre> +File1.asn +File2.asn +File3.asn </pre> + <p>The output files will in this case get their names from the + configuration file. If the configuration file has the name + <c>SetOfFiles.set.asn</c> the name of the output files will be + <c>SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db</c>.</p> + <p>Sometimes in a system of ASN.1 modules there are different + default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The + multi file compilation resolves the default tagging as if + the modules were compiled separately.</p> + <p>Another unwanted effect that may occur in multi file compilation + is name collisions. The compiler solves this problem in two + ways: If the definitions are identical then the output module + keeps only one definition with the original name. But if + definitions only have same name and differs in the definition, + then they will be renamed. The new names will be the definition + name and the original module name concatenated.</p> + <p>If any name collision have occurred the compiler reports a + "NOTICE: ..." message that tells if a definition was renamed, + and the new name that must be used to encode/decode data.</p> + + <p> + <c>Options</c> is a list with options specific for the asn1 + compiler and options that are applied to the Erlang compiler. + The latter are those that not is recognized as asn1 specific. + For <em>preferred option use</em> see <seealso + marker="asn1_ug#preferred option use">Preferred Option Use + section in users guide</seealso>. Available options are: + </p> + <taglist> + <tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag> + <item> + <p> + The encoding rule to be used. The supported encoding rules + are BER (Basic Encoding Rules), + PER aligned (Packed Encoding Rules) and PER unaligned. + If the encoding rule option is omitted <c>ber</c> + is the default. + The <c>per_bin</c> option means the aligned + variant. To use the unaligned variant the <c>uper_bin</c> + option has to be used. + </p> + <p> + The generated Erlang module always gets the same name + as the ASN.1 module and as a consequence of this only one + encoding rule per ASN.1 module can be used at runtime. + </p> + <p> + The <c>ber_bin</c> and <c>per_bin</c> options are + equivalent with the <c>OldOptions</c> <c>ber</c> and <c>per</c> + with the difference that the generated encoding/decoding + functions take advantage of the bit syntax, which in most + cases increases the performance considerably. The result + from encoding is a binary or an iolist. + </p> + </item> + <tag><c>der</c></tag> + <item> + <p> + By this option the Distinguished Encoding Rules (DER) is chosen. + DER is regarded as a specialized variant of the BER encoding + rule, therefore the <c>der</c> option only makes sense together + with the <c>ber</c> or <c>ber_bin</c> option. + This option + sometimes adds sorting and value checks when encoding, which + implies a slower encoding. The decoding routines are the same + as for <c>ber</c>. + </p> + </item> + <tag><c>compact_bit_string</c></tag> + <item> + <p> + Makes it possible to use a compact notation for values + of the BIT STRING type in Erlang. The notation: + </p> + <pre> +BitString = {Unused,Binary}, +Unused = integer(), +Binary = binary() + </pre> + <p> + <c>Unused</c> must be a number in the range 0 to 7. It + tells how many bits in the least significant byte in + <c>Binary</c> that is unused. + For details see + <seealso marker="asn1_ug#BIT STRING"> + BIT STRING type section in users guide + </seealso>. + </p> + </item> + <tag><c>{n2n,EnumTypeName}</c></tag> + <item> + <p> + Tells the compiler to generate functions for conversion between + names (as atoms) and numbers and vice versa for the EnumTypeName specified. There can be multiple occurrences of this option in order to specify several type names. The type names must be declared as ENUMERATIONS in the ASN.1 spec. + If the EnumTypeName does not exist in the ASN.1 spec the + compilation will stop with an error code. + The generated conversion functions are named + <c>name2num_EnumTypeName/1</c> and + <c>num2name_EnumTypeName/1</c>. + </p> + </item> + <tag><c>noobj</c></tag> + <item> + <p>Do not compile (i.e do not produce object code) the generated + <c>.erl</c> file. If this option is omitted the generated Erlang module + will be compiled.</p> + </item> + <tag><c>{i,IncludeDir}</c></tag> + <item> + <p>Adds <c>IncludeDir</c> to the search-path for + <c>.asn1db</c> and asn1 source files. The compiler tries + to open a <c>.asn1db</c> file when a module imports + definitions from another ASN.1 module. If no + <c>.asn1db</c> file is found the asn1 source file is + parsed. Several <c>{i,IncludeDir}</c> can be given. + </p> + </item> + <tag><c>{outdir,Dir}</c></tag> + <item> + <p>Specifies the directory <c>Dir</c> where all generated files + shall be placed. If omitted the files are placed in the + current directory.</p> + </item> + <tag><c>optimize</c></tag> + <item> + <p>This option is only valid together with one of the + <c>per_bin</c> + or <c>ber_bin</c> option. It gives time optimized code + generated and it uses another runtime module and + in the <c>per_bin</c> case a linked-in driver. The result + in the <c>per_bin</c> case from an encode when compiled + with this option will be a binary.</p> + </item> + <tag><c>driver</c></tag> + <item> + <p>Option valid together with <c>ber_bin</c> and <c>optimize</c> + options. It enables the use of a linked-in driver that gives + considerable faster decode. In <c>ber_bin</c> the driver is + enabled only by explicit use of the option <c>driver</c>.</p> + </item> + <tag><c>asn1config</c></tag> + <item> + <p>When one of the specialized decodes, exclusive or + selective decode, is wanted one has to give instructions in + a configuration file. The option <c>asn1config</c> enables + specialized decodes and takes the configuration file, which + has the same name as the ASN.1 spec but with extension + <c>.asn1config</c>, in concern. + </p> + <p>The instructions for exclusive decode must follow the + <seealso marker="asn1_spec#Exclusive Instruction">instruction and grammar in the User's Guide</seealso>. + </p> + <p>You can also find the instructions for selective decode + in the + <seealso marker="asn1_spec#Selective Instruction">User's Guide</seealso>. + </p> + </item> + <tag><c>undec_rest</c></tag> + <item> + <p>A buffer that holds a message, being decoded may + also have some following bytes. Now it is possible to get + those following bytes returned together with the decoded + value. If an asn1 spec is compiled with this option a tuple + <c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a + list or a binary. Earlier versions of the compiler ignored + those following bytes.</p> + </item> + <tag><c>{inline,OutputName}</c></tag> + <item> + <p>Compiling with this option gives one output module + containing all asn1 run-time functionality. The asn1 specs + are provided in a target module Module.set.asn as described + <seealso marker="#asn1set">above</seealso>. The name of the + resulting module containing generated encode/decode functions + and in-lined run-time functions will be + <c>OutputName.erl</c>. The merging/in-lining of code is done + by the <c>igor</c> module of <c>syntax_tools</c>. By default + the functions generated from the first asn1 spec in the + <c>.set.asn</c> are exported, unless a + <c>{export,[atom()]}</c> or <c>{export_all,true}</c> option + are provided. The list of atoms are names of chosen asn1 + specs from the <c>.set.asn</c> file.</p> + </item> + <tag><c>inline</c></tag> + <item> + <p>It is also possible to use the sole argument <c>inline</c>. + It is as <c>{inline,OutputName}</c>, but the output file gets the + default name of the source <c>.set.asn</c> file.</p> + </item> + </taglist> + <p>Any additional option that is applied will be passed to + the final step when the generated .erl file is compiled. + </p> + <p>The compiler generates the following files:</p> + <list type="bulleted"> + <item> + <p><c>Asn1module.hrl</c> (if any SET or SEQUENCE is defined)</p> + </item> + <item> + <p><c>Asn1module.erl</c> the Erlang module with encode, decode and value functions.</p> + </item> + <item> + <p><c>Asn1module.asn1db</c> intermediate format used by the compiler when modules IMPORTS + definitions from each other.</p> + </item> + </list> + </desc> + </func> + <func> + <name>encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}</name> + <fsummary>Encode an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = term()</v> + <v>Bytes = [Int] when integer(Int), Int >= 0, Int =< 255</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module + <c>Module</c>. Returns a list of bytes if successful. To get as fast execution as + possible the + encode function only performs rudimentary tests that the input + <c>Value</c> + is a correct instance of <c>Type</c>. The length of strings is for example + not always checked. Returns <c>{ok,Bytes}</c> if successful or + <c>{error,Reason}</c> if an error occurred. + </p> + </desc> + </func> + <func> + <name>decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}</name> + <fsummary>Decode from Bytes into an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = Reason = term()</v> + <v>Bytes = [Int] when integer(Int), Int >= 0, Int =< 255</v> + </type> + <desc> + <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes + <c>Bytes</c>. Returns <c>{ok,Value}</c> if successful.</p> + </desc> + </func> + <func> + <name>validate(Module,Type,Value) -> ok | {error,Reason}</name> + <fsummary>Validate an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Validates that <c>Value</c> conforms to <c>Type</c> + from <c>Module</c>. <em>Not implemented in this version of the ASN.1 application.</em></p> + </desc> + </func> + <func> + <name>value(Module ,Type) -> {ok,Value} | {error,Reason}</name> + <fsummary>Create an ASN.1 value for test purposes.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Returns an Erlang term which is an example of a valid Erlang + representation of a value of the ASN.1 type <c>Type</c>. The value + is a random value and subsequent calls to this function will for most + types return different values.</p> + </desc> + </func> + <func> + <name>test(Module) -> ok | {error,Reason}</name> + <name>test(Module,Type) -> ok | {error,Reason}</name> + <name>test(Module,Type,Value) -> ok | {error,Reason}</name> + <fsummary>Perform a test of encode and decode for types in an ASN.1 module.</fsummary> + <desc> + <p>Performs a test of encode and decode of all types in <c>Module</c>. + The generated functions are called by this function. + This function is useful during test to secure that the generated + encode and decode functions and the general runtime support work + as expected. <br></br> +<c>test/1</c> iterates over all types in <c>Module</c>. <br></br> +<c>test/2</c> tests type <c>Type</c> with a random value. <br></br> +<c><![CDATA[test/3 tests type <c>Type]]></c> with <c>Value</c>. <br></br> + + Schematically the following happens for each type in the module.</p> + <p></p> + <code type="none"> +{ok,Value} = asn1ct:value(Module,Type), +{ok,Bytes} = asn1ct:encode(Module,Type,Value), +{ok,Value} = asn1ct:decode(Module,Type,Bytes). </code> + </desc> + </func> + </funcs> + +</erlref> + diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml new file mode 100644 index 0000000000..1217a07e9b --- /dev/null +++ b/lib/asn1/doc/src/asn1rt.xml @@ -0,0 +1,208 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>asn1rt</title> + <prepared>Kenneth Lundin</prepared> + <responsible>Kenneth Lundin</responsible> + <docno>1</docno> + <approved>Kenneth Lundin</approved> + <checked></checked> + <date>97-10-04</date> + <rev>A</rev> + <file>asn1.sgml</file> + </header> + <module>asn1rt</module> + <modulesummary>ASN.1 runtime support functions</modulesummary> + <description> + <p>This module is the interface module for the ASN.1 runtime support functions. + To encode and decode ASN.1 types in runtime the functions in this module + should be used.</p> + </description> + + <funcs> + + <func> + <name>start() -> ok |{error,Reason}</name> + <fsummary>Starts the asn1 server.</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>Starts the asn1 server that loads the drivers.</p> + <p>The server schedules a driver that is not blocked by + another caller. The driver is used by the asn1 application if + specs are compiled with options <c>[per_bin, optimize]</c> or + <c>[ber_bin, optimize, driver]</c>. The server will be started + automatically at encode/decode if it isn't done explicitly. If + encode/decode with driver is used in test or industrial code + it is a performance gain to start it explicitly to avoid the + one time load in run-time.</p> + </desc> + </func> + + <func> + <name>stop() -> ok |{error,Reason}</name> + <fsummary>Stops the asn1 server.</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>Stops the asn1 server and unloads the drivers.</p> + </desc> + </func> + + <func> + <name>decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}</name> + <fsummary>Decode from bytes into an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = Reason = term()</v> + <v>Bytes = binary | [Int] when integer(Int), Int >= 0, Int =< 255 | binary</v> + </type> + <desc> + <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes or + binary <c>Bytes</c>. If the module is compiled with <c>ber_bin</c> + or <c>per_bin</c> option <c>Bytes</c> must be a binary. + Returns <c>{ok,Value}</c> if successful.</p> + </desc> + </func> + + <func> + <name>encode(Module,Type,Value)-> {ok,BinOrList} | {error,Reason}</name> + <fsummary>Encode an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = term()</v> + <v>BinOrList = Bytes | binary()</v> + <v>Bytes = [Int|binary|Bytes] when integer(Int), Int >= 0, Int =< 255</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module + <c>Module</c>. Returns a possibly nested list of bytes and or binaries + if successful. If <c>Module</c> was compiled with the options <c>per_bin</c> and <c>optimize</c> the result is a binary. To get as + fast execution as possible the + encode function only performs rudimentary tests that the input + <c>Value</c> + is a correct instance of <c>Type</c>. The length of strings is for example + not always checked. </p> + </desc> + </func> + + <func> + <name>info(Module) -> {ok,Info} | {error,Reason}</name> + <fsummary>Returns compiler information about the Module.</fsummary> + <type> + <v>Module = atom()</v> + <v>Info = list()</v> + <v>Reason = term()</v> + </type> + <desc> + <p><c>info/1</c> returns the version of the asn1 compiler that was + used to compile the module. It also returns the compiler options + that was used.</p> + </desc> + </func> + + <func> + <name>load_driver() -> ok | {error,Reason}</name> + <fsummary>Loads the linked-in driver.</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>This function loads the linked-in driver before the first call + to encode. If this function is not called the driver will be loaded + automatically at the first call to encode. If one doesn't want the + performance cost of a driver load when the application is running, + this function makes it possible to load the driver in an + initialization.</p> + <p>The driver is only used when encoding/decoding ASN.1 files that + were compiled with the options <c>per_bin</c> and <c>optimize</c>.</p> + </desc> + </func> + + <func> + <name>unload_driver() -> ok | {error,Reason}</name> + <fsummary>Unloads the linked-in driver.</fsummary> + <type> + <v>Reason = term()</v> + </type> + <desc> + <p>This function unloads the linked-in driver. + When the driver has been loaded it remains in the environment until + it is unloaded. Normally the driver should remain loaded, it is + crucial for the performance of ASN.1 encoding. </p> + <p>The driver is only used when ASN.1 modules have been compiled + with the flags <c>per_bin</c> and <c>optimize</c>.</p> + </desc> + </func> + + <func> + <name>utf8_binary_to_list(UTF8Binary) -> {ok,UnicodeList} | {error,Reason}</name> + <fsummary>Transforms an utf8 encoded binary to a unicode list.</fsummary> + <type> + <v>UTF8Binary = binary()</v> + <v>UnicodeList = [integer()]</v> + <v>Reason = term()</v> + </type> + <desc> + <p><c>utf8_binary_to_list/1</c> Transforms a UTF8 encoded binary + to a list of integers, where each integer represents one + character as its unicode value. The function fails if the binary + is not a properly encoded UTF8 string.</p> + </desc> + </func> + + <func> + <name>utf8_list_to_binary(UnicodeList) -> {ok,UTF8Binary} | {error,Reason}</name> + <fsummary>Transforms an unicode list ot an utf8 binary.</fsummary> + <type> + <v>UnicodeList = [integer()]</v> + <v>UTF8Binary = binary()</v> + <v>Reason = term()</v> + </type> + <desc> + <p><c>utf8_list_to_binary/1</c> Transforms a list of integers, + where each integer represents one character as its unicode + value, to a UTF8 encoded binary.</p> + </desc> + </func> + + <func> + <name>validate(Module,Type,Value) -> ok | {error,Reason}</name> + <fsummary>Validate an ASN.1 value.</fsummary> + <type> + <v>Module = Type = atom()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Validates that <c>Value</c> conforms to <c>Type</c> + from <c>Module</c>. <em>Not implemented in this version of the ASN.1 application.</em></p> + </desc> + </func> + + </funcs> + +</erlref> + diff --git a/lib/asn1/doc/src/book.xml b/lib/asn1/doc/src/book.xml new file mode 100644 index 0000000000..718e6e7b17 --- /dev/null +++ b/lib/asn1/doc/src/book.xml @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>ASN.1</title> + <prepared>Kenneth Lundin</prepared> + <docno></docno> + <date>1997-12-01</date> + <rev>0.9</rev> + <file>book.sgml</file> + </header> + <insidecover> + </insidecover> + <pagetext>ASN.1</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + diff --git a/lib/asn1/doc/src/exclusive_Win_But.gif b/lib/asn1/doc/src/exclusive_Win_But.gif Binary files differnew file mode 100644 index 0000000000..86dea0547e --- /dev/null +++ b/lib/asn1/doc/src/exclusive_Win_But.gif diff --git a/lib/asn1/doc/src/exclusive_Win_But.ps b/lib/asn1/doc/src/exclusive_Win_But.ps new file mode 100644 index 0000000000..387b978c7f --- /dev/null +++ b/lib/asn1/doc/src/exclusive_Win_But.ps @@ -0,0 +1,465 @@ +%!PS-Adobe-2.0 +%%Title: exclusive_Win_But.ps +%%Creator: fig2dev Version 3.2 Patchlevel 1 +%%CreationDate: Tue Oct 28 13:39:26 2003 +%%For: bertil@super (Bertil Karlsson,UAB/F/P) +%%Orientation: Portrait +%%BoundingBox: 40 368 572 423 +%%Pages: 1 +%%BeginSetup +%%IncludeFeature: *PageSize Letter +%%EndSetup +%%Magnification: 1.0000 +%%EndComments +/MyAppDict 100 dict dup begin def +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +22.0 480.5 translate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + MyAppDict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% left45 +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 32 32 true [ 32 0 0 -32 0 32 ] + {<808080804040404020202020101010100808080804040404 + 020202020101010180808080404040402020202010101010 + 080808080404040402020202010101018080808040404040 + 202020201010101008080808040404040202020201010101 + 808080804040404020202020101010100808080804040404 + 0202020201010101>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P4 exch def +1.1111 1.1111 scale %restore scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit +n -1000 2854 m -1000 -1000 l 10152 -1000 l 10152 2854 l cp clip + 0.06000 0.06000 sc +%%Page: 1 1 +% Polyline +7.500 slw +n 325 975 m 1125 975 l 1125 1575 l 325 1575 l cp gs col-1 s gr +% Polyline +n 1125 975 m 4650 975 l 4650 1575 l 1125 1575 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P4 [16 0 0 -16 75.00 65.00] PATmp PATsp ef gr PATusp gs col-1 s gr +% Polyline +n 4650 975 m 5325 975 l 5325 1575 l 4650 1575 l cp gs col-1 s gr +% Polyline +n 5325 975 m 9140 975 l 9140 1575 l 5325 1575 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P4 [16 0 0 -16 355.00 65.00] PATmp PATsp ef gr PATusp gs col-1 s gr +/Times-Roman ff 180.00 scf sf +4725 1800 m +gs 1 -1 sc (enabled) col-1 sh gr +/Times-Roman ff 180.00 scf sf +6450 1800 m +gs 1 -1 sc (actions:possibleActions) col-1 sh gr +/Times-Roman ff 180.00 scf sf +2550 1800 m +gs 1 -1 sc (buttonList) col-1 sh gr +/Times-Roman ff 180.00 scf sf +600 1800 m +gs 1 -1 sc (state) col-1 sh gr +$F2psEnd +rs +end +showpage diff --git a/lib/asn1/doc/src/fascicules.xml b/lib/asn1/doc/src/fascicules.xml new file mode 100644 index 0000000000..2488e7b57e --- /dev/null +++ b/lib/asn1/doc/src/fascicules.xml @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html"> + Off-Print + </fascicule> +</fascicules> + diff --git a/lib/asn1/doc/src/make.dep b/lib/asn1/doc/src/make.dep new file mode 100644 index 0000000000..eb2c0e9a98 --- /dev/null +++ b/lib/asn1/doc/src/make.dep @@ -0,0 +1,31 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/gandalf/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: asn1_spec.tex asn1_ug.tex asn1ct.tex asn1rt.tex \ + book.tex part.tex ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +asn1_spec.tex: Seq.asn Seq.asn1config + +book.tex: part.xml ref_man.xml + +asn1_ug.tex: ../../../../system/doc/definitions/cite.defs + +# ---------------------------------------------------- +# Pictures that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: exclusive_Win_But.ps selective_TypeList.ps \ + selective_Window2.ps + diff --git a/lib/asn1/doc/src/note.gif b/lib/asn1/doc/src/note.gif Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/asn1/doc/src/note.gif diff --git a/lib/asn1/doc/src/notes.xml b/lib/asn1/doc/src/notes.xml new file mode 100644 index 0000000000..861de05a59 --- /dev/null +++ b/lib/asn1/doc/src/notes.xml @@ -0,0 +1,748 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>asn1 Release Notes</title> + <prepared>otp_appnotes</prepared> + <docno>nil</docno> + <date>nil</date> + <rev>nil</rev> + <file>notes.xml</file> + </header> + <p>This document describes the changes made to the asn1 application.</p> + + +<section><title>Asn1 1.6.12</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.</p> + <p> + Own Id: OTP-8256</p> + </item> + </list> + </section> + +</section> + + +<section><title>Asn1 1.6.11</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new option <c>{n2n,TypeName}</c> can be used to + enable generation of conversion functions from name to number + and vice versa for selected ENUMERATION types. + The option can be repeated many times in order to specify several + types in the same file.<br/> + If the <c>TypeName</c> specified does not exists or is not an + ENUMERATION type, the compilation will be terminated with an + error code.<br/> + Below follows an example on how to use the option from the command line with <c>erlc</c>:<br/> + <c>erlc -bper_bin +optimize +driver +"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn</c> + </p> + <p> + Own Id: OTP-8136 Aux Id: seq11347 </p> + </item> + <item> + <p> + Range checks added for BIT STRING with fixed SIZE + constraint.</p> + <p> + Own Id: OTP-7972 Aux Id: seq11280 </p> + </item> + <item> + <p> + Now support multiple-line comments in asn1-specs as + specified in ASN1 X.680 (07/2002), section 11.6.4</p> + <p> + Own Id: OTP-8043</p> + </item> + <item> + <p> + Now parses and adds abstract syntax for PATTERN subtype + constraint. No other action is taken on this type of + constraint.</p> + <p> + Own Id: OTP-8046</p> + </item> + <item> + <p> + The ASN1 subtype constraint <c>CONTAINING Type</c>, + <c>CONTAINING Type ENCODED BY Value</c> and <c>ENCODED BY + Value</c> now is parsed. Abstract syntax is added but no + further action in generated code is taken.</p> + <p> + Own Id: OTP-8047</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A faulty receive case that catch-ed all messages in the + initialization of the driver has been removed, the + initialization has been restructured.</p> + <p> + Own Id: OTP-7954 Aux Id: seq11220 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The anonymous part of the decode that splits the ASN1 TLV + into Tag Value tuples has been optimized.</p> + <p> + Own Id: OTP-7953</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Error that caused crash when drivers were loaded is now + corrected. Parallel driver for asn1 now enabled.</p> + <p> + Own Id: OTP-7904 Aux Id: seq11220 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Optimized code for ENUMERATION type in encoder/decoder.</p> + <p> + Own Id: OTP-7909</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Removed parallel-driver functionality due to failure + when loading the driver.</p> + <p> + Own Id: OTP-7900 Aux Id: seq11220 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Generated code now uses guards that is not obsolete, e.g. + <c>is_integer/1</c> instead of <c>integer/1</c>.</p> + <p> + Own Id: OTP-7910</p> + </item> + </list> + </section> + +</section> + + +<section><title>Asn1 1.6.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A BIT STRING with a size constraint that has a single + value and an extension as in <c> BIT STRING (SIZE + (16,...))</c> was erroneous encoded/decoded. This is now + corrected and follows X.691 Section 15.6.</p> + <p> + Own Id: OTP-7876 Aux Id: seq11220 </p> + </item> + </list> + </section> + +</section> + <section><title>Asn1 1.6.7</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Now asn1 starts multiple drivers to enable simultaneous + encode/decode in different processes for the + asn1-backends using linked-in driver.</p> + <p> + Own Id: OTP-7801</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Decode of an open_type when the value was empty tagged + type encoded with indefinite length failed. This is now + corrected.</p> + <p> + Own Id: OTP-7759 Aux Id: seq11166 </p> + </item> + <item> + <p> + Encode of BIT STRING with size of exact length, on + compact_bit_string format in UNALIGNED PER failed when + value had the right size, i.e. no padding needed.</p> + <p> + Own Id: OTP-7763 Aux Id: seq11182 </p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + For a BIT STRING with SIZE constraint higher than 255 + compiled with <c>[per_bin,optimize, + compact_bit_string]</c> an improper io-list was created + and sent to the c-driver for complete encoding. This + error has been resolved.</p> + <p> + Own Id: OTP-7734 Aux Id: seq11170 </p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A a SEQUENCE OF with a type that is a CHOICE with + ellipses occurred falsely a compile error. The error + causing that is now removed.</p> + <p> + Own Id: OTP-7708 Aux Id: seq11136 </p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + constrained number with a value-range greater than 512 now + has the proper interpretation of the values that causes + shift to the next number of units (bits), According to + limit condition <c>2^m < "range" =< 2^(m + 1)</c> then the + number of bits are m + 1.</p> + <p> + Own Id: OTP-7681 Aux Id: seq11114 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Can now handle default values of simple types that is + provided on its own format, i.e. not just as + asn1_DEFAULT.</p> + <p> + Own Id: OTP-7678 Aux Id: seq11114 </p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + comparison of two value definitions failed due to new + module name field in valuedef record. It is now + corrected.</p> + <p> + Own Id: OTP-7608</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Bug regarding propagation of parameters of parameterized + type fixed.</p> + <p> + Own Id: OTP-7174 Aux Id: seq10864 </p> + </item> + <item> + <p> + A bug, related to instantiation of a parameterized type + with a type definition in the parameter-list, has been + removed. The definition of the parameter type was in + another module than the instance definition causing + limited module info.</p> + <p> + Own Id: OTP-7299 Aux Id: seq10864 </p> + </item> + <item> + <p> + Removed hard-coded name that may cause name collision.</p> + <p> + Own Id: OTP-7322 Aux Id: seq10864 </p> + </item> + <item> + <p> + Object set of a class with id with properties UNIQUE + OPTIONAL and the id field is lacking in the object is for + now treated as a object without a unique identifier, i.e. + no table is generated for this object.</p> + <p> + Own Id: OTP-7332 Aux Id: seq10864 </p> + </item> + <item> + <p> + Compiler crashed when failed to handle a OID as + ValueFromObject.</p> + <p> + Own Id: OTP-7476 Aux Id: seq10999 </p> + </item> + <item> + <p> + A corrupted encoding may cause a loop when a buffer of at + least two bytes of zero matches tag and length of a SET + component. This behavior occurred only with decoder + generated with <c>ber</c> or <c>ber_bin</c> options. Now a + control breaks the loop.</p> + <p> + Own Id: OTP-7533</p> + </item> + <item> + <p> + Encode of BIT STRING longer than 255 bits with a + <c>SIZE(integer())</c> constraint caused a crash when + spec was compiled with <c>per_bin, optimize</c> options.</p> + <p> + Own Id: OTP-7602 Aux Id: seq11079 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Now supports REAL type of base 2 and 10</p> + <p> + Own Id: OTP-7166 Aux Id: seq10864 </p> + </item> + <item> + <p> + By the asn1 compiler option <c>{record_name_prefix + Name}</c> a prefix is chosen to the name of the record + generated in the .hrl and used in the generated .erl + files.</p> + <p> + Own Id: OTP-7204 Aux Id: seq10853 </p> + </item> + <item> + <p> + The TypeFromObject production now covered</p> + <p> + Own Id: OTP-7295 Aux Id: seq10468 </p> + </item> + <item> + <p> + Extended support for ObjectSetFromObjects. Production + occurred as a part of the RootElementSetSpec of the + ObjectSetSpec. Added also support for Exclusion of + Element in ObjectSetSpec.</p> + <p> + Own Id: OTP-7306 Aux Id: seq10864 </p> + </item> + <item> + <p> + Now implements RELATIVE-OID</p> + <p> + Own Id: OTP-7334 Aux Id: seq10864 </p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Now is ordering, according to the canonical order, of + components in a SET added. Canonical order is described + in X.691 9.2 and X.680 8.6</p> + <p> + Own Id: OTP-7375 Aux Id: unaligned PER </p> + </item> + <item> + <p> + The precedence rules for extended constraints have been + misinterpreted. The rule says for instance that if there + are more than one constraint on a type that have + extension-mark, only the last of the extension-marks would + be kept. This affects the encoding of PER and is now + corrected.</p> + <p> + Own Id: OTP-7400 Aux Id: OTP-7335 </p> + </item> + <item> + <p> + A constrained number with a single-value constraint that + is extensible was falsely encoded/decoded in + aligned/unaligned PER. This is now corrected.</p> + <p> + Own Id: OTP-7403</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The ASN.1 compiler has got a new backend supporting PER + UNALIGNED. Previously it was only support for PER + ALIGNED.</p> + <p> + Own Id: OTP-7335</p> + </item> + <item> + <p> + Now the asn1-compiler handles unions and intersections of + PermittedAlphabet constraints.</p> + <p> + Own Id: OTP-7374 Aux Id: unaligned PER </p> + </item> + <item> + <p> + With the undocumented option <c>no_final_padding</c> the + whole encoded message is not padded to a border of a + byte. Thus the returned encoded message is a + <c>bitstring</c>.</p> + <p> + Own Id: OTP-7407</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.5.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When duplicates of object fields were removed only one + table access function for each unique identifier value + was generated. This can occur when several object sets + are merged by use of ObjectSetFromObjects.</p> + <p> + Own Id: OTP-7263 Aux Id: seq10864 </p> + </item> + <item> + <p> + DER: For some complex types and components with reference + to type in several steps the default value check function + was not generated. This is now fixed.</p> + <p> + Own Id: OTP-7268 Aux Id: seq10684 </p> + </item> + <item> + <p> + Now is the tag in a tagged type as parameter propagated + to the instance.</p> + <p> + Own Id: OTP-7273 Aux Id: seq10864 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Added type T61String that is similar to TeletexString</p> + <p> + Own Id: OTP-7264 Aux Id: seq10864 </p> + </item> + </list> + </section> + +</section> + + +<section><title>Asn1 1.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A bug related to renaming of types has been fixed.This + occurred using the .set.asn functionality.</p> + <p> + Own Id: OTP-7149 Aux Id: seq10853 </p> + </item> + <item> + <p> + syntax error in ASN1 value now correctly shown</p> + <p> + Own Id: OTP-7154 Aux Id: seq10864 </p> + </item> + <item> + <p> + Now a COMPONENTS OF construct in a parameterized type + is expanded correctly</p> + <p> + Own Id: OTP-7155 Aux Id: seq10864 </p> + </item> + <item> + <p> + Now the asn1-compiler also handles empty SEQUENCE DEFAULT + values as <c>{}</c>.</p> + <p> + Own Id: OTP-7169 Aux Id: seq10864 </p> + </item> + <item> + <p> + Now SelectionType gets the tag of the selected type.</p> + <p> + Own Id: OTP-7171 Aux Id: seq10864 </p> + </item> + <item> + <p> + Correction of generated code for decode of an open type + in a SEQUECNE OF/ SET OF</p> + <p> + Own Id: OTP-7193 Aux Id: seq10875 </p> + </item> + </list> + </section> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Misc improvements and bug corrections regarding default + values.</p> + <p> + Own Id: OTP-7199 Aux Id: seq10864 </p> + </item> + </list> + </section> + + + +</section> + +<section><title>Asn1 1.5</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Now generating records in .hrl file for instances of + parameterized SEQUENCE or SET.</p> + <p> + Own Id: OTP-6835</p> + </item> + <item> + <p> + Optimization using bitstr in encode/decode functions. Active with + <c>[per_bin, optimize]</c> options.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-6882</p> + </item> + </list> + </section> + +</section> + +<section><title>Asn1 1.4.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Parsing and encoding/decoding of type constrained with + SIZE with extension is now recovered.</p> + <p> + Own Id: OTP-6763</p> + </item> + <item> + <p> + <c>inline</c> failed because trying to use a removed + module.</p> + <p> + Own Id: OTP-6769</p> + </item> + <item> + <p> + Fixed problem with a reference to a type from an object. + The failure was caused bye change of type name when using + <c>inline</c> option.</p> + <p> + Own Id: OTP-6770</p> + </item> + <item> + <p> + Handling of decode pattern for exclusive decode was false + in the case when an un-decoded component had more than one + following elements that should be decoded.</p> + <p> + Own Id: OTP-6786</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Now the asn1-compiler supports two root lists in SEQUENCE + and SET according to alternative three in + ComponentTypeLists (X.680 07/2002 section 24.1), i.e. + with an extension list between two ellipses.</p> + <p> + Own Id: OTP-5067 Aux Id: seq8452 </p> + </item> + </list> + </section> + +</section> + + <section> + <title>Asn1 1.4.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Merging modules by <c>inline</c> earlier disabled the + driver (used in modules generated with + [optimized]/[optimized,driver] options). Now this is + repaired.</p> + <p>Own Id: OTP-6601</p> + </item> + <item> + <p>Checking phase now aware of which module an INSTANCE OF + is declared in.</p> + <p>Own Id: OTP-6702</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The compiler now handle all forms of ObjectSetSpec + according to ITU-T recommendation X.681 (ISO/IEC + 8824-2:2002).</p> + <p>Own Id: OTP-6698</p> + </item> + <item> + <p>Enhanced support of referencing object sets by + ObjectSetFromObjects.</p> + <p>Own Id: OTP-6707</p> + </item> + <item> + <p>Support for parameterized object in an object set.</p> + <p>Own Id: OTP-6717</p> + </item> + </list> + </section> + + <!-- p>There are also release notes for <url href="notes_history.html">older versions</url>.</p --> + </section> +</chapter> + diff --git a/lib/asn1/doc/src/notes_history.xml b/lib/asn1/doc/src/notes_history.xml new file mode 100644 index 0000000000..e6c423e79e --- /dev/null +++ b/lib/asn1/doc/src/notes_history.xml @@ -0,0 +1,1782 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2006</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>ASN1 Release Notes</title> + <prepared>Bertil Karlsson</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>06-04-24</date> + <rev></rev> + <file>notes_history.sgml</file> + </header> + <p>This document describes the changes made to the asn1 system + from version to version. The intention of this document is to + list all incompatibilities as well as all enhancements and + bug-fixes for every release of the asn1 application. Each release of asn1 + thus constitutes one section in this document. The title of each + section is the version number of asn1.</p> + + + <section> + <title>Asn1 1.4.4.14</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Data in info/0 in generated code is moved to attribute + asn1_info, thus vsn value remains the same if compiler + options for asn1-spec differs but the generated code is + the same.</p> + <p>Own Id: OTP-6462</p> + </item> + <item> + <p>Dialyzer warnings on asn1 are removed, i.e. dead code + removed.</p> + <p>Own Id: OTP-6506</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.13</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Now it is possible to use 'asn1config' and 'inline' + options together. It is also possible to use 'inline' on + a single file like: + <c>asn1ct:compile("MyASN1spec.asn",[inline])</c>.</p> + <p>Own Id: OTP-6405</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.12</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>As a complement to the option "{inline,OutputFile}" it is + now possible to use the option "inline". Then asn1 creates + an output file with the name of the source .set file.</p> + <p>Own Id: OTP-6314</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.11</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>When compiling an asn1 source that reference a type in + another source the compiler uses the asn1db file of the + other source to resolve the reference. It also tests + whether the other source has been updated since the + asn1db file was generated. This last test was to brutal + in that it exits compilation when no source was found, + even though a asn1db file existed. Changed behavior from + a brutal exit to a warning.</p> + <p>Own Id: OTP-6143</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.10</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>asn1 encoding failed on BIT STRING with constraint + <c>(SIZE (32..MAX))</c>.</p> + <p>Own Id: OTP-5932</p> + </item> + <item> + <p>Race condition removed in server for variable names for + generated code.</p> + <p>Own Id: OTP-6111</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.9</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Now exists a default function clause for table lookup of + a table constraint. This causes a nice error instead of a + crash. Did also remove some obsolete funs ({Mod,Fun}) in + generated code.</p> + <p>Own Id: OTP-5783</p> + </item> + <item> + <p>ASN1-compiler failed to derive a value out of an external + reference in some certain cases, when compiling specs so + that the spec with the reference was compiled before the + spec with the defined value.</p> + <p>Own Id: OTP-5812 Aux Id: seq10133 </p> + </item> + <item> + <p>The documentation of how records of embedded types are + named is extended and made clearer by examples and rules. + The section "Naming of Records in .hrl Files" in the + User's Guide is added.</p> + <p>Own Id: OTP-5831 Aux Id: seq10133 </p> + </item> + <item> + <p>The compiler failed to give right name to record/function + of a parameterized type that was referenced through + another instance of a parameterized type in another + module. The fault occurred when modules were compiled in a + certain order. Now the compiler resolves the name + correctly.</p> + <p>Own Id: OTP-5832 Aux Id: seq10133 </p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.8</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The dynamic sort of SET OF values now correctly handles + values encoded in the "ber_bin, der, optimize" mode, the + value of a SET OF is a list of binaries.</p> + <p>Own Id: OTP-5687</p> + </item> + <item> + <p>Bad code was generated for an INTEGER with value-range. If + the value that was encoded had a lower bound with + negative value it caused a crash. This bug is now + removed.</p> + <p>Own Id: OTP-5688 Aux Id: seq10049 </p> + </item> + <item> + <p>Compiler now handles wrong include paths by returning an + error if a referenced module is not available.</p> + <p>Own Id: OTP-5689</p> + </item> + <item> + <p>The bug causing a runtime error when encoding a type + defined by: <c>BIT STRING {a(1),b(2)}</c> with the value + [] in <c>per_bin</c> mode is now removed.</p> + <p>Own Id: OTP-5710 Aux Id: seq10066 </p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Better handling of filename paths</p> + <p>Own Id: OTP-5701</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.7</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Effective constraint for <c>per</c> now corrected. For + instance <c>INTEGER (0|15..269)</c> didn't work properly.</p> + <p>Own Id: OTP-5477 Aux Id: OTP-5511 </p> + </item> + <item> + <p>Adjusted compiler so that functions in generated code + only are exported once.</p> + <p>Own Id: OTP-5509</p> + </item> + <item> + <p>Fixed the compiler failure when handling a value range + constraint with an extension mark that had the Lower + bound and/or Upper bound values as an external reference + to a defined value.</p> + <p>Own Id: OTP-5511 Aux Id: OTP-5466 </p> + </item> + <item> + <p>Removed sorting of elements for SEQUENCE OF. It shall + only be done in SET OF.</p> + <p>Own Id: OTP-5602</p> + </item> + <item> + <p>Corrected code that generated code causing badarith + warning.</p> + <p>Own Id: OTP-5616</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.6</title> + + <section> + <title>Known Bugs and Problems</title> + <list type="bulleted"> + <item> + <p>Compiler now correctly crashes when compiling bad values. + Failed for instance on INTEGER value that was a reference + to a defined value. Also solved problem with a union + constraint on an INTEGER.</p> + <p>Own Id: OTP-5457</p> + </item> + <item> + <p>Additional coverage of object set syntax.</p> + <p>Own Id: OTP-5466</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug due to representation of open_type values is now + fixed. It could cause problem if one used the EXTERNAL + type.</p> + <p>Own Id: OTP-5302</p> + </item> + <item> + <p>Due to an internal error the same code could have been + generated more than one time. This happened for the + exclusive decode functionality.</p> + <p>Own Id: OTP-5378</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.4</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Empty objects caused problems. There was trouble when an + object set referenced imported objects that in turn + referenced imported types. Lacked support of + SelectionType in object. All these have been attended.</p> + <p>Own Id: OTP-5240</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Now it is possible to inline asn1 run-time functionality + in the module generated by the asn1 compiler. Thus, it + will be only one module doing all encoding/decoding.</p> + <p>Own Id: OTP-5243</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.3</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>A class that was referenced in two steps caused a + compiler failure. It is now corrected.</p> + <p>Own Id: OTP-5103</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>Optionally make it possible to get the un-decoded rest along with + the return value. Compile with option <em>undec_rest</em>.</p> + <p>Own Id: OTP-5104</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.2</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>An error due to unchecked referenced imported type resulted + in missing tag in some table constraint cases. This error is + now corrected. Error occurred during decode in + <c>ber_bin optimized</c> version.</p> + <p>Own Id: OTP-5022</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>When a referenced value in another module in turn referenced a + defined value the compilation crashed. This is due to the new + routines for compilation, that external references are resolved + during compilation, and not by the order in which modules are + compiled. This error is now corrected.</p> + <p>Own Id: OTP-4970</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.4</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Functionality for parameterized class is added. Parsing failures on + WithSyntax spec is corrected.</p> + <p>Own Id: OTP-4893</p> + </item> + <item> + <p>The failure due to Parameterized Type when parameter is an object + set is corrected.</p> + <p>Own Id: OTP-4894</p> + <p>Aux Id: OTP-4893</p> + </item> + <item> + <p>Object Identifier values with two components and the first was a + value reference failed due to parsing conflicts. Now it is + corrected.</p> + <p>Own Id: OTP-4895</p> + </item> + <item> + <p>The erroneous comparison of file name and asn1 module name could + cause compilation failure. The situation for this failure is rare, + it requires that other processes modifies the compiled file during + the compilation procedure. It is now fixed.</p> + <p>Own Id: OTP-4944</p> + <p>Aux Id: seq8429</p> + </item> + <item> + <p>Selective decode was ignored when exclusive decode spec in asn1 + configfile was missing. Selective decode failed when the selected + type was the top type. These bugs are now removed.</p> + <p>Own Id: OTP-4953</p> + <p>Aux Id: seq8436</p> + </item> + <item> + <p>The test interface asn1ct:test/1,2,3 and asn1ct:value/2 failed for + open type and EXTERNAL. The bug is now removed.</p> + <p>Own Id: OTP-4955</p> + <p>Aux Id: seq8438)</p> + </item> + <item> + <p>Two equal functions were generated for two components referencing + the same type when they were picked by the action "parts". The bug + is now fixed.</p> + <p>Own Id: OTP-4957</p> + <p>Aux Id: seq8434</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>INTEGER with named number list and ENUMERATED can now be sub + constrained with names from the names list.</p> + <p>Own Id: OTP-4917</p> + </item> + <item> + <p>Now there is support for SelectionType (X 680 section 29)</p> + <p>Own Id: OTP-4918</p> + </item> + <item> + <p>The compiler now resolves circular dependencies. When asn1 specs + IMPORTS from each other so that there are circular dependencies.</p> + <p>Own Id: OTP-4919</p> + </item> + <item> + <p>Now is the asn1 type UTF8String supported. For user instructions + see documentation.</p> + <p>Own Id: OTP-4965</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.3.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The <c>{internal_error,...,{ unrecognized_type,...}}</c> + error occurring for a SET type when compiling with options + <c>[ber_bin,optimize,der]</c> is now corrected.</p> + <p>Own Id: OTP-4866</p> + </item> + <item> + <p>False encode of BIT STRING in PER (per_bin,optimize) is fixed. The error occurred when there was a type like BIT STRING (SIZE(C)) and C > 16.</p> + <p>Own Id: OTP-4869</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.3</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Functionality to handle parameterized object sets have been added.</p> + <p>Own Id: OTP-4832</p> + </item> + <item> + <p>Bug causing duplicated function definitions using exclusive decode is removed.</p> + <p>Own Id: OTP-4833)</p> + </item> + <item> + <p>The race condition when loading asn1 driver is solved.</p> + <p>Own Id: OTP-4835</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>A specialized decode, <em>selective decode</em> is now available. It decodes a chosen internal sub-type of a constructed type.</p> + <p>Own Id: OTP-4856)</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.2.2</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Release of Asn1 1.4.2.1 on R7B, The functionality is the same, but + the layer between the driver and the asn1 erlang code is different.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.2.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>ObjectDescriptor does now work as part of a sequence, set or choice.</p> + <p>Own Id: OTP-4773</p> + </item> + <item> + <p>When a SEQUENCE that have extension mark was decoded inside a + SEQUENCE OF it could cause decode error due to a failure in + restbytes2. It is now corrected.</p> + <p>Own Id: OTP-4791)</p> + </item> + <item> + <p>Now the bug is fixed that caused the compiler crash on an untagged + optional open type.</p> + <p>Own Id: OTP-4792</p> + </item> + <item> + <p>The earlier exit caused by bad in-data is now fixed so it will + return an {error,Reason} tuple.</p> + return an {error,Reason} tuple.</p> + <p>Own Id: OTP-4797</p> + </item> + <item> + <p>Open type encoded with indefinite length is now correct decoded.</p> + <p>Own Id: OTP-4798</p> + </item> + <item> + <p>Now is absent optional open types handled correctly.</p> + <p>Own Id: OTP-4799</p> + </item> + <item> + <p>Now is the necessary functions available for sorting in run-time of + SET and SET OF components.</p> + <p>Own Id: OTP-4809</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.2</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>When a component in a SEQUENCE is a CHOICE (or reference to a CHOICE) + and the SEQUENCE's component and one of the alternatives in the CHOICE + have identical names, an error may occur if one doesn't use the + 'optimized' versions of the compiler. In the older versions (<c>ber, ber_bin, per, per_bin</c>) one could optionally apply a value of a + component as <c>{ComponentName,Value}</c>, and the generated code + chooses the second element of the tuple. However, a value of a CHOICE + must be applied as a tuple: <c>{AlternativeName,Value}</c>. Thus, + in the rare case described above and if the value to the SEQUENCE's + component is not in a tuple notation the + <c>{AlternativeName,Value}</c> will be peeled off in the SEQUENCE + and the value fed to the CHOICE will only be the <c>Value</c> + part of <c>{AlternativeName,Value}</c>, and the encoder crashes. + The best way to avoid this is to use the optimized version of the + compiler where the unnecessary tuple notation + <c>{ComponentName,Value}</c> no longer is allowed. Since it isn't + possible to solve this bug in the compiler.</p> + <p>Own Id: OTP-4693</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>Exclusive decode is enabled by a compiler option and a configuration + file. It makes it possible to leave parts of an ASN.1 encoded message + un-decoded.</p> + <p>Own Id: OTP-4744</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.1.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The documentation about how extensibility is handled is now corrected.</p> + <p>Own Id: OTP-4663</p> + </item> + <item> + <p>Function in object now calls the exported function</p> + <p>Own Id: OTP-4665</p> + </item> + <item> + <p>Now is tags for ObjectClassFieldType analyzed correctly.</p> + <p>Own Id: OTP-4666</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Now is the Default value for an ENUMERATED returned as the name from + the NamedList when decoding.</p> + <p>Own Id: OTP-4633</p> + </item> + <item> + <p>It was an internal failure when permitted alphabet constraint existed + together with for instance a size constraint. E.g. when a + referenced type is constrained by a size constraint and the defined + type in turn is constrained by a permitted alphabet constraint.</p> + <p>Own Id: OTP-4559</p> + </item> + <item> + <p>Record is generated in hrl file for a CHOICE with extension mark + that has an internal SEQUENCE/SET definition.</p> + <p>Own Id: OTP-4560</p> + </item> + <item> + <p>Now is the length of a SEQUENCE/SET OF correctly encoded/decoded (PER).</p> + <p>Own Id: OTP-4590</p> + </item> + <item> + <p>The problem with unordered decoded terms when a component is a + ObjectClassFieldType has been solved.</p> + <p>Own Id: OTP-4591</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>More complex definitions with TableConstraints where the SimpleTable + and ComponentRelation are on different levels is now fully + supported.</p> + <p>Own Id: OTP-4631</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.4</title> + + <section> + <title>Fixed errors and malfunctions</title> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>Each generated .erl file have now a function info/0 that returns + information about the used compiler version and options.</p> + <p>Own Id: OTP-4373</p> + </item> + <item> + <p>When compiling an ASN.1 module the compiler generates an Erlang module + that is compiled by the Erlang compiler. Earlier it was not possible to + add options to the final step, the Erlang compilation. By adding any + option that is not recognized as a specific ASN.1 option it will be + passed to the final step like: <c>erlc +debug_info Mymodule.asn</c> or + <c>asn1ct:compile('Mymodule',[debug_info])</c>.</p> + <p>Own Id: OTP-4491</p> + </item> + <item> + <p>Earlier one couldn't multi file compile modules that had different + tagdefault, which now is possible. Equal Type/Value names in different + modules are resolved by renaming (concatenate type name and module + name): If two types with the same name T exist in module A and module B + they will get the new names TA and TB.</p> + <p>(Own Id: OTP-4492)</p> + <p>Aux Id: OTP-3983</p> + </item> + <item> + <p>BER: Encode/decode of data have been significantly improved. By use of + the compiler options <c>ber_bin</c> and <c>optimize</c>, + optimized code will be generated and the optimized run-time module will + be used.</p> + <p>Own Id: OTP-4493</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.3.3.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Proper length encoding and padding implemented for a <c>BIT STRING</c> with + NamedNumberList and size constraint as value range. This functionality + didn't work in the rare occasion when the NamedNumberList is shorter + than the lower bound of the constraint.As in this example: + <c>TestS ::= BIT STRING {a (0),b (1)} (SIZE (3..8))</c></p> + <p>(Own Id: OTP-4353)</p> + </item> + <item> + <p>Bug in compiler, when an <c>OBJECT IDENTIFIER</c> value consisting of + two identifiers (Defined values or Name form identifiers) was falsely + interpreted causing a compiling error is now corrected.</p> + <p>(Own Id: OTP-4354)</p> + </item> + <item> + <p>Internal error in check phase that caused crash on + <c>ObjectClassFieldType</c> in ber_bin is corrected.</p> + <p>(Own Id: OTP-4390)</p> + </item> + <item> + <p>Tags for open types are handled according to <c>x.680 30.6c</c>, i.e. + open types shall not be tagged <c>IMPLICIT.</c></p> + <p>(Own Id: OTP-4395)</p> + <p>(Aux Id: OTP-4390)</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.3.3</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Now gives the compiler an appropriate error report when exported + undefined types are detected.</p> + <p>(Own Id: OTP-4129)</p> + </item> + <item> + <p>The type <c>ObjectDescriptor</c> is now supported, previously the + implementation of encode/decode for this rarely used type was + incomplete.</p> + <p>(Own Id: OTP-4161)</p> + <p>(Aux Id: seq7165)</p> + </item> + <item> + <p>In case of per and compact_bit_string the rightmost byte were erroneous + truncated when the rightmost bits of that byte were zeros. This is now + corrected.</p> + <p>(Own Id: OTP-4200)</p> + </item> + <item> + <p>Bad match of return-value from decode_length in skipvalue/3 has now been + fixed.</p> + <p>(Own Id: OTP-4232)</p> + </item> + <item> + <p>Now is decode of ENUMERATED handled correctly, when tagged EXPLICIT.</p> + <p>(Own Id: OTP-4234)</p> + </item> + <item> + <p>The compiler now parses and handles the ValueFromObject construct.</p> + <p>(Own Id: OTP-4242)</p> + </item> + <item> + <p>Now does the compiler handle the case when the object set in simple + table and componentrelation constraints is of a CLASS without a UNIQUE + field. In this case is the octets, which is assumed to be encoded, + encoded as an open type.</p> + <p>(Own Id: OTP-4248)</p> + <p>(Aux Id: OTP-4242)</p> + </item> + <item> + <p>Compiler handles objects in AdditionalElementSetSpec in ObjectSetSpec, + i.e. the objects that are referred to after the ellipses in an object set.</p> + <p>(Own Id: OTP-4275)</p> + </item> + <item> + <p>Now are values with a component of type CHOICE encoded with indefinite + length correctly decoded.</p> + <p>(Own Id: OTP-4358)</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The language constructs (from the old 1988 standard) <c>ANY</c> + and <c>ANY DEFINED BY</c> are now implemented.</p> + <p>(Own Id: OTP-2741)</p> + <p>(Aux Id: seq 1188)</p> + </item> + <item> + <p>Now it is checked in run-time if a <c>OBJECT IDENTIFIER</c> value is invalid</p> + <p>(Own Id: OTP-4235)</p> + </item> + <item> + <p>The ASN.1 types EXTERNAL,EMBEDDED PDV and CHARACTER STRING now have full support in the compiler.</p> + <p>(Own Id: OTP-4247)</p> + </item> + <item> + <p>A driver in C does the final job (complete) of the PER encoding when + files are compiled with <c>per_bin</c> and <c>optimize</c> flags. + It gives significant faster encoding for PER.</p> + <p>(Own Id: OTP-4355)</p> + </item> + <item> + <p>Encode and decode of PER encoding has been made faster by moving + analysis done in run-time to compile-time. These optimizations are + available by compiling ASN.1 files with options <c>per_bin</c> and + <c>optimize</c>.</p> + <p>(Own Id: OTP-4381)</p> + <p>(Aux Id: OTP-4355)</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.3.2</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Now does the compiler check values (including referenced values), and + formats the value so it is suitable to use as input to encoding + functions.</p> + <p>(Own Id: OTP-3277)</p> + <p>(Aux Id: OTP-4103)</p> + </item> + <item> + <p>Unnecessary external function calls in generated code are now generated + as internal function calls.</p> + <p>(Own Id: OTP-4073)</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>Now is Information Objects supported in BER encoding.</p> + <p>(Own Id: OTP-3980)</p> + <p>(Aux Id: OTP-3979 OTP-3978)</p> + <p></p> + </item> + <item> + <p>PER: A new option <c>per_bin</c> is now supported. When used the + generated encode/decode functions use binaries and the bit syntax to + get better performance than the old <c>per</c> variant which used + lists. All values input to encode and returned from decode are + compatible between <c>per</c> and <c>per_bin</c> except for + open types which are represented as binaries with per_bin and octet + lists with per. We recommend that you use per_bin instead of per from + now on, the use of binaries will be the default in coming versions and + all improvements and optimizations for PER will be concentrated to that + solution.</p> + <p>(Own Id: OTP-4094)</p> + <p></p> + </item> + <item> + <p>Support for DER implemented. Used by flag +der when compiling. Include + the full BER encoding plus: sorting of SET components, sorting of + encoded elements in SET OF, full check of default values in SET and + SEQUENCE. See new documentation on DER in user_guide sections 1.3.1; + 1.4.11; 1.4.12; 1.4.14; 1.4.16 and 1.10, in the reference manual for + asn1ct.</p> + <p>(Own Id: OTP-4103)</p> + <p></p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.3.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>Do not generate record in .hrl file for SET types</p> + <p>Own Id: OTP-4025</p> + </item> + <item> + <p>Fixed internal error when using BIT STRINGs with Named Number List in combination with <c>compact_bit_string</c> and <c>ber_bin</c> options.</p> + <p>Own Id: OTP-4026</p> + <p>Aux Id: OTP-3982</p> + </item> + <item> + <p>The atom 'com' can now be used in ENUMERATED as an EnumerationItem.</p> + <p>Own Id: OTP-4037</p> + <p>Aux Id: Seq 7036</p> + </item> + <item> + <p>ber: Now it is possible (again) to encode data format "{Type,Value}" in a SEQUENCE OF RequestParameter, when RequestParameter is of type ENUMERATED. The {Type,Value} + notation is not recommended for use, it is redundant and exist only for very ancient backwards compatibility reasons. The "feature" might be removed in forthcoming versions.</p> + <p>Own Id: OTP-4057</p> + <p>Aux Id: Seq 7066</p> + </item> + <item> + <p>A bug in the parser, that caused failure on COMPONENTS OF is now removed.</p> + <p>Own Id: OTP-4058</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.3</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The compiler will now check that a value referenced by name + does exist.</p> + <p>Own Id: OTP-3277</p> + </item> + <item> + <p>BER:Decode of a type T ::= SEQUENCE OF C fails if C is encoded with indefinite length. + This is know corrected.</p> + <p>Own Id: OTP-3811</p> + <p>Aux Id: seq5040</p> + </item> + </list> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The new parser handles imports when one import ends with FROM, a modulename and a reference to a objectidentifier followed by imports from other modules.</p> + <p>Own Id: OTP-3463</p> + </item> + <item> + <p>The compiler did not check that a name mentioned as EXPORTED + actually is defined within the module. + This is now corrected.</p> + <p>Own Id: OTP-3659</p> + </item> + <item> + <p>Removed bug caused by use of nested indefinite length</p> + <p>Own Id: OTP-3994</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>Now supporting most common use of parameterization according to X.683</p> + <p>(Own Id: OTP-3978)</p> + </item> + <item> + <p>PER: Now supporting most common use of Information Objects according to X.681. A new parser has been implemented. The error messages due to syntax errors are slightly different than previous. TableConstraint part of X.682 now also supported.</p> + <p>Own Id: OTP-3979</p> + </item> + <item> + <p>New compiler option added: <c>ber_bin</c>. The compiler generates code with new bit syntax. Run time functions uses bit syntax when feasible. Higher encoding/decoding performance in most cases. Se also comments for Asn1 1.2.9.3.</p> + <p>Own Id: OTP-3981</p> + </item> + <item> + <p>A more compact format of BIT STRING in Erlang is now available by use of the compiler option <c>compact_bit_string</c>. It is much faster when large BIT STRINGs are used.</p> + <p>Own Id: OTP-3982</p> + </item> + <item> + <p>Now possible to merge many ASN.1 input files to one Erlang file by use of a configuration file that lists the ASN.1 files.</p> + <p>Own Id: OTP-3983</p> + </item> + <item> + <p>New documentation in <em>User's Guide</em> in section:</p> + <p>3.1: New compile-time functions and options are described.</p> + <p>4.6: New compact format of BIT STRING is described.</p> + <p>4.8: Additional comments on character strings.</p> + <p>7: New section describing ASN.1 Information Objects.</p> + <p>8: New section describing Parameterization.</p> + <p><em>Reference Manual/asn1ct</em> New compile options are described.</p> + <p>Own Id: OTP-3984</p> + <p>Aux Id: OTP-3978, OTP-3979, OTP-3981, OTP-3982, OTP-3983</p> + </item> + <item> + <p>Added the functionality to invoke ASN1Mod:encode (and decode).</p> + <p>Own Id: OTP-3985</p> + </item> + <item> + <p>Performance improvements by removing not necessary use of apply when calling asn1rt:encode. Also other general improvements.</p> + <p>Own Id: OTP-3988</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.9.6</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The compiler does not check that an exported name actually exists in the ASN.1 module.</p> + <p>Own Id: OTP-3659</p> + </item> + <item> + <p>The compiler does not check that a value referenced by name does exist.</p> + <p>Own Id: OTP-3277</p> + </item> + <item> + <p>BER: The compiler does not take the extensions into account when checking if + the tags are unique in a SEQUENCE or SET.</p> + <p>Own Id: OTP-3304</p> + </item> + </list> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>PER: Trailing zeroes in a BIT STRING declared without named bits + should not be removed in the encodings.</p> + <p>Own Id: OTP-3830</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.9.5</title> + + <section> + <title>Known problems</title> + <p>Same as for 1.2.9.3.</p> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>PER: Constraints are not propagated when types are + referring to each other. Example:</p> + <code type="none"> + + TBCD-STRING ::= OCTET STRING + + LAI ::= TBCD-STRING (SIZE(3)) </code> + <p>The size constraint is not passed on during encode,decode + resulting in wrong encoding for PER , it is + coded with a length determinant which should not be there + when the length is fixed. For BER this does not matter because the constraints does + not affect the encodings.</p> + <p>Own Id: OTP-3713</p> + </item> + <item> + <p>The generated code gets wrong if there are several ENUMERATED fields in a SEQUENCE or SET, this is now corrected.</p> + <p>Own Id: OTP-3796</p> + </item> + <item> + <p>BER:Decode of a type T ::= SEQUENCE OF C fails if C is encoded with indefinite length. + This is know corrected.</p> + <p>Own Id: OTP-3811</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.9.3</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The compiler does not check that an exported name actually exists in the ASN.1 module.</p> + <p>Own Id: OTP-3659</p> + </item> + <item> + <p>The compiler does not check that a value referenced by name does exist.</p> + <p>Own Id: OTP-3277</p> + </item> + <item> + <p>BER: The compiler does not take the extensions into account when checking if + the tags are unique in a SEQUENCE or SET.</p> + <p>Own Id: OTP-3304</p> + </item> + </list> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>This version supports soft upgrade from versions 1.2.6 1.2.7.</p> + </item> + <item> + <p>In an ENUMERATED type like this:</p> + <code type="none"> +\011\011T ::= ENUMERATED { blue, green} </code> + <p>The symbols was encoded/decoded with the wrong values, i.e in + reverse order. This is now corrected.</p> + <p>Own Id: OTP-3700</p> + </item> + <item> + <p>PER: OCTET STRING with Size constrained to a single value i.e fixed size + was treated wrong during encode and decode. This is now corrected.</p> + <p>Own Id: OTP-3701</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>There is now a new compiler option <c>ber_bin</c> available that can be used to + generate encode/decode functions for BER that uses the new "bit-syntax" to + make the functions more efficient. The <c>ber_bin</c> option is used + as an alternative to the <c>ber</c> and <c>per</c> options.</p> + <p>The encode function then produces a + possibly nested list of binaries and integer lists. The decode function does + in this case require a single binary as input instead of a list. + The modules generated with this option require that you have an R7A or later + system, otherwise they will not compile and the runtime module asn1rt_ber_bin + can not be executed.</p> + <p>The ber_bin option is not officially supported in this version (will be + in a later version) but is provided for those who want to try it. + It should be significantly faster at decode and is slightly faster at encode. + Exactly how performance differs between this binary approach and the + list approach depends highly on the type of input. + Another thing worth noting is that both approaches still have a lot of + solutions in common which can be improved a lot to gain even better + performance.</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.9.2</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>BER: Encode/decode of extension components did not work properly. This is now corrected.</p> + <p>Own Id: OTP-3395</p> + <p>Aux Id: </p> + <p>PER:The encode/decode of NULL as an open type has been corrected. An open type must always have a length of at least 1 byte even if the contained + value (e.g NULL) encodes to nothing.</p> + <p>Own Id: OTP-3496</p> + <p>Aux Id: </p> + </item> + <item> + <p>BER:In the current implementation extension components of a SEQUENCE are required + to be present when they are specified as mandatory. This is an error, all extension + components are "optional" even if they are not specified to have the OPTIONAL or + DEFAULT property. This is now corrected.</p> + <p>Own Id: OTP-3278</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The ASN.1 language feature <c>COMPONENTS OF</c> is now implemented.</p> + <p>Own Id: OTP-2515</p> + </item> + <item> + <p>The encoding and decoding of ENUMERATED and + INTEGER with NamedNumbers is made more efficient and thus + faster in runtime.</p> + <p>Own Id: OTP-3464</p> + <p>Aux Id:</p> + </item> + <item> + <p>Added support for encode/decode of open type which is + constrained to a specific type. Previously the value of + an open type had to be a list of octets, but now the Erlang + representation of the specific type used in the constraint + is used both as input to encode and as output from decode.</p> + <p>Own Id: OTP-3569</p> + <p>Aux Id: </p> + </item> + <item> + <p>PER: GeneralString, GraphicalString etc. i.e all strings + that are not so called "known-multiplier character + string types" are now supported by the runtime + encode/decode functions.</p> + <p>Own Id: OTP-3573</p> + <p>Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.6</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The ASN.1 language feature <c>COMPONENTS OF</c> is not implemented.</p> + <p>Own Id: OTP-2515</p> + </item> + <item> + <p>The compiler does not check that a value referenced by name does exist.</p> + <p>Own Id: OTP-3277</p> + </item> + <item> + <p>BER:In the current implementation extension components of a SEQUENCE are required + to be present when they are specified as mandatory. This is an error, all extension + components are "optional" even if they are not specified to have the OPTIONAL or + DEFAULT property.</p> + <p>Own Id: OTP-3278</p> + </item> + <item> + <p>BER: The compiler does not take the extensions into account when checking if + the tags are unique in a SEQUENCE or SET.</p> + <p>Own Id: OTP-3304</p> + </item> + </list> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>This version supports soft upgrade from versions 1.1.1, 1.1.5 and 1.1.6. + Two new runtime modules <c>asn1rt_ber_v1</c> and + <c>asn1rt_per_v1</c> are delivered together with the old ones. This makes + it possible to continue running applications with modules generated with the + previous version of the asn1 compiler while modules generated by this version + will use the new runtime modules. Note that it is only advice-able to continue + running old generates if they are working perfectly and have no need + for the corrections made in this version of the asn1 application.</p> + </item> + <item> + <p>BER: SEQUENCEs encoded with indefinite length was not correctly decoded. + This in now corrected.</p> + <p>Own Id: OTP-3352</p> + <p>Aux Id: Seq 4100</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.2.4</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The compiler now detects multiple definitions of values and types and reports this as + an error. Previously this was detected when the generated Erlang module was compiled.</p> + <p>Own Id: OTP-3105</p> + </item> + <item> + <p>BER: An error regarding encoding of <c>ENUMERATED</c> present in asn1-1.1.1 + is corrected. The new version 1.1.2 of asn1 containing this correction is + delivered as a "patch".</p> + <p>Own Id: OTP-3169</p> + </item> + <item> + <p>BER: Decoding of <c>SEQUENCE OF</c> and <c>SET OF</c> with indefinite length is corrected. + The correction was first delivered in version 1.1.2.</p> + <p>Own Id: OTP-3170</p> + </item> + <item> + <p>BER: Encoding and decoding of <c>ENUMERATED</c> + with extensionmark + "..." did not work (crashed with a runtime error). This + has now been corrected. If an unknown enumerated value is + decoded (for an extensible enumerated type) + it is returned as <c>{asn1_enum,Value}</c> where + <c>Value</c> is an integer. Enumerated values in this format + are also accepted by the encoder. + ASN.1 modules containing + <c>ENUMERATED</c> with extensionmark should be + recompiled with the corrected + version of the compiler. The BER runtime functions are also + corrected. + Note that this correction has already been delivered as a + bugfix for R4B (OTP-2951).</p> + <p>Own Id: OTP-3202</p> + <p>Aux Id: Seq3745</p> + </item> + <item> + <p>BER: The primitive/constructed bit in the tag byte of an encoding + is not correct when it comes to user defined tags. + For example in </p> + <code type="none"> + T ::= [2] SEQUENCE { a BOOLEAN} </code> + <p>the tag 2 does not get the constructed bit set which it should. + This is now corrected.</p> + <p>Own Id: OTP-3241</p> + </item> + <item> + <p>The decoder can now detect if there are unexpected bytes + remaining when all components of a sequence are decoded. + The decoder will then return <c>{error,{asn1{unexpected,Bytes}}}</c></p> + <p>Own Id: OTP-3270</p> + </item> + <item> + <p>Values of type <c>OBJECT IDENTIFIER</c> was sometimes returned as an Erlang list + (ASN.1 constants) and sometimes as a tuple (from the decode functions). This is now + changed so that <c>OBJECT IDENTIFIER</c> values always are represented as an Erlang + tuple.</p> + <p>Own Id: OTP-3280</p> + </item> + <item> + <p>PER:The encode/decode functions could not handle integers with + a range greater than 16#7ffffff. This limit is now removed.</p> + <p>Own Id: OTP-3287</p> + </item> + <item> + <p>PER: The encoding/decoding of the length for a SET OF/SEQUENCE OF + was wrong if there was a size constraint. This is now corrected.</p> + <p>Own Id: OTP-3291</p> + </item> + <item> + <p>PER: Encoding of a constrained INTEGER (range > 16 k) was wrong for + the value 0. This is now corrected.</p> + <p>Own Id: OTP-3306</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The ASN.1 module name and the filename where the ASN.1 + specification resides must match each other (has always been the + case). This is now checked by the compiler. The check requires that + the names match in a case or case insensitive way depending on the + characteristics for the current system.</p> + <p>Own Id: OTP-1843</p> + </item> + <item> + <p>PER: Encode/decode of an extension value (i.e not within the root set) for + <c>ENUMERATED</c> did not work properly. This is now corrected. + If an unknown enumerated value is + decoded (for an extensible enumerated type) + it is returned as <c>{asn1_enum,Value}</c> where + <c>Value</c> is an integer. Enumerated values in this format + are also accepted by the encoder (if the value is >= the number of known + extension values).</p> + <p>Own Id: OTP-2930</p> + </item> + <item> + <p>Unnecessary printouts from the compiler are removed. + The compiler version and the compiler options are now + printed to stdout.</p> + <p>Own Id: OTP-3276</p> + </item> + <item> + <p>In order to better suite the use of ASN.1 in embedded systems only + the modules needed in runtime are now listed in the <c>.app</c> file.</p> + <p>Own Id: OTP-3279</p> + </item> + <item> + <p>The compiler now supports extensionmarker in constraint specifications. + Example:</p> + <code type="none"> +INTEGER (0..10, ...) </code> + <p>In previous version this was reported as a syntax error.</p> + <p>Own Id: OTP-3281</p> + </item> + <item> + <p>A very limited part of ITU-T recommendation X.681 + Abstract Syntax Notation One (ASN.1): Information + object specification is now implemented. Specifically \011 + TYPE IDENTIFIER is recognized by the compiler.</p> + <p>Own Id: OTP-3325</p> + </item> + <item> + <p>Parameterization of ASN.1 specifications (ITU-T X.683) is now + supported to a limited extent.</p> + <p>Own Id: OTP-3326</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.1.3.1</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>BER Encoding and decoding of <c>ENUMERATED</c> + with extensionmark + "..." did not work (crashed with a runtime error). This + has now been corrected. If an unknown enumerated value is + decoded (for an extensible enumerated type) + it is returned as <c>{asn1_enum,Value}</c> where + <c>Value</c> is an integer. Enumerated values in this format + are also accepted by the encoder. + ASN.1 modules containing + <c>ENUMERATED</c> with extensionmark should be + recompiled with the corrected + version of the compiler. The BER runtime functions are also + corrected. + Note that this correction has already been delivered as a + bug-fix for R4B (OTP-2951).</p> + <p>Own Id: OTP-3202</p> + <p>Aux Id: Seq3745</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.1.1</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The syntactic construct <c>COMPONENTS OF</c> is not + implemented.</p> + <p>Own Id: OTP-2515</p> + </item> + <item> + <p><c>ANY</c> and <c>ANY DEFINED BY</c> are currently not + supported.</p> + <p>Own Id: OTP-2741</p> + <p>Aux Id: seq 1188</p> + </item> + <item> + <p>Multiple definitions of the same Type or Value is not detected + by the compiler. The error occurs when the generated Erlang + module is compiled.</p> + <p>Own Id: OTP-3105</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.1</title> + + <section> + <title>Known problems</title> + <list type="bulleted"> + <item> + <p>The primitive/constructed bit in the tag byte of an encoding + is not correct when it comes to user defined tags. + For example in</p> + <code type="none"> + T ::= [2] SEQUENCE { a BOOLEAN} </code> + <p>the tag 2 does not get the constructed bit set which it should. + This is now corrected.</p> + <p>Own Id: OTP-3241</p> + </item> + </list> + </section> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The BER decoder failed to decode certain nested data types + where <c>IMPLICIT</c> tags where involved. + This is now corrected.</p> + <p>Own Id: OTP-2719</p> + <p>Aux Id: seq 1148</p> + </item> + <item> + <p>The handling of types with extension marker "..." is corrected. + Earlier each SEQUENCE and SET with an extension marker got an + extra field named <c>asn1_EXT</c> in the generated record. + This was a mistake and that field is now removed (concerns + both BER and BER).</p> + <p>Own Id: OTP-2724</p> + <p>Aux Id: seq 1148, OTP-2719</p> + </item> + <item> + <p>The decoder (both BER and PER) could not handle unnamed + bits of a <c>BIT STRING</c> if the type had any + named bits declared. This is now corrected and the unnamed + bits are returned as <c>{bit,Pos}</c> where Pos is the bit + position. The <c>{bit,Pos}</c> can be used as input to the + encoder too.</p> + <p>Own Id: OTP-2725</p> + <p>Aux Id: seq 1148,OTP-2719,OTP-2724</p> + </item> + <item> + <p>The functions <c>asn1rt:decode</c> and <c>asn1ct:decode</c> + did not always return <c>{ok,Result}</c> or + <c>{error,Reason}</c> as documented. This is now corrected.</p> + <p>Own Id: OTP-2730</p> + <p>Aux Id: seq 1158</p> + </item> + <item> + <p>The compiler did not accept CHOICE types as components + of a SEQUENCE or SET when + the modules tag default was IMPLICIT. + Example:</p> + <code type="none"> +C ::= CHOICE { ......} +A ::= SEQUENCE { +a [1] C, -- This was not accepted +..... </code> + <p>This was an error + caused by a misinterpretation of the ASN.1 standard. This + is now corrected.</p> + <p>Own Id: OTP-2731</p> + <p>Aux Id: seq 1163</p> + </item> + <item> + <p>When decoding a SEQUENCE A which contains an OPTIONAL component + b which is a SEQUENCE with mandatory components, the decoder + does not detect as an error that a mandatory component of b + is missing. The same error could occur also in other cases + with nested types and optional components of SEQUENCE or SET. + This is now corrected.</p> + <p>Own Id: OTP-2738</p> + <p>Aux Id: seq 1183</p> + </item> + <item> + <p>BER Encoding and decoding of <c>ENUMERATED</c> + with extensionmark + "..." did not work (crashed with a runtime error). This + has now been corrected. If an unknown enumerated value is + decoded (for an extensible enumerated type) + it is returned as <c>{asn1_enum,Value}</c> where + <c>Value</c> is an integer. Enumerated values in this format + are also accepted by the encoder. + ASN.1 modules containing + <c>ENUMERATED</c> with extensionmark should be + recompiled with the corrected + version of the compiler. The BER runtime functions are also + corrected.</p> + <p>Own Id: OTP-2951</p> + <p>Aux Id: Seq 1446 OTP-2929</p> + </item> + <item> + <p>The compiler does now accept all valid value notations + for the OBJECT IDENTIFIER type. The generated code for + those values is also corrected.</p> + <p>Own Id: OTP-3059</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The code generated for BER is significantly enhanced resulting + in less code and around 300% better performance in runtime + for the encoding of complex ASN.1 values. The performance of + decoding is unchanged.</p> + <p>Own Id: OTP-2806</p> + </item> + </list> + </section> + </section> + + <section> + <title>Asn1 1.0.3</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The <c>asn1.app</c> file is corrected.</p> + <p>Own Id: OTP-2640</p> + </item> + <item> + <p>The encoding of integers in BER did not comply with the + standard for all values. The values was not encoded + in the minimum number of octets as required. This is + now corrected in the runtime module <c>asn1rt_ber</c>.</p> + <p>Own Id: OTP-2666</p> + </item> + </list> + </section> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The compiler now generates explicit exports directives for + all generated + functions that should be exported (instead of -compile(export_all)). + This eliminates the warnings from the Erlang compiler when + compiling the + generated file.</p> + <p>Own Id: OTP-1845</p> + </item> + </list> + </section> + </section> + + <section> + <title>R3B02 (Asn1 1.0.2)</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The decoding of a BER encoded SEQUENCE with optional component + of type SEQUENCE (also with optional components) could result + in an error or wrong result if the tags are equal.</p> + <p>Own Id: OTP-2226</p> + </item> + <item> + <p>The encoding of (PER) SEQUENCE with extensionmark was wrong. + This is now corrected.</p> + <p>Own Id: OTP-2349</p> + </item> + </list> + </section> + </section> + + <section> + <title>R3A (Asn1 0.9)</title> + + <section> + <title>Fixed errors and malfunctions</title> + <list type="bulleted"> + <item> + <p>The asn1 compiler now detects the use of an implicit tag before <c>CHOICE</c> as an error (in accordance with the standard)</p> + <p>Own Id: OTP-1844</p> + </item> + <item> + <p>An OPTIONAL CHOICE embedded in SEQUENCE when BER coding + caused an error when generating decode code. This is now + corrected.</p> + <p>Own Id: OTP-1857</p> + <p>Aux Id: OTP-1848</p> + </item> + </list> + </section> + </section> + + <section> + <title>1 ASN1 0.8.1</title> + <p>This is the first release of the ASN1 application. This version is + released for beta-testing. Some functionality will be added until the + 1.0 version is released. See the release notes for the latest version + for the exact details about new features. A list of missing features + and restrictions can be found in the chapter below.</p> + + <section> + <title>1.1 Missing features and other restrictions</title> + <p></p> + <list type="bulleted"> + <item> + <p>The encoding rules BER and PER (aligned) is supported. <em>PER (unaligned) IS NOT SUPPORTED</em>.</p> + </item> + <item> + <p>NOT SUPPORTED types <c>ANY</c> and <c>ANY DEFINED BY</c> + (is not in the standard any more).</p> + </item> + <item> + <p>NOT SUPPORTED types <c>EXTERNAL</c> and <c>EMBEDDED-PDV</c>. </p> + </item> + <item> + <p>NOT SUPPORTED type <c>REAL</c> (planned to be implemented). </p> + </item> + <item> + <p>The code generation support for value definitions in the ASN.1 notation is very limited + (planned to be enhanced).</p> + </item> + <item> + <p>The support for constraints is limited to:</p> + </item> + </list> + <list type="bulleted"> + <item> + <p>SizeConstraint SIZE(X)</p> + </item> + <item> + <p>SingleValue (1)</p> + </item> + <item> + <p>ValueRange (X..Y)</p> + </item> + <item> + <p>PermittedAlpabet FROM (but not for BMPString and UniversalString when generating PER).</p> + </item> + <item> + <p>Complex expressions in constraints is not supported (planned to be extended).</p> + </item> + <item> + <p>The current version of the compiler has very limited error checking:</p> + </item> + <item> + <p>Stops at first syntax error.</p> + </item> + <item> + <p>Does not stop when a reference to an undefined type is found , + but prints an error message. Compilation of the generated + Erlang module will then fail.</p> + </item> + <item> + <p>A whole number of other semantical controls is currently + missing. This means that the compiler will give little + or bad help to detect what's wrong with an ASN.1 + specification, but will mostly work very well when the + ASN.1 specification is correct.</p> + </item> + </list> + <list type="bulleted"> + <item> + <p>The maximum INTEGER supported in this version is a + signed 64 bit integer. This limitation is probably quite + reasonable. (Planned to be extended).</p> + </item> + <item> + <p>Only AUTOMATIC TAGS supported for PER.</p> + </item> + <item> + <p>Only EXPLICIT and IMPLICIT TAGS supported for BER.</p> + </item> + <item> + <p>The compiler supports decoding of BER-data with indefinite + length but it is not possible to produce data with indefinite + length with the encoder.</p> + </item> + </list> + </section> + </section> +</chapter> + diff --git a/lib/asn1/doc/src/part.xml b/lib/asn1/doc/src/part.xml new file mode 100644 index 0000000000..19ee64b4a0 --- /dev/null +++ b/lib/asn1/doc/src/part.xml @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Asn1 User's Guide</title> + <prepared>Kenneth Lundin</prepared> + <docno></docno> + <date>1999-02-12</date> + <rev>0.9</rev> + <file>part.sgml</file> + </header> + <description> + <p>The <em>Asn1</em> application + contains modules with compile-time and run-time support for ASN.1. + </p> + </description> + <xi:include href="asn1_ug.xml"/> + <xi:include href="asn1_spec.xml"/> +</part> + diff --git a/lib/asn1/doc/src/part_notes.xml b/lib/asn1/doc/src/part_notes.xml new file mode 100644 index 0000000000..b0a6887aa5 --- /dev/null +++ b/lib/asn1/doc/src/part_notes.xml @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Asn1 Release Notes</title> + <prepared>Ingela Anderton Andin</prepared> + <docno></docno> + <date>>2004-09-07</date> + <rev></rev> + <file>part_notes.sgml</file> + </header> + <description> + <p>The <em>Asn1</em> application + contains modules with compile-time and run-time support for ASN.1.</p> + <p>There are also release notes for + <url href="notes_history.html">older versions</url>.</p> + </description> + <xi:include href="notes.xml"/> +</part> + diff --git a/lib/asn1/doc/src/ref_man.xml b/lib/asn1/doc/src/ref_man.xml new file mode 100644 index 0000000000..a0af1f5be3 --- /dev/null +++ b/lib/asn1/doc/src/ref_man.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Asn1 Reference Manual</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>1997-10-04</date> + <rev>1.3.1</rev> + <file>application.sgml</file> + </header> + <description> + <p>The <em>Asn1</em> application + contains modules with compile-time and run-time support for ASN.1.</p> + </description> + <xi:include href="asn1ct.xml"/> + <xi:include href="asn1rt.xml"/> +</application> + diff --git a/lib/asn1/doc/src/selective_TypeList.gif b/lib/asn1/doc/src/selective_TypeList.gif Binary files differnew file mode 100644 index 0000000000..b1bf0a4f5b --- /dev/null +++ b/lib/asn1/doc/src/selective_TypeList.gif diff --git a/lib/asn1/doc/src/selective_TypeList.ps b/lib/asn1/doc/src/selective_TypeList.ps new file mode 100644 index 0000000000..0d1f301240 --- /dev/null +++ b/lib/asn1/doc/src/selective_TypeList.ps @@ -0,0 +1,266 @@ +%!PS-Adobe-2.0 +%%Title: selective_TypeList.ps +%%Creator: fig2dev Version 3.2 Patchlevel 1 +%%CreationDate: Tue Oct 28 15:52:00 2003 +%%For: bertil@super (Bertil Karlsson,UAB/F/P) +%%Orientation: Portrait +%%BoundingBox: 158 178 453 614 +%%Pages: 1 +%%BeginSetup +%%IncludeFeature: *PageSize Letter +%%EndSetup +%%Magnification: 1.0000 +%%EndComments +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +55.5 677.0 translate +1 -1 scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit +n -1000 9310 m -1000 -1000 l 7626 -1000 l 7626 9310 l cp clip + 0.06000 0.06000 sc +%%Page: 1 1 +% Arc +7.500 slw +gs clippath +2363 5348 m 2475 5400 l 2352 5407 l 2484 5432 l 2495 5373 l cp +clip +n 2470.1 5021.7 378.3 -100.7 89.3 arcn +gs col0 s gr + gr + +% arrowhead +n 2363 5348 m 2475 5400 l 2352 5407 l 2357 5378 l 2363 5348 l cp gs 0.00 setgray ef gr col0 s +% Arc +gs clippath +2384 7192 m 2475 7275 l 2355 7245 l 2474 7309 l 2502 7256 l cp +clip +n 2896.9 6337.5 1028.0 -114.2 114.2 arcn +gs col0 s gr + gr + +% arrowhead +n 2384 7192 m 2475 7275 l 2355 7245 l 2369 7218 l 2384 7192 l cp gs 0.00 setgray ef gr col0 s +% Arc +gs clippath +2448 7504 m 2550 7575 l 2427 7561 l 2553 7608 l 2575 7552 l cp +clip +n 2512.5 7462.5 118.6 -108.4 71.6 arcn +gs col0 s gr + gr + +% arrowhead +n 2448 7504 m 2550 7575 l 2427 7561 l 2438 7533 l 2448 7504 l cp gs 0.00 setgray ef gr col0 s +% Arc +gs clippath +2869 2255 m 2775 2175 l 2896 2202 l 2775 2141 l 2748 2195 l cp +clip +n 1347.8 5222.4 3365.1 42.6 -64.9 arcn +gs col0 s gr + gr + +% arrowhead +n 2869 2255 m 2775 2175 l 2896 2202 l 2882 2229 l 2869 2255 l cp gs 0.00 setgray ef gr col0 s +% Arc +gs clippath +5199 1837 m 5250 1950 l 5152 1874 l 5236 1980 l 5283 1943 l cp +clip +n 4021.7 2817.4 1503.7 -141.2 -35.2 arc +gs col0 s gr + gr + +% arrowhead +n 5199 1837 m 5250 1950 l 5152 1874 l 5176 1856 l 5199 1837 l cp gs 0.00 setgray ef gr col0 s +/Times-Roman ff 180.00 scf sf +2400 1350 m +gs 1 -1 sc (Action ::= SEQUENCE ) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 1590 m +gs 1 -1 sc ( { ) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 1830 m +gs 1 -1 sc ( number INTEGER DEFAULT 15,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 2310 m +gs 1 -1 sc ( }) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 2790 m +gs 1 -1 sc (Key ::= [11] EXPLICIT Button) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 3030 m +gs 1 -1 sc (Handle ::= [12] Key) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 3270 m +gs 1 -1 sc (Button ::= SEQUENCE ) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 3510 m +gs 1 -1 sc ( {) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 3750 m +gs 1 -1 sc ( number INTEGER,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 3990 m +gs 1 -1 sc ( on BOOLEAN) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 4230 m +gs 1 -1 sc ( }) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 4950 m +gs 1 -1 sc ( {) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 5190 m +gs 1 -1 sc ( vsn INTEGER,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 5670 m +gs 1 -1 sc ( }) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 6150 m +gs 1 -1 sc (Status ::= SEQUENCE ) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 6390 m +gs 1 -1 sc ( {) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 6630 m +gs 1 -1 sc ( state INTEGER,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 6870 m +gs 1 -1 sc ( buttonList SEQUENCE OF Button,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 7110 m +gs 1 -1 sc ( enabled BOOLEAN OPTIONAL,) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 7830 m +gs 1 -1 sc ( noOfActions INTEGER) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 8070 m +gs 1 -1 sc ( }) col0 sh gr +/Times-Roman ff 180.00 scf sf +2400 8310 m +gs 1 -1 sc ( }) col0 sh gr +/Times-Roman ff 180.00 scf sf +3150 4725 m +gs 1 -1 sc (::= CHOICE) col0 sh gr +/Times-Bold ff 195.00 scf sf +2400 4710 m +gs 1 -1 sc (Window) col0 sh gr +/Times-Bold ff 195.00 scf sf +2400 5430 m +gs 1 -1 sc ( status) col0 sh gr +/Times-Roman ff 180.00 scf sf +3225 5475 m +gs 1 -1 sc (E) col0 sh gr +/Times-Roman ff 180.00 scf sf +3150 7350 m +gs 1 -1 sc (CHOICE {) col0 sh gr +/Times-Bold ff 195.00 scf sf +2400 7350 m +gs 1 -1 sc ( actions) col0 sh gr +/Times-Roman ff 180.00 scf sf +3975 7575 m +gs 1 -1 sc (SEQUENCE OF Action) col0 sh gr +/Times-Bold ff 195.00 scf sf +2400 7590 m +gs 1 -1 sc ( possibleActions) col0 sh gr +/Times-Roman ff 180.00 scf sf +5550 2100 m +gs 1 -1 sc (12, on TRUE}) col0 sh gr +/Times-Bold ff 195.00 scf sf +2400 2070 m +gs 1 -1 sc ( handle) col0 sh gr +/Times-Bold ff 195.00 scf sf +4950 2100 m +gs 1 -1 sc (number ) col0 sh gr +/Times-Roman ff 225.00 scf sf +1950 5100 m +gs 1 -1 sc (1) col0 sh gr +/Times-Roman ff 225.00 scf sf +1725 6450 m +gs 1 -1 sc (2) col0 sh gr +/Times-Roman ff 225.00 scf sf +2250 7575 m +gs 1 -1 sc (3) col0 sh gr +/Times-Roman ff 225.00 scf sf +4800 4950 m +gs 1 -1 sc (4) col0 sh gr +/Times-Roman ff 225.00 scf sf +4200 1200 m +gs 1 -1 sc (5) col0 sh gr +/Times-Roman ff 180.00 scf sf +3150 2100 m +gs 1 -1 sc ([0] Handle DEFAULT {) col0 sh gr +$F2psEnd +rs +showpage diff --git a/lib/asn1/doc/src/selective_Window2.gif b/lib/asn1/doc/src/selective_Window2.gif Binary files differnew file mode 100644 index 0000000000..9ee2b0710e --- /dev/null +++ b/lib/asn1/doc/src/selective_Window2.gif diff --git a/lib/asn1/doc/src/selective_Window2.ps b/lib/asn1/doc/src/selective_Window2.ps new file mode 100644 index 0000000000..d5a95ca591 --- /dev/null +++ b/lib/asn1/doc/src/selective_Window2.ps @@ -0,0 +1,515 @@ +%!PS-Adobe-2.0 +%%Title: selective_Window2.ps +%%Creator: fig2dev Version 3.2 Patchlevel 1 +%%CreationDate: Tue Oct 28 16:55:06 2003 +%%For: bertil@super (Bertil Karlsson,UAB/F/P) +%%Orientation: Landscape +%%BoundingBox: 134 128 460 713 +%%Pages: 1 +%%BeginSetup +%%IncludeFeature: *PageSize A4 +%%EndSetup +%%Magnification: 1.0000 +%%EndComments +/MyAppDict 100 dict dup begin def +/$F2psDict 200 dict def +$F2psDict begin +$F2psDict /mtrx matrix put +/col-1 {0 setgray} bind def +/col0 {0.000 0.000 0.000 srgb} bind def +/col1 {0.000 0.000 1.000 srgb} bind def +/col2 {0.000 1.000 0.000 srgb} bind def +/col3 {0.000 1.000 1.000 srgb} bind def +/col4 {1.000 0.000 0.000 srgb} bind def +/col5 {1.000 0.000 1.000 srgb} bind def +/col6 {1.000 1.000 0.000 srgb} bind def +/col7 {1.000 1.000 1.000 srgb} bind def +/col8 {0.000 0.000 0.560 srgb} bind def +/col9 {0.000 0.000 0.690 srgb} bind def +/col10 {0.000 0.000 0.820 srgb} bind def +/col11 {0.530 0.810 1.000 srgb} bind def +/col12 {0.000 0.560 0.000 srgb} bind def +/col13 {0.000 0.690 0.000 srgb} bind def +/col14 {0.000 0.820 0.000 srgb} bind def +/col15 {0.000 0.560 0.560 srgb} bind def +/col16 {0.000 0.690 0.690 srgb} bind def +/col17 {0.000 0.820 0.820 srgb} bind def +/col18 {0.560 0.000 0.000 srgb} bind def +/col19 {0.690 0.000 0.000 srgb} bind def +/col20 {0.820 0.000 0.000 srgb} bind def +/col21 {0.560 0.000 0.560 srgb} bind def +/col22 {0.690 0.000 0.690 srgb} bind def +/col23 {0.820 0.000 0.820 srgb} bind def +/col24 {0.500 0.190 0.000 srgb} bind def +/col25 {0.630 0.250 0.000 srgb} bind def +/col26 {0.750 0.380 0.000 srgb} bind def +/col27 {1.000 0.500 0.500 srgb} bind def +/col28 {1.000 0.630 0.630 srgb} bind def +/col29 {1.000 0.750 0.750 srgb} bind def +/col30 {1.000 0.880 0.880 srgb} bind def +/col31 {1.000 0.840 0.000 srgb} bind def + +end +save +77.5 92.5 translate + 90 rotate +1 -1 scale +.9 .9 scale % to make patterns same scale as in xfig + +% This junk string is used by the show operators +/PATsstr 1 string def +/PATawidthshow { % cx cy cchar rx ry string + % Loop over each character in the string + { % cx cy cchar rx ry char + % Show the character + dup % cx cy cchar rx ry char char + PATsstr dup 0 4 -1 roll put % cx cy cchar rx ry char (char) + false charpath % cx cy cchar rx ry char + /clip load PATdraw + % Move past the character (charpath modified the + % current point) + currentpoint % cx cy cchar rx ry char x y + newpath + moveto % cx cy cchar rx ry char + % Reposition by cx,cy if the character in the string is cchar + 3 index eq { % cx cy cchar rx ry + 4 index 4 index rmoveto + } if + % Reposition all characters by rx ry + 2 copy rmoveto % cx cy cchar rx ry + } forall + pop pop pop pop pop % - + currentpoint + newpath + moveto +} bind def +/PATcg { + 7 dict dup begin + /lw currentlinewidth def + /lc currentlinecap def + /lj currentlinejoin def + /ml currentmiterlimit def + /ds [ currentdash ] def + /cc [ currentrgbcolor ] def + /cm matrix currentmatrix def + end +} bind def +% PATdraw - calculates the boundaries of the object and +% fills it with the current pattern +/PATdraw { % proc + save exch + PATpcalc % proc nw nh px py + 5 -1 roll exec % nw nh px py + newpath + PATfill % - + restore +} bind def +% PATfill - performs the tiling for the shape +/PATfill { % nw nh px py PATfill - + PATDict /CurrentPattern get dup begin + setfont + % Set the coordinate system to Pattern Space + PatternGState PATsg + % Set the color for uncolored pattezns + PaintType 2 eq { PATDict /PColor get PATsc } if + % Create the string for showing + 3 index string % nw nh px py str + % Loop for each of the pattern sources + 0 1 Multi 1 sub { % nw nh px py str source + % Move to the starting location + 3 index 3 index % nw nh px py str source px py + moveto % nw nh px py str source + % For multiple sources, set the appropriate color + Multi 1 ne { dup PC exch get PATsc } if + % Set the appropriate string for the source + 0 1 7 index 1 sub { 2 index exch 2 index put } for pop + % Loop over the number of vertical cells + 3 index % nw nh px py str nh + { % nw nh px py str + currentpoint % nw nh px py str cx cy + 2 index show % nw nh px py str cx cy + YStep add moveto % nw nh px py str + } repeat % nw nh px py str + } for + 5 { pop } repeat + end +} bind def + +% PATkshow - kshow with the current pattezn +/PATkshow { % proc string + exch bind % string proc + 1 index 0 get % string proc char + % Loop over all but the last character in the string + 0 1 4 index length 2 sub { + % string proc char idx + % Find the n+1th character in the string + 3 index exch 1 add get % string proe char char+1 + exch 2 copy % strinq proc char+1 char char+1 char + % Now show the nth character + PATsstr dup 0 4 -1 roll put % string proc chr+1 chr chr+1 (chr) + false charpath % string proc char+1 char char+1 + /clip load PATdraw + % Move past the character (charpath modified the current point) + currentpoint newpath moveto + % Execute the user proc (should consume char and char+1) + mark 3 1 roll % string proc char+1 mark char char+1 + 4 index exec % string proc char+1 mark... + cleartomark % string proc char+1 + } for + % Now display the last character + PATsstr dup 0 4 -1 roll put % string proc (char+1) + false charpath % string proc + /clip load PATdraw + neewath + pop pop % - +} bind def +% PATmp - the makepattern equivalent +/PATmp { % patdict patmtx PATmp patinstance + exch dup length 7 add % We will add 6 new entries plus 1 FID + dict copy % Create a new dictionary + begin + % Matrix to install when painting the pattern + TilingType PATtcalc + /PatternGState PATcg def + PatternGState /cm 3 -1 roll put + % Check for multi pattern sources (Level 1 fast color patterns) + currentdict /Multi known not { /Multi 1 def } if + % Font dictionary definitions + /FontType 3 def + % Create a dummy encoding vector + /Encoding 256 array def + 3 string 0 1 255 { + Encoding exch dup 3 index cvs cvn put } for pop + /FontMatrix matrix def + /FontBBox BBox def + /BuildChar { + mark 3 1 roll % mark dict char + exch begin + Multi 1 ne {PaintData exch get}{pop} ifelse % mark [paintdata] + PaintType 2 eq Multi 1 ne or + { XStep 0 FontBBox aload pop setcachedevice } + { XStep 0 setcharwidth } ifelse + currentdict % mark [paintdata] dict + /PaintProc load % mark [paintdata] dict paintproc + end + gsave + false PATredef exec true PATredef + grestore + cleartomark % - + } bind def + currentdict + end % newdict + /foo exch % /foo newlict + definefont % newfont +} bind def +% PATpcalc - calculates the starting point and width/height +% of the tile fill for the shape +/PATpcalc { % - PATpcalc nw nh px py + PATDict /CurrentPattern get begin + gsave + % Set up the coordinate system to Pattern Space + % and lock down pattern + PatternGState /cm get setmatrix + BBox aload pop pop pop translate + % Determine the bounding box of the shape + pathbbox % llx lly urx ury + grestore + % Determine (nw, nh) the # of cells to paint width and height + PatHeight div ceiling % llx lly urx qh + 4 1 roll % qh llx lly urx + PatWidth div ceiling % qh llx lly qw + 4 1 roll % qw qh llx lly + PatHeight div floor % qw qh llx ph + 4 1 roll % ph qw qh llx + PatWidth div floor % ph qw qh pw + 4 1 roll % pw ph qw qh + 2 index sub cvi abs % pw ph qs qh-ph + exch 3 index sub cvi abs exch % pw ph nw=qw-pw nh=qh-ph + % Determine the starting point of the pattern fill + %(px, py) + 4 2 roll % nw nh pw ph + PatHeight mul % nw nh pw py + exch % nw nh py pw + PatWidth mul exch % nw nh px py + end +} bind def + +% Save the original routines so that we can use them later on +/oldfill /fill load def +/oldeofill /eofill load def +/oldstroke /stroke load def +/oldshow /show load def +/oldashow /ashow load def +/oldwidthshow /widthshow load def +/oldawidthshow /awidthshow load def +/oldkshow /kshow load def + +% These defs are necessary so that subsequent procs don't bind in +% the originals +/fill { oldfill } bind def +/eofill { oldeofill } bind def +/stroke { oldstroke } bind def +/show { oldshow } bind def +/ashow { oldashow } bind def +/widthshow { oldwidthshow } bind def +/awidthshow { oldawidthshow } bind def +/kshow { oldkshow } bind def +/PATredef { + MyAppDict begin + { + /fill { /clip load PATdraw newpath } bind def + /eofill { /eoclip load PATdraw newpath } bind def + /stroke { PATstroke } bind def + /show { 0 0 null 0 0 6 -1 roll PATawidthshow } bind def + /ashow { 0 0 null 6 3 roll PATawidthshow } + bind def + /widthshow { 0 0 3 -1 roll PATawidthshow } + bind def + /awidthshow { PATawidthshow } bind def + /kshow { PATkshow } bind def + } { + /fill { oldfill } bind def + /eofill { oldeofill } bind def + /stroke { oldstroke } bind def + /show { oldshow } bind def + /ashow { oldashow } bind def + /widthshow { oldwidthshow } bind def + /awidthshow { oldawidthshow } bind def + /kshow { oldkshow } bind def + } ifelse + end +} bind def +false PATredef +% Conditionally define setcmykcolor if not available +/setcmykcolor where { pop } { + /setcmykcolor { + 1 sub 4 1 roll + 3 { + 3 index add neg dup 0 lt { pop 0 } if 3 1 roll + } repeat + setrgbcolor - pop + } bind def +} ifelse +/PATsc { % colorarray + aload length % c1 ... cn length + dup 1 eq { pop setgray } { 3 eq { setrgbcolor } { setcmykcolor + } ifelse } ifelse +} bind def +/PATsg { % dict + begin + lw setlinewidth + lc setlinecap + lj setlinejoin + ml setmiterlimit + ds aload pop setdash + cc aload pop setrgbcolor + cm setmatrix + end +} bind def + +/PATDict 3 dict def +/PATsp { + true PATredef + PATDict begin + /CurrentPattern exch def + % If it's an uncolored pattern, save the color + CurrentPattern /PaintType get 2 eq { + /PColor exch def + } if + /CColor [ currentrgbcolor ] def + end +} bind def +% PATstroke - stroke with the current pattern +/PATstroke { + countdictstack + save + mark + { + currentpoint strokepath moveto + PATpcalc % proc nw nh px py + clip newpath PATfill + } stopped { + (*** PATstroke Warning: Path is too complex, stroking + with gray) = + cleartomark + restore + countdictstack exch sub dup 0 gt + { { end } repeat } { pop } ifelse + gsave 0.5 setgray oldstroke grestore + } { pop restore pop } ifelse + newpath +} bind def +/PATtcalc { % modmtx tilingtype PATtcalc tilematrix + % Note: tiling types 2 and 3 are not supported + gsave + exch concat % tilingtype + matrix currentmatrix exch % cmtx tilingtype + % Tiling type 1 and 3: constant spacing + 2 ne { + % Distort the pattern so that it occupies + % an integral number of device pixels + dup 4 get exch dup 5 get exch % tx ty cmtx + XStep 0 dtransform + round exch round exch % tx ty cmtx dx.x dx.y + XStep div exch XStep div exch % tx ty cmtx a b + 0 YStep dtransform + round exch round exch % tx ty cmtx a b dy.x dy.y + YStep div exch YStep div exch % tx ty cmtx a b c d + 7 -3 roll astore % { a b c d tx ty } + } if + grestore +} bind def +/PATusp { + false PATredef + PATDict begin + CColor PATsc + end +} bind def + +% crosshatch45 +11 dict begin +/PaintType 1 def +/PatternType 1 def +/TilingType 1 def +/BBox [0 0 1 1] def +/XStep 1 def +/YStep 1 def +/PatWidth 1 def +/PatHeight 1 def +/Multi 2 def +/PaintData [ + { clippath } bind + { 32 32 true [ 32 0 0 -32 0 32 ] + {<828282824444444428282828101010102828282844444444 + 828282820101010182828282444444442828282810101010 + 282828284444444482828282010101018282828244444444 + 282828281010101028282828444444448282828201010101 + 828282824444444428282828101010102828282844444444 + 8282828201010101>} + imagemask } bind +] def +/PaintProc { + pop + exec fill +} def +currentdict +end +/P6 exch def +1.1111 1.1111 scale %restore scale + +/cp {closepath} bind def +/ef {eofill} bind def +/gr {grestore} bind def +/gs {gsave} bind def +/sa {save} bind def +/rs {restore} bind def +/l {lineto} bind def +/m {moveto} bind def +/rm {rmoveto} bind def +/n {newpath} bind def +/s {stroke} bind def +/sh {show} bind def +/slc {setlinecap} bind def +/slj {setlinejoin} bind def +/slw {setlinewidth} bind def +/srgb {setrgbcolor} bind def +/rot {rotate} bind def +/sc {scale} bind def +/sd {setdash} bind def +/ff {findfont} bind def +/sf {setfont} bind def +/scf {scalefont} bind def +/sw {stringwidth} bind def +/tr {translate} bind def +/tnt {dup dup currentrgbcolor + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add + 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb} + bind def +/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul + 4 -2 roll mul srgb} bind def +/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def +/$F2psEnd {$F2psEnteredState restore end} def +%%EndProlog + +$F2psBegin +10 setmiterlimit +n -1000 7375 m -1000 -1000 l 11348 -1000 l 11348 7375 l cp clip + 0.06000 0.06000 sc +%%Page: 1 1 +% Polyline +7.500 slw +n 3150 975 m 3150 1500 l gs col0 s gr +% Polyline +n 4800 3600 m 9975 3600 l 9975 4125 l 4800 4125 l cp gs col0 s gr +% Polyline +n 5925 3600 m 5925 4125 l gs col0 s gr +% Polyline +n 7800 4200 m 7500 5325 l gs col0 s gr +% Polyline +n 5400 5550 m 7200 5550 l 7200 6075 l 5400 6075 l cp gs /PC [[1.00 1.00 1.00] [0.00 0.00 0.00]] def +15.00 15.00 sc P6 [16 0 0 -16 360.00 370.00] PATmp PATsp ef gr PATusp gs col0 s gr +% Polyline +n 7200 5550 m 9300 5550 l 9300 6075 l 7200 6075 l cp gs col0 s gr +% Polyline +n 2400 975 m 9700 975 l 9700 1500 l 2400 1500 l cp gs col0 s gr +% Polyline +n 6150 975 m 6150 1500 l gs col0 s gr +% Polyline +n 6825 975 m 6825 1500 l gs col0 s gr +% Polyline + [60] 0 sd +n 7800 975 m 7800 1500 l gs col0 s gr [] 0 sd +% Polyline + [60] 0 sd +n 8775 975 m 8775 1500 l gs col0 s gr [] 0 sd +% Polyline +gs clippath +6667 1636 m 6775 1575 l 6709 1679 l 6807 1586 l 6765 1543 l cp +clip +n 6775 1575 m 4800 3450 l gs col0 s gr gr + +% arrowhead +n 6667 1636 m 6775 1575 l 6709 1679 l col0 s +% Polyline +n 7850 1575 m 9975 3450 l gs col0 s gr +/Times-Roman ff 180.00 scf sf +600 1275 m +gs 1 -1 sc (Window:status message) col0 sh gr +/Times-Roman ff 180.00 scf sf +2550 1800 m +gs 1 -1 sc (state) col0 sh gr +/Times-Roman ff 180.00 scf sf +4275 1800 m +gs 1 -1 sc (buttonList) col0 sh gr +/Times-Roman ff 180.00 scf sf +8625 1875 m +gs 1 -1 sc (actions:possibleActions) col0 sh gr +/Times-Roman ff 180.00 scf sf +5025 4350 m +gs 1 -1 sc (number) col0 sh gr +/Times-Roman ff 180.00 scf sf +7275 4425 m +gs 1 -1 sc (handle) col0 sh gr +/Times-Roman ff 180.00 scf sf +5850 6375 m +gs 1 -1 sc (number) col0 sh gr +/Times-Roman ff 180.00 scf sf +8100 6375 m +gs 1 -1 sc (on) col0 sh gr +/Times-Roman ff 180.00 scf sf +6225 1800 m +gs 1 -1 sc (enabled) col0 sh gr +/Times-Roman ff 180.00 scf sf +7275 1350 m +gs 1 -1 sc ([1]) col0 sh gr +/Times-Roman ff 180.00 scf sf +8175 1350 m +gs 1 -1 sc ([2]) col0 sh gr +/Times-Roman ff 180.00 scf sf +9150 1350 m +gs 1 -1 sc ([3]) col0 sh gr +$F2psEnd +rs +end +showpage diff --git a/lib/asn1/doc/src/warning.gif b/lib/asn1/doc/src/warning.gif Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/asn1/doc/src/warning.gif |
