aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc')
-rw-r--r--lib/diameter/doc/src/diameter.xml457
-rw-r--r--lib/diameter/doc/src/diameter_app.xml13
-rw-r--r--lib/diameter/doc/src/diameter_transport.xml62
3 files changed, 241 insertions, 291 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index 2abfbff209..fdd18929df 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -43,8 +43,8 @@ under the License.
<description>
<p>
-This module provides the interface with which a user
-creates a service that sends and receives messages using the
+This module provides the interface with which a user can
+implement a Diameter node that sends and receives messages using the
Diameter protocol as defined in RFC 3588.</p>
<p>
@@ -61,17 +61,15 @@ marker="diameter_app">diameter_app(3)</seealso> callback modules as
specified in the service configuration.</p>
<p>
-Beware the difference between <em>diameter application</em> and
-<em>Diameter application</em>.
+Beware the difference between <em>diameter</em> (not capitalised) and
+<em>Diameter</em> (capitalised).
The former refers to the Erlang application named diameter whose main
-api is defined here, the latter to an application of the Diameter
-protocol in the sense of RFC 3588.
-More generally, capitalized Diameter refers to the RFC
-and diameter to this implementation.</p>
+api is defined here, the latter to Diameter protocol in the sense of
+RFC 3588.</p>
<p>
-The diameter application must be started before calling functions in
-this module.</p>
+The diameter application must be started before calling most functions
+in this module.</p>
</description>
@@ -100,10 +98,9 @@ Defined in <seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso>
<item>
<p>
A name identifying a Diameter application in
-service configuration passed to <seealso
-marker="#start_service">start_service/2</seealso> and passed to
-<seealso marker="#call">call/4</seealso> when sending requests
-belonging to the application.</p>
+service configuration.
+Passed to <seealso marker="#call">call/4</seealso> when sending requests
+defined by the application.</p>
<marker id="application_module"/>
</item>
@@ -121,19 +118,14 @@ ExtraArgs = list()
A module implementing the callback interface defined in <seealso
marker="diameter_app">diameter_app(3)</seealso>, along with any
extra arguments to be appended to those documented for the interface.
-Any extra arguments are appended to the documented list of arguments for
-each function.
-Note that additional arguments specific to an outgoing request be
+Note that extra arguments specific to an outgoing request can be
specified to <seealso marker="#call">call/4</seealso>, in which case
-the call-specific arguments are appended to any specified with the
-callback module.</p>
+those are are appended to any module-specific extra arguments.</p>
<p>
Specifying a <c>#diameter_callback{}</c> record allows individual
functions to be configured in place of the usual <seealso
-marker="diameter_app">diameter_app(3)</seealso> callbacks, with
-default implementations provided by module <c>diameter_callback</c>
-unless otherwise specified.
+marker="diameter_app">diameter_app(3)</seealso> callbacks.
See that module for details.</p>
<marker id="application_opt"/>
@@ -143,9 +135,8 @@ See that module for details.</p>
<item>
<p>
-Options defining a Diameter application as configured in an
-<c>application</c> option passed to
-<seealso marker="#start_service">start_service/2</seealso>.</p>
+Options defining a Diameter application.
+Has one the following types.</p>
<taglist>
@@ -154,7 +145,8 @@ Options defining a Diameter application as configured in an
<p>
An unique identifier for the application in the scope of the
service.
-Optional, defaults to the value of the <c>dictionary</c> option.</p>
+Defaults to the value of the <c>dictionary</c> option if
+unspecified.</p>
</item>
<tag><c>{dictionary, atom()}</c></tag>
@@ -170,20 +162,20 @@ marker="diameter_dict">diameter_dict(4)</seealso>.</p>
<tag><c>{module, <seealso marker="#application_module">application_module()</seealso>}</c></tag>
<item>
<p>
-A callback module with which messages of the Diameter application are
+The callback module with which messages of the Diameter application are
handled.
See <seealso marker="diameter_app">diameter_app(3)</seealso> for
-information on the required interface and semantics.</p>
+the required interface and semantics.</p>
</item>
<tag><c>{state, term()}</c></tag>
<item>
<p>
The initial callback state.
-Defaults to the value of the <c>alias</c> option if unspecified.
-The prevailing state is passed to certain
+The prevailing state is passed to some
<seealso marker="diameter_app">diameter_app(3)</seealso>
-callbacks, which can then return a new state.</p>
+callbacks, which can then return a new state.
+Defaults to the value of the <c>alias</c> option if unspecified.</p>
</item>
<tag><c>{call_mutates_state, true|false}</c></tag>
@@ -191,19 +183,18 @@ callbacks, which can then return a new state.</p>
<p>
Specifies whether or not the <seealso
marker="diameter_app#pick_peer">pick_peer/4</seealso>
-application callback (following from a call to
-<seealso marker="#call">call/4</seealso>)
-can modifiy state,
+application callback can modify the application state,
Defaults to <c>false</c> if unspecified.</p>
+<note>
<p>
-Note that <seealso
-marker="diameter_app#pick_peer">pick_peer</seealso> callbacks are
-serialized when these are allowed to modify state, which is a
+<seealso marker="diameter_app#pick_peer">pick_peer</seealso> callbacks
+are serialized when these are allowed to modify state, which is a
potential performance bottleneck.
A simple Diameter client may suffer no ill effects from using mutable
-state but a server or agent that responds to incoming request but
-sending its own requests should probably avoid it.</p>
+state but a server or agent that responds to incoming request should
+probably avoid it.</p>
+</note>
</item>
<tag><c>{answer_errors, callback|report|discard}</c></tag>
@@ -214,9 +205,9 @@ decode errors are handled.
If <c>callback</c> then errors result in a <seealso
marker="diameter_app#handle_answer">handle_answer/4</seealso>
callback in the same fashion as for <seealso
-marker="diameter_app#handle_request">handle_request/3</seealso>, in the
-<c>errors</c> field of the <c>diameter_packet</c> record passed into
-the callback.
+marker="diameter_app#handle_request">handle_request/3</seealso>, with
+errors communicated in the <c>errors</c> field of the
+<c>#diameter_packet{}</c> record passed to the callback.
If <c>report</c> then an answer containing errors is discarded
without a callback and a warning report is written to the log.
If <c>discard</c> then an answer containing errors is silently
@@ -240,7 +231,8 @@ Defaults to <c>report</c> if unspecified.</p>
<p>
Options available to <seealso marker="#call">call/4</seealso> when
-sending an outgoing Diameter request.</p>
+sending an outgoing Diameter request.
+Has one of the following types.</p>
<taglist>
@@ -249,7 +241,7 @@ sending an outgoing Diameter request.</p>
<p>
Extra arguments to append to callbacks to the callback
module in question.
-These are appended to any extra arguments configured with the callback
+These are appended to any extra arguments configured on the callback
itself.
Multiple options append to the argument list.</p>
</item>
@@ -299,120 +291,55 @@ to fail.</p>
<item>
<p>
-AVP values used in outgoing CER/CEA messages during capabilities exchange.
-Can be configured both on a service and a transport, the latter taking
-precedence over the former.</p>
+AVP values sent in outgoing CER or CEA messages during capabilities
+exchange.
+Can be configured both on a service and a transport, values specified
+on the latter taking precedence over any specified on the former.
+Has one of the following types.</p>
<taglist>
<tag><c>{'Origin-Host', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag>
-<item>
-<p>
-Value of the Origin-Host AVP in outgoing messages.</p>
-</item>
-
<tag><c>{'Origin-Realm', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag>
-<item>
-<p>
-Value of the Origin-Realm AVP in outgoing messages.</p>
-</item>
-
<tag><c>{'Host-IP-Address', [<seealso marker="diameter_dict#DATA_TYPES">Address()</seealso>]}</c></tag>
<item>
<p>
-Values of Host-IP-Address AVPs.
-Optional.</p>
-
-<p>
-The list of addresses is available to the start function of a
-transport module, which either uses them as is or returns a new list
-in order for the correct list of addresses to be sent in capabilities
-exchange messages.</p>
+An address list is available to the start function of a
+<seealso marker="diameter_transport">transport module</seealso>, which
+can return a new list for use in the subsequent CER or CEA.
+Host-IP-Address need not be specified if the transport start function
+returns an address list.</p>
</item>
<tag><c>{'Vendor-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
-<item>
-<p>
-Value of the Vendor-Id AVP sent in an outgoing capabilities
-exchange message.</p>
-</item>
-
<tag><c>{'Product-Name', <seealso marker="#UTF8String">UTF8String()</seealso>}</c></tag>
-<item>
-<p>
-Value of the Product-Name AVP sent in an outgoing capabilities
-exchange message.</p>
-</item>
-
<tag><c>{'Origin-State-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
<item>
<p>
-Value of Origin-State-Id to be included in outgoing messages sent by
-diameter itself.
-In particular, the AVP will be included in CER/CEA and DWR/DWA messages.
-Optional.</p>
-
-<p>
+Origin-State-Id is optional but will be included in outgoing messages
+sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA.
Setting a value of <c>0</c> (zero) is equivalent to not setting a
value as documented in RFC 3588.
The function <seealso
marker="#origin_state_id">origin_state_id/0</seealso>
-can be used as to retrieve a value that is set when the diameter
+can be used as to retrieve a value that is computed when the diameter
application is started.</p>
</item>
<tag><c>{'Supported-Vendor-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
-<item>
-<p>
-Values of Supported-Vendor-Id AVPs sent in an outgoing
-capabilities exchange message.
-Optional, defaults to the empty list.</p>
-</item>
-
<tag><c>{'Auth-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
-<item>
-<p>
-Values of Auth-Application-Id AVPs sent in an outgoing
-capabilities exchange message.
-Optional, defaults to the empty list.</p>
-</item>
-
<tag><c>{'Inband-Security-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
<item>
<p>
-Values of Inband-Security-Id AVPs sent in an outgoing
-capabilities exchange message.
-Optional, defaults to the empty list, which is equivalent to a
-list containing only 0 (= NO_INBAND_SECURITY).</p>
-
-<p>
+Inband-Security-Id defaults to the empty list, which is equivalent to a
+list containing only 0 (= NO_INBAND_SECURITY).
If 1 (= TLS) is specified then TLS is selected if the CER/CEA received
from the peer offers it.</p>
</item>
<tag><c>{'Acct-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag>
-<item>
-<p>
-Values of Acct-Application-Id AVPs sent in an outgoing
-capabilities exchange message.
-Optional, defaults to the empty list.</p>
-</item>
-
<tag><c>{'Vendor-Specific-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Grouped()</seealso>]}</c></tag>
-<item>
-<p>
-Values of Vendor-Specific-Application-Id AVPs sent in
-an outgoing capabilities exchange message.
-Optional, defaults to the empty list.</p>
-</item>
-
<tag><c>{'Firmware-Revision', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag>
-<item>
-<p>
-Value of the Firmware-Revision AVP sent in an outgoing capabilities
-exchange message.
-Optional.</p>
-</item>
</taglist>
@@ -444,11 +371,13 @@ eval(F) ->
Applying an evaluable() <c>E</c> to an argument list <c>A</c>
is meant in the sense of <c>eval([E|A])</c>.</p>
+<warning>
<p>
-Beware of using local funs (that is, fun expressions not of the
-form <c>fun Module:Name/Arity</c>) in situations in which the fun is
-not short-lived and code is to be upgraded at runtime since any
-processes retaining such a fun will have a reference to old code.</p>
+Beware of using fun expressions of the form <c>fun Name/Arity</c> (not
+fun Mod:Name/Arity) in situations in which the fun is not short-lived
+and code is to be upgraded at runtime since any processes retaining
+such a fun will have a reference to old code.</p>
+</warning>
<marker id="peer_filter"/>
</item>
@@ -501,14 +430,14 @@ specified value, or all peers if the atom <c>any</c>.</p>
<item>
<p>
Matches only those peers whose <c>Origin-Realm</c> has the
-value, or all peers if the atom <c>any</c>.</p>
+specified value, or all peers if the atom <c>any</c>.</p>
</item>
<tag><c>{eval, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
<item>
<p>
Matches only those peers for which the specified <seealso
-marker="evaluable">#evaluable()</seealso> returns
+marker="#evaluable">evaluable()</seealso> returns
<c>true</c> on the connection's <c>diameter_caps</c> record.
Any other return value or exception is equivalent to <c>false</c>.</p>
</item>
@@ -522,20 +451,21 @@ Matches only those peers not matched by the specified filter.</p>
<tag><c>{all, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag>
<item>
<p>
-Matches only those peers matched by each filter of the specified list.</p>
+Matches only those peers matched by each filter in the specified list.</p>
</item>
<tag><c>{any, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag>
<item>
<p>
-Matches only those peers matched by at least one filter of the
+Matches only those peers matched by at least one filter in the
specified list.</p>
</item>
</taglist>
+<note>
<p>
-Note that the <c>host</c> and <c>realm</c> filters examine the
+The <c>host</c> and <c>realm</c> filters examine the
outgoing request as passed to <seealso marker="#call">call/4</seealso>,
assuming that this is a record- or list-valued <seealso
marker="diameter_app#message">diameter_app:message()</seealso>, and that
@@ -543,11 +473,12 @@ the message contains at most one of each AVP.
If this is not the case then the <c>{host|realm, <seealso
marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c>
filters must be used to achieve the desired result.
-Note also that an empty host/realm (which should not be typical)
+An empty host/realm (which should not be typical)
is equivalent to an unspecified one for the purposes of filtering.</p>
+</note>
<p>
-An invalid filter is equivalent to <c>{any, []}</c>, a filter
+An invalid filter is equivalent to <c>{any,[]}</c>, a filter
that matches no peer.</p>
<marker id="service_event"/>
@@ -556,12 +487,12 @@ that matches no peer.</p>
<tag><c>service_event() = #diameter_event{}</c></tag>
<item>
<p>
-Event message sent to processes that have subscribed using <seealso
-marker="#subscribe">subscribe/1</seealso>.</p>
+An event message sent to processes that have subscribed to these using
+<seealso marker="#subscribe">subscribe/1</seealso>.</p>
<p>
-The <c>info</c> field of the event record can be one of the
-following.</p>
+The <c>info</c> field of the event record can have one of the
+following types.</p>
<taglist>
@@ -578,19 +509,19 @@ Pkt = #diameter_packet{}
<p>
The RFC 3539 watchdog state machine has
-transitioned into (<c>up</c>) or out of (<c>down</c>) the open
+transitioned into (<c>up</c>) or out of (<c>down</c>) the OKAY
state.
-If a <c>diameter_packet</c> record is present in an <c>up</c> tuple
-then there has been an exchange of capabilities exchange messages and
-the record contains the received CER or CEA, otherwise the
-connection has reestablished without the loss or transport
+If a <c>#diameter_packet{}</c> record is present in an <c>up</c> event
+then there has been a capabilties exchange on a newly established
+transport connection and the record contains the received CER or CEA.
+Otherwise a connection has reestablished without the loss or
connectivity.</p>
<p>
-Note that a single up/down event for a given peer corresponds to
-as many <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso>
-callbacks as there are Diameter applications that have been negotiated
-during capablilities exchange.
+Note that a single <c>up</c>/<c>down</c> event for a given peer
+corresponds to one <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso>
+callback for each of the Diameter applications negotiated during
+capablilities exchange.
That is, the event communicates connectivity with the
peer as a whole while the callbacks communicate connectivity with
respect to individual Diameter applications.</p>
@@ -605,8 +536,10 @@ Opts = [<seealso marker="#transport_opt">transport_opt()</seealso>]
<p>
A connecting transport is attempting to establish/reestablish a
-transport connection with a peer following <c>reconnect_timer</c> or
-<c>watchdog_timer</c> expiry.</p>
+transport connection with a peer following <seealso
+marker="#reconnect_timer">reconnect_timer</seealso> or
+<seealso marker="#watchdog_timer">watchdog_timer</seealso>
+expiry.</p>
</item>
<tag><c>{closed, Ref, Reason, Config}</c></tag>
@@ -617,8 +550,8 @@ Config = {connect|listen, [<seealso marker="#transport_opt">transport_opt()</see
</code>
<p>
-Capabilities exchange has failed. <c>Reason</c> can be one of
-the following.</p>
+Capabilities exchange has failed.
+<c>Reason</c> can have one of the following types.</p>
<taglist>
@@ -635,11 +568,11 @@ CB = <seealso marker="#evaluable">evaluable()</seealso>
<p>
An incoming CER has been answered with the indicated result code or
discarded.
-The capabilities record contains pairs of values for the the local
-node and remote peer.
-The packet record contains the CER in question.
+<c>Caps</c> contains pairs of values for the the local node and remote
+peer.
+<c>Pkt</c> contains the CER in question.
In the case of rejection by a capabilities callback, the tuple
-indicates the rejecting callback.</p>
+contains the rejecting callback.</p>
</item>
<tag><c>{'CER', Caps, {ResultCode, Pkt}}</c></tag>
@@ -653,9 +586,8 @@ Pkt = #diameter_packet{}
<p>
An incoming CER contained errors and has been answered with the
indicated result code.
-The capabilities record contains only values for the the local
-node.
-The packet record contains the CER in question.</p>
+<c>Caps</c> contains only values for the the local node.
+<c>Pkt</c> contains the CER in question.</p>
</item>
<tag><c>{'CEA', Result, Caps, Pkt}</c></tag>
@@ -671,11 +603,11 @@ ResultCode = integer()
An incoming CEA has been rejected for the indicated reason.
An integer-valued <c>Result</c> indicates the result code sent
by the peer.
-The capabilities record contains pairs of values for the the local
-node and remote peer.
-The packet record contains the CEA in question.
+<c>Caps</c> contains pairs of values for the the local node and remote
+peer.
+<c>Pkt</c> contains the CEA in question.
In the case of rejection by a capabilities callback, the tuple
-indicates the rejecting callback.</p>
+contains the rejecting callback.</p>
</item>
<tag><c>{'CEA', Caps, Pkt}</c></tag>
@@ -686,9 +618,9 @@ Pkt = #diameter_packet{}
</code>
<p>
-An incoming CER contained errors and has been rejected.
-The capabilities record contains only values for the the local node.
-The packet record contains the CEA in question.</p>
+An incoming CEA contained errors and has been rejected.
+<c>Caps</c> contains only values for the the local node.
+<c>Pkt</c> contains the CEA in question.</p>
</item>
</taglist>
@@ -732,9 +664,9 @@ that is somewhat unique.</p>
<tag><c>service_opt()</c></tag>
<item>
<p>
-Options accepted by <seealso
+An option passed to <seealso
marker="#start_service">start_service/2</seealso>.
-Can be any <seealso marker="#capability"><c>capability()</c></seealso> tuple as
+Can be any <seealso marker="#capability">capability()</seealso> as
well as the following.</p>
<taglist>
@@ -745,17 +677,15 @@ well as the following.</p>
Defines a Diameter application supported by the service.</p>
<p>
-A service must define one application for each Diameter application it
-intends to support.
-For an outgoing Diameter request, the application is specified by
-passing the desired application's <seealso
-marker="#application_alias"><c>application_alias()</c></seealso> to
-<seealso marker="#call">call/4</seealso>, while for an
+A service must configure one <c>application</c> for each Diameter
+application it intends to support.
+For an outgoing Diameter request, the relevant <seealso
+marker="#application_alias">application_alias()</seealso> is
+passed to <seealso marker="#call">call/4</seealso>, while for an
incoming request the application identifier in the message
-header determines the application (and callback module), the
-application identifier being specified in the <seealso
-marker="diameter_dict">dictionary</seealso> file defining the
-application.</p>
+header determines the application, the identifier being specified in
+the application's <seealso marker="diameter_dict">dictionary</seealso>
+file.</p>
</item>
</taglist>
@@ -766,8 +696,9 @@ application.</p>
<tag><c>transport_opt()</c></tag>
<item>
<p>
-Options accepted by <seealso
-marker="#add_transport">add_transport/2</seealso>.</p>
+An option passed to <seealso
+marker="#add_transport">add_transport/2</seealso>.
+Has one of the following types.</p>
<taglist>
<tag><c>{transport_module, atom()}</c></tag>
@@ -778,10 +709,6 @@ marker="diameter_transport">diameter_transport(3)</seealso>.
Defaults to <c>diameter_tcp</c> if unspecified.</p>
<p>
-The interface required of a transport module is documented in <seealso
-marker="diameter_transport">diameter_transport(3)</seealso>.</p>
-
-<p>
Multiple <c>transport_module</c> and <c>transport_config</c>
options are allowed.
The order of these is significant in this case (and only in this case),
@@ -790,7 +717,7 @@ a <c>transport_module</c> being paired with the first
default value for trailing modules.
Transport starts will be attempted with each of the
modules in order until one establishes a connection within the
-corresponding timeout (see <c>transport_config</c> below) or all fail.</p>
+corresponding timeout (see below) or all fail.</p>
</item>
<tag><c>{transport_config, term()}</c></tag>
@@ -824,28 +751,24 @@ To listen on both SCTP and TCP, define one transport for each.</p>
<tag><c>{applications, [<seealso marker="#application_alias">application_alias()</seealso>]}</c></tag>
<item>
<p>
-The list of Diameter applications to which usage of the transport
-should be restricted.
-Defaults to all applications configured on the service
-in question.
-Must only specify applications defined on the service to which
-the transport is added.</p>
+The list of Diameter applications to which the transport should be
+restricted.
+Defaults to all applications configured on the service in question.
+Applications not configured on the service in question are ignored.</p>
</item>
<tag><c>{capabilities, [<seealso marker="#capability">capability()</seealso>]}</c></tag>
<item>
<p>
AVP's used to construct outgoing CER/CEA messages.
-Any AVP specified takes precedence over a corresponding value specified
-for the service in question.</p>
+Values take precedence over any specified on the service in
+question.</p>
<p>
Specifying a capability as a transport option
-may be particularly appropriate for Inband-Security-Id in case
+may be particularly appropriate for Inband-Security-Id, in case
TLS is desired over TCP as implemented by
-<seealso marker="diameter_tcp">diameter_tcp(3)</seealso> but
-not over SCTP as implemented by
-<seealso marker="diameter_sctp">diameter_sctp(3)</seealso>.</p>
+<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>.</p>
</item>
<tag><c>{capabilities_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag>
@@ -854,9 +777,9 @@ not over SCTP as implemented by
A callback invoked upon reception of CER/CEA during capabilities
exchange in order to ask whether or not the connection should
be accepted.
-Applied to the transport reference (as returned by <seealso
-marker="#add_transport">add_transport/2</seealso>) and
-<c>diameter_caps</c> record of the connection.
+Applied to the relevant <seealso
+marker="#transport_ref">transport_ref()</seealso> and the
+<c>#diameter_caps{}</c> record of the connection.
Returning <c>ok</c> accepts the connection.
Returning <c>integer()</c> causes an incoming
CER to be answered with the specified Result-Code.
@@ -871,6 +794,8 @@ code causes the transport connection to be broken.</p>
Multiple <c>capabilities_cb</c> options can be specified, in which
case the corresponding callbacks are applied until either all return
<c>ok</c> or one does not.</p>
+
+<marker id="watchdog_timer"/>
</item>
<tag><c>{watchdog_timer, TwInit}</c></tag>
@@ -892,6 +817,8 @@ the callback.</p>
<p>
An integer value must be at least 6000 as required by RFC 3539.
Defaults to 30000 if unspecified.</p>
+
+<marker id="reconnect_timer"/>
</item>
<tag><c>{reconnect_timer, Tc}</c></tag>
@@ -902,7 +829,7 @@ Tc = <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>
<p>
For a connecting transport, the RFC 3588 Tc timer, in milliseconds.
-Note that this timer determines the frequency with which the transport
+Note that this timer determines the frequency with which a transport
will attempt to establish a connection with its peer only <em>before</em>
an initial connection is established: once there is an initial
connection it's watchdog_timer that determines the frequency of
@@ -915,8 +842,8 @@ regarded as an initial connection rather than a reestablishment,
causing the RFC 3539 state machine to pass to state OPEN rather than
REOPEN.
Note that these semantics are not goverened by the RFC and
-that a listening transport's reconnect_timer should be greater than its
-peer's Tc plus jitter.</p>
+that a listening transport's <c>reconnect_timer</c> should be greater
+than its peer's Tw plus jitter.</p>
<p>
Defaults to 30000 for a connecting transport and 60000 for a listening
@@ -954,12 +881,12 @@ identifies the configuration.</p>
<!-- ===================================================================== -->
<func>
-<name>add_transport(SvcName, {connect|listen, Options})
+<name>add_transport(SvcName, {connect|listen, [Opt]})
-> {ok, Ref} | {error, Reason}</name>
<fsummary>Add transport capability to a service.</fsummary>
<type>
<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
-<v>Options = [<seealso marker="#transport_opt">transport_opt()</seealso>]</v>
+<v>Opt = <seealso marker="#transport_opt">transport_opt()</seealso></v>
<v>Ref = <seealso marker="#transport_ref">transport_ref()</seealso></v>
<v>Reason = term()</v>
</type>
@@ -984,16 +911,20 @@ marker="diameter_app#peer_up">peer_up/3</seealso> callback
after which the caller can exchange Diameter messages with the peer over
the transport.
In addition to CER/CEA, the service takes responsibility for the
-handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.</p>
+handling of DWR/DWA and required by RFC 3539, as well as for DPR/DPA.</p>
<p>
The returned reference uniquely identifies the transport within the
scope of the service.
Note that the function returns before a transport connection has been
-established.
+established.</p>
+
+<note>
+<p>
It is not an error to add a transport to a service that has not yet
been configured: a service can be started after configuring
-transports.</p>
+its transports.</p>
+</note>
<marker id="call"/>
</desc>
@@ -1002,48 +933,47 @@ transports.</p>
<!-- ===================================================================== -->
<func>
-<name>call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason}</name>
+<name>call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason}</name>
<fsummary>Send a Diameter request message.</fsummary>
<type>
<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
<v>App = <seealso marker="#application_alias">application_alias()</seealso></v>
<v>Request = <seealso marker="diameter_app#message">diameter_app:message()</seealso></v>
<v>Answer = term()</v>
-<v>Options = [<seealso marker="#call_opt">call_opt()</seealso>]</v>
+<v>Opt = <seealso marker="#call_opt">call_opt()</seealso></v>
</type>
<desc>
<p>
-Send a Diameter request message and possibly return the answer or error.</p>
+Send a Diameter request message.</p>
<p>
-<c>App</c> identifies the Diameter application in which the request is
+<c>App</c> specifies the Diameter application in which the request is
defined and callbacks to the corresponding callback module
will follow as described below and in <seealso
marker="diameter_app">diameter_app(3)</seealso>.
-Unless the <c>detach</c> option has been specified to cause an earlier
-return, the call returns either when an answer message is received
-from the peer or an error occurs.
-In the case of an answer, the return value is as returned by a
+Unless the <c>detach</c> option is specified, the call returns either
+when an answer message is received from the peer or an error occurs.
+In the answer case, the return value is as returned by a
<seealso
marker="diameter_app#handle_answer">handle_answer/4</seealso>
callback.
-In the case of an error, whether or not the error is returned directly
+In the error case, whether or not the error is returned directly
by diameter or from a <seealso
marker="diameter_app#handle_error">handle_error/4</seealso>
callback depends on whether or not the outgoing request is
-successfully encoded for transmission from the peer, the cases being
+successfully encoded for transmission to the peer, the cases being
documented below.</p>
<p>
If there are no suitable peers, or if
<seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
-rejects them by returning 'false', then <c>{error, no_connection}</c>
+rejects them by returning <c>false</c>, then <c>{error,no_connection}</c>
is returned.
Otherwise <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso>
is followed by a
<seealso
marker="diameter_app#prepare_request">prepare_request/3</seealso>
-callback, the message is encoded and sent.</p>
+callback, the message is encoded and then sent.</p>
<p>
There are several error cases which may prevent an
@@ -1056,7 +986,7 @@ callback:</p>
<item>
<p>
If the initial encode of the outgoing request
-fails, then the request process fails and <c>{error, encode}</c>
+fails, then the request process fails and <c>{error,encode}</c>
is returned.</p>
</item>
@@ -1073,7 +1003,7 @@ callback takes place with <c>Reason = timeout</c>.</p>
If the request is successfully encoded and sent but the service in
question is stopped before an answer is received then a
<seealso marker="diameter_app#handle_error">handle_error/4</seealso>
-callback takes place <c>Reason = cancel</c>.</p>
+callback takes place with <c>Reason = cancel</c>.</p>
</item>
<item>
@@ -1100,7 +1030,7 @@ callback.</p>
<p>
If an encode error takes place during
retransmission then the request process fails and
-<c>{error, failure}</c> is returned.</p>
+<c>{error,failure}</c> is returned.</p>
</item>
<item>
@@ -1108,7 +1038,7 @@ retransmission then the request process fails and
If an application callback made in processing the request fails
(pick_peer, prepare_request, prepare_retransmit,
handle_answer or handle_error) then either
-<c>{error, encode}</c> or <c>{error, failure}</c>
+<c>{error,encode}</c> or <c>{error,failure}</c>
is returned depending on whether or not there has been an
attempt to send the request over the transport.</p>
</item>
@@ -1116,9 +1046,9 @@ attempt to send the request over the transport.</p>
</list>
<p>
-Note that <c>{error, encode}</c> is the only return value which
+Note that <c>{error,encode}</c> is the only return value which
guarantees that the request has <em>not</em> been sent over the
-transport.</p>
+transport connection.</p>
<marker id="origin_state_id"/>
</desc>
@@ -1167,7 +1097,7 @@ An arity-3-valued <c>Pred</c> removes all transports for which
<c>Pred(Ref, Type, Opts)</c> returns <c>true</c>, where <c>Type</c> and
<c>Opts</c> are as passed to <seealso
marker="#add_transport">add_transport/2</seealso> and <c>Ref</c> is
-as returned by the corresponding call.
+as returned by it.
The remaining forms are equivalent to an arity-3 fun as follows.</p>
<code>
@@ -1183,7 +1113,7 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end
<p>
Removing a transport causes all associated transport connections to
be broken.
-A base application DPR message with
+A DPR message with
Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent
to each connected peer before disassociating the transport configuration
from the service and terminating the transport upon reception of
@@ -1198,10 +1128,12 @@ DPA or timeout.</p>
<!-- ===================================================================== -->
<func>
-<name>service_info(SvcName, Item) -> term()</name>
+<name>service_info(SvcName, Info) -> term()</name>
<fsummary>Return information about a started service.</fsummary>
<type>
<v>SvcName = <seealso marker="#service_name">service_name()</seealso></v>
+<v>Info = Item | [Info]</v>
+<v>Item = atom()</v>
</type>
<desc>
<p>
@@ -1224,16 +1156,14 @@ Return information about a started service.
<tag><c>'Firmware-Revision'</c></tag>
<item>
<p>
-Return a capability value as configured on the service at <seealso
-marker="#start_service">start_service/2</seealso>.
-Note that all capabilities are returned in a tagged list with the
-<c>capabilities</c> item.</p>
+Return a capability value as configured with <seealso
+marker="#start_service">start_service/2</seealso>.</p>
</item>
<tag><c>applications</c></tag>
<item>
<p>
-Return the list of applications configured on the service at <seealso
+Return the list of applications as configured with <seealso
marker="#start_service">start_service/2</seealso>.
</p>
</item>
@@ -1241,22 +1171,22 @@ marker="#start_service">start_service/2</seealso>.
<tag><c>capabilities</c></tag>
<item>
<p>
-Return a tagged list of all capabilities values configured on the service
-at <seealso
+Return a tagged list of all capabilities values as configured with
+<seealso
marker="#start_service">start_service/2</seealso>.</p>
</item>
<tag><c>transport</c></tag>
<item>
<p>
-Return a list containing one entry for every transport configured on
-the service with <seealso
+Return a list containing one entry for each of the service's transport
+as configured with <seealso
marker="#add_transport">add_transport/2</seealso>.
Each entry is a tagged list containing both configuration and
information about established peer connections.
An example return value with for a client service with Origin-Host
-"client.example.com" configured with a single transport connected to "server.example.com"
-might look as follows.</p>
+"client.example.com" configured with a single transport connected to
+"server.example.com" might look as follows.</p>
<code>
[[{ref,#Ref&lt;0.0.0.93>},
@@ -1306,21 +1236,20 @@ might look as follows.</p>
</code>
<p>
-Here <c>ref</c> is the <seealso
-marker="#transport_ref">transport_ref()</seealso> of the service's
-transport and <c>options</c> are as were passed to <seealso
+Here <c>ref</c> is a <seealso
+marker="#transport_ref">transport_ref()</seealso> and <c>options</c>
+the corresponding <seealso
+marker="#transport_opt">transport_opt()</seealso> list passed to <seealso
marker="#add_transport">add_transport/2</seealso>.
The <c>watchdog</c> entry shows the state of a connection's RFC 3539 watchdog
state machine.
The <c>peer</c> entry identifies the <seealso
marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso> for
-which there will have been a <seealso
-marker="diameter_app#peer_up">peer_up</seealso> callback for the
-Diameter applications negotiated during capabilities exchange, which
-are identified by the <c>apps</c> entry, <c>common</c> in this case
-being the <seealso
-marker="#application_alias">application_alias()</seealso> of this
-application with Application Id 0.
+which there will have been <seealso
+marker="diameter_app#peer_up">peer_up</seealso> callbacks for the
+Diameter applications identified by the <c>apps</c> entry,
+<c>common</c> being the <seealso
+marker="#application_alias">application_alias()</seealso>.
The <c>caps</c> entry identifies the capabilities sent by the local
node and received from the peer during capabilities exchange.
The <c>port</c> entry displays socket-level information about the
@@ -1353,7 +1282,7 @@ connection might look as follows.</p>
{port,3868}]}]},
{accept,[[{watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
{peer,{&lt;0.58.0>,{1346,171491,999511}}},
- {apps,[{0,server}]},
+ {apps,[{0,common}]},
{caps,[{origin_host,{"server.example.com","client.example.com"}},
{origin_realm,{"example.com","example.com"}},
{host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
@@ -1419,7 +1348,7 @@ A return value for the server above might look as follows.</p>
{port,3868}]}]},
{watchdog,{&lt;0.56.0>,{1346,171481,226895},okay}},
{peer,{&lt;0.58.0>,{1346,171491,999511}}},
- {apps,[{0,server}]},
+ {apps,[{0,common}]},
{caps,[{origin_host,{"server.example.com","client.example.com"}},
{origin_realm,{"example.com","example.com"}},
{host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}},
@@ -1481,6 +1410,12 @@ The Diameter-level statistics returned by <c>transport</c> and
</taglist>
+<p>
+Requesting info for an unknown service causes <c>undefined</c> to be
+returned.
+Requesting a list of items causes a tagged list to be
+returned.</p>
+
<marker id="services"/>
</desc>
</func>
@@ -1554,8 +1489,7 @@ Start a diameter service.</p>
<p>
A service defines a locally-implemented Diameter node, specifying the
-capabilities of the node to be used during capabilities exchange and
-the Diameter applications that it supports.
+capabilities to be advertised during capabilities exchange.
Transports are added to a service using <seealso
marker="#add_transport">add_transport/2</seealso>.
</p>
@@ -1599,6 +1533,19 @@ Stop the diameter application.</p>
<p>
Stop a diameter service.</p>
+<p>
+Stopping a service causes all associated transport connections to be
+broken.
+A DPR message with be sent as in the case of <seealso
+marker="#remove_transport">remove_transport/2</seealso>.</p>
+
+<note>
+<p>
+Stopping a transport does not remove any associated transports:
+<seealso marker="#remove_transport">remove_transport/2</seealso> must
+be called to remove transport configuration.</p>
+</note>
+
<marker id="subscribe"/>
</desc>
</func>
@@ -1614,7 +1561,7 @@ Stop a diameter service.</p>
<desc>
<p>
Subscribe to <seealso
-marker="#service_event"><c>service_event()</c></seealso> messages from
+marker="#service_event">service_event()</seealso> messages from
a service.</p>
<p>
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index 6e5c957eec..f6d53808f5 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -140,8 +140,8 @@ list of <c>{FieldName, FieldValue}</c> pairs.</p>
<p>
A third representation allows a message to be specified as a list
-whose head is a <c>diameter_header</c> record and whose tail is a list
-of <c>diameter_avp</c> records.
+whose head is a <c>#diameter_header{}</c> record and whose tail is a list
+of <c>#diameter_avp{}</c> records.
This representation is used by diameter itself when relaying requests
as directed by the return value of a
<seealso marker="#handle_request">handle_request/3</seealso>
@@ -158,10 +158,9 @@ are sent exactly as specified.</p>
<tag><c>packet() = #diameter_packet{}</c></tag>
<item>
<p>
-A container for incoming and outgoing Diameters message that's passed
+A container for incoming and outgoing Diameter messages that's passed
through encode/decode and transport.
-Fields of a packet() record should not be set in return values except
-as documented.</p>
+Fields should not be set in return values except as documented.</p>
</item>
<marker id="peer_ref"/>
@@ -356,7 +355,7 @@ Extra arguments passed to <seealso
marker="diameter#call">diameter:call/4</seealso> can be used to
communicate transport data to the callback.
A returned <seealso marker="#packet">packet()</seealso> can also set the <c>header</c> field to a
-<c>diameter_header</c> record in order to specify values that should
+<c>#diameter_header{}</c> record in order to specify values that should
be preserved in the outgoing request, although this should typically
not be necessary and allows the callback to set header values
inappropriately.
@@ -603,7 +602,7 @@ header of the relayed request.</p>
The returned <c>Opts</c> should not specify <c>detach</c>.
A subsequent <seealso marker="#handle_answer">handle_answer/4</seealso>
callback for the relayed request must return its first
-argument, the <c>diameter_packet</c> record containing the answer
+argument, the <c>#diameter_packet{}</c> record containing the answer
message.
Note that the <c>extra</c> option can be specified to supply arguments
that can distinguish the relay case from others if so desired.
diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml
index 4ed02e3881..4890333669 100644
--- a/lib/diameter/doc/src/diameter_transport.xml
+++ b/lib/diameter/doc/src/diameter_transport.xml
@@ -93,16 +93,19 @@ It should not link to the parent.
It should exit if its transport connection with its peer is lost.</p>
<p>
-Transport processes for a given service are started sequentially.</p>
-
-<p>
-The start function should use the 'Host-IP-Address' list on the service,
-namely <c>Svc#diameter_service.host_ip_address</c>, and/or
+The capabilities in the <c>#diameter_service{}</c> record are as
+passed to <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso> and
+<seealso
+marker="diameter#add_transport">diameter:add_transport/2</seealso>,
+values passed to the latter overriding those passed to the former.
+The start function should use the <c>Host-IP-Address</c> list and/or
<c>Opts</c> to select an appropriate list of local IP addresses,
-and should return this list if different from the service addresses.
-The returned list is used to populate 'Host-IP-Address' AVPs in outgoing
-capabilities exchange messages, the service addresses being used
-otherwise.</p>
+and should return this list if different from the
+<c>#diameter_service{}</c> addresses.
+The returned list is used to populate <c>Host-IP-Address</c> AVPs in
+outgoing capabilities exchange messages, the
+<c>#diameter_service{}</c> addresses being used otherwise.</p>
<marker id="MESSAGES"/>
</desc>
@@ -129,9 +132,10 @@ diameter.</p>
<item>
<p>
An outbound Diameter message.
-Packet can be either <c>binary()</c> (the message to be sent)
-or a <c>#diameter_packet{}</c> whose <c>transport_data</c> field
-containes a value other than undefined.</p>
+<c>Packet</c> can be either binary() (the message to be sent)
+or a <c>#diameter_packet{}</c> record whose <c>transport_data</c>
+field contains a value other than undefined and whose <c>bin</c> field
+contains the binary to send.</p>
</item>
<tag><c>{diameter, {close, Pid}}</c></tag>
@@ -140,7 +144,7 @@ containes a value other than undefined.</p>
A request to close the transport connection.
The transport process should terminate after closing the
connection.
-Pid is the pid() of the parent process.</p>
+<c>Pid</c> is the pid() of the parent process.</p>
</item>
<tag><c>{diameter, {tls, Ref, Type, Bool}}</c></tag>
@@ -148,17 +152,17 @@ Pid is the pid() of the parent process.</p>
<p>
Indication of whether or not capabilities exchange has selected
inband security using TLS.
-Ref is a reference() that must be included in the
+<c>Ref</c> is a reference() that must be included in the
<c>{diameter, {tls, Ref}}</c> reply message to the transport's
parent process (see below).
-Type is either <c>connect</c> or <c>accept</c> depending on
+<c>Type</c> is either <c>connect</c> or <c>accept</c> depending on
whether the process has been started for a connecting or listening
transport respectively.
-Bool is a boolean() indicating whether or not the transport connection
-should be upgraded to TLS.</p>
+<c>Bool</c> is a boolean() indicating whether or not the transport
+connection should be upgraded to TLS.</p>
<p>
-If TLS is requested (Bool = true) then a connecting process should
+If TLS is requested (<c>Bool = true</c>) 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 <c>{diameter, {tls, Ref}}</c>
@@ -182,18 +186,18 @@ to its parent.</p>
<tag><c>{diameter, {self(), connected}}</c></tag>
<item>
<p>
-Inform the parent that the transport process with Type = accept has
+Inform the parent that the transport process with <c>Type=accept</c> has
established a connection with the peer.
-Not sent if the transport process has Type = connect.</p>
+Not sent if the transport process has <c>Type=connect</c>.</p>
</item>
<tag><c>{diameter, {self(), connected, Remote}}</c></tag>
<item>
<p>
-Inform the parent that the transport process with Type = connect
+Inform the parent that the transport process with <c>Type=connect</c>
has established a connection with a peer.
-Not sent if the transport process has Type = accept.
-Remote is an arbitrary term that uniquely identifies the remote
+Not sent if the transport process has <c>Type=accept</c>.
+<c>Remote</c> is an arbitrary term that uniquely identifies the remote
endpoint to which the transport has connected.</p>
</item>
@@ -201,14 +205,14 @@ endpoint to which the transport has connected.</p>
<item>
<p>
An inbound Diameter message.
-Packet can be either <c>binary()</c> (the message to be sent)
-or <c>#diameter_packet{}</c>
-whose <c>packet</c> field contains a <c>binary()</c>.
-Any value (other than undefined) set in
+<c>Packet</c> can be either binary() (the received message)
+or a <c>#diameter_packet{}</c> record
+whose <c>bin</c> field contains the received binary().
+Any value (other than <c>undefined</c>) set in
the <c>transport_data</c> field will be passed back with a
corresponding answer message in the case that the inbound message is a
request unless the sender sets another value.
-How the <c>transport_data</c> is used/interpreted is up to the
+How <c>transport_data</c> is used/interpreted is up to the
transport module.</p>
</item>
@@ -216,7 +220,7 @@ transport module.</p>
<item>
<p>
Acknowledgment of a successful TLS handshake.
-Ref is the reference() received in the
+<c>Ref</c> is the reference() received in the
<c>{diameter, {tls, Ref, Type, Bool}}</c> message in response
to which the reply is sent.
A transport must exit if a handshake is not successful.</p>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-07 21:07:37 +0000