diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_app.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 148 |
1 files changed, 80 insertions, 68 deletions
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index a9ae0ebbec..4a4b212787 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -5,7 +5,7 @@ <header> <copyright> -<year>2011</year> +<year>2011</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,8 +45,8 @@ A diameter service as started by <seealso marker="diameter#start_service">diameter:start_service/2</seealso> 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 +the application. +The messages and AVPs of the application are defined in a dictionary file whose format is documented in <seealso marker="diameter_dict">diameter_dict(4)</seealso> while the callback module is documented here. @@ -106,11 +106,13 @@ and, for the call-specific callbacks, any extra arguments passed to <taglist> +<marker id="capabilities"/> + <tag><c>capabilities() = #diameter_caps{}</c></tag> <item> <p> A record containing the identities of -the local and remote Diameter peers 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 @@ -119,6 +121,8 @@ Optional or possibly multiple values are encoded as lists of values, mandatory values as the bare value.</p> </item> +<marker id="message"/> + <tag><c>message() = record() | list()</c></tag> <item> <p> @@ -136,8 +140,8 @@ list of <c>{FieldName, FieldValue}</c> pairs.</p> <p> A third representation allows a message to be specified as a list -whose head is a <c>diameter_header</c> record and whose tail is a list -of <c>diameter_avp</c> records. +whose head is a <c>#diameter_header{}</c> record and whose tail is a list +of <c>#diameter_avp{}</c> records. This representation is used by diameter itself when relaying requests as directed by the return value of a <seealso marker="#handle_request">handle_request/3</seealso> @@ -149,15 +153,18 @@ are sent exactly as specified.</p> </item> +<marker id="packet"/> + <tag><c>packet() = #diameter_packet{}</c></tag> <item> <p> -A container for incoming and outgoing Diameters message that's passed +A container for incoming and outgoing Diameter messages that's passed through encode/decode and transport. -Fields of a packet() record should not be set in return values except -as documented.</p> +Fields should not be set in return values except as documented.</p> </item> +<marker id="peer_ref"/> + <tag><c>peer_ref() = term()</c></tag> <item> <p> @@ -165,20 +172,15 @@ A term identifying a transport connection with a Diameter peer. Should be treated opaquely.</p> </item> -<tag><c>peer() = {peer_ref(), capabilities()}</c></tag> +<marker id="peer"/> + +<tag><c>peer() = {<seealso marker="#peer_ref">peer_ref()</seealso>, <seealso marker="#capabilities">capabilities()</seealso>}</c></tag> <item> <p> A tuple representing a Diameter peer connection.</p> </item> -<tag><c>service_name() = term()</c></tag> -<item> -<p> -The service supporting the Diameter application. -Specified to <seealso -marker="diameter#start_service">diameter:start_service/2</seealso> -when starting the service.</p> -</item> +<marker id="state"/> <tag><c>state() = term()</c></tag> <item> @@ -211,9 +213,9 @@ process.</p> <name>Mod:peer_up(SvcName, Peer, State) -> NewState</name> <fsummary>Invoked when a transport connection has been established</fsummary> <type> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> -<v>State = NewState = state()</v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>State = NewState = <seealso marker="#state">state()</seealso></v> </type> <desc> <p> @@ -230,9 +232,9 @@ the callback module in question has been configured.</p> <name>Mod:peer_down(SvcName, Peer, State) -> NewState</name> <fsummary>Invoked when a transport connection has been lost.</fsummary> <type> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> -<v>State = NewState = state()</v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>State = NewState = <seealso marker="#state">state()</seealso></v> </type> <desc> <p> @@ -248,21 +250,17 @@ call to <seealso marker="#peer_up">peer_up/3</seealso>.</p> -> {ok, Peer} | {Peer, NewState} | false</name> <fsummary>Select a target peer for an outgoing request.</fsummary> <type> -<v>Candidates = [peer()]</v> -<v>Peer = peer() | false</v> -<v>SvcName = service_name()</v> -<v>State = NewState = state()</v> +<v>Candidates = [<seealso marker="#peer">peer()</seealso>]</v> +<v>Peer = <seealso marker="#peer">peer()</seealso> | false</v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>State = NewState = <seealso marker="#state">state()</seealso></v> </type> <desc> <p> Invoked as a consequence of a call to <seealso marker="diameter#call">diameter:call/4</seealso> to select a destination -peer for an outgoing request, the return value indicating the selected peer. -A new application state can also be returned but only if the Diameter -application in question was -configured with the option <c>call_mutates_state</c> set to -<c>true</c>, as documented for <seealso -marker="diameter#start_service">diameter:start_service/2</seealso>.</p> +peer for an outgoing request, the return value indicating the selected +peer.</p> <p> The candidate peers list will only include those @@ -282,7 +280,8 @@ equivalent when callback state is mutable, as are <c>{ok, Peer}</c> and <c>{Peer, State}</c>. Returning a peer as <c>false</c> causes <c>{error, no_connection}</c> to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>. -Returning a peer() from an initial pick_peer/4 callback will result in a +Returning a <seealso marker="#peer">peer()</seealso> from an initial +pick_peer/4 callback will result in a <seealso marker="#prepare_request">prepare_request/3</seealso> callback followed by either <seealso marker="#handle_answer">handle_answer/4</seealso> @@ -301,6 +300,19 @@ marker="#pick_peer">pick_peer/4</seealso> will be, since a retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.</p> +<note> +<p> +<c>{Peer, NewState}</c> and its equivalents can only be returned if +the Diameter application in question was +configured with the <seealso +marker="diameter#application_opt">diameter:application_opt()</seealso> +<c>{call_mutates_state, true}</c>. +Otherwise, the <c>State</c> argument is always +the intial value as configured on the application, not any subsequent +value returned by a <seealso marker="#peer_up">peer_up/3</seealso> +or <seealso marker="#peer_down">peer_down/3</seealso> callback.</p> +</note> + <marker id="prepare_request"/> </desc> @@ -310,10 +322,10 @@ received from a previously selected peer.</p> <name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name> <fsummary>Return a request for encoding and transport.</fsummary> <type> -<v>Packet = packet()</v> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> -<v>Action = {send, packet() | message()} | {discard, Reason} | discard</v> +<v>Packet = <seealso marker="#packet">packet()</seealso></v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>Action = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</v> </type> <desc> <p> @@ -325,14 +337,14 @@ callback need not be limited to this usage. Many implementations may simply want to return <c>{send, Packet}</c></p> <p> -A returned packet() should set the request to be encoded in its +A returned <seealso marker="#packet">packet()</seealso> should set the request to be encoded in its <c>msg</c> field and can set the <c>transport_data</c> field in order to pass information to the transport module. Extra arguments passed to <seealso marker="diameter#call">diameter:call/4</seealso> can be used to communicate transport data to the callback. -A returned packet() can also set the <c>header</c> field to a -<c>diameter_header</c> record in order to specify values that should +A returned <seealso marker="#packet">packet()</seealso> can also set the <c>header</c> field to a +<c>#diameter_header{}</c> record in order to specify values that should be preserved in the outgoing request, although this should typically not be necessary and allows the callback to set header values inappropriately. @@ -355,10 +367,10 @@ discarded}</c>.</p> <name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name> <fsummary>Return a request for encoding and retransmission.</fsummary> <type> -<v>Packet = packet()</v> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> -<v>Result = {send, packet() | message()} | {discard, Reason} | discard</v> +<v>Packet = <seealso marker="#packet">packet()</seealso></v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>Result = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</v> </type> <desc> <p> @@ -366,7 +378,7 @@ Invoked to return a request for encoding and retransmission. Has the same role as <seealso marker="#prepare_request">prepare_request/3</seealso> in the case that a peer connection is lost an an alternate peer selected but the -argument packet() is as returned by the initial +argument <seealso marker="#packet">packet()</seealso> is as returned by the initial <c>prepare_request/3</c>.</p> <p> @@ -385,10 +397,10 @@ discarded}</c>.</p> <name>Mod:handle_answer(Packet, Request, SvcName, Peer) -> Result</name> <fsummary>Receive an answer message from a peer.</fsummary> <type> -<v>Packet = packet()</v> -<v>Request = message()</v> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> +<v>Packet = <seealso marker="#packet">packet()</seealso></v> +<v>Request = <seealso marker="#message">message()</seealso></v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> <v>Result = term()</v> </type> <desc> @@ -401,7 +413,7 @@ specified.</p> <p> The decoded answer record is in the <c>msg</c> field of the argument -packet(), +<seealso marker="#packet">packet()</seealso>, the undecoded binary in the <c>packet</c> field. <c>Request</c> is the outgoing request message as was returned from <seealso marker="#prepare_request">prepare_request/3</seealso> or @@ -438,9 +450,9 @@ marker="diameter#start_service">diameter:start_service/2</seealso>.</p> <fsummary>Return an error from a outgoing request.</fsummary> <type> <v>Reason = timeout | failover | term()</v> -<v>Request = message()</v> -<v>SvcName = service_name()</v> -<v>Peer = peer()</v> +<v>Request = <seealso marker="#message">message()</seealso></v> +<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> +<v>Peer = <seealso marker="#peer">peer()</seealso></v> <v>Result = term()</v> </type> <desc> @@ -469,14 +481,14 @@ callback returned false.</p> <name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name> <fsummary>Receive an incoming request.</fsummary> <type> -<v>Packet = packet()</v> +<v>Packet = <seealso marker="#packet">packet()</seealso></v> <v>SvcName = term()</v> -<v>Peer = peer()</v> -<v>Action = Reply | {relay, Opts} | discard | {eval, Action, PostF}</v> -<v>Reply = {reply, message()} +<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>Action = Reply | {relay, [Opt]} | discard | {eval, Action, PostF}</v> +<v>Reply = {reply, <seealso marker="#message">message()</seealso>} | {protocol_error, 3000..3999}</v> -<v>Opts = diameter:call_opts()</v> -<v>PostF = diameter:evaluable()</v> +<v>Opt = <seealso marker="diameter#call_opt">diameter:call_opt()</seealso></v> +<v>PostF = <seealso marker="diameter#evaluable">diameter:evaluable()</seealso></v> </type> <desc> <p> @@ -492,13 +504,13 @@ itself as defining either the application in question or the Relay application.</p> <p> -The argument packet() has the following signature.</p> +The argument <seealso marker="#packet">packet()</seealso> has the following signature.</p> <code> #diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], + errors = [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso> | {<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>, #diameter_avp{}}], bin = binary(), transport_data = term()} </code> @@ -515,8 +527,8 @@ The <c>errors</c> 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. +answer <seealso marker="#message">message()</seealso> before sending it to the peer: +the returned <seealso marker="#message">message()</seealso> need only set any other required AVP's. Note that the errors detected by diameter are all of the 5xxx series (Permanent Failures). The <c>errors</c> list is empty if the request has been received in @@ -526,7 +538,7 @@ the relay application.</p> The <c>transport_data</c> field contains an arbitrary term passed into diameter from the transport module in question, or the atom <c>undefined</c> if the transport specified no data. -The term is preserved in the packet() containing any answer message +The term is preserved in the <seealso marker="#packet">packet()</seealso> containing any answer message sent back to the transport process unless another value is explicitly specified.</p> @@ -535,7 +547,7 @@ The semantics of each of the possible return values are as follows.</p> <taglist> -<tag><c>{reply, message()}</c></tag> +<tag><c>{reply, <seealso marker="#message">message()</seealso>}</c></tag> <item> <p> Send the specified answer message to the peer.</p> @@ -579,7 +591,7 @@ header of the relayed request.</p> The returned <c>Opts</c> should not specify <c>detach</c>. A subsequent <seealso marker="#handle_answer">handle_answer/4</seealso> callback for the relayed request must return its first -argument, the <c>diameter_packet</c> record containing the answer +argument, the <c>#diameter_packet{}</c> record containing the answer message. Note that the <c>extra</c> option can be specified to supply arguments that can distinguish the relay case from others if so desired. |