.TH diameter_codec 3erl "diameter 1.12.1" "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 \fBdiameter_app(3erl)\fR\& callbacks\&. Similarly, outgoing Diameter messages are encoded into binary() before being passed to the appropriate \fBdiameter_transport(3erl)\fR\& module for transmission\&. The functions in this module implement this encode/decode\&.
.LP

.RS -4
.B
Note:
.RE
Calls to this module are made by diameter itself as a consequence of configuration passed to \fBdiameter:start_service/2\fR\&\&. 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 \fBdiameter:call/4\fR\& and the callback interface documented in \fBdiameter_app(3erl)\fR\&\&.

.LP
The \fBheader()\fR\& and \fBpacket()\fR\& 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 \fBmessage()\fR\& 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 or the AVP is unknown\&. The type of a decoded value is as document in \fBdiameter_dict(5)\fR\&\&.
.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 \fBdiameterc(1)\fR\& or \fBdiameter_make:codec/2\fR\&\&. 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 \fBpacket()\fR\& returned by \fBdecode/2\fR\& are as extracted from the incoming message\&. Values set in an \fBpacket()\fR\& passed to \fBencode/2\fR\& 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 \fBdictionary()\fR\& 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() | list()\fR\&:
The representation of a Diameter message as passed to \fBdiameter:call/4\fR\& or returned from a \fBhandle_request/3\fR\& callback\&. The record representation is as outlined in \fBdiameter_dict(5)\fR\&: 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 \fI{AvpName, AvpValue}\fR\& pairs\&.
.RS 2
.LP
Another list-valued representation allows a message to be specified as a list whose head is a \fBheader()\fR\& and whose tail is an \fBavp()\fR\& list\&. This representation is used by diameter itself when relaying requests as directed by the return value of a \fBhandle_request/3\fR\& 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\&.
.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 = \fBheader()\fR\& | 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 = [\fBavp()\fR\&] | 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 = \fBmessage()\fR\& | undefined\fR\&:
The incoming/outgoing message\&. For an incoming message, a record if the message can be decoded in a non-relay application, \fIundefined\fR\& otherwise\&. For an outgoing message, setting a \fI[\fBheader()\fR\& | \fBavp()\fR\&]\fR\& list is equivalent to setting the \fIheader\fR\& and \fIavps\fR\& fields to the corresponding values\&.
.LP

.RS -4
.B
Warning:
.RE
A record-valued \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 \fBhandle_request/3\fR\& callback in \fBdiameter_app(3erl)\fR\&\&. For an incoming answer, the \fBdiameter:application_opt()\fR\& \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 \fBdiameter_transport(3erl)\fR\&\&.
.RE
.RE
.SH EXPORTS
.LP
.B
decode(Mod, Bin) -> Pkt
.br
.RS
.LP
Types:

.RS 3
Mod = \fBdictionary()\fR\&
.br
Bin = binary()
.br
Pkt = \fBpacket()\fR\&
.br
.RE
.RE
.RS
.LP
Decode a Diameter message\&.
.RE

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

.RS 3
Mod = \fBdictionary()\fR\&
.br
Msg = \fBmessage()\fR\& | \fBpacket()\fR\&
.br
Pkt = \fBpacket()\fR\&
.br
.RE
.RE
.RS
.LP
Encode a Diameter message\&.
.RE

.SH "SEE ALSO"

.LP
\fBdiameterc(1)\fR\&, \fBdiameter_app(3erl)\fR\&, \fBdiameter_dict(5)\fR\&, \fBdiameter_make(3erl)\fR\&