aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2011-11-30 12:31:26 +0100
committerAnders Svensson <[email protected]>2011-12-06 18:25:48 +0100
commitf2a4059d06f8b76d2c1da14197f170deebd64f45 (patch)
tree913c4ebd4a6bc4b571a1d77efe9af81b811159db
parent3bd6fcfd8ae399a903e50a9510ee279bde154039 (diff)
downloadotp-f2a4059d06f8b76d2c1da14197f170deebd64f45.tar.gz
otp-f2a4059d06f8b76d2c1da14197f170deebd64f45.tar.bz2
otp-f2a4059d06f8b76d2c1da14197f170deebd64f45.zip
Update documentation
-rw-r--r--lib/diameter/doc/src/diameter_dict.xml147
1 files changed, 90 insertions, 57 deletions
diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml
index 01616f519d..cc638dbc18 100644
--- a/lib/diameter/doc/src/diameter_dict.xml
+++ b/lib/diameter/doc/src/diameter_dict.xml
@@ -36,7 +36,7 @@ under the License.
<!-- ===================================================================== -->
<file>diameter_dict</file>
-<filesummary>Dictionary inteface of the diameter application.</filesummary>
+<filesummary>Dictionary interface of the diameter application.</filesummary>
<description>
<p>
@@ -74,7 +74,7 @@ corresponding to applications defined in section 2.4 of RFC 3588:
application with application identifier 0,
<c>diameter_gen_accounting</c> for the Diameter Base Accounting
application with application identifier 3 and
-<c>diameter_gen_relay</c>the Relay application with application
+<c>diameter_gen_relay</c> 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.
@@ -94,18 +94,16 @@ defined.</p>
<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.
+Each section starts with a tag followed by zero or more arguments
+and 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>
+Whitespace separates individual tokens but is otherwise insignificant.</p>
<p>
The tags, their arguments and the contents of each corresponding
section are as follows.
-Each section can occur at most once unless otherwise specified.
+Each section can occur multiple times unless otherwise specified.
The order in which sections are specified is unimportant.</p>
<taglist>
@@ -115,7 +113,8 @@ The order in which sections are specified is unimportant.</p>
<p>
Defines the integer Number as the Diameter Application Id of the
application in question.
-Required if the dictionary defines <c>@messages</c>.
+Can occur at most once and is required if the dictionary defines
+<c>@messages</c>.
The section has empty content.</p>
<p>
@@ -136,16 +135,13 @@ Example:</p>
<item>
<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>
+Can occur at most once and defaults to the name of the dictionary file
+minus any extension if unspecified.
+The section has empty content.</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>
+Note that a dictionary module should have a unique name so as not collide
+with existing modules in the system.</p>
<p>
Example:</p>
@@ -159,22 +155,22 @@ Example:</p>
<tag><c>@prefix Name</c></tag>
<item>
<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>
+Defines Name as the prefix to be added to record and constant names
+(followed by a <c>'_'</c> character) in the generated dictionary
+module and hrl.
+Can occur at most once.
+The section has empty content.</p>
<p>
-A prefix is optional but can
-be used to disambiguate record and constant names
-resulting from similarly named messages and AVPs in different
-Diameter applications.</p>
+A prefix is optional but can be be used to disambiguate between record
+and constant names resulting from similarly named messages and AVPs in
+different Diameter applications.</p>
<p>
Example:</p>
<code>
-@prefix etsi_e2_
+@prefix etsi_e2
</code>
</item>
@@ -182,10 +178,12 @@ Example:</p>
<tag><c>@vendor Number Name</c></tag>
<item>
<p>
-Defines the integer Number as the the default Vendor-ID of AVPs for
+Defines the integer Number as the the default Vendor-Id of AVPs for
which the V flag is set.
Name documents the owner of the application
but is otherwise unused.
+Can occur at most once and is required if an AVP sets the V flag and
+is not otherwise assigned a Vendor-Id.
The section has empty content.</p>
<p>
@@ -200,10 +198,9 @@ Example:</p>
<tag><c>@avp_vendor_id Number</c></tag>
<item>
<p>
-Defines the integer Number as the Vendor-ID of the AVPs listed in the
+Defines the integer Number as the Vendor-Id of the AVPs listed in the
section content, overriding the <c>@vendor</c> default.
-The section content consists of AVP names.
-Can occur zero or more times (with different values of Number).</p>
+The section content consists of AVP names.</p>
<p>
Example:</p>
@@ -221,13 +218,27 @@ Region-Set
<tag><c>@inherits Mod</c></tag>
<item>
<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>
+Defines the name of a dictionary module containing AVP
+definitions that should be imported into the current dictionary.
+The section content consists of the names of those AVPs whose
+definitions should be imported from the dictionary, an empty list
+causing all to be imported.
+Any listed AVPs must not be defined in the current dictionary and
+it is an error to inherit the same AVP from more than one
+dictionary.</p>
+
+<p>
+Note that an inherited AVP that sets the V flag takes its Vendor-Id
+from either <c>@avp_vendor_id</c> in the inheriting dictionary or
+<c>@vendor</c> in the inherited dictionary.
+In particular, <c>@avp_vendor_id</c> in the inherited dictionary is
+ignored.
+Inheriting from a dictionary that specifies the required <c>@vendor</c>
+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>
-Can occur 0 or more times (with different values of Mod) but all
-dictionaries should typically inherit RFC3588 AVPs from
+All dictionaries should typically inherit RFC3588 AVPs from
<c>diameter_gen_base_rfc3588</c>.</p>
<p>
@@ -248,13 +259,11 @@ The section consists of definitions of the form</p>
<p><c>Name Code Type Flags</c></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 <seealso
-marker="#DATA_TYPES">DATA TYPES</seealso> below or a
-type as defined by a <c>@custom_types</c> section.</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,
+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>
<p>
Example:</p>
@@ -262,8 +271,8 @@ Example:</p>
<code>
@avp_types
-Location-Information 350 Grouped VM
-Requested-Information 353 Enumerated V
+Location-Information 350 Grouped MV
+Requested-Information 353 Enumerated V
</code>
<p>
@@ -276,21 +285,36 @@ to 0 as mandated by the current draft standard.</p>
<tag><c>@custom_types Mod</c></tag>
<item>
<p>
-Defines AVPs for which module Mod provides encode/decode.
+Specifies AVPs for which module Mod provides encode/decode functions.
The section contents consists of AVP names.
-For each AVP Name in the content, <c>Mod:Name(encode|decode, Type, Data)</c>
-is expected to provide encode/decode for values of the AVP, where Type
-is the type of the AVP as declared in the <c>@avp_types</c> section
-of the dictionary and Data is the value to encoded/decoded.</p>
+For each such name, <c>Mod:Name(encode|decode, Type, Data)</c> is
+expected to provide encode/decode for values of the AVP, where Name is
+the name of the AVP, Type is it's type as declared in the
+<c>@avp_types</c> section of the dictionary and Data is the value to
+encode/decode.</p>
+
+<p>
+Example:</p>
+
+<code>
+@custom_types rfc4005_avps
+
+Framed-IP-Address
+</code>
+</item>
+<tag><c>@codecs Mod</c></tag>
+<item>
<p>
-Can occur 0 or more times (with different values of Mod).</p>
+Like <c>@custom_types</c> but requires the specified module to export
+<c>Mod:Type(encode|decode, Name, Data)</c> rather than
+<c>Mod:Name(encode|decode, Type, Data)</c>.</p>
<p>
Example:</p>
<code>
-@custom_types rfc4005_avps
+@codecs rfc4005_avps
Framed-IP-Address
</code>
@@ -360,6 +384,10 @@ SIP-Deregistration-Reason ::= &lt; AVP Header: 383 >
[ SIP-Reason-Info ]
* [ AVP ]
</code>
+
+<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>
<tag><c>@enum Name</c></tag>
@@ -371,11 +399,9 @@ 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).
-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 <c>@messages</c> or
-<c>@grouped</c> section.</p>
+Note that the AVP in question can be defined in an inherited
+dictionary in order to introduce additional values to an enumeration
+otherwise defined in another dictionary.</p>
<p>
Example:</p>
@@ -390,11 +416,18 @@ REMOVE_SIP_SERVER 3
</code>
</item>
+<tag><c>@end</c></tag>
+<item>
+<p>
+Causes parsing of the dictionary to terminate:
+any remaining content is ignored.</p>
+</item>
+
</taglist>
<p>
Comments can be included in a dictionary file using semicolon:
-text from a semicolon to end of line is ignored.</p>
+characters from a semicolon to end of line are ignored.</p>
<marker id="MESSAGE_RECORDS"/>
</section>