aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc/src/diameter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/diameter/doc/src/diameter.xml')
-rw-r--r--lib/diameter/doc/src/diameter.xml218
1 files changed, 109 insertions, 109 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml
index db19fbb271..4804b07b30 100644
--- a/lib/diameter/doc/src/diameter.xml
+++ b/lib/diameter/doc/src/diameter.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
<!ENTITY spawn_opt
'<seealso marker="erts:erlang#spawn_opt-2">erlang:spawn_opt/2</seealso>'>
@@ -130,7 +130,7 @@ ExtraArgs = list()
<p>
A module implementing the callback interface defined in &man_app;,
along with any
-extra arguments to be appended to those documented for the interface.
+extra arguments to be appended to those documented.
Note that extra arguments specific to an outgoing request can be
specified to &call;, in which case
those are are appended to any module-specific extra arguments.</p>
@@ -138,7 +138,7 @@ 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 &man_app; callbacks.
-See that module for details.</p>
+See <c>diameter_callback.erl</c> for details.</p>
<marker id="application_opt"/>
</item>
@@ -155,7 +155,7 @@ Has one the following types.</p>
<tag><c>{alias, &application_alias;}</c></tag>
<item>
<p>
-An unique identifier for the application in the scope of the
+A unique identifier for the application in the scope of the
service.
Defaults to the value of the <c>dictionary</c> option if
unspecified.</p>
@@ -166,8 +166,8 @@ unspecified.</p>
<p>
The name of an encode/decode module for the Diameter
messages defined by the application.
-These modules are generated from a specification file whose format is
-documented in &man_dict;.</p>
+These modules are generated from files whose format is documented in
+&man_dict;.</p>
</item>
<tag><c>{module, &application_module;}</c></tag>
@@ -195,15 +195,14 @@ Specifies whether or not the &app_pick_peer;
application callback can modify the application state.
Defaults to <c>false</c> if unspecified.</p>
-<note>
+<warning>
<p>
-&app_pick_peer; callbacks
-are serialized when these are allowed to modify state, which is a
-potential performance bottleneck.
+&app_pick_peer; callbacks are serialized when this option is <c>true</c>,
+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 should
probably avoid it.</p>
-</note>
+</warning>
</item>
<tag><c>{answer_errors, callback|report|discard}</c></tag>
@@ -234,7 +233,7 @@ Defaults to <c>report</c> if unspecified.</p>
<item>
<p>
Determines the manner in which incoming requests are handled when an
-error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot
+error other than 3007 (DIAMETER_APPLICATION_UNSUPPORTED, which cannot
be associated with an application callback module), is detected.</p>
<p>
@@ -244,7 +243,8 @@ If <c>answer</c> then even 5xxx errors are answered without a
callback unless the connection in question has configured the RFC 3588
common dictionary as noted below.
If <c>callback</c> then a &app_handle_request; callback always takes
-place and the return value determines the answer sent to the peer.</p>
+place and its return value determines the answer sent to the peer, if
+any.</p>
<p>
Defaults to <c>answer_3xxx</c> if unspecified.</p>
@@ -252,13 +252,14 @@ Defaults to <c>answer_3xxx</c> if unspecified.</p>
<note>
<p>
Answers sent by diameter set the E-bit in the Diameter Header.
-Since RFC 3588 allowed only 3xxx result codes in an
+Since RFC 3588 allows only 3xxx result codes in an
<c>answer-message</c>, <c>answer</c> has the same semantics as
-<c>answer_3xxx</c> if the peer connection in question has configured
-the RFC 3588 common dictionary, <c>diameter_gen_base_rfc3588</c>.
-RFC 6733 allows both 3xxx and 5xxx result codes in an
-<c>answer-message</c> so a connection configured with the RFC 6733
-common dictionary, <c>diameter_gen_base_rfc6733</c>, does
+<c>answer_3xxx</c> when the transport in question has
+been configured with <c>diameter_gen_base_rfc3588</c> as its common
+dictionary.
+Since RFC 6733 allows both 3xxx and 5xxx result codes in an
+<c>answer-message</c>, a transport with
+<c>diameter_gen_base_rfc6733</c> as its common dictionary does
distinguish between <c>answer_3xxx</c> and <c>answer</c>.</p>
</note>
</item>
@@ -291,9 +292,8 @@ Multiple options append to the argument list.</p>
<tag><c>{filter, &peer_filter;}</c></tag>
<item>
<p>
-A filter to apply to the list of available peers before passing them to
-the &app_pick_peer;
-callback for the application in question.
+A filter to apply to the list of available peers before passing it to
+the &app_pick_peer; callback for the application in question.
Multiple options are equivalent a single <c>all</c> filter on the
corresponding list of filters.
Defaults to <c>none</c>.</p>
@@ -312,7 +312,7 @@ Defaults to 5000.</p>
<p>
Causes &call; to return <c>ok</c> as
soon as the request in
-question has been encoded instead of waiting for and returning
+question has been encoded, instead of waiting for and returning
the result from a subsequent &app_handle_answer; or
&app_handle_error; callback.</p>
</item>
@@ -331,8 +331,8 @@ An invalid option will cause &call; to fail.</p>
<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.
+Can be configured both on a service and a transport, values
+on the latter taking precedence.
Has one of the following types.</p>
<taglist>
@@ -358,7 +358,7 @@ question communicates an address list as described in
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 &the_rfc;.
+value, as documented in &the_rfc;.
The function &origin_state_id;
can be used as to retrieve a value that is computed when the diameter
application is started.</p>
@@ -370,8 +370,8 @@ application is started.</p>
<item>
<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
+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>
@@ -437,38 +437,38 @@ Has one of the following types.</p>
<p>
Matches any peer.
This is a convenience that provides a filter equivalent to no
-filter at all.</p>
+filter.</p>
</item>
<tag><c>host</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Host</c> has the same value
-as <c>Destination-Host</c> in the outgoing request in question,
+Matches only those peers whose Origin-Host has the same value
+as Destination-Host in the outgoing request in question,
or any peer if the request does not contain
-a <c>Destination-Host</c> AVP.</p>
+a Destination-Host AVP.</p>
</item>
<tag><c>realm</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Realm</c> has the same value
-as <c>Destination-Realm</c> in the outgoing request in question,
+Matches only those peers whose Origin-Realm has the same value
+as Destination-Realm in the outgoing request in question,
or any peer if the request does not contain
-a <c>Destination-Realm</c> AVP.</p>
+a Destination-Realm AVP.</p>
</item>
<tag><c>{host, any|&dict_DiameterIdentity;}</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Host</c> has the
+Matches only those peers whose Origin-Host has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
<tag><c>{realm, any|&dict_DiameterIdentity;</c></tag>
<item>
<p>
-Matches only those peers whose <c>Origin-Realm</c> has the
+Matches only those peers whose Origin-Realm has the
specified value, or all peers if the atom <c>any</c>.</p>
</item>
@@ -477,7 +477,8 @@ specified value, or all peers if the atom <c>any</c>.</p>
<p>
Matches only those peers for which the specified
<c>&evaluable;</c> returns
-<c>true</c> on the connection's <c>diameter_caps</c> record.
+<c>true</c> when applied to the connection's <c>diameter_caps</c>
+record.
Any other return value or exception is equivalent to <c>false</c>.</p>
</item>
@@ -508,10 +509,10 @@ that matches no peer.</p>
<note>
<p>
-The <c>host</c> and <c>realm</c> filters examine the
-outgoing request as passed to &call;,
-assuming that this is a record- or list-valued <c>&codec_message;</c>,
-and that the message contains at most one of each AVP.
+The <c>host</c> and <c>realm</c> filters cause the Destination-Host
+and Destination-Realm AVPs to be extracted from the
+outgoing request, assuming it to be a record- or list-valued
+<c>&codec_message;</c>, and assuming at most one of each AVP.
If this is not the case then the <c>{host|realm, &dict_DiameterIdentity;}</c>
filters must be used to achieve the desired result.
An empty <c>&dict_DiameterIdentity;</c>
@@ -555,7 +556,7 @@ Can have one of the following types.</p>
<p>
The service is being started or stopped.
No event precedes a <c>start</c> event.
-No event follows a <c>stop</c> event and this event
+No event follows a <c>stop</c> event, and this event
implies the termination of all transport processes.</p>
</item>
@@ -575,16 +576,15 @@ The RFC 3539 watchdog state machine has
transitioned into (<c>up</c>) or out of (<c>down</c>) the OKAY
state.
If a <c>#diameter_packet{}</c> 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>
+then there has been a capabilities exchange on a newly established
+transport connection and the record contains the received CER or
+CEA.</p>
<p>
Note that a single <c>up</c> or <c>down</c> event for a given peer
corresponds to multiple &app_peer_up; or &app_peer_down;
callbacks, one for each of the Diameter applications negotiated during
-capablilities exchange.
+capabilities 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>
@@ -599,7 +599,7 @@ Opts = [&transport_opt;]
<p>
A connecting transport is attempting to establish/reestablish a
-transport connection with a peer following &reconnect_timer; or
+transport connection with a peer following &connect_timer; or
&watchdog_timer; expiry.</p>
</item>
@@ -627,10 +627,10 @@ CB = &evaluable;
</pre>
<p>
-An incoming CER has been answered with the indicated result code or
+An incoming CER has been answered with the indicated result code, or
discarded.
-<c>Caps</c> contains pairs of values for the local node and remote
-peer.
+<c>Caps</c> contains pairs of values, for the local node and remote
+peer respectively.
<c>Pkt</c> contains the CER in question.
In the case of rejection by a capabilities callback, the tuple
contains the rejecting callback.</p>
@@ -647,7 +647,7 @@ Pkt = #diameter_packet{}
<p>
An incoming CER contained errors and has been answered with the
indicated result code.
-<c>Caps</c> contains only values for the local node.
+<c>Caps</c> contains values for the local node only.
<c>Pkt</c> contains the CER in question.</p>
</item>
@@ -754,7 +754,7 @@ Defines a Diameter application supported by the service.</p>
<p>
A service must configure one tuple for each Diameter
application it intends to support.
-For an outgoing Diameter request, the relevant <c>&application_alias;</c> is
+For an outgoing request, the relevant <c>&application_alias;</c> is
passed to &call;, while for an
incoming request the application identifier in the message
header determines the application, the identifier being specified in
@@ -765,7 +765,7 @@ the application's &dictionary; file.</p>
The capabilities advertised by a node must match its configured
applications. In particular, <c>application</c> configuration must
be matched by corresponding &capability; configuration, of
-Application-Id AVP's in particular.</p>
+*-Application-Id AVPs in particular.</p>
</warning>
</item>
@@ -778,10 +778,11 @@ Application-Id AVP's in particular.</p>
<item>
<p>
Specifies the degree to which the service allows multiple transport
-connections to the same peer.</p>
+connections to the same peer, as identified by its Origin-Host
+at capabilities exchange.</p>
<p>
-If type <c>[node()]</c> then a connection is rejected if another already
+If <c>[node()]</c> then a connection is rejected if another already
exists on any of the specified nodes.
Types <c>false</c>, <c>node</c>, <c>nodes</c> and
&evaluable; are equivalent to
@@ -803,8 +804,8 @@ Defaults to <c>nodes</c>.</p>
<item>
<p>
Specifies a constant value <c>H</c> for the topmost <c>32-N</c> bits of
-of 32-bit End-to-End and Hop-by-Hop identifiers generated
-by the service, either explicity or as a return value of a function
+of 32-bit End-to-End and Hop-by-Hop Identifiers generated
+by the service, either explicitly or as a return value of a function
to be evaluated at &start_service;.
In particular, an identifier <c>Id</c> is mapped to a new identifier
as follows.</p>
@@ -812,11 +813,11 @@ as follows.</p>
(H bsl N) bor (Id band ((1 bsl N) - 1))
</pre>
<p>
-Note that &the_rfc; requires that End-to-End identifiers remain unique
+Note that &the_rfc; requires that End-to-End Identifiers remain unique
for a period of at least 4 minutes and that this and the call rate
-places a lower bound on the appropriate values of <c>N</c>:
-at a rate of <c>R</c> requests per second an <c>N</c>-bit counter
-traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes so
+places a lower bound on appropriate values of <c>N</c>:
+at a rate of <c>R</c> requests per second, an <c>N</c>-bit counter
+traverses all of its values in <c>(1 bsl N) div (R*60)</c> minutes, so
the bound is <c>4*R*60 =&lt; 1 bsl N</c>.</p>
<p><c>N</c> must lie in the range <c>0..32</c> and <c>H</c> must be a
@@ -829,7 +830,7 @@ Defaults to <c>{0,32}</c>.</p>
<p>
Multiple Erlang nodes implementing the same Diameter node should
be configured with different sequence masks to ensure that each node
-uses a unique range of End-to-End and Hop-by-Hop identifiers for
+uses a unique range of End-to-End and Hop-by-Hop Identifiers for
outgoing requests.</p>
</warning>
</item>
@@ -852,7 +853,7 @@ by the specified function, evaluated whenever a peer connection
becomes available or a remote service requests information about local
connections.
The value <c>true</c> is equivalent to <c>fun &nodes;</c>.
-The value <c>node()</c> in a node list is ignored, so a collection of
+The value <c>node()</c> in a list is ignored, so a collection of
services can all be configured to share with the same list of
nodes.</p>
@@ -899,7 +900,7 @@ If <c>evaluable()</c> then only peers returned by the specified
function are used, evaluated whenever a remote service communicates
information about an available peer connection.
The value <c>true</c> is equivalent to <c>fun &nodes;</c>.
-The value <c>node()</c> in a node list is ignored.</p>
+The value <c>node()</c> in a list is ignored.</p>
<p>
Defaults to <c>false</c>.</p>
@@ -946,7 +947,7 @@ Applications not configured on the service in question are ignored.</p>
The capabilities advertised by a node must match its configured
applications.
In particular, setting <c>applications</c> on a transport typically
-implies having to set matching Application-Id AVP's in a
+implies having to set matching *-Application-Id AVPs in a
&capabilities; tuple.</p>
</warning>
@@ -956,7 +957,7 @@ implies having to set matching Application-Id AVP's in a
<tag><c>{capabilities, [&capability;]}</c></tag>
<item>
<p>
-AVP's used to construct outgoing CER/CEA messages.
+AVPs used to construct outgoing CER/CEA messages.
Values take precedence over any specified on the service in
question.</p>
@@ -1021,14 +1022,45 @@ case the corresponding callbacks are applied until either all return
The number of milliseconds after which a transport process having an
established transport connection will be terminated if the expected
capabilities exchange message (CER or CEA) is not received from the peer.
-For a connecting transport, the timing of reconnection attempts is
-governed by &watchdog_timer; or &reconnect_timer; expiry.
+For a connecting transport, the timing of connection attempts is
+governed by &connect_timer; or &watchdog_timer; expiry.
For a listening transport, the peer determines the timing.</p>
<p>
Defaults to 10000.</p>
</item>
+<marker id="connect_timer"/>
+<tag><c>{connect_timer, Tc}</c></tag>
+<item>
+<pre>
+Tc = &dict_Unsigned32;
+</pre>
+
+<p>
+For a connecting transport, the &the_rfc; Tc timer, in milliseconds.
+This timer determines the frequency with which a transport
+attempts to establish an initial connection with its peer
+following transport configuration.
+Once an initial connection has been
+established, &watchdog_timer; determines the frequency of
+reconnection attempts, as required by RFC 3539.</p>
+
+<p>
+For a listening transport, the timer specifies the time after which a
+previously connected peer will be forgotten: a connection after this time is
+regarded as an initial connection rather than reestablishment,
+causing the RFC 3539 state machine to pass to state OKAY rather than
+REOPEN.
+Note that these semantics are not governed by the RFC and
+that a listening transport's &connect_timer; should be greater
+than its peer's Tw plus jitter.</p>
+
+<p>
+Defaults to 30000 for a connecting transport and 60000 for a listening
+transport.</p>
+</item>
+
<marker id="disconnect_cb"/>
<tag><c>{disconnect_cb, &evaluable;}</c></tag>
@@ -1036,14 +1068,12 @@ Defaults to 10000.</p>
<p>
A callback invoked prior to terminating the transport process of a
transport connection having watchdog state <c>OKAY</c>.
-Applied to <c>Reason=transport|service|application</c> and the
-<c>&transport_ref;</c> and
-<c>&app_peer;</c>
-in question, <c>Reason</c> indicating whether the diameter
-application is being stopped, the service in question is being stopped
-at &stop_service; or
-the transport in question is being removed at &remove_transport;,
-respectively.</p>
+Applied to <c>application|service|transport</c> and the
+<c>&transport_ref;</c> and <c>&app_peer;</c> in question:
+<c>application</c> indicates that the diameter application is
+being stopped, <c>service</c> that the service in question is being
+stopped by &stop_service;, and <c>transport</c> that the transport in
+question is being removed by &remove_transport;.</p>
<p>
The return value can have one of the following types.</p>
@@ -1145,36 +1175,6 @@ See &man_tcp; for the behaviour of that module.</p>
</note>
</item>
-<marker id="reconnect_timer"/>
-<tag><c>{reconnect_timer, Tc}</c></tag>
-<item>
-<pre>
-Tc = &dict_Unsigned32;
-</pre>
-
-<p>
-For a connecting transport, the &the_rfc; Tc timer, in milliseconds.
-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 reconnection attempts, as required by RFC 3539.</p>
-
-<p>
-For a listening transport, the timer specifies the time after which a
-previously connected peer will be forgotten: a connection after this time is
-regarded as an initial connection rather than a reestablishment,
-causing the RFC 3539 state machine to pass to state OKAY rather than
-REOPEN.
-Note that these semantics are not governed by the RFC and
-that a listening transport's &reconnect_timer; should be greater
-than its peer's Tw plus jitter.</p>
-
-<p>
-Defaults to 30000 for a connecting transport and 60000 for a listening
-transport.</p>
-</item>
-
<marker id="spawn_opt"/>
<tag><c>{spawn_opt, [term()]}</c></tag>
<item>
@@ -1661,7 +1661,7 @@ R_Flag}</c>.</p>
Note that <c>watchdog</c>, <c>peer</c>, <c>apps</c>, <c>caps</c>
and <c>port</c> entries depend on connectivity
with the peer and may not be present.
-Note also that the <c>statistics</c> entry presents values acuumulated
+Note also that the <c>statistics</c> entry presents values accumulated
during the lifetime of the transport configuration.</p>
<p>