Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       diameter_codec - Decode and encode of Diameter messages.

DESCRIPTION

       Incoming  Diameter  messages  are  decoded  from  binary()  before  being  communicated to
       diameter_app(3erl) callbacks. Similarly,  outgoing  Diameter  messages  are  encoded  into
       binary()  before  being  passed  to  the  appropriate  diameter_transport(3erl) module for
       transmission. The functions in this module implement this encode/decode.

   Note:
       Calls to this module are made by diameter itself as a consequence of configuration  passed
       to  diameter:start_service/2.  The  encode/decode  functions  may also be useful for other
       purposes (eg. test) but the diameter user does not  need  to  call  them  explicitly  when
       sending and receiving messages using diameter:call/4 and the callback interface documented
       in diameter_app(3erl).

       The header() and packet() records below are defined in diameter.hrl, which can be included
       as follows.

       -include_lib("diameter/include/diameter.hrl").

       Application-specific  records  are defined in the hrl files resulting from dictionary file
       compilation.

DATA TYPES

         uint8() = 0..255:

         uint24() = 0..16777215:

         uint32() = 0..4294967295:
           8-bit, 24-bit and 32-bit integers occurring in Diameter and AVP headers.

         avp() = #diameter_avp{}:
           The application-neutral representation of an AVP. Primarily intended for use by  relay
           applications   that   need  to  handle  arbitrary  Diameter  applications.  A  service
           implementing a specific Diameter application (for which it  configures  a  dictionary)
           can manipulate values of type message() instead.

           Fields have the following types.

           code = uint32():

           is_mandatory = boolean():

           need_encryption = boolean():

           vendor_id = uint32() | undefined:
             Values in the AVP header, corresponding to AVP Code, the M flag, P flags and Vendor-
             ID respectively. A Vendor-ID other than undefined implies a set V flag.

           data = iolist():
             The data bytes of the AVP.

           name = atom():
             The name of the AVP as defined in the dictionary file in question, or  undefined  if
             the AVP is unknown to the dictionary file in question.

           value = term():
             The decoded value of an AVP. Will be undefined on decode if the data bytes could not
             be decoded or the AVP is unknown. The type of a decoded  value  is  as  document  in
             diameter_dict(5).

           type = atom():
             The  type  of  the  AVP  as  specified in the dictionary file in question (or one it
             inherits). Possible  types  are  undefined  and  the  Diameter  types:  OctetString,
             Integer32, Integer64, Unsigned32, Unsigned64, Float32, Float64, Grouped, Enumerated,
             Address,  Time,  UTF8String,   DiameterIdentity,   DiameterURI,   IPFilterRule   and
             QoSFilterRule.

         dictionary() = module():
           The   name   of  a  generated  dictionary  module  as  generated  by  diameterc(1)  or
           diameter_make:codec/2.  The  interface  provided  by  a  dictionary   module   is   an
           implementation detail that may change.

         header() = #diameter_header{}:
           The  record  representation  of  the Diameter header. Values in a packet() returned by
           decode/2 are as extracted from the incoming message. Values set in an packet()  passed
           to  encode/2  are  preserved  in  the  encoded binary(), with the exception of length,
           cmd_code and application_id, all of  which  are  determined  by  the  dictionary()  in
           question.

     Note:
         It  is  not  necessary  to set header fields explicitly in outgoing messages as diameter
         itself will set appropriate values. Setting inappropriate values can be useful for  test
         purposes.

           Fields have the following types.

           version = uint8():

           length = uint24():

           cmd_code = uint24():

           application_id = uint32():

           hop_by_hop_id = uint32():

           end_to_end_id = uint32():
             Values  of  the  Version,  Message  Length, Command-Code, Application-ID, Hop-by-Hop
             Identifier and End-to-End Identifier fields of the Diameter header.

           is_request = boolean():

           is_proxiable = boolean():

           is_error = boolean():

           is_retransmitted = boolean():
             Values corresponding to the R(equest), P(roxiable), E(rror)  and  T(Potentially  re-
             transmitted message) flags of the Diameter header.

         message() = record() | list():
           The representation of a Diameter message as passed to diameter:call/4 or returned from
           a  handle_request/3  callback.  The  record   representation   is   as   outlined   in
           diameter_dict(5):  a  message  as  defined in a dictionary file is encoded as a record
           with one field for each component AVP. Equivalently, a message can also be encoded  as
           a  list  whose  head  is  the  atom-valued  message name (as specified in the relevant
           dictionary file) and whose tail is a list of {AvpName, AvpValue} pairs.

           Another list-valued representation allows a message to be specified as  a  list  whose
           head  is  a  header()  and whose tail is an avp() list. This representation is used by
           diameter itself  when  relaying  requests  as  directed  by  the  return  value  of  a
           handle_request/3 callback. It differs from the other other two in that it bypasses the
           checks for messages that do not agree with their  definitions  in  the  dictionary  in
           question: messages are sent exactly as specified.

         packet() = #diameter_packet{}:
           A  container  for  incoming  and outgoing Diameter messages. Fields have the following
           types.

           header = header() | undefined:
             The Diameter header of the message. Can be (and typically should be)  undefined  for
             an  outgoing  message  in  a  non-relay application, in which case diameter provides
             appropriate values.

           avps = [avp()] | undefined:
             The AVPs of the message. Ignored for an outgoing message if the msg field is set  to
             a value other than undefined.

           msg = message() | undefined:
             The  incoming/outgoing message. For an incoming message, a record if the message can
             be decoded in a non-relay application, undefined otherwise. For an outgoing message,
             setting  a  [header()  |  avp()]  list  is equivalent to setting the header and avps
             fields to the corresponding values.

       Warning:
           A record-valued msg field does not  imply an absence  of  decode  errors.  The  errors
           field should also be examined.

           bin = binary():
             The incoming message prior to encode or the outgoing message after encode.

           errors = [5000..5999 | {5000..5999, avp()}]:
             Errors  detected  at decode of an incoming message, as identified by a corresponding
             5xxx series Result-Code (Permanent Failures). For an incoming request, these  should
             be  used  to  formulate an appropriate answer as documented for the handle_request/3
             callback    in    diameter_app(3erl).    For     an     incoming     answer,     the
             diameter:application_opt() answer_errors determines the behaviour.

           transport_data = term():
             An  arbitrary  term  of  meaning  only  to  the  transport  process  in question, as
             documented in diameter_transport(3erl).

EXPORTS

       decode(Mod, Bin) -> Pkt

              Types:

                 Mod = dictionary()
                 Bin = binary()
                 Pkt = packet()

              Decode a Diameter message.

       encode(Mod, Msg) -> Pkt

              Types:

                 Mod = dictionary()
                 Msg = message() | packet()
                 Pkt = packet()

              Encode a Diameter message.

SEE ALSO

       diameterc(1), diameter_app(3erl), diameter_dict(5), diameter_make(3erl)