Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
diameter_codec(3)	   Erlang Module Definition	     diameter_codec(3)

NAME
       diameter_codec -	Decode and encode of Diameter messages.

DESCRIPTION
       Incoming	 Diameter messages are decoded from binary() before being com-
       municated to diameter_app(3) callbacks.	Similarly,  outgoing  Diameter
       messages	are encoded into binary() before being passed to the appropri-
       ate diameter_transport(3) module	for transmission. The functions	 docu-
       mented here implement the default encode/decode.

   Warning:
       The  diameter user does not need	to call	functions here explicitly when
       sending and receiving messages using diameter:call/4 and	 the  callback
       interface  documented  in diameter_app(3): diameter itself provides en-
       code/decode  as	a  consequence	of  configuration  passed  to	diame-
       ter:start_service/2,  and the results may differ	from those returned by
       the functions documented	here, depending	on configuration.

       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 in-
	   tended 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	 unde-
	     fined 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 ques-
	     tion, 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, the AVP is unknown,  or  if  the
	     decode format is none. The	type of	a decoded value	is as document
	     in	diameter_dict(4).

	   type	= atom():
	     The type of the AVP as specified in the dictionary	file in	 ques-
	     tion  (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  QoS-
	     FilterRule.

	 dictionary() =	module():
	   The	name  of  a generated dictionary module	as generated by	diame-
	   terc(1) or diameter_make:codec/2. The interface provided by a  dic-
	   tionary 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  mes-
	 sages	as  diameter itself will set appropriate values. Setting inap-
	 propriate 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() |	maybe_improper_list():
	   The representation of  a  Diameter  message	as  passed  to	diame-
	   ter:call/4 or returned from a handle_request/3 callback. The	record
	   representation is as	outlined in diameter_dict(4): a	message	as de-
	   fined  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 either a list of
	   AVP	name/values pairs or a map with	values keyed on	AVP names. The
	   format  at  decode  is  determined  by  diameter:service_opt()  de-
	   code_format.	Any of the formats is accepted at encode.

	   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 re-
	   quests as directed by the return value of a handle_request/3	 call-
	   back.  It differs from the other two	in that	it bypasses the	checks
	   for messages	that do	not agree with their definitions in  the  dic-
	   tionary 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 term
	     corresponding to the configured decode format if the message  can
	     be	 decoded  in a non-relay application, undefined	otherwise. For
	     an	outgoing message, setting a [header() |	avp()] list is equiva-
	     lent  to  setting the header and avps fields to the corresponding
	     values.

       Warning:
	   A value in the msg field does not imply an absence  of  decode  er-
	   rors. The errors field should also be examined.

	   bin = binary():
	     The  incoming message prior to encode or the outgoing message af-
	     ter 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 ap-
	     propriate	answer as documented for the handle_request/3 callback
	     in	diameter_app(3). For an	incoming answer, the diameter:applica-
	     tion_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(3).

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(3), diameter_dict(4),	diameter_make(3)

Ericsson AB			 diameter 2.2		     diameter_codec(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=diameter_codec&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help