diff options
Diffstat (limited to 'lib/diameter/doc/src')
-rw-r--r-- | lib/diameter/doc/src/diameter.xml | 152 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 4 | ||||
-rw-r--r-- | lib/diameter/doc/src/diameter_transport.xml | 6 |
3 files changed, 132 insertions, 30 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index a35fd5b3a8..15f398c5f8 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -833,6 +833,7 @@ request a connection with one peer over SCTP or another To listen on both SCTP and TCP, define one transport for each.</p> </item> +<marker id="applications"/> <tag><c>{applications, [<seealso marker="#application_alias">application_alias()</seealso>]}</c></tag> <item> <p> @@ -842,6 +843,7 @@ Defaults to all applications configured on the service in question. Applications not configured on the service in question are ignored.</p> </item> +<marker id="capabilities"/> <tag><c>{capabilities, [<seealso marker="#capability">capability()</seealso>]}</c></tag> <item> <p> @@ -856,33 +858,136 @@ TLS is desired over TCP as implemented by <seealso marker="diameter_tcp">diameter_tcp(3)</seealso>.</p> </item> +<marker id="capabilities_cb"/> <tag><c>{capabilities_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag> <item> <p> 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 relevant <c><seealso -marker="#transport_ref">transport_ref()</seealso></c> 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. -Returning <c>discard</c> causes an incoming CER to -be discarded. -Returning <c>unknown</c> is equivalent to returning <c>3010</c>, -DIAMETER_UNKNOWN_PEER. -Returning anything but <c>ok</c> or a 2xxx series result -code causes the transport connection to be broken.</p> +Applied to the <c><seealso +marker="#transport_ref">transport_ref()</seealso></c> and +<c>#diameter_caps{}</c> record of the connection.</p> + +<p> +The return value can have one of the following types.</p> + +<taglist> +<tag><c>ok</c></tag> +<item> +<p> +Accept the connection.</p> +</item> + +<tag><c>integer()</c></tag> +<item> +<p> +Causes an incoming CER to be answered with the specified Result-Code.</p> +</item> + +<tag><c>discard</c></tag> +<item> +<p> +Causes an incoming CER to be discarded without CEA being sent.</p> +</item> + +<tag><c>unknown</c></tag> +<item> +<p> +Equivalent to returning <c>3010</c>, DIAMETER_UNKNOWN_PEER.</p> +</item> +</taglist> <p> +Returning anything but <c>ok</c> or a 2xxx series result +code causes the transport connection to be broken. 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> +</item> -<marker id="watchdog_timer"/> +<marker id="disconnect_cb"/> +<tag><c>{disconnect_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag> + +<item> +<p> +A callback invoked prior to requesting shutdown of a transport process +for a transport connection having watchdog state <c>OKAY</c>. +Applied to <c>Reason=transport|service|application</c> and the +<c><seealso marker="#transport_ref">transport_ref()</seealso></c> and +<c><seealso marker="diameter_app#peer">diameter_app:peer()</seealso></c> +in question, <c>Reason</c> indicating whether the the diameter +application is being stopped, the service in question is being stopped +at <seealso +marker="diameter#stop_service">diameter:stop_service/1</seealso> or +the transport in question is being removed at <seealso +marker="diameter#remove_transport">diameter:remove_transport/2</seealso>, +respectively.</p> + +<p> +The return value can have one of the following types.</p> + +<taglist> +<tag><c>{dpr, [option()]}</c></tag> +<item> +<p> +Causes Disconnect-Peer-Request to be sent to the peer, transport +process shutdown being requested after reception of +Disconnect-Peer-Answer or timeout. +An <c>option()</c> can be one of the following.</p> + +<taglist> +<tag><c>{timeout, integer()}</c></tag> +<item> +<p> +Transport process shutdown will be requested after this number of +milliseconds if DPA is not received. +Defaults to 1000.</p> +</item> + +<tag><c>{cause, 0|rebooting|1|busy|2|goaway}</c></tag> +<item> +<p> +The Disconnect-Cause to send, <c>REBOOTING</c>, <c>BUSY</c> and +<c>DO_NOT_WANT_TO_TALK_TO_YOU</c> respectively. +Defaults to <c>rebooting</c> for <c>Reason=service|application</c> and +<c>goaway</c> for <c>Reason=transport</c>.</p> +</item> +</taglist> +</item> + +<tag><c>dpr</c></tag> +<item> +<p> +Equivalent to <c>{dpr, []}</c>.</p> +</item> + +<tag><c>close</c></tag> +<item> +<p> +Causes transport process shutdown to be requested without +Disconnect-Peer-Request being sent to the peer.</p> </item> +<tag><c>ignore</c></tag> +<item> +<p> +Equivalent to not having configured the callback.</p> +</item> +</taglist> + +<p> +Multiple <c>disconnect_cb</c> options can be specified, in which +case the corresponding callbacks are applied until one of them returns +a value other than <c>ignore</c>. +All callbacks returning <c>ignore</c> is equivalent to not having +configured them.</p> + +<p> +Defaults to a single callback returning <c>dpr</c>.</p> +</item> + +<marker id="watchdog_timer"/> <tag><c>{watchdog_timer, TwInit}</c></tag> <item> <code> @@ -902,10 +1007,9 @@ 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> +<marker id="reconnect_timer"/> <tag><c>{reconnect_timer, Tc}</c></tag> <item> <code> @@ -1161,7 +1265,7 @@ at the time the diameter application was started.</p> <!-- ===================================================================== --> <func> -<name>remove_transport(SvcName, Pred) -> ok</name> +<name>remove_transport(SvcName, Pred) -> ok | {error, Reason}</name> <fsummary>Remove previously added transports.</fsummary> <type> <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v> @@ -1171,6 +1275,7 @@ at the time the diameter application was started.</p> <v> | fun((<seealso marker="#transport_ref">transport_ref()</seealso>, list()) -> boolean())</v> <v> | fun((list()) -> boolean())</v> <v>MFA = {atom(), atom(), list()}</v> +<v>Reason = term()</v> </type> <desc> <p> @@ -1196,15 +1301,12 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end </code> <p> -Removing a transport causes all associated transport connections to -be broken. -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 -DPA or timeout.</p> - -<!-- TODO: document the timeout value, possibly make configurable. --> +Removing a transport causes the corresponding transport processes to +be asked to terminate. +Whether or not a DPR message is sent to a peer is +controlled by +value of <seealso marker="disconnect_cb">disconnect_cb</seealso> +configured on the transport.</p> <marker id="service_info"/> </desc> diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 9d8a6568eb..ac056c2d39 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -309,12 +309,12 @@ by either <seealso marker="#handle_answer">handle_answer/4</seealso> or <seealso marker="#handle_error">handle_error/4</seealso> depending on whether or not an answer message is received from the peer. If the transport becomes unavailable after <seealso -marker="prepare_request">prepare_request/3</seealso> then a new <seealso +marker="#prepare_request">prepare_request/3</seealso> then a new <seealso marker="#pick_peer">pick_peer/4</seealso> callback may take place to failover to an alternate peer, after which <seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso> takes the place of <seealso -marker="prepare_request">prepare_request/3</seealso> in resending the +marker="#prepare_request">prepare_request/3</seealso> in resending the request. There is no guarantee that a <seealso marker="#pick_peer">pick_peer/4</seealso> callback to select diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index d9b36a1e09..0c8b41397a 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -149,9 +149,9 @@ contains the binary to send.</p> <tag><c>{diameter, {close, Pid}}</c></tag> <item> <p> -A request to close the transport connection. -The transport process should terminate after closing the -connection. +A request to terminate the transport process after having received DPA +in response to DPR. +The transport process should exit. <c>Pid</c> is the pid() of the parent process.</p> </item> |