.TH diameter_codec 3erl "diameter 2.2.7" "Ericsson AB" "Erlang Module Definition"
.SH NAME
diameter_codec \- Decode and encode of Diameter messages.
.SH DESCRIPTION
.LP
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 documented here implement the default encode/decode\&.
.LP

.RS -4
.B
Warning:
.RE
The diameter user does not need to call functions here explicitly when sending and receiving messages using diameter:call/4 and the callback interface documented in diameter_app(3erl): diameter itself provides encode/decode as a consequence of configuration passed to diameter:start_service/2, and the results may differ from those returned by the functions documented here, depending on configuration\&.

.LP
The header() and packet() records below are defined in diameter\&.hrl, which can be included as follows\&.
.LP
.nf

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

.fi
.LP
Application-specific records are defined in the hrl files resulting from dictionary file compilation\&.
.SH "DATA TYPES"

.LP

.RS 2
.TP 2
.B
\fIuint8() = 0\&.\&.255\fR\&:

.TP 2
.B
\fIuint24() = 0\&.\&.16777215\fR\&:

.TP 2
.B
\fIuint32() = 0\&.\&.4294967295\fR\&:
8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP headers\&.
.TP 2
.B
\fIavp() = #diameter_avp{}\fR\&:
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\&.
.RS 2
.LP
Fields have the following types\&.
.RE

.RS 2
.TP 2
.B
\fIcode = uint32()\fR\&:

.TP 2
.B
\fIis_mandatory = boolean()\fR\&:

.TP 2
.B
\fIneed_encryption = boolean()\fR\&:

.TP 2
.B
\fIvendor_id = uint32() | undefined\fR\&:
Values in the AVP header, corresponding to AVP Code, the M flag, P flags and Vendor-ID respectively\&. A Vendor-ID other than \fIundefined\fR\& implies a set V flag\&.
.TP 2
.B
\fIdata = iolist()\fR\&:
The data bytes of the AVP\&.
.TP 2
.B
\fIname = atom()\fR\&:
The name of the AVP as defined in the dictionary file in question, or \fIundefined\fR\& if the AVP is unknown to the dictionary file in question\&.
.TP 2
.B
\fIvalue = term()\fR\&:
The decoded value of an AVP\&. Will be \fIundefined\fR\& on decode if the data bytes could not be decoded, the AVP is unknown, or if the decode format is \fInone\fR\&\&. The type of a decoded value is as document in diameter_dict(5)\&.
.TP 2
.B
\fItype = atom()\fR\&:
The type of the AVP as specified in the dictionary file in question (or one it inherits)\&. Possible types are \fIundefined\fR\& and the Diameter types: \fIOctetString\fR\&, \fIInteger32\fR\&, \fIInteger64\fR\&, \fIUnsigned32\fR\&, \fIUnsigned64\fR\&, \fIFloat32\fR\&, \fIFloat64\fR\&, \fIGrouped\fR\&, \fIEnumerated\fR\&, \fIAddress\fR\&, \fITime\fR\&, \fIUTF8String\fR\&, \fIDiameterIdentity\fR\&, \fIDiameterURI\fR\&, \fIIPFilterRule\fR\& and \fIQoSFilterRule\fR\&\&.
.RE
.TP 2
.B
\fIdictionary() = module()\fR\&:
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\&.
.TP 2
.B
\fIheader() = #diameter_header{}\fR\&:
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 \fIlength\fR\&, \fIcmd_code\fR\& and \fIapplication_id\fR\&, all of which are determined by the dictionary() in question\&.
.LP

.RS -4
.B
Note:
.RE
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\&.

.RS 2
.LP
Fields have the following types\&.
.RE

.RS 2
.TP 2
.B
\fIversion = uint8()\fR\&:

.TP 2
.B
\fIlength = uint24()\fR\&:

.TP 2
.B
\fIcmd_code = uint24()\fR\&:

.TP 2
.B
\fIapplication_id = uint32()\fR\&:

.TP 2
.B
\fIhop_by_hop_id = uint32()\fR\&:

.TP 2
.B
\fIend_to_end_id = uint32()\fR\&:
Values of the Version, Message Length, Command-Code, Application-ID, Hop-by-Hop Identifier and End-to-End Identifier fields of the Diameter header\&.
.TP 2
.B
\fIis_request = boolean()\fR\&:

.TP 2
.B
\fIis_proxiable = boolean()\fR\&:

.TP 2
.B
\fIis_error = boolean()\fR\&:

.TP 2
.B
\fIis_retransmitted = boolean()\fR\&:
Values corresponding to the R(equest), P(roxiable), E(rror) and T(Potentially re-transmitted message) flags of the Diameter header\&.
.RE
.TP 2
.B
\fImessage() = record() | maybe_improper_list()\fR\&:
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 either a list of AVP name/values pairs or a map with values keyed on AVP names\&. The format at decode is determined by diameter:service_opt() decode_format\&. Any of the formats is accepted at encode\&.
.RS 2
.LP
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 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\&.
.RE

.TP 2
.B
\fIpacket() = #diameter_packet{}\fR\&:
A container for incoming and outgoing Diameter messages\&. Fields have the following types\&.
.RS 2
.TP 2
.B
\fIheader = header() | undefined\fR\&:
The Diameter header of the message\&. Can be (and typically should be) \fIundefined\fR\& for an outgoing message in a non-relay application, in which case diameter provides appropriate values\&.
.TP 2
.B
\fIavps = [avp()] | undefined\fR\&:
The AVPs of the message\&. Ignored for an outgoing message if the \fImsg\fR\& field is set to a value other than \fIundefined\fR\&\&.
.TP 2
.B
\fImsg = message() | undefined\fR\&:
The incoming/outgoing message\&. For an incoming message, a term corresponding to the configured decode format if the message can be decoded in a non-relay application, \fIundefined\fR\& otherwise\&. For an outgoing message, setting a \fI[header() | avp()]\fR\& list is equivalent to setting the \fIheader\fR\& and \fIavps\fR\& fields to the corresponding values\&.
.LP

.RS -4
.B
Warning:
.RE
A value in the \fImsg\fR\& field does \fInot\fR\& imply an absence of decode errors\&. The \fIerrors\fR\& field should also be examined\&.

.TP 2
.B
\fIbin = binary()\fR\&:
The incoming message prior to encode or the outgoing message after encode\&.
.TP 2
.B
\fIerrors = [5000\&.\&.5999 | {5000\&.\&.5999, avp()}]\fR\&:
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() \fIanswer_errors\fR\& determines the behaviour\&.
.TP 2
.B
\fItransport_data = term()\fR\&:
An arbitrary term of meaning only to the transport process in question, as documented in diameter_transport(3erl)\&.
.RE
.RE
.SH EXPORTS
.LP
.B
decode(Mod, Bin) -> Pkt
.br
.RS
.LP
Types:

.RS 3
Mod = dictionary()
.br
Bin = binary()
.br
Pkt = packet()
.br
.RE
.RE
.RS
.LP
Decode a Diameter message\&.
.RE

.LP
.B
encode(Mod, Msg) -> Pkt
.br
.RS
.LP
Types:

.RS 3
Mod = dictionary()
.br
Msg = message() | packet()
.br
Pkt = packet()
.br
.RE
.RE
.RS
.LP
Encode a Diameter message\&.
.RE

.SH "SEE ALSO"

.LP
diameterc(1), diameter_app(3erl), diameter_dict(5), diameter_make(3erl)