DESCRIPTION
Incoming Diameter messages are decoded from binary() before being communicated to diameter_app(3erl) callbacks. Similarly, outgoing Diameter messages are encoded into binary() before being passed to the appropriate diameter_transport(3erl) module for transmission. The functions in this module implement this encode/decode.
Note: Calls to this module are made by diameter itself as a consequence of configuration passed to diameter:start_service/2. 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 diameter:call/4 and the callback interface documented in diameter_app(3erl).
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 defined 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 respectively. 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 diameter_dict(5).
- 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 diameterc(1) or diameter_make:codec/2. 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/2 are as extracted from the incoming message. Values set in an packet() passed to encode/2 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.
-
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 corresponding 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 diameter:call/4 or returned from a handle_request/3 callback. The record representation is as outlined in diameter_dict(5): 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 handle_request/3 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() | undefined:
- The Diameter header of the message. Can be (and typically should be) undefined for an outgoing message in a non-relay application, in which case diameter provides appropriate values.
- avps = [avp()] | undefined:
- The AVPs of the message. Ignored for an outgoing message if the msg field is set to a value other than undefined.
- msg = message() | undefined:
- The incoming/outgoing message. For an incoming message, a record if the message can be decoded in a non-relay application, undefined otherwise. For an outgoing message, setting a [header() | avp()] list is equivalent to setting the header and avps fields to the corresponding values.
-
- bin = binary():
- The incoming message prior to encode or the outgoing message after encode.
- errors = [5000..5999 | {5000..5999, avp()}]:
- Errors detected at decode of an incoming message, as identified by a corresponding 5xxx series Result-Code (Permanent Failures). For an incoming request, these should be used to formulate an appropriate answer as documented for the handle_request/3 callback in diameter_app(3erl). For an incoming answer, the diameter:application_opt() answer_errors determines the behaviour.
- transport_data = term():
- An arbitrary term of meaning only to the transport process in question, as documented in diameter_transport(3erl).
EXPORTS
decode(Mod, Bin) -> Pkt
-
Types:
-
Mod = dictionary()
Bin = binary()
Pkt = packet()
-
Mod = dictionary()
-
Decode a Diameter message.
encode(Mod, Msg) -> Pkt
-
Types:
-
Mod = dictionary()
Msg = message() | packet()
Pkt = packet()
-
Mod = dictionary()
-
Encode a Diameter message.