NAME

       diameter_tcp - Diameter transport over TCP.

DESCRIPTION

       This  module  implements  diameter  transport  over  TCP  using  gen_tcp(3erl).  It can be
       specified as the value  of  a  transport_module  option  to  diameter:add_transport/2  and
       implements   the   behaviour  documented  in  diameter_transport(3erl).  TLS  security  is
       supported,  either  as  an  upgrade  following  capabilities  exchange  or  at  connection
       establishment.

       Note  that  the ssl application is required for TLS and must be started before configuring
       TLS capability on diameter transports.

EXPORTS

       start({Type, Ref}, Svc, [Opt]) -> {ok, Pid} | {ok, Pid, [LAddr]} | {error, Reason}

              Types:

                 Type = connect | accept
                 Ref = diameter:transport_ref()
                 Svc = #diameter_service{}
                 Opt = OwnOpt | SslOpt | TcpOpt
                 Pid = pid()
                 LAddr = inet:ip_address()
                 Reason = term()
                 OwnOpt = {raddr, inet:ip_address()} | {rport, integer()}  |  {accept,  Match}  |
                 {port, integer()} | {fragment_timer, infinity | 0..16#FFFFFFFF}
                 SslOpt = {ssl_options, true | list()}
                 TcpOpt = term()
                 Match = inet:ip_address() | string() | [Match]

              The start function required by diameter_transport(3erl).

              Options  raddr  and  rport  specify  the  remote  address and port for a connecting
              transport and are not valid for a listening transport.

              Option accept specifies remote addresses for a listening transport and is not valid
              for  a connecting transport. If specified, a remote address that does not match one
              of the specified addresses causes the connection to  be  aborted.  Multiple  accept
              options  can  be specified. A string-valued Match that does not parse as an address
              is interpreted as a regular expression.

              Option ssl_options must be specified for a transport that  should  support  TLS:  a
              value  of true results in a TLS handshake immediately upon connection establishment
              while list() specifies options to be passed to  ssl:connect/2  or  ssl:ssl_accept/2
              after capabilities exchange if TLS is negotiated.

              Option  fragment_timer  specifies  the timeout, in milliseconds, of a timer used to
              flush messages from the incoming byte stream even if the number of bytes  indicated
              in  the  Message Length field of its Diameter Header have not yet been accumulated:
              such a message is received  over  the  transport  interface  after  two  successive
              timeouts without the reception of additional bytes. Defaults to 1000.

              Remaining  options  are  any  accepted  by ssl:connect/3 or gen_tcp:connect/3 for a
              connecting  transport,  or  ssl:listen/2  or  gen_tcp:listen/2  for   a   listening
              transport,  depending  on  whether  or  not {ssl_options, true} has been specified.
              Options binary, packet and active cannot be specified. Also,  option  port  can  be
              specified  for  a  listening  transport  to  specify  the local listening port, the
              default being the standardized  3868  if  unspecified.  Note  that  the  option  ip
              specifies the local address.

              An  ssl_options list must be specified if and only if the transport in question has
              set Inband-Security-Id to 1 (TLS), as specified to either  diameter:start_service/2
              or   diameter:add_transport/2,   so   that   the  transport  process  will  receive
              notification of  whether  or  not  to  commence  with  a  TLS  handshake  following
              capabilities  exchange.  Failing  to  specify  an  options  list  on  a TLS-capable
              transport for which TLS is negotiated will cause TLS handshake to fail. Failing  to
              specify TLS capability when ssl_options has been specified will cause the transport
              process to wait for a  notification  that  will  not  be  forthcoming,  which  will
              eventually cause the RFC 3539 watchdog to take down the connection.

              If  an  ip  option  is not specified then the first element of a non-empty Host-IP-
              Address list in Svc provides the local IP address. If neither is specified then the
              default  address  selected  by  gen_tcp(3erl)  is  used. In all cases, the selected
              address is either returned from start/3 or passed in a connected message  over  the
              transport interface.

SEE ALSO

       diameter(3erl), diameter_transport(3erl), gen_tcp(3erl), inet(3erl), ssl(3erl)