Provided by:
erlang-manpages_14.b.4-dfsg-1ubuntu1_all 
NAME
diameter_dict - Dictionary inteface of the diameter application.
DESCRIPTION
A diameter service as configured with diameter:start_service/2
specifies one or more supported Diameter applications. Each Diameter
application specifies a dictionary module that knows how to encode and
decode its messages and AVP's. The dictionary module is in turn
generated from a file that defines these messages and AVP's. The format
of such a file is defined in FILE FORMAT below. Users add support for
their specific applications by creating dictionary files, compiling
them to Erlang modules using diameterc and configuring the resulting
dictionaries modules on a service.
The codec generation also results in a hrl file 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. (Modulo other available formats as discussed in
diameter_app(3erl).) These records and the underlying Erlang data types
corresponding to Diameter data formats are discussed in MESSAGE RECORDS
and DATA TYPES respectively. The generated hrl also contains defines
for the possible values of AVPs of type Enumerated.
The diameter application includes three dictionary modules
corresponding to applications defined in section 2.4 of RFC 3588:
diameter_gen_base_rfc3588 for the Diameter Common Messages application
with application identifier 0, diameter_gen_accounting for the Diameter
Base Accounting application with application identifier 3 and
diameter_gen_relaythe Relay application with application identifier
0xFFFFFFFF. The Common Message and Relay applications are the only
applications that diameter itself has any specific knowledge of. The
Common Message application is used for messages that diameter itself
handles: CER/CEA, DWR/DWA and DPR/DPA. The Relay application is given
special treatment with regard to encode/decode since the messages and
AVP's it handles are not specifically defined.
FILE FORMAT
A dictionary 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 at most once unless
otherwise specified. The order in which sections are specified is
unimportant.
@id Number:
Defines the integer Number as the Diameter Application Id of the
application in question. Required if the dictionary defines
@messages. 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
@name Mod:
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
@prefix Name:
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_
@vendor Number Name:
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
@avp_vendor_id Number:
Defines the integer Number as the Vendor-ID of the AVP's listed in
the section content, overriding the @vendor default. The section
content consists of AVP names. Can occur zero or more times (with
different values of Number).
Example:
@avp_vendor_id 2937
WWW-Auth
Domain-Index
Region-Set
@inherits Mod:
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
@avp_types:
Defines the name, code, type and flags of individual AVPs. The
section consists of definitions of the form
Name Code Type Flags
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 DATA TYPES below or a type
as defined by a @custom_types tag.
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: diameter will
set the P flag to 0 as mandated by the current draft standard.
@custom_types Mod:
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
@messages:
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 ]
@grouped:
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 ]
@enum Name:
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). The AVP
in question can be defined in an inherited dictionary in order to
introduce additional values. An AVP so extended must be referenced
by in a @messages or @grouped section.
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.
MESSAGE RECORDS
The hrl generated from a dictionary specification defines records for
the messages and grouped AVPs defined in @messages and @grouped
sections. For each message or grouped AVP definition, a record is
defined whose name is the message or AVP name prefixed with any
dictionary prefix defined with @prefix and whose fields are the names
of the AVPs contained in the message or grouped AVP in the order
specified in the definition in question. For example, the grouped AVP
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.
DATA TYPES
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 diameter:call/4 in a
request record when sending a request, returned in a resulting answer
record and passed to a handle_request callback upon reception of an
incoming request.
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
{{1968,1,20},{3,14,8}} and {{2104,2,26},{9,42,23}} (both inclusive) can
be encoded.
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 currently parsed by diameter.
SEE ALSO
diameterc(1), diameter(3erl), diameter_app(3erl)