<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>diameter_sctp(3)</title>
<prepared>Anders Svensson</prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev></rev>
<file>diameter_sctp.xml</file>
</header>
<module>diameter_sctp</module>
<modulesummary>Diameter transport over SCTP.</modulesummary>
<description>
<p>
This module implements diameter transport over SCTP using gen_sctp.
It can be specified as the value of a transport_module option to
<seealso
marker="diameter#add_transport">diameter:add_transport/2</seealso>
and implements the behaviour documented in
<seealso marker="diameter_transport">diameter_transport(3)</seealso>.</p>
<marker id="start"/>
</description>
<!-- ===================================================================== -->
<funcs>
<func>
<name>start({Type, Ref}, Svc, [Opt])
-> {ok, Pid, [LAddr]} | {error, Reason}</name>
<fsummary>Start a transport process.</fsummary>
<type>
<v>Type = connect | accept</v>
<v>Ref = reference()</v>
<v>Svc = #diameter_service{}</v>
<v>Opt = {raddr, ip_address()} | {rport, integer()} | term()</v>
<v>Pid = pid()</v>
<v>LAddr = ip_address()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>
The start function required by <seealso
marker="diameter_transport#start">diameter_transport(3)</seealso>.</p>
<p>
The only diameter_sctp-specific argument is the options list.
Options <c>raddr</c> and <c>rport</c> specify the remote address
and port for a connector and not valid for a listener.
The former is required while latter defaults to 3868 if unspecified.
More than one <c>raddr</c> option can be specified, in which case the
connector in question attempts each in sequence until an association
is established.
Remaining options are any accepted by gen_sctp:open/1, with the exception
of options <c>mode</c>, <c>binary</c>, <c>list</c>, <c>active</c>
and <c>sctp_events</c>.
Note that options <c>ip</c> and <c>port</c> specify the local address
and port respectively.</p>
<p>
Multiple <c>ip</c> options can be specified for a multihomed peer.
If none are specified then the values of Host-IP-Address
on the service are used. (In particular, one of these must be specified.)
Option <c>port</c> defaults to 3868 for a listener and 0 for a connector.</p>
<p>
diameter_sctp uses the <c>transport_data</c> field of
the <c>diameter_packet</c> record to communicate the stream on which an
inbound message has been received, or on which an outbound message
should be sent: the value will be of the form <c>{stream, Id}</c>
on an inbound message passed to a <seealso
marker="diameter_app#handle_request">handle_request</seealso> or <seealso
marker="diameter_app#handle_answer">handle_answer</seealso> callback.
For an outbound message, either <c>undefined</c> (explicitly of
by specifying the outbound message as a <c>binary()</c>) or a tuple
should be set in the return value of <seealso
marker="diameter_app#handle_request">handle_request</seealso>
(typically by retaining the value passed into this function)
or <seealso
marker="diameter_app#prepare_request">prepare_request</seealso>.
The value <c>undefined</c> uses a "next outbound stream" id and then
increments this modulo the total number outbound streams. That
is, successive values of <c>undefined</c> cycle through all outbound
streams.</p>
<!-- TODO: Some way of getting at the number of available outbound -->
<!-- streams. -->
</desc>
</func>
</funcs>
<!-- ===================================================================== -->
<!-- ===================================================================== -->
<section>
<title>SEE ALSO</title>
<p>
<seealso marker="diameter_transport">diameter_transport(3)</seealso></p>
</section>
</erlref>
