1diameter_codec(3)          Erlang Module Definition          diameter_codec(3)
2
3
4

NAME

6       diameter_codec - Decode and encode of Diameter messages.
7

DESCRIPTION

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
15   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
23
24       The header() and packet() records below are  defined  in  diameter.hrl,
25       which can be included as follows.
26
27       -include_lib("diameter/include/diameter.hrl").
28
29
30       Application-specific  records  are  defined  in the hrl files resulting
31       from dictionary file compilation.
32

DATA TYPES

34         uint8() = 0..255:
35
36
37         uint24() = 0..16777215:
38
39
40         uint32() = 0..4294967295:
41           8-bit, 24-bit and 32-bit integers occurring  in  Diameter  and  AVP
42           headers.
43
44         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
51           Fields have the following types.
52
53           code = uint32():
54
55
56           is_mandatory = boolean():
57
58
59           need_encryption = boolean():
60
61
62           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
67           data = iolist():
68             The data bytes of the AVP.
69
70           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
75           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
81           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
89         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
94         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
102     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
107
108           Fields have the following types.
109
110           version = uint8():
111
112
113           length = uint24():
114
115
116           cmd_code = uint24():
117
118
119           application_id = uint32():
120
121
122           hop_by_hop_id = uint32():
123
124
125           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
130           is_request = boolean():
131
132
133           is_proxiable = boolean():
134
135
136           is_error = boolean():
137
138
139           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
144         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
156           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
164         packet() = #diameter_packet{}:
165           A  container  for  incoming  and outgoing Diameter messages. Fields
166           have the following types.
167
168           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
173           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
177           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
185       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
189
190           bin = binary():
191             The  incoming message prior to encode or the outgoing message af‐
192             ter encode.
193
194           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
202           transport_data = term():
203             An  arbitrary  term  of  meaning only to the transport process in
204             question, as documented in diameter_transport(3).
205

EXPORTS

207       decode(Mod, Bin) -> Pkt
208
209              Types:
210
211                 Mod = dictionary()
212                 Bin = binary()
213                 Pkt = packet()
214
215              Decode a Diameter message.
216
217       encode(Mod, Msg) -> Pkt
218
219              Types:
220
221                 Mod = dictionary()
222                 Msg = message() | packet()
223                 Pkt = packet()
224
225              Encode a Diameter message.
226

SEE ALSO

228       diameterc(1), diameter_app(3), diameter_dict(4), diameter_make(3)
229
230
231
232Ericsson AB                     diameter 2.2.5               diameter_codec(3)
Impressum