diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_codec.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_codec.xml | 271 |
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() = 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> |