.TH diameter_tcp 3erl "diameter 2.2.7.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
diameter_tcp \- Diameter transport over TCP.
.SH DESCRIPTION
.LP
This module implements diameter transport over TCP using gen_tcp(3erl)\&. It can be specified as the value of a \fItransport_module\fR\& 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\&.
.LP
Note that the ssl application is required for TLS and must be started before configuring TLS capability on diameter transports\&.
.SH EXPORTS
.LP
.B
start({Type, Ref}, Svc, [Opt]) -> {ok, Pid} | {ok, Pid, [LAddr]} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Type = connect | accept
.br
Ref = diameter:transport_ref()
.br
Svc = #diameter_service{}
.br
Opt = OwnOpt | SslOpt | TcpOpt
.br
Pid = pid()
.br
LAddr = inet:ip_address()
.br
Reason = term()
.br
OwnOpt = {raddr, inet:ip_address()} | {rport, integer()} | {accept, Match} | {port, integer()} | {fragment_timer, infinity | 0\&.\&.16#FFFFFFFF} | {message_cb, diameter:eval()} | {sender, boolean()}
.br
SslOpt = {ssl_options, true | list()}
.br
TcpOpt = term()
.br
Match = inet:ip_address() | string() | [Match]
.br
.RE
.RE
.RS
.LP
The start function required by diameter_transport(3erl)\&.
.LP
Options \fIraddr\fR\& and \fIrport\fR\& specify the remote address and port for a connecting transport and are not valid for a listening transport\&.
.LP
Option \fIaccept\fR\& 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 \fIaccept\fR\& options can be specified\&. A string-valued \fIMatch\fR\& that does not parse as an address is interpreted as a regular expression\&.
.LP
Option \fIssl_options\fR\& must be specified for a transport that should support TLS: a value of \fItrue\fR\& results in a TLS handshake immediately upon connection establishment while \fIlist()\fR\& specifies options to be passed to ssl:connect/2 or ssl:handshake/2 after capabilities exchange if TLS is negotiated\&.
.LP
Option \fIfragment_timer\fR\& 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\&.
.LP
Option \fIsender\fR\& specifies whether or not to use a dedicated process for sending outgoing messages, which avoids the possibility of send blocking reception\&. Defaults to \fIfalse\fR\&\&. If set to \fItrue\fR\& then a \fImessage_cb\fR\& that avoids the possibility of messages being queued in the sender process without bound should be configured\&.
.LP
Option \fImessage_cb\fR\& specifies a callback that is invoked on incoming and outgoing messages, that can be used to implement flow control\&. It is applied to two arguments: an atom indicating the reason for the callback (\fIsend\fR\&, \fIrecv\fR\&, or \fIack\fR\& after a completed send), and the message in question (binary() on \fIrecv\fR\&, binary() or diameter_packet record on \fIsend\fR\& or \fIack\fR\&, or \fIfalse\fR\& on \fIack\fR\& when an incoming request has been discarded)\&. It should return a list of actions and a new callback as tail; eg\&. \fI[fun cb/3, State]\fR\&\&. Valid actions are the atoms \fIsend\fR\& or \fIrecv\fR\&, to cause a following message-valued action to be sent/received, a message to send/receive (binary() or diameter_packet record), or a boolean() to enable/disable reading on the socket\&. More than one \fIsend\fR\&/\fIrecv\fR\&/message sequence can be returned from the same callback, and an initial \fIsend\fR\&/\fIrecv\fR\& can be omitted if the same as the value passed as the callback\&'s first argument\&. Reading is initially enabled, and returning \fIfalse\fR\& does not imply there cannot be subsequent \fIrecv\fR\& callbacks since messages may already have been read\&. An empty tail is equivalent to the prevailing callback\&. Defaults to a callback equivalent to \fIfun(ack, _) -> []; (_, Msg) -> [Msg] end\fR\&\&.
.LP
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 \fI{ssl_options, true}\fR\& has been specified\&. Options \fIbinary\fR\&, \fIpacket\fR\& and \fIactive\fR\& cannot be specified\&. Also, option \fIport\fR\& can be specified for a listening transport to specify the local listening port, the default being the standardized 3868\&. Note that the option \fIip\fR\& specifies the local address\&.
.LP
An \fIssl_options\fR\& list must be specified if and only if the transport in question has set \fIInband-Security-Id\fR\& to 1 (\fITLS\fR\&), 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 \fIssl_options\fR\& 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\&.
.LP
The first element of a non-empty \fIHost-IP-Address\fR\& list in \fISvc\fR\& provides the local IP address if an \fIip\fR\& option is not specified\&. The local address is either returned fromstart/3 or passed in a \fIconnected\fR\& message over the transport interface\&.
.RE

.SH "SEE ALSO"

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