A diameter service as configured with
The codec generation also results in an hrl that defines records
for the messages and grouped AVP's defined for the application, these
records being what a user of the diameter application sends and
receives.
These records and the underlying Erlang data types corresponding to
Diameter data formats are discussed in
The diameter application defines the base application of RFC 3588 in the file diameter_gen_base_rfc3588.dia, and this is the only application that diameter itself has any specific knowledge of. Other applications are callback modules configured for an application as far as diameter is concerned.
A generated hrl also contains defines for the values of defined for AVPs of type Enumerated.
See
A specification file consists of distinct sections. Each section starts with a line consisting of a tag followed by zero or more arguments. Each section ends at the the start of the next section or end of file. Tags consist of an ampersand character followed by a keyword and are separated from their arguments by whitespace. Whitespace within a section separates individual tokens but its quantity is insignificant.
The tags, their arguments and the contents of each corresponding section are as follows. Each section can occur only once unless otherwise specified. The order in which sections are specified is unimportant.
Defines the integer Number as the Diameter Application Id of the application in question. The section has empty content.
The Application Id is set in the Diameter Header of outgoing messages of the application, and the value in the header of an incoming message is used to identify the relevant dictionary module.
Example:
@id 16777231
Defines the name of the generated dictionary module. The section has empty content. Mod must match the regular expression '^[a-zA-Z0-9][-_a-zA-Z0-9]*$'; that is, contains only alphanumerics, hyphens and underscores begin with an alphanumeric.
A name is optional and defaults to the name of the dictionary file minus any extension. Note that a generated module must have a unique name an not colide with another module in the system.
Example:
@name etsi_e2
Defines Name as the prefix to be added to record and constant names in the generated dictionary module and hrl. The section has empty content. Name must be of the same form as a @name.
A prefix is optional but can be used to disambiguate record and constant names resulting from similarly named messages and AVP's in different Diameter applications.
Example:
@prefix etsi_e2_
Defines the integer Number as the the default Vendor-ID of AVP's for which the V flag is set. Name documents the owner of the application but is otherwise unused. The section has empty content.
Example:
@vendor 13019 ETSI
Defines the integer Number as the Vendor-ID of the AVP's listed in the
section content, overriding the
Example:
@avp_vendor_id 2937
WWW-Auth
Domain-Index
Region-Set
Defines the name of a generated dictionary module containing AVP definitions referenced by the dictionary but not defined by it. The section content is empty.
Can occur 0 or more times (with different values of Mod) but all dictionaries should typically inherit RFC3588 AVPs from diameter_gen_base_rfc3588.
Example:
@inherits diameter_gen_base_rfc3588
Defines the name, code, type and flags of individual AVPs. The section consists of definitions of the form
where Code is the integer AVP code, Flags is a string of V,
M and P characters indicating the flags to be
set on an outgoing AVP or a single - (minus) character if none are to
be set.
Type identifies either an AVP Data Format as defined in
Example:
@avp_types
Location-Information 350 Grouped VM
Requested-Information 353 Enumerated V
Note that the P flag has been deprecated by the Diameter Maintenance and Extensions Working Group of the IETF.
Defines AVPs for which module Mod provides encode/decode. The section contents consists of type names. For each AVP Name defined with custom type Type, Mod should export the function Name/3 with arguments encode|decode, Type and Data, the latter being the term to be encoded/decoded. The function returns the encoded/decoded value.
Can occur 0 or more times (with different values of Mod).
Example:
@custom_types rfc4005_types
Framed-IP-Address
Defines the messages of the application. The section content consists of definitions of the form specified in section 3.2 of RFC 3588, "Command Code ABNF specification".
@messages
RTR ::= < Diameter Header: 287, REQ, PXY >
< Session-Id >
{ Auth-Application-Id }
{ Auth-Session-State }
{ Origin-Host }
{ Origin-Realm }
{ Destination-Host }
{ SIP-Deregistration-Reason }
[ Destination-Realm ]
[ User-Name ]
* [ SIP-AOR ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]
RTA ::= < Diameter Header: 287, PXY >
< Session-Id >
{ Auth-Application-Id }
{ Result-Code }
{ Auth-Session-State }
{ Origin-Host }
{ Origin-Realm }
[ Authorization-Lifetime ]
[ Auth-Grace-Period ]
[ Redirect-Host ]
[ Redirect-Host-Usage ]
[ Redirect-Max-Cache-Time ]
* [ Proxy-Info ]
* [ Route-Record ]
* [ AVP ]
Defines the contents of the AVPs of the application having type Grouped. The section content consists of definitions of the form specified in section 4.4 of RFC 3588, "Grouped AVP Values".
Example:
@grouped
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
Defines values of AVP Name having type Enumerated. Section content consists of names and corresponding integer values. Integer values can be prefixed with 0x to be interpreted as hexidecimal.
Can occur 0 or more times (with different values of Name).
Example:
@enum SIP-Reason-Code
PERMANENT_TERMINATION 0
NEW_SIP_SERVER_ASSIGNED 1
SIP_SERVER_CHANGE 2
REMOVE_SIP_SERVER 3
Comments can be included in a dictionary file using semicolon: text from a semicolon to end of line is ignored.
The hrl generated from a dictionary specification defines records for the
messages and grouped AVPs defined in
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
will result in the following record definition given an empty prefix.
-record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
'SIP-Reason-Info',
'AVP'}).
The values encoded in the fields of generated records depends on the type and number of times the AVP can occur. In particular, an AVP which is specified as occurring exactly once is encoded as a value of the AVP's type while an AVP with any other specification is encoded as a list of values of the AVP's type. The AVP's type is as specified in the AVP definition, the RFC 3588 types being described below.
The data formats defined in sections 4.2 ("Basic AVP Data
Formats") and 4.3 ("Derived AVP Data Formats") of RFC 3588 are encoded
as values of the types defined here.
Values are passed to
Basic AVP Data Formats
OctetString() = [0..255]
Integer32() = -2147483647..2147483647
Integer64() = -9223372036854775807..9223372036854775807
Unsigned32() = 0..4294967295
Unsigned64() = 0..18446744073709551615
Float32() = '-infinity' | float() | infinity
Float64() = '-infinity' | float() | infinity
Grouped() = record()
On encode, an OctetString() can be specified as an iolist(), excessively large floats (in absolute value) are equivalent to infinity or '-infinity' and excessively large integers result in encode failure. The records for grouped AVPs are as discussed in the previous section.
Derived AVP Data Formats
Address() = OctetString()
| tuple()
On encode, an OctetString() IPv4 address is parsed in the usual x.x.x.x format while an IPv6 address is parsed in any of the formats specified by section 2.2 of RFC 2373, "Text Representation of Addresses". An IPv4 tuple() has length 4 and contains values of type 0..255. An IPv6 tuple() has length 8 and contains values of type 0..65535. The tuple representation is used on decode.
Time() = {date(), time()}
where
date() = {Year, Month, Day}
time() = {Hour, Minute, Second}
Year = integer()
Month = 1..12
Day = 1..31
Hour = 0..23
Minute = 0..59
Second = 0..59
Additionally, values that can be encoded are
limited by way of their encoding as four octets as required by RFC
3588 with the required extension from RFC 2030.
In particular, only values between
UTF8String() = [integer()]
List elements are the UTF-8 encodings of the individual characters in the string. Invalid codepoints will result in encode/decode failure.
DiameterIdentity() = OctetString()
A value must have length at least 1.
DiameterURI() = OctetString()
| #diameter_URI{type = Type,
fqdn = FQDN,
port = Port,
transport = Transport,
protocol = Protocol}
where
Type = aaa | aaas
FQDN = OctetString()
Port = integer()
Transport = sctp | tcp
Protocol = diameter | radius | 'tacacs+'
On encode, fields port, transport and protocol default to 3868, sctp and diameter respectively. The grammar of an OctetString-valued DiameterURI() is as specified in section 4.3 of RFC 3588. The record representation is used on decode.
Enumerated() = Integer32()
On encode, values can be specified using the macros defined in a dictionary's hrl file.
IPFilterRule() = OctetString()
QoSFilterRule() = OctetString()
Values of these types are not parsed by diameter.