From e28ced7b0be4282063ca111782f13f4ba4f6c3ac Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 5 Oct 2012 01:47:30 +0200 Subject: Improve other diameter_app doc --- lib/diameter/doc/src/diameter_app.xml | 192 ++++++++++++++++++++-------------- 1 file changed, 112 insertions(+), 80 deletions(-) diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 98c8b8c807..9d8a6568eb 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -112,7 +112,8 @@ and, for the call-specific callbacks, any extra arguments passed to

A record containing the identities of -the local Diameter node and the remote Diameter peer having an established transport +the local Diameter node and the remote Diameter peer having an +established transport connection, as well as the capabilities as determined by capabilities exchange. Each field of the record is a 2-tuple consisting of @@ -168,13 +169,14 @@ Fields should not be set in return values except as documented.

peer_ref() = term()

-A term identifying a transport connection with a Diameter peer. -Should be treated opaquely.

+A term identifying a transport connection with a Diameter peer.

 -peer() = {peer_ref(), capabilities()} +peer() = + {peer_ref(), + capabilities()}

A tuple representing a Diameter peer connection.

@@ -219,10 +221,29 @@ process.

-Invoked when a transport connection has been established -and a successful capabilities exchange has indicated that the peer -supports the Diameter application of the application on which -the callback module in question has been configured.

+Invoked to signal the availability of a peer connection. +In particular, capabilities exchange with the peer has indicated +support for the application in question, the RFC 3539 watchdog state +machine for the connection has reached state OKAY and Diameter +messages can be both sent and received.

+ + +

+A watchdog state machine can reach state OKAY from state +SUSPECT without a new capabilities exchange taking place. +A new transport connection (and capabilities exchange) results in a +new peer_ref().

+ + + +

+There is no requirement that a callback return before incoming +requests are received: handle_request/3 callbacks must be +handled independently of peer_up/3 and peer_down/3.

+ @@ -238,36 +259,42 @@ the callback module in question has been configured.

-Invoked when a transport connection has been lost following a previous -call to peer_up/3.

+Invoked to signal that a peer connection is no longer available +following a previous call to peer_up/3. +In particular, that the RFC 3539 watchdog state machine for the +connection has left state OKAY and the peer will no longer be a +candidate in pick_peer() +callbacks.

 -Mod:pick_peer(Candidates, Reserved, SvcName, State) - -> {ok, Peer} | {Peer, NewState} | false +Mod:pick_peer(Candidates, _Reserved, SvcName, State) + -> Selection | false Select a target peer for an outgoing request. Candidates = [peer()] -Peer = peer() | false SvcName = diameter:service_name() State = NewState = state() +Selection = {ok, Peer} | {Peer, NewState} +Peer = peer() | false

Invoked as a consequence of a call to diameter:call/4 to select a destination -peer for an outgoing request, the return value indicating the selected -peer.

+peer for an outgoing request. +The return value indicates the selected peer.

-The candidate peers list will only include those -which are selected by any filter option specified in the call to -diameter:call/4, and only -those which have indicated support for the Diameter application in -question. +The candidate list contains only those peers that have advertised +support for the Diameter application in question during capabilities +exchange, that have not be excluded by a filter option in +the call to diameter:call/4 +and whose watchdog state machine is in the OKAY state. The order of the elements is unspecified except that any peers whose Origin-Host and Origin-Realm matches that of the outgoing request (in the sense of a {filter, {all, [host, realm]}} @@ -275,36 +302,40 @@ option to diameter:call/4) will be placed at the head of the list.

-The return values false and {false, State} are -equivalent when callback state is mutable, as are -{ok, Peer} and {Peer, State}. -Returning a peer as false causes {error, no_connection} -to be returned from diameter:call/4. -Returning a peer() from an initial -pick_peer/4 callback will result in a -prepare_request/3 callback -followed by either handle_answer/4 +A callback that returns a peer() will be followed by a +prepare_request/3 +callback and, if the latter indicates that the request should be sent, +by either handle_answer/4 or handle_error/4 depending on whether or not an answer message is received from the peer. -If transport with the peer is lost before this then a new pick_peer/4 callback takes place to -select an alternate peer.

- -

-Note that there is no guarantee that a 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 +request. +There is no guarantee that a pick_peer/4 callback to select -an alternate peer will be followed by any additional callbacks, only -that the initial pick_peer/4 will be, since a +an alternate peer will be followed by any additional callbacks since a retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.

