From f472ddbedec007b37fff5b40a379b97656f15bce Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 12 Oct 2012 02:51:34 +0200 Subject: Document transport_opt() disconnect_cb Callback makes sending of DPR configurable. --- lib/diameter/doc/src/diameter.xml | 149 +++++++++++++++++++++++----- lib/diameter/doc/src/diameter_transport.xml | 6 +- 2 files changed, 128 insertions(+), 27 deletions(-) (limited to 'lib/diameter/doc/src') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 80863f8eff..e1442a108e 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -822,6 +822,7 @@ request a connection with one peer over SCTP or another To listen on both SCTP and TCP, define one transport for each.

+ {applications, [application_alias()]}

@@ -831,6 +832,7 @@ Defaults to all applications configured on the service in question. Applications not configured on the service in question are ignored.

 + {capabilities, [capability()]}

@@ -845,33 +847,136 @@ TLS is desired over TCP as implemented by diameter_tcp(3).

 + {capabilities_cb, evaluable()}

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 transport_ref() and the -#diameter_caps{} record of the connection. -Returning ok accepts the connection. -Returning integer() causes an incoming -CER to be answered with the specified Result-Code. -Returning discard causes an incoming CER to -be discarded. -Returning unknown is equivalent to returning 3010, -DIAMETER_UNKNOWN_PEER. -Returning anything but ok or a 2xxx series result -code causes the transport connection to be broken.

+Applied to the transport_ref() and +#diameter_caps{} record of the connection.

+ +

+The return value can have one of the following types.

+ +ok + +

+Accept the connection.

+ + +integer() + +

+Causes an incoming CER to be answered with the specified Result-Code.

+ + +discard + +

+Causes an incoming CER to be discarded without CEA being sent.

+ + +unknown +

+Equivalent to returning 3010, DIAMETER_UNKNOWN_PEER.

+ + + +

+Returning anything but ok or a 2xxx series result +code causes the transport connection to be broken. Multiple capabilities_cb options can be specified, in which case the corresponding callbacks are applied until either all return ok or one does not.

+ - + +{disconnect_cb, evaluable()} + + +

+A callback invoked prior to requesting shutdown of a transport process +for a transport connection having watchdog state OKAY. +Applied to Reason=transport|service|application and the +transport_ref() and +diameter_app:peer() +in question, Reason indicating whether the the diameter +application is being stopped, the service in question is being stopped +at diameter:stop_service/1 or +the transport in question is being removed at diameter:remove_transport/2, +respectively.

+ +

+The return value can have one of the following types.

+ + +{dpr, [option()]} + +

+Causes Disconnect-Peer-Request to be sent to the peer, transport +process shutdown being requested after reception of +Disconnect-Peer-Answer or timeout. +An option() can be one of the following.

+ + +{timeout, integer()} + +

+Transport process shutdown will be requested after this number of +milliseconds if DPA is not received. +Defaults to 1000.

 +{cause, 0|rebooting|1|busy|2|goaway} + +

+The Disconnect-Cause to send, REBOOTING, BUSY and +DO_NOT_WANT_TO_TALK_TO_YOU respectively. +Defaults to rebooting for Reason=service|application and +goaway for Reason=transport.

+ + + + +dpr + +

+Equivalent to {dpr, []}.

+ + +close + +

+Causes transport process shutdown to be requested without +Disconnect-Peer-Request being sent to the peer.

+ + +ignore + +

+Equivalent to not having configured the callback.

+ + + +

+Multiple disconnect_cb options can be specified, in which +case the corresponding callbacks are applied until one of them returns +a value other than ignore. +All callbacks returning ignore is equivalent to not having +configured them.

+ +

+Defaults to a single callback returning dpr.

+ + + {watchdog_timer, TwInit} @@ -891,10 +996,9 @@ the callback.

An integer value must be at least 6000 as required by RFC 3539. Defaults to 30000 if unspecified.

- - + {reconnect_timer, Tc} @@ -1185,15 +1289,12 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end

-Removing a transport causes all associated transport connections to -be broken. -A DPR message with -Disconnect-Cause DO_NOT_WANT_TO_TALK_TO_YOU 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.

- - +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 disconnect_cb +configured on the transport.

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.

{diameter, {close, Pid}}

-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. Pid is the pid() of the parent process.

 -- cgit v1.2.3 From 8b1bba0c46e6afdcd820c09ba8e432e447088854 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Tue, 6 Nov 2012 16:14:00 +0100 Subject: Fix broken doc link Broken in commit e28ced7b. --- lib/diameter/doc/src/diameter_app.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/diameter/doc/src') 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 handle_answer/4 or handle_error/4 depending on whether or not an answer message is received from the peer. If the transport becomes unavailable after prepare_request/3 then a new prepare_request/3 then a new pick_peer/4 callback may take place to failover to an alternate peer, after which prepare_retransmit/3 takes the place of prepare_request/3 in resending the +marker="#prepare_request">prepare_request/3 in resending the request. There is no guarantee that a pick_peer/4 callback to select -- cgit v1.2.3 From d192dc3d1e0726ab23ebeaa39cca965535952032 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 8 Nov 2012 16:28:47 +0100 Subject: Correct diameter:remove_transport/2 doc Error can be returned if the service process goes down while remove_transport is ongoing. --- lib/diameter/doc/src/diameter.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'lib/diameter/doc/src') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index e1442a108e..b40161045d 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -1254,7 +1254,7 @@ at the time the diameter application was started.

-remove_transport(SvcName, Pred) -> ok +remove_transport(SvcName, Pred) -> ok | {error, Reason} Remove previously added transports. SvcName = service_name() @@ -1264,6 +1264,7 @@ at the time the diameter application was started.

    | fun((transport_ref(), list()) -> boolean())     | fun((list()) -> boolean()) MFA = {atom(), atom(), list()} +Reason = term()

-- cgit v1.2.3