The R13B03 release.OTP_R13B03

1 files changed, 208 insertions, 0 deletions

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 =&lt; 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 =&lt; 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>
+