From a9a922ccfd5361c7c47d4a23cad97ded0bfde8cd Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Thu, 19 May 2011 12:28:37 +0200 Subject: Fix broken doc links. --- lib/diameter/doc/src/diameter_app.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/diameter/doc/src/diameter_app.xml') diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index c2fecce768..d78882c18d 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -236,7 +236,7 @@ the callback module in question has been configured.

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

+call to peer_up/3.

 -- cgit v1.2.3 From 14b63ae11e0a7c3d028ec4ff6e4532705a800157 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 12:34:22 +0200 Subject: Various documentation fixes and improvements. Added an introductory chapter to the User's Guide as well as more detailed release notes. --- lib/diameter/doc/src/diameter_app.xml | 182 +++++++++++++++++++--------------- 1 file changed, 104 insertions(+), 78 deletions(-) (limited to 'lib/diameter/doc/src/diameter_app.xml') diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index d78882c18d..fc359b9d1d 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -47,23 +47,12 @@ configures one of more Diameter applications, each of whose configuration specifies a callback that handles messages specific to its application. The messages and AVPs of the Diameter application are defined in a -specification file whose format is documented in +dictionary file whose format is documented in diameter_dict(4) while the callback module is documented here. The callback module implements the Diameter application-specific functionality of a service.

- -

-The arities of the callback functions below assume no extra arguments. -All functions will also be passed any extra arguments configured with -the callback module itself when calling diameter:start_service/2 -and, except for peer_up, peer_down and handle_request, any extra -arguments passed to diameter:call/4.

- -

A callback module must export all of the functions documented below. The functions themselves are of three distinct flavours:

@@ -72,8 +61,8 @@ The functions themselves are of three distinct flavours:

peer_up/3 and -peer_down/3 signal the attainment -or loss of communicativity with a Diameter peer.

+peer_down/3 signal the +attainment or loss of connectivity with a Diameter peer.

 @@ -98,6 +87,17 @@ is called in response to an incoming Diameter request message.

+ +

+The arities given for the the callback functions here assume no extra +arguments. +All functions will also be passed any extra arguments configured with +the callback module itself when calling diameter:start_service/2 +and, for the call-specific callbacks, any extra arguments passed to +diameter:call/4.

+ + @@ -131,8 +131,8 @@ a message as defined in a dictionary file is encoded as a record with one field for each component AVP. Equivalently, a message can also be encoded as a list whose head is the atom-valued message name (the record name minus any -prefix in the dictionary file) and whose tail is a list of -{FieldName, FieldValue} pairs.

+prefix specified in the relevant dictionary file) and whose tail is a +list of {FieldName, FieldValue} pairs.

A third representation allows a message to be specified as a list @@ -144,7 +144,8 @@ as directed by the return value of a callback. It differs from the other other two in that it bypasses the checks for messages that do not agree with their definitions in the dictionary in -question: messages are sent exactly as specified.

+question (since relays agents must handle arbitrary request): messages +are sent exactly as specified.

 @@ -153,8 +154,8 @@ question: messages are sent exactly as specified.

A container for incoming and outgoing Diameters message that's passed through encode/decode and transport. -Defined in diameter.hrl. -Fields should not be altered except as documented.

+Fields of a packet() record should not be set in return values except +as documented.

peer_ref() = term() @@ -243,11 +244,11 @@ call to peer_up/3.

-Mod:pick_peer(Cands, Reserved, SvcName, State) +Mod:pick_peer(Candidates, Reserved, SvcName, State) -> {ok, Peer} | {Peer, NewState} | false Select a target peer for an outgoing request. -Cands = [Peer] +Candidates = [peer()] Peer = peer() | false SvcName = service_name() State = NewState = state() @@ -266,11 +267,9 @@ marker="diameter#start_service">diameter:start_service/2.

The candidate peers list will only include those which are selected by any filter option specified in the call to -diameter:call/4.

- +diameter:call/4, and only +those which have indicated support for the Diameter application in +question.

The return values false and {false, State} are @@ -326,13 +325,14 @@ A returned packet() should set the request to be encoded in its to pass information to the transport module. Extra arguments passed to diameter:call/4 can be used to -communicate transport data to the callback.

- -

-Any returned packet() can set the header field to a +communicate transport data to the callback. +A returned packet() can also set the header field to a diameter_header record in order to specify values that should -be preserved in the outgoing request. -A specified message_length is ignored.

+be preserved in the outgoing request, although this should typically +not be necessary and allows the callback to set header values +inappropriately. +A returned length, cmd_code or application_id is +ignored.

Returning {discard, Reason} causes the request to be aborted @@ -361,7 +361,7 @@ 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 -Packet passed to prepare_retransmit/3 is as returned by +argument packet() is as returned by the initial prepare_request/3.

