Provided by: erlang-manpages_14.b.4-dfsg-1ubuntu1_all bug

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)