<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- diameter_dict(4)</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/diameter-0.9.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Diameter</strong><br><strong>Reference Manual</strong><br><small>Version 0.9</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p>
<ul class="flipMenu">
<li id="no" title="diameter " expanded="false">diameter<ul>
<li><a href="diameter.html">
Top of manual page
</a></li>
<li title="add_transport-2"><a href="diameter.html#add_transport-2">add_transport/2</a></li>
<li title="call-4"><a href="diameter.html#call-4">call/4</a></li>
<li title="origin_state_id-0"><a href="diameter.html#origin_state_id-0">origin_state_id/0</a></li>
<li title="remove_transport-2"><a href="diameter.html#remove_transport-2">remove_transport/2</a></li>
<li title="service_info-2"><a href="diameter.html#service_info-2">service_info/2</a></li>
<li title="services-0"><a href="diameter.html#services-0">services/0</a></li>
<li title="session_id-1"><a href="diameter.html#session_id-1">session_id/1</a></li>
<li title="start-0"><a href="diameter.html#start-0">start/0</a></li>
<li title="start_service-2"><a href="diameter.html#start_service-2">start_service/2</a></li>
<li title="stop-0"><a href="diameter.html#stop-0">stop/0</a></li>
<li title="stop_service-1"><a href="diameter.html#stop_service-1">stop_service/1</a></li>
<li title="subscribe-1"><a href="diameter.html#subscribe-1">subscribe/1</a></li>
<li title="unsubscribe-1"><a href="diameter.html#unsubscribe-1">unsubscribe/1</a></li>
</ul>
</li>
<li title="diameterc"><a href="diameterc.html">diameterc</a></li>
<li id="no" title="diameter_app " expanded="false">diameter_app<ul>
<li><a href="diameter_app.html">
Top of manual page
</a></li>
<li title="Mod:peer_up-3"><a href="diameter_app.html#Mod:peer_up-3">Mod:peer_up/3</a></li>
<li title="Mod:peer_down-3"><a href="diameter_app.html#Mod:peer_down-3">Mod:peer_down/3</a></li>
<li title="Mod:pick_peer-4"><a href="diameter_app.html#Mod:pick_peer-4">Mod:pick_peer/4</a></li>
<li title="Mod:prepare_request-3"><a href="diameter_app.html#Mod:prepare_request-3">Mod:prepare_request/3</a></li>
<li title="Mod:prepare_retransmit-3"><a href="diameter_app.html#Mod:prepare_retransmit-3">Mod:prepare_retransmit/3</a></li>
<li title="Mod:handle_answer-4"><a href="diameter_app.html#Mod:handle_answer-4">Mod:handle_answer/4</a></li>
<li title="Mod:handle_error-4"><a href="diameter_app.html#Mod:handle_error-4">Mod:handle_error/4</a></li>
<li title="Mod:handle_request-3"><a href="diameter_app.html#Mod:handle_request-3">Mod:handle_request/3</a></li>
</ul>
</li>
<li title="diameter_dict"><a href="diameter_dict.html">diameter_dict</a></li>
<li id="no" title="diameter_transport " expanded="false">diameter_transport<ul>
<li><a href="diameter_transport.html">
Top of manual page
</a></li>
<li title="Mod:start-3"><a href="diameter_transport.html#Mod:start-3">Mod:start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_tcp " expanded="false">diameter_tcp<ul>
<li><a href="diameter_tcp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_tcp.html#start-3">start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_sctp " expanded="false">diameter_sctp<ul>
<li><a href="diameter_sctp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_sctp.html#start-3">start/3</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>diameter_dict</h1></center>
<h3>FILE</h3>
<div class="REFBODY">diameter_dict</div>
<h3>FILE SUMMARY</h3>
<div class="REFBODY">Dictionary inteface of the diameter application.</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>
A diameter service as configured with <span class="bold_code"><a href="diameter.html#start_service">diameter:start_service/2</a></span>
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
<span class="bold_code"><a href="#FILE_FORMAT">FILE FORMAT</a></span> below.
Users add support for their specific applications by creating
dictionary files, compiling them to Erlang modules using
<span class="bold_code"><a href="diameterc.html">diameterc</a></span> and configuring the
resulting dictionaries modules on a service.</p>
<p>
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 <span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span>.)
These records and the underlying Erlang data types corresponding to
Diameter data formats are discussed in <span class="bold_code"><a href="#MESSAGE_RECORDS">MESSAGE RECORDS</a></span> and <span class="bold_code"><a href="#DATA_TYPES">DATA TYPES</a></span> respectively.
The generated hrl also contains defines for the possible values of
AVPs of type Enumerated.</p>
<p>
The diameter application includes three dictionary modules
corresponding to applications defined in section 2.4 of RFC 3588:
<span class="code">diameter_gen_base_rfc3588</span> for the Diameter Common Messages
application with application identifier 0,
<span class="code">diameter_gen_accounting</span> for the Diameter Base Accounting
application with application identifier 3 and
<span class="code">diameter_gen_relay</span>the 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.</p>
<a name="FILE_FORMAT"></a>
</p></div>
<h3><a name="id202200">FILE FORMAT</a></h3>
<div class="REFBODY">
<p>
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.</p>
<p>
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.</p>
<dl>
<dt><strong><span class="code">@id Number</span></strong></dt>
<dd>
<p>
Defines the integer Number as the Diameter Application Id of the
application in question.
The section has empty content.</p>
<p>
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.</p>
<p>
Example:</p>
<div class="example"><pre>
@id 16777231
</pre></div>
</dd>
<dt><strong><span class="code">@name Mod</span></strong></dt>
<dd>
<p>
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.</p>
<p>
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.</p>
<p>
Example:</p>
<div class="example"><pre>
@name etsi_e2
</pre></div>
</dd>
<dt><strong><span class="code">@prefix Name</span></strong></dt>
<dd>
<p>
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.</p>
<p>
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.</p>
<p>
Example:</p>
<div class="example"><pre>
@prefix etsi_e2_
</pre></div>
</dd>
<dt><strong><span class="code">@vendor Number Name</span></strong></dt>
<dd>
<p>
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.</p>
<p>
Example:</p>
<div class="example"><pre>
@vendor 13019 ETSI
</pre></div>
</dd>
<dt><strong><span class="code">@avp_vendor_id Number</span></strong></dt>
<dd>
<p>
Defines the integer Number as the Vendor-ID of the AVP's listed in the
section content, overriding the <span class="code">@vendor</span> default.
The section content consists of AVP names.
Can occur zero or more times (with different values of Number).</p>
<p>
Example:</p>
<div class="example"><pre>
@avp_vendor_id 2937
WWW-Auth
Domain-Index
Region-Set
</pre></div>
</dd>
<dt><strong><span class="code">@inherits Mod</span></strong></dt>
<dd>
<p>
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.</p>
<p>
Can occur 0 or more times (with different values of Mod) but all
dictionaries should typically inherit RFC3588 AVPs from
<span class="code">diameter_gen_base_rfc3588</span>.</p>
<p>
Example:</p>
<div class="example"><pre>
@inherits diameter_gen_base_rfc3588
</pre></div>
</dd>
<dt><strong><span class="code">@avp_types</span></strong></dt>
<dd>
<p>
Defines the name, code, type and flags of individual AVPs.
The section consists of definitions of the form</p>
<p><span class="code">Name Code Type Flags</span></p>
<p>
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 <span class="bold_code"><a href="#DATA_TYPES">DATA TYPES</a></span> below or a
type as defined by a <span class="code">@custom_types</span> tag.</p>
<p>
Example:</p>
<div class="example"><pre>
@avp_types
Location-Information 350 Grouped VM
Requested-Information 353 Enumerated V
</pre></div>
<p>
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.</p>
</dd>
<dt><strong><span class="code">@custom_types Mod</span></strong></dt>
<dd>
<p>
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.</p>
<p>
Can occur 0 or more times (with different values of Mod).</p>
<p>
Example:</p>
<div class="example"><pre>
@custom_types rfc4005_types
Framed-IP-Address
</pre></div>
</dd>
<dt><strong><span class="code">@messages</span></strong></dt>
<dd>
<p>
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".</p>
<div class="example"><pre>
@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 ]
</pre></div>
</dd>
<dt><strong><span class="code">@grouped</span></strong></dt>
<dd>
<p>
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".</p>
<p>
Example:</p>
<div class="example"><pre>
@grouped
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
</pre></div>
</dd>
<dt><strong><span class="code">@enum Name</span></strong></dt>
<dd>
<p>
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.</p>
<p>
Can occur 0 or more times (with different values of Name).</p>
<p>
Example:</p>
<div class="example"><pre>
@enum SIP-Reason-Code
PERMANENT_TERMINATION 0
NEW_SIP_SERVER_ASSIGNED 1
SIP_SERVER_CHANGE 2
REMOVE_SIP_SERVER 3
</pre></div>
</dd>
</dl>
<p>
Comments can be included in a dictionary file using semicolon:
text from a semicolon to end of line is ignored.</p>
<a name="MESSAGE_RECORDS"></a>
</div>
<h3><a name="id202565">MESSAGE RECORDS</a></h3>
<div class="REFBODY">
<p>
The hrl generated from a dictionary specification defines records for the
messages and grouped AVPs defined in <span class="code">@messages</span> and
<span class="code">@grouped</span> 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 <span class="code">@prefix</span> 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</p>
<div class="example"><pre>
SIP-Deregistration-Reason ::= < AVP Header: 383 >
{ SIP-Reason-Code }
[ SIP-Reason-Info ]
* [ AVP ]
</pre></div>
<p>
will result in the following record definition given an empty
prefix.</p>
<div class="example"><pre>
-record('SIP-Deregistration-Reason' {'SIP-Reason-Code',
'SIP-Reason-Info',
'AVP'}).
</pre></div>
<p>
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.</p>
<a name="DATA_TYPES"></a>
</div>
<h3><a name="id202624">DATA TYPES</a></h3>
<div class="REFBODY">
<p>
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 <span class="bold_code"><a href="diameter.html#call">diameter:call/4</a></span>
in a request record when sending a request, returned in a resulting
answer record and passed to a <span class="bold_code"><a href="diameter_app.html#handle_request">handle_request</a></span>
callback upon reception of an incoming request.</p>
<p>
<strong>Basic AVP Data Formats</strong></p>
<a name="OctetString"></a>
<a name="Integer32"></a>
<a name="Integer64"></a>
<a name="Unsigned32"></a>
<a name="Unsigned64"></a>
<a name="Float32"></a>
<a name="Float64"></a>
<a name="Grouped"></a>
<div class="example"><pre>
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()
</pre></div>
<p>
On encode, an OctetString() can be specified as an iolist(),
excessively large floats (in absolute value) are equivalent to
<span class="code">infinity</span> or <span class="code">'-infinity'</span> and excessively large integers
result in encode failure.
The records for grouped AVPs are as discussed in the previous
section.</p>
<p>
<strong>Derived AVP Data Formats</strong></p>
<a name="Address"></a>
<div class="example"><pre>
Address() = OctetString()
| tuple()
</pre></div>
<p>
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.</p>
<a name="Time"></a>
<div class="example"><pre>
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
</pre></div>
<p>
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 <span class="code">{{1968,1,20},{3,14,8}}</span>
and <span class="code">{{2104,2,26},{9,42,23}}</span> (both inclusive) can be encoded.</p>
<a name="UTF8String"></a>
<div class="example"><pre>
UTF8String() = [integer()]
</pre></div>
<p>
List elements are the UTF-8 encodings of the individual characters
in the string.
Invalid codepoints will result in encode/decode failure.</p>
<a name="DiameterIdentity"></a>
<div class="example"><pre>
DiameterIdentity() = OctetString()
</pre></div>
<p>
A value must have length at least 1.</p>
<a name="DiameterURI"></a>
<div class="example"><pre>
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+'
</pre></div>
<p>
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.</p>
<a name="Enumerated"></a>
<div class="example"><pre>
Enumerated() = Integer32()
</pre></div>
<p>
On encode, values can be specified using the macros defined in a
dictionary's hrl file.</p>
<a name="IPFilterRule"></a>
<a name="QoSFilterRule"></a>
<div class="example"><pre>
IPFilterRule() = OctetString()
QoSFilterRule() = OctetString()
</pre></div>
<p>
Values of these types are not currently parsed by diameter.</p>
</div>
<h3><a name="id202855">SEE ALSO</a></h3>
<div class="REFBODY">
<p>
<span class="bold_code"><a href="diameterc.html">diameterc(1)</a></span>,
<span class="bold_code"><a href="diameter.html">diameter(3)</a></span>,
<span class="bold_code"><a href="diameter_app.html">diameter_app(3)</a></span></p>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2011-2011 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
153de8e767391ee69acb7025d88d7586
>
files
>
517
