.TH diameter_transport 3erl "diameter 1.12.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
diameter_transport \- Diameter transport interface.
.SH DESCRIPTION
.LP
A module specified as a \fItransport_module\fR\& to \fBdiameter:add_transport/2\fR\& 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() | \fBdiameter_codec:packet()\fR\&\fR\&:
A Diameter message as passed over the transport interface\&.
.RS 2
.LP
For an inbound message from a transport process, a \fBdiameter_codec:packet()\fR\& 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 \fBdiameter_codec:packet()\fR\& 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 = \fBdiameter:transport_ref()\fR\&
.br
Svc = #diameter_service{}
.br
Config = term()
.br
Pid = pid()
.br
LAddrs = [\fBinet:ip_address()\fR\&]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Start a transport process\&. Called by diameter as a consequence of a call to \fBdiameter:add_transport/2\fR\& 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 \fBdiameter:add_transport/2\fR\& that has lead to starting of a transport process\&.
.LP
\fISvc\fR\& contains capabilities passed to \fBdiameter:start_service/2\fR\& and \fBdiameter:add_transport/2\fR\&, values passed to the latter overriding those passed to the former\&.
.LP
\fIConfig\fR\& is as passed in \fItransport_config\fR\& tuple in the \fBdiameter:transport_opt()\fR\& list passed to \fBdiameter:add_transport/2\fR\&\&.
.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 \fBMESSAGES\fR\& 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, \fBmessage()\fR\&}}\fR\&:
An outbound Diameter message\&.
.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 \fBstart/3\fR\&\&.
.TP 2
.B
\fI{diameter, {recv, \fBmessage()\fR\&}}\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
\fBdiameter_tcp(3erl)\fR\&, \fBdiameter_sctp(3erl)\fR\&