NAME

       diameter_transport - Diameter transport interface.

DESCRIPTION

       A  module  specified  as a transport_module to diameter:add_transport/2 must implement the
       interface documented here. The interface consists of a function with which diameter starts
       a  transport process and a message interface with which the transport process communicates
       with the process that starts it (aka its parent).

DATA TYPES

         message() = binary() | diameter_codec:packet():
           A Diameter message as passed over the transport interface.

           For an inbound message  from  a  transport  process,  a  diameter_codec:packet()  must
           contain  the received message in its bin field. In the case of an inbound request, any
           value set in the transport_data field will passed back to the transport module in  the
           corresponding answer message, unless the sender supplies another value.

           For  an outbound message to a transport process, a diameter_codec:packet() has a value
           other than undefined in its transport_data field and has the binary() to send  in  its
           bin field.

EXPORTS

       Mod:start({Type, Ref}, Svc, Config) -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}

              Types:

                 Type = connect | accept
                 Ref = diameter:transport_ref()
                 Svc = #diameter_service{}
                 Config = term()
                 Pid = pid()
                 LAddrs = [inet:ip_address()]
                 Reason = term()

              Start  a  transport  process.  Called  by  diameter  as  a consequence of a call to
              diameter:add_transport/2 in order to establish or  accept  a  transport  connection
              respectively. A transport process maintains a connection with a single remote peer.

              Type  indicates  whether  the  transport process in question is being started for a
              connecting (Type=connect) or listening (Type=accept) transport. In the latter case,
              transport  processes  are  started  as required to accept connections from multiple
              peers.

              Ref is the value that was returned from the call to  diameter:add_transport/2  that
              has lead to starting of a transport process.

              Svc     contains    capabilities    passed    to    diameter:start_service/2    and
              diameter:add_transport/2, values passed to the latter overriding  those  passed  to
              the former.

              Config  is as passed in transport_config tuple in the diameter:transport_opt() list
              passed to diameter:add_transport/2.

              The start function should use the Host-IP-Address list  in  Svc  and/or  Config  to
              select  and  return  an  appropriate  list of local IP addresses. In the connecting
              case, the local address list can instead be communicated  in  a  connected  message
              (see  MESSAGES below) following connection establishment. In either case, the local
              address list is used to populate  Host-IP-Address  AVPs  in  outgoing  capabilities
              exchange messages if Host-IP-Address is unspecified.

              A  transport  process  must  implement  the  message interface documented below. It
              should retain the pid of its parent, monitor the parent and terminate if  it  dies.
              It  should  not link to the parent. It should exit if its transport connection with
              its peer is lost.

MESSAGES

       All messages sent over the transport interface are of the form {diameter, term()}.

       A transport process can expect messages of the following types from its parent.

         {diameter, {send, message()}}:
           An outbound Diameter message.

         {diameter, {close, Pid}}:
           A request to terminate the transport process after having received DPA in response  to
           DPR. The transport process should exit. Pid is the pid() of the parent process.

         {diameter, {tls, Ref, Type, Bool}}:
           Indication  of whether or not capabilities exchange has selected inband security using
           TLS. Ref is a reference() that must be included in the {diameter,  {tls,  Ref}}  reply
           message  to  the  transport's  parent  process  (see below). Type is either connect or
           accept depending on whether the process has been started for a connecting or listening
           transport  respectively.  Bool  is a boolean() indicating whether or not the transport
           connection should be upgraded to TLS.

           If TLS is requested (Bool=true) then  a  connecting  process  should  initiate  a  TLS
           handshake with the peer and an accepting process should prepare to accept a handshake.
           A successful handshake should be followed by a {diameter, {tls, Ref}} message  to  the
           parent process. A failed handshake should cause the process to exit.

           This  message  is  only  sent  to  a  transport  process over whose Inband-Security-Id
           configuration has indicated support for TLS.

       A transport process should send messages of the following types to its parent.

         {diameter, {self(), connected}}:
           Inform the parent that the  transport  process  with  Type=accept  has  established  a
           connection with the peer. Not sent if the transport process has Type=connect.

         {diameter, {self(), connected, Remote}}:

         {diameter, {self(), connected, Remote, [LocalAddr]}}:
           Inform  the  parent  that  the  transport  process with Type=connect has established a
           connection with a peer. Not sent if the transport process has Type=accept.  Remote  is
           an  arbitrary term that uniquely identifies the remote endpoint to which the transport
           has connected. A LocalAddr list has the same semantics as one returned from start/3.

         {diameter, {recv, message()}}:
           An inbound Diameter message.

         {diameter, {tls, Ref}}:
           Acknowledgment of a successful TLS handshake. Ref is the reference() received  in  the
           {diameter,  {tls,  Ref, Type, Bool}} message in response to which the reply is sent. A
           transport must exit if a handshake is not successful.

SEE ALSO

       diameter_tcp(3erl), diameter_sctp(3erl)