@@ -391,10 +391,12 @@ 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.

+callback takes place unless the detach option was +specified.

-The decoded answer record is in the msg field of Packet, +The decoded answer record is in the msg field of the argument +packet(), the undecoded binary in the packet field. Request is the outgoing request message as was returned from prepare_request/3 or @@ -414,8 +416,10 @@ 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}. -There is no handle_error/4 callback in this case. +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.

@@ -440,7 +444,8 @@ 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.

+callback takes place (unless the detach option was +specified).

Reason timeout indicates that an answer message has not been @@ -449,8 +454,7 @@ 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. -

+callback returned false.

@@ -463,40 +467,33 @@ callback returned false. Packet = packet() SvcName = term() Peer = peer() -Action = Reply | NoReply | Relay | {eval, Action, ContF} +Action = Reply | {relay, Opts} | discard | {eval, Action, ContF} Reply = {reply, message()} - | {protocol_error, ResultCode} -NoReply = discard -Relay = {relay, Opts} -Opts = list() + | {protocol_error, 3000..3999} +Opts = diameter:call_opts() ContF = diameter:evaluable() -ResultCode = 3000..3999

-Invoked when a request message is received from a peer.

- -

+Invoked when a request message is received from a peer. The application in which the callback takes place (that is, the callback module as configured with diameter:start_service/2) is determined by the Application Identifier in the header of the -incoming Diameter request message, the selected module being the one +incoming request message, the selected module being the one whose corresponding dictionary declares -itself as defining the application in question, or the RFC 3588 relay -application if the specific application is unsupported but the relay -application has been advertised.

+itself as defining either the application in question or the Relay +application.

-The packet() in which the incoming request is communicated has the -following signature.

+The argument packet() has the following signature.

#diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = [integer() | {integer(), #diameter_avp{}}], + errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], bin = binary(), transport_data = term()} @@ -509,12 +506,16 @@ in diameter_dict(4).

-The errors field specifies any non-protocol errors that were -encountered in decoding the request and can be returned in a -reply tuple to have diameter set the Result-Code and Failed-AVP -AVP's appropriately. -The list is empty if the request has been received in the relay -application.

+The errors field specifies any Result-Code's identifying errors +that were encountered in decoding the request. +In this case diameter will set both Result-Code and +Failed-AVP AVP's in a returned +answer message() before sending it to the peer: +the returned message() need only set any other required AVP's. +Note that the errors detected by diameter are all of the 5xxx series +(Permanent Failures). +The errors list is empty if the request has been received in +the relay application.

The transport_data field contains an arbitrary term passed into @@ -525,34 +526,59 @@ sent back to the transport process unless another value is explicitly specified.

-The semantics of each of the possible return values are as follows. -(TODO: more.)

+The semantics of each of the possible return values are as follows.

-{reply, Answer} +{reply, message()}

Send the specified answer message to the peer.

 -{relay, Opts} +{protocol_error, 3000..3999}

-Relay a request to another peer.

- - -{protocol_error, ResultCode} - +Send an answer message to the peer containing the specified +protocol error. +Equivalent to

+ +{reply, ['answer-message' | Avps] +

-Send an answer message to the peer containing the specified 3xxx -protocol error.

+where Avps sets the Origin-Host, Origin-Realm, the specified +Result-Code and (if the request sent one) Session-Id AVP's.

-RFC 3588 mandates that only answers with a 3xxx series +Note that RFC 3588 mandates that only answers with a 3xxx series Result-Code (protocol errors) may set the E bit. -Returning a non-3xxx value in a {protocol_error, ResultCode} -tuple will cause the request process in question to fail.

+Returning a non-3xxx value in a protocol_error tuple +will cause the request process in question to fail.

+ + +{relay, Opts} + +

+Relay a request to another peer. +The appropriate Route-Record AVP will be added to the relayed request +by diameter and pick_peer/4 +and prepare_request/3 +callback will take place just as if diameter:call/4 had been called +explicitly. +However, returning a relay tuple also causes the End-to-End +Identifier to be preserved in the header of the relayed request as +required by RFC 3588.

+ +

+The returned Opts should not specify detach and +the handle_answer/4 +callback following from a relayed request must return its first +argument, the diameter_packet record containing the answer +message. +Note that the extra option can be specified to supply arguments +that can distinguish the relay case from others if so desired, +although the form of the request message may be sufficient.

 discard @@ -565,14 +591,14 @@ Discard the request.

Handle the request as if Action has been returned and then -evaluate the evaluable() ContF in the request process.

+evaluate ContF in the request process.

Note that diameter will respond to protocol errors in an incoming -request without invoking the a handle_request/3 callback.

+request without invoking handle_request/3.

 -- cgit v1.2.3