diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_dict.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_dict.xml | 206 |
1 files changed, 119 insertions, 87 deletions
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 98adebf145..1034781ff2 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -1,11 +1,22 @@ <?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "fileref.dtd"> +<!DOCTYPE erlref SYSTEM "fileref.dtd" [ + <!ENTITY format + '<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso>'> + <!ENTITY records + '<seealso marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso>'> + <!ENTITY types + '<seealso marker="#DATA_TYPES">DATA TYPES</seealso>'> + <!ENTITY % also SYSTEM "seealso.ent" > + <!ENTITY % here SYSTEM "seehere.ent" > + %also; + %here; +]> <fileref> <header> <copyright> -<year>2011</year><year>2012</year> +<year>2011</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -40,42 +51,43 @@ under the License. <description> <p> -A diameter service as configured with <seealso -marker="diameter#start_service">diameter:start_service/2</seealso> +A diameter service, as configured with &mod_start_service;, specifies one or more supported Diameter applications. Each Diameter application specifies a dictionary module that knows how to encode and decode its messages and AVPs. The dictionary module is in turn generated from a file that defines these messages and AVPs. -The format of such a file is defined in -<seealso marker="#FILE_FORMAT">FILE FORMAT</seealso> below. +The format of such a file is defined in &format; below. Users add support for their specific applications by creating dictionary files, compiling them to Erlang modules using -<seealso marker="diameterc">diameterc</seealso> and configuring the +either &man_compile; or &man_make; 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 AVPs defined for the application, these -records being what a user of the diameter application sends and receives. -(Modulo other available formats as discussed in <seealso -marker="diameter_app">diameter_app(3)</seealso>.) +Dictionary module generation also results in a hrl file that defines +records for the messages and Grouped AVPs defined by the +dictionary, these records being what a user of the diameter +application sends and receives, modulo other possible formats as +discussed in &man_app;. These records and the underlying Erlang data types corresponding to -Diameter data formats are discussed in <seealso -marker="#MESSAGE_RECORDS">MESSAGE RECORDS</seealso> and <seealso -marker="#DATA_TYPES">DATA TYPES</seealso> respectively. -The generated hrl also contains defines for the possible values of +Diameter data formats are discussed in &records; and &types; +respectively. +The generated hrl also contains macro definitions 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: -<c>diameter_gen_base_rfc3588</c> for the Diameter Common Messages -application with application identifier 0, -<c>diameter_gen_accounting</c> for the Diameter Base Accounting +The diameter application includes five dictionary modules +corresponding to applications defined in section 2.4 of &the_rfc;: +<c>diameter_gen_base_rfc3588</c> and <c>diameter_gen_base_rfc6733</c> +for the Diameter Common Messages application with application +identifier 0, +<c>diameter_gen_accounting</c> (for RFC 3588) and +<c>diameter_gen_acct_rfc6733</c> for the Diameter Base Accounting application with application identifier 3 and <c>diameter_gen_relay</c> the Relay application with application -identifier 0xFFFFFFFF. +identifier 0xFFFFFFFF.</p> + +<p> 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 @@ -108,6 +120,8 @@ The order in which sections are specified is unimportant.</p> <taglist> +<marker id="id"/> + <tag><c>@id Number</c></tag> <item> <p> @@ -125,12 +139,14 @@ is used to identify the relevant dictionary module.</p> <p> Example:</p> -<code> +<pre> @id 16777231 -</code> +</pre> </item> +<marker id="name"/> + <tag><c>@name Mod</c></tag> <item> <p> @@ -146,12 +162,14 @@ with existing modules in the system.</p> <p> Example:</p> -<code> +<pre> @name etsi_e2 -</code> +</pre> </item> +<marker id="prefix"/> + <tag><c>@prefix Name</c></tag> <item> <p> @@ -169,12 +187,14 @@ different Diameter applications.</p> <p> Example:</p> -<code> +<pre> @prefix etsi_e2 -</code> +</pre> </item> +<marker id="vendor"/> + <tag><c>@vendor Number Name</c></tag> <item> <p> @@ -189,12 +209,14 @@ The section has empty content.</p> <p> Example:</p> -<code> +<pre> @vendor 13019 ETSI -</code> +</pre> </item> +<marker id="avp_vendor_id"/> + <tag><c>@avp_vendor_id Number</c></tag> <item> <p> @@ -205,16 +227,18 @@ The section content consists of AVP names.</p> <p> Example:</p> -<code> +<pre> @avp_vendor_id 2937 WWW-Auth Domain-Index Region-Set -</code> +</pre> </item> +<marker id="inherits"/> + <tag><c>@inherits Mod</c></tag> <item> <p> @@ -238,18 +262,20 @@ is equivalent to using <c>@avp_vendor_id</c> with a copy of the dictionary's definitions but the former makes for easier reuse.</p> <p> -All dictionaries should typically inherit RFC3588 AVPs from +All dictionaries should typically inherit &the_rfc; AVPs from <c>diameter_gen_base_rfc3588</c>.</p> <p> Example:</p> -<code> +<pre> @inherits diameter_gen_base_rfc3588 -</code> +</pre> </item> +<marker id="avp_types"/> + <tag><c>@avp_types</c></tag> <item> <p> @@ -260,7 +286,7 @@ The section consists of definitions of the form</p> <p> where Code is the integer AVP code, Type identifies an AVP Data Format -as defined in <seealso marker="#DATA_TYPES">DATA TYPES</seealso> below, +as defined in section &types; below, and Flags is a string of V, M and P characters indicating the flags to be set on an outgoing AVP or a single <c>'-'</c> (minus) character if none are to be set.</p> @@ -268,22 +294,22 @@ none are to be set.</p> <p> Example:</p> -<code> +<pre> @avp_types Location-Information 350 Grouped MV Requested-Information 353 Enumerated V -</code> +</pre> <warning> <p> -The P flag has been deprecated by the Diameter Maintenance -and Extensions Working Group of the IETF and should be omitted -to conform to the current draft standard.</p> +The P flag has been deprecated by &the_rfc;.</p> </warning> </item> +<marker id="custom_types"/> + <tag><c>@custom_types Mod</c></tag> <item> <p> @@ -298,13 +324,15 @@ encode/decode.</p> <p> Example:</p> -<code> +<pre> @custom_types rfc4005_avps Framed-IP-Address -</code> +</pre> </item> +<marker id="codecs"/> + <tag><c>@codecs Mod</c></tag> <item> <p> @@ -315,22 +343,24 @@ Like <c>@custom_types</c> but requires the specified module to export <p> Example:</p> -<code> +<pre> @codecs rfc4005_avps Framed-IP-Address -</code> +</pre> </item> +<marker id="messages"/> + <tag><c>@messages</c></tag> <item> <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> +section 3.2 of &the_rfc;, "Command Code Format Specification".</p> <!-- RFC 4740 RTR/RTA --> -<code> +<pre> @messages RTR ::= < Diameter Header: 287, REQ, PXY > @@ -363,35 +393,39 @@ RTA ::= < Diameter Header: 287, PXY > * [ Proxy-Info ] * [ Route-Record ] * [ AVP ] -</code> +</pre> </item> +<marker id="grouped"/> + <tag><c>@grouped</c></tag> <item> <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> +section 4.4 of &the_rfc;, "Grouped AVP Values".</p> <p> Example:</p> -<code> +<pre> @grouped SIP-Deregistration-Reason ::= < AVP Header: 383 > { SIP-Reason-Code } [ SIP-Reason-Info ] * [ AVP ] -</code> +</pre> <p> Specifying a Vendor-Id in the definition of a grouped AVP is equivalent to specifying it with <c>@avp_vendor_id</c>.</p> </item> +<marker id="enum"/> + <tag><c>@enum Name</c></tag> <item> <p> @@ -408,16 +442,18 @@ otherwise defined in another dictionary.</p> <p> Example:</p> -<code> +<pre> @enum SIP-Reason-Code PERMANENT_TERMINATION 0 NEW_SIP_SERVER_ASSIGNED 1 SIP_SERVER_CHANGE 2 REMOVE_SIP_SERVER 3 -</code> +</pre> </item> +<marker id="end"/> + <tag><c>@end</c></tag> <item> <p> @@ -444,28 +480,28 @@ The hrl generated from a dictionary specification defines records for the messages and grouped AVPs defined in <c>@messages</c> and <c>@grouped</c> 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 <c>@prefix</c> and whose fields are the names of the AVPs +name is the message or AVP name, prefixed with any dictionary prefix +defined with <c>@prefix</c>, 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> -<code> +<pre> SIP-Deregistration-Reason ::= < AVP Header: 383 > { SIP-Reason-Code } [ SIP-Reason-Info ] * [ AVP ] -</code> +</pre> <p> will result in the following record definition given an empty prefix.</p> -<code> +<pre> -record('SIP-Deregistration-Reason' {'SIP-Reason-Code', 'SIP-Reason-Info', 'AVP'}). -</code> +</pre> <p> The values encoded in the fields of generated records depends on the @@ -473,7 +509,7 @@ 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 +The AVP's type is as specified in the AVP definition, the &the_rfc; types being described below.</p> <marker id="DATA_TYPES"/> @@ -486,13 +522,11 @@ types being described below.</p> <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 +Formats") and 4.3 ("Derived AVP Data Formats") of &the_rfc; are encoded as values of the types defined here. -Values are passed to <seealso -marker="diameter#call">diameter:call/4</seealso> +Values are passed to &mod_call; in a request record when sending a request, returned in a resulting -answer record and passed to a <seealso -marker="diameter_app#handle_request">handle_request</seealso> +answer record and passed to a &app_handle_request; callback upon reception of an incoming request.</p> <p> @@ -507,7 +541,7 @@ callback upon reception of an incoming request.</p> <marker id="Float64"/> <marker id="Grouped"/> -<code> +<pre> OctetString() = [0..255] Integer32() = -2147483647..2147483647 Integer64() = -9223372036854775807..9223372036854775807 @@ -516,7 +550,7 @@ Unsigned64() = 0..18446744073709551615 Float32() = '-infinity' | float() | infinity Float64() = '-infinity' | float() | infinity Grouped() = record() -</code> +</pre> <p> On encode, an OctetString() can be specified as an iolist(), @@ -530,10 +564,10 @@ section.</p> <em>Derived AVP Data Formats</em></p> <marker id="Address"/> -<code> +<pre> Address() = OctetString() | tuple() -</code> +</pre> <p> On encode, an OctetString() IPv4 address is parsed in the usual @@ -545,7 +579,7 @@ An IPv6 tuple() has length 8 and contains values of type 0..65535. The tuple representation is used on decode.</p> <marker id="Time"/> -<code> +<pre> Time() = {date(), time()} where @@ -559,19 +593,19 @@ where Hour = 0..23 Minute = 0..59 Second = 0..59 -</code> +</pre> <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. +limited by way of their encoding as four octets as required by +&the_rfc; with the required extension from RFC 2030. In particular, only values between <c>{{1968,1,20},{3,14,8}}</c> and <c>{{2104,2,26},{9,42,23}}</c> (both inclusive) can be encoded.</p> <marker id="UTF8String"/> -<code> +<pre> UTF8String() = [integer()] -</code> +</pre> <p> List elements are the UTF-8 encodings of the individual characters @@ -579,15 +613,15 @@ in the string. Invalid codepoints will result in encode/decode failure.</p> <marker id="DiameterIdentity"/> -<code> +<pre> DiameterIdentity() = OctetString() -</code> +</pre> <p> A value must have length at least 1.</p> <marker id="DiameterURI"/> -<code> +<pre> DiameterURI() = OctetString() | #diameter_URI{type = Type, fqdn = FQDN, @@ -602,19 +636,19 @@ where Port = integer() Transport = sctp | tcp Protocol = diameter | radius | 'tacacs+' -</code> +</pre> <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. +section 4.3 of &the_rfc;. The record representation is used on decode.</p> <marker id="Enumerated"/> -<code> +<pre> Enumerated() = Integer32() -</code> +</pre> <p> On encode, values can be specified using the macros defined in a @@ -622,10 +656,10 @@ dictionary's hrl file.</p> <marker id="IPFilterRule"/> <marker id="QoSFilterRule"/> -<code> +<pre> IPFilterRule() = OctetString() QoSFilterRule() = OctetString() -</code> +</pre> <p> Values of these types are not currently parsed by diameter.</p> @@ -639,9 +673,7 @@ Values of these types are not currently parsed by diameter.</p> <title>SEE ALSO</title> <p> -<seealso marker="diameterc">diameterc(1)</seealso>, -<seealso marker="diameter">diameter(3)</seealso>, -<seealso marker="diameter_app">diameter_app(3)</seealso></p> +&man_compile;, &man_main;, &man_app;, &man_codec;, &man_make;</p> </section> |