<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- diameter_transport(3)</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/diameter-1.3.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Diameter</strong><br><strong>Reference Manual</strong><br><small>Version 1.3</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p>
<ul class="flipMenu">
<li id="no" title="diameter " expanded="false">diameter<ul>
<li><a href="diameter.html">
Top of manual page
</a></li>
<li title="add_transport-2"><a href="diameter.html#add_transport-2">add_transport/2</a></li>
<li title="call-4"><a href="diameter.html#call-4">call/4</a></li>
<li title="origin_state_id-0"><a href="diameter.html#origin_state_id-0">origin_state_id/0</a></li>
<li title="remove_transport-2"><a href="diameter.html#remove_transport-2">remove_transport/2</a></li>
<li title="service_info-2"><a href="diameter.html#service_info-2">service_info/2</a></li>
<li title="services-0"><a href="diameter.html#services-0">services/0</a></li>
<li title="session_id-1"><a href="diameter.html#session_id-1">session_id/1</a></li>
<li title="start-0"><a href="diameter.html#start-0">start/0</a></li>
<li title="start_service-2"><a href="diameter.html#start_service-2">start_service/2</a></li>
<li title="stop-0"><a href="diameter.html#stop-0">stop/0</a></li>
<li title="stop_service-1"><a href="diameter.html#stop_service-1">stop_service/1</a></li>
<li title="subscribe-1"><a href="diameter.html#subscribe-1">subscribe/1</a></li>
<li title="unsubscribe-1"><a href="diameter.html#unsubscribe-1">unsubscribe/1</a></li>
</ul>
</li>
<li title="diameterc"><a href="diameterc.html">diameterc</a></li>
<li id="no" title="diameter_app " expanded="false">diameter_app<ul>
<li><a href="diameter_app.html">
Top of manual page
</a></li>
<li title="Mod:peer_up-3"><a href="diameter_app.html#Mod:peer_up-3">Mod:peer_up/3</a></li>
<li title="Mod:peer_down-3"><a href="diameter_app.html#Mod:peer_down-3">Mod:peer_down/3</a></li>
<li title="Mod:pick_peer-4"><a href="diameter_app.html#Mod:pick_peer-4">Mod:pick_peer/4</a></li>
<li title="Mod:prepare_request-3"><a href="diameter_app.html#Mod:prepare_request-3">Mod:prepare_request/3</a></li>
<li title="Mod:prepare_retransmit-3"><a href="diameter_app.html#Mod:prepare_retransmit-3">Mod:prepare_retransmit/3</a></li>
<li title="Mod:handle_answer-4"><a href="diameter_app.html#Mod:handle_answer-4">Mod:handle_answer/4</a></li>
<li title="Mod:handle_error-4"><a href="diameter_app.html#Mod:handle_error-4">Mod:handle_error/4</a></li>
<li title="Mod:handle_request-3"><a href="diameter_app.html#Mod:handle_request-3">Mod:handle_request/3</a></li>
</ul>
</li>
<li id="no" title="diameter_codec " expanded="false">diameter_codec<ul>
<li><a href="diameter_codec.html">
Top of manual page
</a></li>
<li title="decode-2"><a href="diameter_codec.html#decode-2">decode/2</a></li>
<li title="encode-2"><a href="diameter_codec.html#encode-2">encode/2</a></li>
</ul>
</li>
<li title="diameter_dict"><a href="diameter_dict.html">diameter_dict</a></li>
<li id="no" title="diameter_make " expanded="false">diameter_make<ul>
<li><a href="diameter_make.html">
Top of manual page
</a></li>
<li title="codec-2"><a href="diameter_make.html#codec-2">codec/2</a></li>
</ul>
</li>
<li id="loadscrollpos" title="diameter_transport " expanded="true">diameter_transport<ul>
<li><a href="diameter_transport.html">
Top of manual page
</a></li>
<li title="Mod:start-3"><a href="diameter_transport.html#Mod:start-3">Mod:start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_tcp " expanded="false">diameter_tcp<ul>
<li><a href="diameter_tcp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_tcp.html#start-3">start/3</a></li>
</ul>
</li>
<li id="no" title="diameter_sctp " expanded="false">diameter_sctp<ul>
<li><a href="diameter_sctp.html">
Top of manual page
</a></li>
<li title="start-3"><a href="diameter_sctp.html#start-3">start/3</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>diameter_transport</h1></center>
<h3>MODULE</h3>
<div class="REFBODY">diameter_transport</div>
<h3>MODULE SUMMARY</h3>
<div class="REFBODY">Diameter transport interface.</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>
A module specified as a <span class="code">transport_module</span> to <span class="bold_code"><a href="diameter.html#add_transport-2">diameter:add_transport/2</a></span>
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).</p>
</p></div>
<h3><a name="id77966">DATA TYPES</a></h3>
<div class="REFBODY">
<dl>
<a name="message"></a>
<dt><strong><span class="code">message() = binary() | <span class="bold_code"><a href="diameter_codec.html#packet">diameter_codec:packet()</a></span></span></strong></dt>
<dd>
<p>
A Diameter message as passed over the transport interface.</p>
<p>
For an inbound message from a transport process, a <span class="bold_code"><a href="diameter_codec.html#packet">diameter_codec:packet()</a></span> must
contain the received message in its <span class="code">bin</span> field.
In the case of an inbound request, any value set in the
<span class="code">transport_data</span> field will passed back to the transport module
in the corresponding answer message, unless the sender supplies
another value.</p>
<p>
For an outbound message to a transport process, a <span class="bold_code"><a href="diameter_codec.html#packet">diameter_codec:packet()</a></span> has a
value other than <span class="code">undefined</span> in its <span class="code">transport_data</span> field
and has the binary() to send in its <span class="code">bin</span> field.</p>
</dd>
</dl>
</div>
<h3>EXPORTS</h3>
<p><a name="Mod:start-3"><span class="bold_code">Mod:start({Type, Ref}, Svc, Config)
-> {ok, Pid}
| {ok, Pid, LAddrs}
| {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Type = connect | accept</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Ref = <span class="bold_code"><a href="diameter.html#transport_ref">diameter:transport_ref()</a></span></span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Svc = #diameter_service{}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Config = term()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Pid = pid()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">LAddrs = [<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','kernel','inet.html#type-ip_address');">inet:ip_address()</a></span>]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>
Start a transport process.
Called by diameter as a consequence of a call to <span class="bold_code"><a href="diameter.html#add_transport-2">diameter:add_transport/2</a></span> in
order to establish or accept a transport connection respectively.
A transport process maintains a connection with a single remote peer.</p>
<p>
<span class="code">Type</span> indicates whether the transport process in question
is being started for a connecting (<span class="code">Type=connect</span>) or listening
(<span class="code">Type=accept</span>) transport.
In the latter case, transport processes are started as required to
accept connections from multiple peers.</p>
<p>
Ref is the value that was returned from the call to <span class="bold_code"><a href="diameter.html#add_transport-2">diameter:add_transport/2</a></span>
that has lead to starting of a transport process.</p>
<p>
<span class="code">Svc</span> contains the capabilities passed to <span class="bold_code"><a href="diameter.html#start_service-2">diameter:start_service/2</a></span> and
<span class="bold_code"><a href="diameter.html#add_transport-2">diameter:add_transport/2</a></span>, values passed to the latter overriding those
passed to the former.</p>
<p>
<span class="code">Config</span> is as passed in <span class="code">transport_config</span> tuple in the
<span class="bold_code"><a href="diameter.html#transport_opt">diameter:transport_opt()</a></span> list passed to <span class="bold_code"><a href="diameter.html#add_transport-2">diameter:add_transport/2</a></span>.</p>
<p>
The start function should use the <span class="code">Host-IP-Address</span> list and/or
<span class="code">Config</span> to select an appropriate list of local IP addresses,
and should return this list if different from the
<span class="code">#diameter_service{}</span> addresses.
The returned list is used to populate <span class="code">Host-IP-Address</span> AVPs in
outgoing capabilities exchange messages, the
<span class="code">#diameter_service{}</span> addresses being used otherwise.</p>
<p>
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.</p>
</p></div>
<a name="MESSAGES"></a>
<h3><a name="id78224">MESSAGES</a></h3>
<div class="REFBODY">
<p>
All messages sent over the transport interface are of the
form <span class="code">{diameter, term()}</span>.</p>
<p>
A transport process can expect messages of the following types from
its parent.</p>
<dl>
<dt><strong><span class="code">{diameter, {send, <span class="bold_code"><a href="#message">message()</a></span>}}</span></strong></dt>
<dd>
<p>
An outbound Diameter message.</p>
</dd>
<dt><strong><span class="code">{diameter, {close, Pid}}</span></strong></dt>
<dd>
<p>
A request to terminate the transport process after having received DPA
in response to DPR.
The transport process should exit.
<span class="code">Pid</span> is the pid() of the parent process.</p>
</dd>
<dt><strong><span class="code">{diameter, {tls, Ref, Type, Bool}}</span></strong></dt>
<dd>
<p>
Indication of whether or not capabilities exchange has selected
inband security using TLS.
<span class="code">Ref</span> is a reference() that must be included in the
<span class="code">{diameter, {tls, Ref}}</span> reply message to the transport's
parent process (see below).
<span class="code">Type</span> is either <span class="code">connect</span> or <span class="code">accept</span> depending on
whether the process has been started for a connecting or listening
transport respectively.
<span class="code">Bool</span> is a boolean() indicating whether or not the transport
connection should be upgraded to TLS.</p>
<p>
If TLS is requested (<span class="code">Bool=true</span>) 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 <span class="code">{diameter, {tls, Ref}}</span>
message to the parent process.
A failed handshake should cause the process to exit.</p>
<p>
This message is only sent to a transport process over whose
<span class="code">Inband-Security-Id</span> configuration has indicated support for
TLS.</p>
</dd>
</dl>
<p>
A transport process should send messages of the following types
to its parent.</p>
<dl>
<dt><strong><span class="code">{diameter, {self(), connected}}</span></strong></dt>
<dd>
<p>
Inform the parent that the transport process with <span class="code">Type=accept</span> has
established a connection with the peer.
Not sent if the transport process has <span class="code">Type=connect</span>.</p>
</dd>
<dt><strong><span class="code">{diameter, {self(), connected, Remote}}</span></strong></dt>
<dd>
<p>
Inform the parent that the transport process with <span class="code">Type=connect</span>
has established a connection with a peer.
Not sent if the transport process has <span class="code">Type=accept</span>.
<span class="code">Remote</span> is an arbitrary term that uniquely identifies the remote
endpoint to which the transport has connected.</p>
</dd>
<dt><strong><span class="code">{diameter, {recv, <span class="bold_code"><a href="#message">message()</a></span>}}</span></strong></dt>
<dd>
<p>
An inbound Diameter message.</p>
</dd>
<dt><strong><span class="code">{diameter, {tls, Ref}}</span></strong></dt>
<dd>
<p>
Acknowledgment of a successful TLS handshake.
<span class="code">Ref</span> is the reference() received in the
<span class="code">{diameter, {tls, Ref, Type, Bool}}</span> message in response
to which the reply is sent.
A transport must exit if a handshake is not successful.</p>
</dd>
</dl>
</div>
<h3><a name="id78441">SEE ALSO</a></h3>
<div class="REFBODY">
<p>
<span class="bold_code"><a href="diameter_tcp.html">diameter_tcp(3)</a></span>, <span class="bold_code"><a href="diameter_sctp.html">diameter_sctp(3)</a></span></p>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2011-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
