From 67ffc483c80d29334c6c7739bcf1be756f374dfb Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Tue, 20 Nov 2012 13:11:19 +0100 Subject: Add content to diameter_codec(3) and diameter_make(3) --- lib/diameter/doc/src/diameter_codec.xml | 271 ++++++++++++++++++++++++++++++-- 1 file changed, 259 insertions(+), 12 deletions(-) (limited to 'lib/diameter/doc/src/diameter_codec.xml') 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 @@ diameter_dict(4)'> + diameter_dict(4)'> %also; @@ -38,44 +42,288 @@ under the License. diameter_codec -Diameter encode/decode. +Decode and encode of Diameter messages.

-

+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.

+ + +

+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;.

+ + +

+The &header; and &packet; records below +are defined in diameter.hrl, which can be included as follows.

+ +
+-include_lib("diameter/include/diameter.hrl").
+
+ +

+Application-specific records are definied in the hrl +files resulting from dictionary file compilation.

 +
+DATA TYPES + +

+ + + + + +uint8()  = 0..255 +uint24() = 0..16777215 +uint32() = 0..4294967295 + +

+8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP +headers.

+ + + + +avp() = #diameter_avp{} + +

+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.

+ +

+Fields have the following types.

+ + + +code = uint32() +is_mandatory = boolean() +need_encryption = boolean() +vendor_id = uint32() | undefined + +

+Values in the AVP header, corresponding to AVP Code, the M flag, P +flags and Vendor-ID respectivelty. +A Vendor-ID other than undefined implies a set V flag.

+ + +data = iolist() + +

+The data bytes of the AVP.

+ + +name = atom() + +

+The name of the AVP as defined in the dictionary file in question, or +undefined if the AVP is unknown to the dictionary file in +question.

+ + +value = term() + +

+The decoded value of an AVP. +Will be undefined 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;.

+ + +type = atom() + +

+The type of the AVP as specified in the dictionary file in question +(or one it inherits). +Possible types are undefined and the Diameter types: +OctetString, Integer32, Integer64, +Unsigned32, Unsigned64, Float32, Float64, +Grouped, Enumerated, Address, Time, +UTF8String, DiameterIdentity, DiameterURI, +IPFilterRule and QoSFilterRule.

+ + + + + + + + +dictionary() = module() + + +

+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.

+ + + + +header() = #diameter_header{} + +

+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 length, cmd_code +and application_id, all of which are determined by the +&dictionary; in question.

+ + +

+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.

+ + +

+Fields have the following types.

+ + + +version = uint8() +length = uint24() +cmd_code = uint24() +application_id = uint32() +hop_by_hop_id = uint32() +end_to_end_id = uint32() + +

+Values of the Version, Message Length, Command-Code, Application-ID, +Hop-by-Hop Identifier and End-to-End Identifier fields of the Diameter +header.

+ + +is_request = boolean() +is_proxiable = boolean() +is_error = boolean() +is_retransmitted = boolean() + +

+Values correspoding to the R(equest), P(roxiable), E(rror) +and T(Potentially re-transmitted message) flags of the Diameter +header.

+ + + + + + + + +message() = record() | list() + +

+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 {AvpName, AvpValue} pairs.

+ +

+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.

+ + + + + +packet() = #diameter_packet{} + +

+A container for incoming and outgoing Diameter messages. +Fields have the following types.

+ + + +header = &header; + + + +msg = &message; + + + +bin = binary() + + + +errors = [&dict_Unsigned32; | {&dict_Unsigned32;, avp()}] + + + +transport_data = term() + + + + + + + + + +
+ + + -decode(Mod, Bin) -> #diameter_packet{} -Decode an incoming Diameter message. +decode(Mod, Bin) -> &packet; +Decode a Diameter message. - - +Mod = &dictionary; +Bin = binary()

-

+Decode a Diameter message.

 encode(Mod, Msg) -> binary() -Encode an outgoing Diameter message. +Encode a Diameter message. - - +Mod = &dictionary; +Msg = &message; | &packet;

+Encode a Diameter message.

@@ -90,8 +338,7 @@ under the License. SEE ALSO

-&man_main;, -&man_dict;

+&man_compile;, &man_app;, &man_dict;, &man_make;

-- cgit v1.2.3