.TH diameter_transport 3erl "diameter 2.2.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
diameter_transport \- Diameter transport interface.
.SH DESCRIPTION
.LP
A module specified as a \fItransport_module\fR\& 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)\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
\fImessage() = binary() | diameter_codec:packet()\fR\&:
A Diameter message as passed over the transport interface\&.
.RS 2
.LP
For an inbound message from a transport process, a diameter_codec:packet() must contain the received message in its \fIbin\fR\& field\&. In the case of an inbound request, any value set in the \fItransport_data\fR\& field will passed back to the transport module in the corresponding answer message, unless the sender supplies another value\&.
.RE

.RS 2
.LP
For an outbound message to a transport process, a diameter_codec:packet() has a value other than \fIundefined\fR\& in its \fItransport_data\fR\& field and has the binary() to send in its \fIbin\fR\& field\&.
.RE

.RE
.SH EXPORTS
.LP
.B
Mod:start({Type, Ref}, Svc, Config) -> {ok, Pid} | {ok, Pid, LAddrs} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Type = connect | accept
.br
Ref = diameter:transport_ref()
.br
Svc = #diameter_service{}
.br
Config = term()
.br
Pid = pid()
.br
LAddrs = [inet:ip_address()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
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\&.
.LP
\fIType\fR\& indicates whether the transport process in question is being started for a connecting (\fIType=connect\fR\&) or listening (\fIType=accept\fR\&) transport\&. In the latter case, transport processes are started as required to accept connections from multiple peers\&.
.LP
Ref is the value that was returned from the call to diameter:add_transport/2 that has lead to starting of a transport process\&.
.LP
\fISvc\fR\& contains capabilities passed to diameter:start_service/2 and diameter:add_transport/2, values passed to the latter overriding those passed to the former\&.
.LP
\fIConfig\fR\& is as passed in \fItransport_config\fR\& tuple in the diameter:transport_opt() list passed to diameter:add_transport/2\&.
.LP
The start function should use the \fIHost-IP-Address\fR\& list in \fISvc\fR\& and/or \fIConfig\fR\& 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 \fIconnected\fR\& message (see MESSAGES below) following connection establishment\&. In either case, the local address list is used to populate \fIHost-IP-Address\fR\& AVPs in outgoing capabilities exchange messages if \fIHost-IP-Address\fR\& is unspecified\&.
.LP
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\&.
.RE

.SH "MESSAGES"

.LP
All messages sent over the transport interface are of the form \fI{diameter, term()}\fR\&\&.
.LP
A transport process can expect messages of the following types from its parent\&.
.RS 2
.TP 2
.B
\fI{diameter, {send, message() | false}}\fR\&:
An outbound Diameter message\&. The atom \fIfalse\fR\& can only be received when request acknowledgements have been requests: see the \fIack\fR\& message below\&.
.TP 2
.B
\fI{diameter, {close, Pid}}\fR\&:
A request to terminate the transport process after having received DPA in response to DPR\&. The transport process should exit\&. \fIPid\fR\& is the pid() of the parent process\&.
.TP 2
.B
\fI{diameter, {tls, Ref, Type, Bool}}\fR\&:
Indication of whether or not capabilities exchange has selected inband security using TLS\&. \fIRef\fR\& is a reference() that must be included in the \fI{diameter, {tls, Ref}}\fR\& reply message to the transport\&'s parent process (see below)\&. \fIType\fR\& is either \fIconnect\fR\& or \fIaccept\fR\& depending on whether the process has been started for a connecting or listening transport respectively\&. \fIBool\fR\& is a boolean() indicating whether or not the transport connection should be upgraded to TLS\&.
.RS 2
.LP
If TLS is requested (\fIBool=true\fR\&) 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 \fI{diameter, {tls, Ref}}\fR\& message to the parent process\&. A failed handshake should cause the process to exit\&.
.RE

.RS 2
.LP
This message is only sent to a transport process over whose \fIInband-Security-Id\fR\& configuration has indicated support for TLS\&.
.RE

.RE
.LP
A transport process should send messages of the following types to its parent\&.
.RS 2
.TP 2
.B
\fI{diameter, {self(), connected}}\fR\&:
Inform the parent that the transport process with \fIType=accept\fR\& has established a connection with the peer\&. Not sent if the transport process has \fIType=connect\fR\&\&.
.TP 2
.B
\fI{diameter, {self(), connected, Remote}}\fR\&:

.TP 2
.B
\fI{diameter, {self(), connected, Remote, [LocalAddr]}}\fR\&:
Inform the parent that the transport process with \fIType=connect\fR\& has established a connection with a peer\&. Not sent if the transport process has \fIType=accept\fR\&\&. \fIRemote\fR\& is an arbitrary term that uniquely identifies the remote endpoint to which the transport has connected\&. A \fILocalAddr\fR\& list has the same semantics as one returned from start/3\&.
.TP 2
.B
\fI{diameter, ack}\fR\&:
Request acknowledgements of unanswered requests\&. A transport process should send this once before passing incoming Diameter messages into diameter\&. As a result, every Diameter request passed into diameter with a \fIrecv\fR\& message (below) will be answered with a \fIsend\fR\& message (above), either a message() for the transport process to send or the atom \fIfalse\fR\& if the request has been discarded or otherwise not answered\&.
.RS 2
.LP
This is to allow a transport process to keep count of the number of incoming request messages that have not yet been answered or discarded, to allow it to regulate the amount of incoming traffic\&. Both diameter_tcp and diameter_sctp request acknowledgements when a \fImessage_cb\fR\& is configured, turning send/recv message into callbacks that can be used to regulate traffic\&.
.RE

.TP 2
.B
\fI{diameter, {recv, message()}}\fR\&:
An inbound Diameter message\&.
.TP 2
.B
\fI{diameter, {tls, Ref}}\fR\&:
Acknowledgment of a successful TLS handshake\&. \fIRef\fR\& is the reference() received in the \fI{diameter, {tls, Ref, Type, Bool}}\fR\& message in response to which the reply is sent\&. A transport must exit if a handshake is not successful\&.
.RE
.SH "SEE ALSO"

.LP
diameter_tcp(3erl), diameter_sctp(3erl)