+

+Returning false or {false, NewState} causes {error, +no_connection} to be returned from diameter:call/4.

+ +

+The return values false and {false, State} (that is, +NewState = State) are equivalent, as are {ok, Peer} and +{Peer, State}.

+

-{Peer, NewState} and its equivalents can only be returned if -the Diameter application in question was -configured with the {Peer, NewState} is only allowed if +the Diameter application in question was configured with the diameter:application_opt() {call_mutates_state, true}. Otherwise, the State argument is always @@ -360,7 +391,7 @@ ignored.

A returned PostF will be evaluated on any encoded #diameter_packet{} prior to transmission, the bin field -of this record containing the encoded binary. +containing the encoded binary. The return value is ignored.

@@ -395,8 +426,9 @@ Invoked to return a request for encoding and retransmission. Has the same role as prepare_request/3 in the case that a peer connection is lost an an alternate peer selected but the -argument packet() is as returned by the initial -prepare_request/3.

+argument packet() is as returned +by the initial prepare_request/3.

Returning {discard, Reason} causes the request to be aborted @@ -423,40 +455,41 @@ discarded}.

Invoked when an answer message is received from a peer. -The return value is returned from the call to diameter:call/4 for which the -callback takes place unless the detach option was -specified.

+The return value is returned from diameter:call/4 unless the +detach option was specified.

-The decoded answer record is in the msg field of the argument -packet(), -the undecoded binary in the packet field. +The decoded answer record and undecoded binary are in the msg +and bin fields of the argument +packet() respectively. Request is the outgoing request message as was returned from prepare_request/3 or -prepare_retransmit/3 -before the request was passed to the transport.

+prepare_retransmit/3.

For any given call to diameter:call/4 there is at most one -call to the handle_answer callback of the application in question: any +handle_answer/4 callback: any duplicate answer (due to retransmission or otherwise) is discarded. -Similarly, only one of handle_answer/4 or handle_error/4 is -called for any given request.

+Similarly, only one of handle_answer/4 or +handle_error/4 is +called.

By default, an incoming answer message that cannot be successfully -decoded causes the request process in question to fail, causing the -relevant call to diameter:call/4 -to return {error, failure} (unless the detach option was -specified). -In particular, there is no handle_error/4 callback in this +decoded causes the request process to fail, causing +diameter:call/4 +to return {error, failure} unless the detach option was +specified. +In particular, there is no handle_error/4 callback in this case. -Application configuration may change this behaviour as described for -diameter:start_service/2.

+The diameter:application_opt() +answer_errors can be set to change this behaviour.

 @@ -474,21 +507,20 @@ marker="diameter#start_service">diameter:start_service/2.

-Invoked when an error occurs before an answer message is received from -a peer in response to an outgoing request. -The return value is returned from the call to diameter:call/4 for which the -callback takes place (unless the detach option was -specified).

+Invoked when an error occurs before an answer message is received +in response to an outgoing request. +The return value is returned from diameter:call/4 unless the +detach option was specified.

Reason timeout indicates that an answer message has not been -received within the required time. +received within the time specified with the corresponding diameter:call_opt(). Reason failover indicates that the transport connection to the peer to which the request has -been sent has been lost but that not alternate node was available, -possibly because a pick_peer/4 -callback returned false.

+been sent has become unavailable and that not alternate peer was +not selected.

 @@ -504,8 +536,7 @@ callback returned false.

Action = Reply | {relay, [Opt]} | discard - | {eval, Action, PostF} - | {eval_packet, Action, PostF} + | {eval|eval_packet, Action, PostF} Reply = {reply, message()} | {protocol_error, 3000..3999} Opt = diameter:call_opt() @@ -624,7 +655,8 @@ causes the request to be answered with 3002 (DIAMETER_UNABLE_TO_DELIVER).

discard

-Discard the request.

+Discard the request. +No answer message is sent to the peer.

 {eval, Action, PostF} @@ -640,7 +672,7 @@ The return value is ignored.

Like eval but evaluate PostF on any encoded #diameter_packet{} prior to transmission, the bin field -of this record containing the encoded binary. +containing the encoded binary. The return value is ignored.

 -- cgit v1.2.3