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)