From f2a4059d06f8b76d2c1da14197f170deebd64f45 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Wed, 30 Nov 2011 12:31:26 +0100 Subject: Update documentation --- lib/diameter/doc/src/diameter_dict.xml | 147 ++++++++++++++++++++------------- 1 file changed, 90 insertions(+), 57 deletions(-) (limited to 'lib/diameter/doc/src/diameter_dict.xml') 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. diameter_dict -Dictionary inteface of the diameter application. +Dictionary interface of the diameter application.

@@ -74,7 +74,7 @@ corresponding to applications defined in section 2.4 of RFC 3588: 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 +diameter_gen_relay 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.

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.

+Whitespace separates individual tokens but is otherwise 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. +Each section can occur multiple times unless otherwise specified. The order in which sections are specified is unimportant.

@@ -115,7 +113,8 @@ The order in which sections are specified is unimportant.

Defines the integer Number as the Diameter Application Id of the application in question. -Required if the dictionary defines @messages. +Can occur at most once and is required if the dictionary defines +@messages. The section has empty content.

@@ -136,16 +135,13 @@ Example:

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.

+Can occur at most once and defaults to the name of the dictionary file +minus any extension if unspecified. +The section has empty content.

-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.

+Note that a dictionary module should have a unique name so as not collide +with existing modules in the system.

Example:

@@ -159,22 +155,22 @@ Example:

@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.

+Defines Name as the prefix to be added to record and constant names +(followed by a '_' character) in the generated dictionary +module and hrl. +Can occur at most once. +The section has empty content.

-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.

+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.

Example:

-@prefix etsi_e2_ +@prefix etsi_e2 @@ -182,10 +178,12 @@ Example:

@vendor Number Name

-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.

@@ -200,10 +198,9 @@ Example:

@avp_vendor_id Number

-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 @vendor default. -The section content consists of AVP names. -Can occur zero or more times (with different values of Number).

+The section content consists of AVP names.

Example:

@@ -221,13 +218,27 @@ 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.

+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.

+ +

+Note that an inherited AVP that sets the V flag takes its Vendor-Id +from either @avp_vendor_id in the inheriting dictionary or +@vendor in the inherited dictionary. +In particular, @avp_vendor_id in the inherited dictionary is +ignored. +Inheriting from a dictionary that specifies the required @vendor +is equivalent to using @avp_vendor_id with a copy of the +dictionary's definitions but the former makes for easier reuse.

-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 diameter_gen_base_rfc3588.

@@ -248,13 +259,11 @@ 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 section.

+where Code is the integer AVP code, Type identifies an AVP Data Format +as defined in DATA 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 '-' (minus) character if +none are to be set.

Example:

@@ -262,8 +271,8 @@ Example:

@avp_types -Location-Information 350 Grouped VM -Requested-Information 353 Enumerated V +Location-Information 350 Grouped MV +Requested-Information 353 Enumerated V

@@ -276,21 +285,36 @@ to 0 as mandated by the current draft standard.

@custom_types Mod

-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, Mod:Name(encode|decode, Type, Data) -is expected to provide encode/decode for values of the AVP, where Type -is the type of the AVP as declared in the @avp_types section -of the dictionary and Data is the value to encoded/decoded.

+For each such name, Mod:Name(encode|decode, Type, Data) 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 +@avp_types section of the dictionary and Data is the value to +encode/decode.

+ +

+Example:

+ + +@custom_types rfc4005_avps + +Framed-IP-Address + + +@codecs Mod +

-Can occur 0 or more times (with different values of Mod).

+Like @custom_types but requires the specified module to export +Mod:Type(encode|decode, Name, Data) rather than +Mod:Name(encode|decode, Type, Data).

Example:

-@custom_types rfc4005_avps +@codecs rfc4005_avps Framed-IP-Address @@ -360,6 +384,10 @@ SIP-Deregistration-Reason ::= < AVP Header: 383 > [ SIP-Reason-Info ] * [ AVP ] + +

+Specifying a Vendor-Id in the definition of a grouped AVP is +equivalent to specifying it with @avp_vendor_id.

 @enum Name @@ -371,11 +399,9 @@ 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.

+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.

Example:

@@ -390,11 +416,18 @@ REMOVE_SIP_SERVER 3 +@end + +

+Causes parsing of the dictionary to terminate: +any remaining content is ignored.

+ +

Comments can be included in a dictionary file using semicolon: -text from a semicolon to end of line is ignored.

+characters from a semicolon to end of line are ignored.

-- cgit v1.2.3