1diameter_codec(3) Erlang Module Definition diameter_codec(3)
2
6 diameter_codec - Decode and encode of Diameter messages.
7
9 Incoming Diameter messages are decoded from binary() before being com‐
10 municated to diameter_app(3) callbacks. Similarly, outgoing Diameter
11 messages are encoded into binary() before being passed to the appropri‐
12 ate diameter_transport(3) module for transmission. The functions docu‐
13 mented here implement the default encode/decode.
14 Warning:
16 The diameter user does not need to call functions here explicitly when
17 sending and receiving messages using diameter:call/4 and the callback
18 interface documented in diameter_app(3): diameter itself provides en‐
19 code/decode as a consequence of configuration passed to diame‐
20 ter:start_service/2, and the results may differ from those returned by
21 the functions documented here, depending on configuration.
22 The header() and packet() records below are defined in diameter.hrl,
25 which can be included as follows.
26 -include_lib("diameter/include/diameter.hrl").
28 Application-specific records are defined in the hrl files resulting
31 from dictionary file compilation.
32
34 uint8() = 0..255:
35 uint24() = 0..16777215:
38 uint32() = 0..4294967295:
41 8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP
42 headers.
43 avp() = #diameter_avp{}:
45 The application-neutral representation of an AVP. Primarily in‐
46 tended for use by relay applications that need to handle arbitrary
47 Diameter applications. A service implementing a specific Diameter
48 application (for which it configures a dictionary) can manipulate
49 values of type message() instead.
50 Fields have the following types.
52 code = uint32():
54 is_mandatory = boolean():
57 need_encryption = boolean():
60 vendor_id = uint32() | undefined:
63 Values in the AVP header, corresponding to AVP Code, the M flag,
64 P flags and Vendor-ID respectively. A Vendor-ID other than unde‐
65 fined implies a set V flag.
66 data = iolist():
68 The data bytes of the AVP.
69 name = atom():
71 The name of the AVP as defined in the dictionary file in ques‐
72 tion, or undefined if the AVP is unknown to the dictionary file
73 in question.
74 value = term():
76 The decoded value of an AVP. Will be undefined on decode if the
77 data bytes could not be decoded, the AVP is unknown, or if the
78 decode format is none. The type of a decoded value is as document
79 in diameter_dict(4).
80 type = atom():
82 The type of the AVP as specified in the dictionary file in ques‐
83 tion (or one it inherits). Possible types are undefined and the
84 Diameter types: OctetString, Integer32, Integer64, Unsigned32,
85 Unsigned64, Float32, Float64, Grouped, Enumerated, Address, Time,
86 UTF8String, DiameterIdentity, DiameterURI, IPFilterRule and QoS‐
87 FilterRule.
88 dictionary() = module():
90 The name of a generated dictionary module as generated by diame‐
91 terc(1) or diameter_make:codec/2. The interface provided by a dic‐
92 tionary module is an implementation detail that may change.
93 header() = #diameter_header{}:
95 The record representation of the Diameter header. Values in a
96 packet() returned by decode/2 are as extracted from the incoming
97 message. Values set in an packet() passed to encode/2 are preserved
98 in the encoded binary(), with the exception of length, cmd_code and
99 application_id, all of which are determined by the dictionary() in
100 question.
101 Note:
103 It is not necessary to set header fields explicitly in outgoing mes‐
104 sages as diameter itself will set appropriate values. Setting inap‐
105 propriate values can be useful for test purposes.
106 Fields have the following types.
109 version = uint8():
111 length = uint24():
114 cmd_code = uint24():
117 application_id = uint32():
120 hop_by_hop_id = uint32():
123 end_to_end_id = uint32():
126 Values of the Version, Message Length, Command-Code, Application-
127 ID, Hop-by-Hop Identifier and End-to-End Identifier fields of the
128 Diameter header.
129 is_request = boolean():
131 is_proxiable = boolean():
134 is_error = boolean():
137 is_retransmitted = boolean():
140 Values corresponding to the R(equest), P(roxiable), E(rror) and
141 T(Potentially re-transmitted message) flags of the Diameter
142 header.
143 message() = record() | maybe_improper_list():
145 The representation of a Diameter message as passed to diame‐
146 ter:call/4 or returned from a handle_request/3 callback. The record
147 representation is as outlined in diameter_dict(4): a message as de‐
148 fined in a dictionary file is encoded as a record with one field
149 for each component AVP. Equivalently, a message can also be encoded
150 as a list whose head is the atom-valued message name (as specified
151 in the relevant dictionary file) and whose tail is either a list of
152 AVP name/values pairs or a map with values keyed on AVP names. The
153 format at decode is determined by diameter:service_opt() de‐
154 code_format. Any of the formats is accepted at encode.
155 Another list-valued representation allows a message to be specified
157 as a list whose head is a header() and whose tail is an avp() list.
158 This representation is used by diameter itself when relaying re‐
159 quests as directed by the return value of a handle_request/3 call‐
160 back. It differs from the other two in that it bypasses the checks
161 for messages that do not agree with their definitions in the dic‐
162 tionary in question: messages are sent exactly as specified.
163 packet() = #diameter_packet{}:
165 A container for incoming and outgoing Diameter messages. Fields
166 have the following types.
167 header = header() | undefined:
169 The Diameter header of the message. Can be (and typically should
170 be) undefined for an outgoing message in a non-relay application,
171 in which case diameter provides appropriate values.
172 avps = [avp()] | undefined:
174 The AVPs of the message. Ignored for an outgoing message if the
175 msg field is set to a value other than undefined.
176 msg = message() | undefined:
178 The incoming/outgoing message. For an incoming message, a term
179 corresponding to the configured decode format if the message can
180 be decoded in a non-relay application, undefined otherwise. For
181 an outgoing message, setting a [header() | avp()] list is equiva‐
182 lent to setting the header and avps fields to the corresponding
183 values.
184 Warning:
186 A value in the msg field does not imply an absence of decode er‐
187 rors. The errors field should also be examined.
188 bin = binary():
191 The incoming message prior to encode or the outgoing message af‐
192 ter encode.
193 errors = [5000..5999 | {5000..5999, avp()}]:
195 Errors detected at decode of an incoming message, as identified
196 by a corresponding 5xxx series Result-Code (Permanent Failures).
197 For an incoming request, these should be used to formulate an ap‐
198 propriate answer as documented for the handle_request/3 callback
199 in diameter_app(3). For an incoming answer, the diameter:applica‐
200 tion_opt() answer_errors determines the behaviour.
201 transport_data = term():
203 An arbitrary term of meaning only to the transport process in
204 question, as documented in diameter_transport(3).
205
207 decode(Mod, Bin) -> Pkt
208 Types:
210 Mod = dictionary()
212 Bin = binary()
213 Pkt = packet()
214 Decode a Diameter message.
216 encode(Mod, Msg) -> Pkt
218 Types:
220 Mod = dictionary()
222 Msg = message() | packet()
223 Pkt = packet()
224 Encode a Diameter message.
226
228 diameterc(1), diameter_app(3), diameter_dict(4), diameter_make(3)
229Ericsson AB diameter 2.2.4 diameter_codec(3)