Add content to diameter_codec(3) and diameter_make(3)

1 files changed, 259 insertions, 12 deletions

diff --git a/lib/diameter/doc/src/diameter_codec.xml b/lib/diameter/doc/src/diameter_codec.xml
index 041616e54b..fb245936cf 100644
--- a/lib/diameter/doc/src/diameter_codec.xml
+++ b/lib/diameter/doc/src/diameter_codec.xml
@@ -1,5 +1,9 @@
 <?xml version="1.0" encoding="latin1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd" [
+  <!ENTITY records
+  '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'>
+  <!ENTITY types
+  '<seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>'>
   <!ENTITY % also SYSTEM "seealso.ent" >
   <!ENTITY % here SYSTEM "seehere.ent" >
   %also;
@@ -38,44 +42,288 @@ under the License.
 </header>
 
 <module>diameter_codec</module>
-<modulesummary>Diameter encode/decode.</modulesummary>
+<modulesummary>Decode and encode of Diameter messages.</modulesummary>
 
 <description>
 
 <p>
-</p>
+Incoming Diameter messages are decoded from binary() before being
+communicated to &man_app; callbacks.
+Similarly, outgoing Diameter messages are encoded into binary() before
+being passed to the appropriate &man_transport; module for
+transmission.
+The functions in this module implement this encode/decode.</p>
+
+<note>
+<p>
+Calls to this module are made by diameter itself as a consequence of
+configuration passed to &mod_start_service;.
+The encode/decode functions may also be useful for other purposes (eg.
+test) but the diameter user does not need to call them explicitly when
+sending and receiving messages using &mod_call; and the callback
+interface documented in &man_app;.</p>
+</note>
+
+<p>
+The &header; and &packet; records below
+are defined in diameter.hrl, which can be included as follows.</p>
+
+<pre>
+-include_lib("diameter/include/diameter.hrl").
+</pre>
+
+<p>
+Application-specific records are definied in the hrl
+files resulting from dictionary file compilation.</p>
 
 </description>
 
 <!-- ===================================================================== -->
 
+<section>
+<title>DATA TYPES</title>
+
+<p></p>
+
+<taglist>
+
+<marker id="integers"/>
+
+<tag><c>uint8()&nbsp; = 0..255</c></tag>
+<tag><c>uint24() = 0..16777215</c></tag>
+<tag><c>uint32() = 0..4294967295</c></tag>
+<item>
+<p>
+8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP
+headers.</p>
+</item>
+
+<marker id="avp"/>
+
+<tag><c>avp() = #diameter_avp{}</c></tag>
+<item>
+<p>
+The application-neutral representation of an AVP.
+Primarily intended for use by relay applications that need to handle
+arbitrary Diameter applications.
+A service implementing a specific Diameter application
+(for which it configures a dictionary) can manipulate values of type
+&message; instead.</p>
+
+<p>
+Fields have the following types.</p>
+
+<taglist>
+
+<tag><c>code = uint32()</c></tag>
+<tag><c>is_mandatory = boolean()</c></tag>
+<tag><c>need_encryption = boolean()</c></tag>
+<tag><c>vendor_id = uint32() | undefined</c></tag>
+<item>
+<p>
+Values in the AVP header, corresponding to AVP Code, the M flag, P
+flags and Vendor-ID respectivelty.
+A Vendor-ID other than <c>undefined</c> implies a set V flag.</p>
+</item>
+
+<tag><c>data = iolist()</c></tag>
+<item>
+<p>
+The data bytes of the AVP.</p>
+</item>
+
+<tag><c>name = atom()</c></tag>
+<item>
+<p>
+The name of the AVP as defined in the dictionary file in question, or
+<c>undefined</c> if the AVP is unknown to the dictionary file in
+question.</p>
+</item>
+
+<tag><c>value = term()</c></tag>
+<item>
+<p>
+The decoded value of an AVP.
+Will be <c>undefined</c> on decode if the data bytes could
+not be decoded or the AVP is unknown.
+The type of a decoded value is as document in &types;.</p>
+</item>
+
+<tag><c>type = atom()</c></tag>
+<item>
+<p>
+The type of the AVP as specified in the dictionary file in question
+(or one it inherits).
+Possible types are <c>undefined</c> and the Diameter types:
+<c>OctetString</c>, <c>Integer32</c>, <c>Integer64</c>,
+<c>Unsigned32</c>, <c>Unsigned64</c>, <c>Float32</c>, <c>Float64</c>,
+<c>Grouped</c>, <c>Enumerated</c>, <c>Address</c>, <c>Time</c>,
+<c>UTF8String</c>, <c>DiameterIdentity</c>, <c>DiameterURI</c>,
+<c>IPFilterRule</c> and <c>QoSFilterRule</c>.</p>
+</item>
+
+</taglist>
+
+</item>
+
+<marker id="dictionary"/>
+
+<tag><c>dictionary() = module()</c></tag>
+<item>
+
+<p>
+The name of a generated dictionary module as generated by &man_compile;
+or &make_codec;.
+The interface provided by a dictionary module is an
+implementation detail that may change.</p>
+</item>
+
+<marker id="header"/>
+
+<tag><c>header() = #diameter_header{}</c></tag>
+<item>
+<p>
+The record representation of the Diameter header.
+Values in a &packet; returned by &decode; are as extracted from the
+incoming message.
+Values set in an &packet; passed to &encode; are preserved in the
+encoded binary(), with the exception of <c>length</c>, <c>cmd_code</c>
+and <c>application_id</c>, all of which are determined by the
+&dictionary; in question.</p>
+
+<note>
+<p>
+It is not necessary to set header fields explicitly in outgoing
+messages as diameter itself will set appropriate values.
+Setting inappropriate values can be useful for test purposes.</p>
+</note>
+
+<p>
+Fields have the following types.</p>
+
+<taglist>
+
+<tag><c>version = uint8()</c></tag>
+<tag><c>length = uint24()</c></tag>
+<tag><c>cmd_code = uint24()</c></tag>
+<tag><c>application_id = uint32()</c></tag>
+<tag><c>hop_by_hop_id = uint32()</c></tag>
+<tag><c>end_to_end_id = uint32()</c></tag>
+<item>
+<p>
+Values of the Version, Message Length, Command-Code, Application-ID,
+Hop-by-Hop Identifier and End-to-End Identifier fields of the Diameter
+header.</p>
+</item>
+
+<tag><c>is_request = boolean()</c></tag>
+<tag><c>is_proxiable = boolean()</c></tag>
+<tag><c>is_error = boolean()</c></tag>
+<tag><c>is_retransmitted = boolean()</c></tag>
+<item>
+<p>
+Values correspoding to the R(equest), P(roxiable), E(rror)
+and T(Potentially re-transmitted message) flags of the Diameter
+header.</p>
+</item>
+
+</taglist>
+
+</item>
+
+<marker id="message"/>
+
+<tag><c>message() = record() | list()</c></tag>
+<item>
+<p>
+The representation of a Diameter message as passed to
+&mod_call; or returned from a &app_handle_request; callback.
+The record representation is as outlined in &records;:
+a message as defined in a dictionary file is encoded as a record with
+one field for each component AVP.
+Equivalently, a message can also be encoded as a list whose head is
+the atom-valued message name (as specified in the relevant dictionary
+file) and whose tail is a list of <c>{AvpName, AvpValue}</c> pairs.</p>
+
+<p>
+Another list-valued representation allows a message to be specified
+as a list whose head is a &header; and whose tail is an &avp; list.
+This representation is used by diameter itself when relaying requests
+as directed by the return value of a &app_handle_request; callback.
+It differs from the other other two in that it bypasses the checks for
+messages that do not agree with their definitions in the dictionary in
+question: messages are sent exactly as specified.</p>
+
+</item>
+
+<marker id="packet"/>
+
+<tag><c>packet() = #diameter_packet{}</c></tag>
+<item>
+<p>
+A container for incoming and outgoing Diameter messages.
+Fields have the following types.</p>
+
+<taglist>
+
+<tag><c>header = &header;</c></tag>
+<item>
+</item>
+
+<tag><c>msg = &message;</c></tag>
+<item>
+</item>
+
+<tag><c>bin = binary()</c></tag>
+<item>
+</item>
+
+<tag><c>errors = [&dict_Unsigned32; | {&dict_Unsigned32;, avp()}]</c></tag>
+<item>
+</item>
+
+<tag><c>transport_data = term()</c></tag>
+<item>
+</item>
+
+</taglist>
+
+</item>
+
+</taglist>
+
+</section>
+
+<!-- ===================================================================== -->
+
 <funcs>
 
 <func>
-<name>decode(Mod, Bin) -> #diameter_packet{}</name>
-<fsummary>Decode an incoming Diameter message.</fsummary>
+<name>decode(Mod, Bin) -> &packet;</name>
+<fsummary>Decode a Diameter message.</fsummary>
 <type>
-<v></v>
-<v></v>
+<v>Mod = &dictionary;</v>
+<v>Bin = binary()</v>
 </type>
 <desc>
 
 <p>
-</p>
+Decode a Diameter message.</p>
 
 </desc>
 </func>
 
 <func>
 <name>encode(Mod, Msg) -> binary()</name>
-<fsummary>Encode an outgoing Diameter message.</fsummary>
+<fsummary>Encode a Diameter message.</fsummary>
 <type>
-<v></v>
-<v></v>
+<v>Mod = &dictionary;</v>
+<v>Msg = &message; | &packet;</v>
 </type>
 <desc>
 
 <p>
+Encode a Diameter message.
 </p>
 
 </desc>
@@ -90,8 +338,7 @@ under the License.
 <title>SEE ALSO</title>
 
 <p>
-&man_main;,
-&man_dict;</p>
+&man_compile;, &man_app;, &man_dict;, &man_make;</p>
 
 </section>