diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_app.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 256 |
1 files changed, 106 insertions, 150 deletions
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 290b8a3984..c0aa2518af 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,5 +1,8 @@ <?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> +<!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY % ents SYSTEM "diameter.ent" > + %ents; +]> <erlref> <header> @@ -41,15 +44,13 @@ Callback module of a Diameter application.</modulesummary> <description> <p> -A diameter service as started by <seealso -marker="diameter#start_service">diameter:start_service/2</seealso> +A diameter service as started by &mod_start_service; configures one of more Diameter applications, each of whose configuration specifies a callback that handles messages specific to 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. +&man_dict; while the callback module is documented here. The callback module implements the Diameter application-specific functionality of a service.</p> @@ -60,26 +61,24 @@ The functions themselves are of three distinct flavours:</p> <list> <item> <p> -<seealso marker="#peer_up">peer_up/3</seealso> and -<seealso marker="#peer_down">peer_down/3</seealso> signal the +&peer_up; and &peer_down; signal the attainment or loss of connectivity with a Diameter peer.</p> </item> <item> <p> -<seealso marker="#pick_peer">pick_peer/4</seealso>, -<seealso marker="#prepare_request">prepare_request/3</seealso>, -<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>, -<seealso marker="#handle_answer">handle_answer/4</seealso> -and <seealso marker="#handle_error">handle_error/4</seealso> are (or may -be) called as a consequence of a call to <seealso -marker="diameter#call">diameter:call/4</seealso> to send an outgoing +&pick_peer;, +&prepare_request;, +&prepare_retransmit;, +&handle_answer; +and &handle_error; are (or may be) called as a consequence of a call +to &mod_call; to send an outgoing Diameter request message.</p> </item> <item> <p> -<seealso marker="#handle_request">handle_request/3</seealso> +&handle_request; is called in response to an incoming Diameter request message.</p> </item> @@ -92,10 +91,9 @@ is called in response to an incoming Diameter request message.</p> 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 <seealso -marker="diameter#start_service">diameter:start_service/2</seealso> +the callback module itself when calling &mod_start_service; and, for the call-specific callbacks, any extra arguments passed to -<seealso marker="diameter#call">diameter:call/4</seealso>.</p> +&mod_call;.</p> </note> <!-- ===================================================================== --> @@ -128,7 +126,7 @@ mandatory values as the bare value.</p> <item> <p> The representation of a Diameter message as passed to -<seealso marker="diameter#call">diameter:call/4</seealso>. +&mod_call;. The record representation is as outlined in <seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>: @@ -145,7 +143,7 @@ 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> +&handle_request; 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 @@ -174,9 +172,7 @@ A term identifying a transport connection with a Diameter peer.</p> <marker id="peer"/> -<tag><c>peer() = - {<seealso marker="#peer_ref">peer_ref()</seealso>, - <seealso marker="#capabilities">capabilities()</seealso>}</c></tag> +<tag><c>peer() = {&peer_ref;, &capabilities;}</c></tag> <item> <p> A tuple representing a Diameter peer connection.</p> @@ -188,13 +184,9 @@ A tuple representing a Diameter peer connection.</p> <item> <p> The state maintained by the application callback functions -<seealso marker="#peer_up">peer_up/3</seealso>, -<seealso marker="#peer_down">peer_down/3</seealso> and (optionally) -<seealso marker="#pick_peer">pick_peer/4</seealso>. +&peer_up;, &peer_down; and (optionally) &pick_peer;. The initial state is configured in the call to -<seealso -marker="diameter#start_service">diameter:start_service/2</seealso> -that configures the application on a service. +&mod_start_service; that configures the application on a service. Callback functions returning a state are evaluated in a common service-specific process while those not returning state are evaluated in a request-specific @@ -215,9 +207,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 = <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> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> +<v>State = NewState = &state;</v> </type> <desc> <p> @@ -238,11 +230,8 @@ new peer_ref().</p> <note> <p> There is no requirement that a callback return before incoming -requests are received: <seealso -marker="#handle_request">handle_request/3</seealso> callbacks must be -handled independently of <seealso -marker="#peer_up">peer_up/3</seealso> and <seealso -marker="#peer_down">peer_down/3</seealso>.</p> +requests are received: &handle_request; callbacks must be +handled independently of &peer_up; and &peer_down;.</p> </note> <marker id="peer_down"/> @@ -253,19 +242,17 @@ marker="#peer_down">peer_down/3</seealso>.</p> <name>Mod:peer_down(SvcName, Peer, State) -> NewState</name> <fsummary>Invoked when a transport connection has been lost.</fsummary> <type> -<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> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> +<v>State = NewState = &state;</v> </type> <desc> <p> Invoked to signal that a peer connection is no longer available -following a previous call to <seealso -marker="#peer_up">peer_up/3</seealso>. +following a previous call to &peer_up;. In particular, that the RFC 3539 watchdog state machine for the connection has left state <c>OKAY</c> and the peer will no longer be a -candidate in <seealso marker="#pick_peer">pick_peer()</seealso> -callbacks.</p> +candidate in &pick_peer; callbacks.</p> <marker id="pick_peer"/> </desc> @@ -276,16 +263,15 @@ callbacks.</p> -> Selection | false</name> <fsummary>Select a target peer for an outgoing request.</fsummary> <type> -<v>Candidates = [<seealso marker="#peer">peer()</seealso>]</v> -<v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v> -<v>State = NewState = <seealso marker="#state">state()</seealso></v> +<v>Candidates = [&peer;]</v> +<v>SvcName = &mod_service_name;</v> +<v>State = NewState = &state;</v> <v>Selection = {ok, Peer} | {Peer, NewState}</v> -<v>Peer = <seealso marker="#peer">peer()</seealso> | false</v> +<v>Peer = &peer; | false</v> </type> <desc> <p> -Invoked as a consequence of a call to <seealso -marker="diameter#call">diameter:call/4</seealso> to select a destination +Invoked as a consequence of a call to &mod_call; to select a destination peer for an outgoing request. The return value indicates the selected peer.</p> @@ -293,39 +279,34 @@ The return value indicates the selected peer.</p> 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 <c>filter</c> option in -the call to <seealso marker="diameter#call">diameter:call/4</seealso> +the call to &mod_call; and whose watchdog state machine is in the <c>OKAY</c> 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 <c>{filter, {all, [host, realm]}}</c> -option to <seealso marker="diameter#call">diameter:call/4</seealso>) +option to &mod_call;) will be placed at the head of the list.</p> <p> A callback that returns a peer() will be followed by a -<seealso marker="#prepare_request">prepare_request/3</seealso> +&prepare_request; callback and, if the latter indicates that the request should be sent, -by either <seealso marker="#handle_answer">handle_answer/4</seealso> -or <seealso marker="#handle_error">handle_error/4</seealso> depending +by either &handle_answer; +or &handle_error; 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="#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 +If the transport becomes unavailable after &prepare_request; then a +new &pick_peer; callback may take place to +failover to an alternate peer, after which &prepare_retransmit; takes the +place of &prepare_request; in resending the request. -There is no guarantee that a <seealso -marker="#pick_peer">pick_peer/4</seealso> callback to select +There is no guarantee that a &pick_peer; callback to select 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.</p> <p> Returning <c>false</c> or <c>{false, NewState}</c> causes <c>{error, -no_connection}</c> to be returned from <seealso -marker="diameter#call">diameter:call/4</seealso>.</p> +no_connection}</c> to be returned from &mod_call;.</p> <p> The return values <c>false</c> and <c>{false, State}</c> (that is, @@ -335,13 +316,12 @@ The return values <c>false</c> and <c>{false, State}</c> (that is, <note> <p> The return value <c>{Peer, NewState}</c> is only allowed 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>. +the Diameter application in question was configured with the +&mod_application_opt; <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> +value returned by a &peer_up; +or &peer_down; callback.</p> </note> <marker id="prepare_request"/> @@ -353,15 +333,13 @@ or <seealso marker="#peer_down">peer_down/3</seealso> callback.</p> <name>Mod:prepare_request(Packet, SvcName, Peer) -> Action</name> <fsummary>Return a request for encoding and transport.</fsummary> <type> -<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>Packet = &packet;</v> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> <v>Action = Send | Discard | {eval_packet, Action, PostF}</v> -<v>Send = {send, <seealso marker="#packet">packet()</seealso> - | <seealso marker="#message">message()</seealso>}</v> +<v>Send = {send, &packet; | &message;}</v> <v>Discard = {discard, Reason} | discard</v> -<v>PostF = - <seealso marker="diameter#evaluable">diameter:evaluable()</seealso>}</v> +<v>PostF = &mod_evaluable;}</v> </type> <desc> <p> @@ -371,16 +349,15 @@ to modify the outgoing request. Many implementations may simply want to return <c>{send, Packet}</c></p> <p> -A returned <seealso marker="#packet">packet()</seealso> should set the +A returned &packet; 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 process. -Extra arguments passed to <seealso -marker="diameter#call">diameter:call/4</seealso> can be used to +Extra arguments passed to &mod_call; can be used to communicate transport (or any other) data to the callback.</p> <p> -A returned <seealso marker="#packet">packet()</seealso> can set +A returned &packet; can set the <c>header</c> field to a <c>#diameter_header{}</c> to specify values that should be preserved in the outgoing request, values otherwise being those in @@ -396,8 +373,7 @@ The return value is ignored.</p> <p> Returning <c>{discard, Reason}</c> causes the request to be aborted -and the <seealso -marker="diameter#call">diameter:call/4</seealso> for which the +and the &mod_call; for which the callback has taken place to return <c>{error, Reason}</c>. Returning <c>discard</c> is equivalent to returning <c>{discard, discarded}</c>.</p> @@ -410,30 +386,25 @@ discarded}</c>.</p> <name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Action</name> <fsummary>Return a request for encoding and retransmission.</fsummary> <type> -<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>Packet = &packet;</v> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> <v>Action = Send | Discard | {eval_packet, Action, PostF}</v> -<v>Send = {send, <seealso marker="#packet">packet()</seealso> - | <seealso marker="#message">message()</seealso>}</v> +<v>Send = {send, &packet; | &message;}</v> <v>Discard = {discard, Reason} | discard</v> -<v>PostF = - <seealso marker="diameter#evaluable">diameter:evaluable()</seealso>}</v> +<v>PostF = &mod_evaluable;}</v> </type> <desc> <p> 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 +Has the same role as &prepare_request; in the case that a peer connection is lost an an alternate peer selected but the -argument <seealso marker="#packet">packet()</seealso> is as returned -by the initial <seealso -marker="#prepare_request">prepare_request/3</seealso>.</p> +argument &packet; is as returned +by the initial &prepare_request;.</p> <p> Returning <c>{discard, Reason}</c> causes the request to be aborted -and a <seealso -marker="#handle_error">handle_error/4</seealso> callback to +and a &handle_error; callback to take place with <c>Reason</c> as initial argument. Returning <c>discard</c> is equivalent to returning <c>{discard, discarded}</c>.</p> @@ -446,49 +417,41 @@ 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 = <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>Packet = &packet;</v> +<v>Request = &message;</v> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> <v>Result = term()</v> </type> <desc> <p> Invoked when an answer message is received from a peer. -The return value is returned from <seealso -marker="diameter#call">diameter:call/4</seealso> unless the +The return value is returned from &mod_call; unless the <c>detach</c> option was specified.</p> <p> The decoded answer record and undecoded binary are in the <c>msg</c> and <c>bin</c> fields of the argument -<seealso marker="#packet">packet()</seealso> respectively. +&packet; respectively. <c>Request</c> is the outgoing request message as was returned from -<seealso marker="#prepare_request">prepare_request/3</seealso> or -<seealso - marker="#prepare_retransmit">prepare_retransmit/3</seealso>.</p> +&prepare_request; or &prepare_retransmit;.</p> <p> -For any given call to <seealso -marker="diameter#call">diameter:call/4</seealso> there is at most one -<seealso marker="#handle_answer">handle_answer/4</seealso> callback: any +For any given call to &mod_call; there is at most one +&handle_answer; callback: any duplicate answer (due to retransmission or otherwise) is discarded. -Similarly, only one of <seealso -marker="#handle_answer">handle_answer/4</seealso> or -<seealso marker="#handle_error">handle_error/4</seealso> is -called.</p> +Similarly, only one of &handle_answer; or +&handle_error; is called.</p> <p> By default, an incoming answer message that cannot be successfully decoded causes the request process to fail, causing -<seealso marker="diameter#call">diameter:call/4</seealso> +&mod_call; to return <c>{error, failure}</c> unless the <c>detach</c> option was specified. -In particular, there is no <seealso -marker="#handle_error">handle_error/4</seealso> callback in this +In particular, there is no &handle_error; callback in this case. -The <seealso -marker="diameter#application_opt">diameter:application_opt()</seealso> +The &mod_application_opt; <c>answer_errors</c> can be set to change this behaviour.</p> <marker id="handle_error"/> @@ -500,23 +463,21 @@ marker="diameter#application_opt">diameter:application_opt()</seealso> <fsummary>Return an error from a outgoing request.</fsummary> <type> <v>Reason = timeout | failover | term()</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>Request = &message;</v> +<v>SvcName = &mod_service_name;</v> +<v>Peer = &peer;</v> <v>Result = term()</v> </type> <desc> <p> Invoked when an error occurs before an answer message is received in response to an outgoing request. -The return value is returned from <seealso -marker="diameter#call">diameter:call/4</seealso> unless the +The return value is returned from &mod_call; unless the <c>detach</c> option was specified.</p> <p> Reason <c>timeout</c> indicates that an answer message has not been -received within the time specified with the corresponding <seealso -marker="diameter#call_opt">diameter:call_opt()</seealso>. +received within the time specified with the corresponding &mod_call_opt;. Reason <c>failover</c> indicates that the transport connection to the peer to which the request has been sent has become unavailable and that not alternate peer was @@ -530,25 +491,23 @@ not selected.</p> <name>Mod:handle_request(Packet, SvcName, Peer) -> Action</name> <fsummary>Receive an incoming request.</fsummary> <type> -<v>Packet = <seealso marker="#packet">packet()</seealso></v> +<v>Packet = &packet;</v> <v>SvcName = term()</v> -<v>Peer = <seealso marker="#peer">peer()</seealso></v> +<v>Peer = &peer;</v> <v>Action = Reply | {relay, [Opt]} | discard | {eval|eval_packet, Action, PostF}</v> -<v>Reply = {reply, <seealso marker="#packet">packet()</seealso> - | <seealso marker="#message">message()</seealso>} +<v>Reply = {reply, &packet; | &message;} | {protocol_error, 3000..3999}</v> -<v>Opt = <seealso marker="diameter#call_opt">diameter:call_opt()</seealso></v> -<v>PostF = <seealso marker="diameter#evaluable">diameter:evaluable()</seealso></v> +<v>Opt = &mod_call_opt;</v> +<v>PostF = &mod_evaluable;</v> </type> <desc> <p> 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 <seealso -marker="diameter#start_service">diameter:start_service/2</seealso>) +callback module as configured with &mod_start_service;) is determined by the Application Identifier in the header of the incoming request message, the selected module being the one whose corresponding <seealso @@ -557,13 +516,13 @@ itself as defining either the application in question or the Relay application.</p> <p> -The argument <seealso marker="#packet">packet()</seealso> has the following signature.</p> +The argument &packet; has the following signature.</p> <pre> #diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso> | {<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>, #diameter_avp{}}], + errors = [&dict_Unsigned32; | {&dict_Unsigned32;, #diameter_avp{}}], bin = binary(), transport_data = term()} </pre> @@ -580,8 +539,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 <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. +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 <c>errors</c> list is empty if the request has been received in @@ -591,21 +550,19 @@ 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 if a <seealso -marker="#packet">message()</seealso> is returned but must be set -explicitly in a returned <seealso marker="#packet">packet()</seealso>.</p> +The term is preserved if a &message; is returned but must be set +explicitly in a returned &packet;.</p> <p> The semantics of each of the possible return values are as follows.</p> <taglist> -<tag><c>{reply, <seealso marker="#packet">packet()</seealso> - | <seealso marker="#message">message()</seealso>}</c></tag> +<tag><c>{reply, &packet; | &message;}</c></tag> <item> <p> Send the specified answer message to the peer. -In the case of a <seealso marker="#packet">packet()</seealso>, the +In the case of a &packet;, the message to be sent must be set in the <c>msg</c> field and the <c>header</c> field can be set to a <c>#diameter_header{}</c> to specify values that should be @@ -640,23 +597,22 @@ Relay a request to another peer in the role of a Diameter relay agent. If a routing loop is detected then the request is answered with 3005 (DIAMETER_LOOP_DETECTED). Otherwise a Route-Record AVP (containing the sending peer's Origin-Host) is -added to the request and <seealso marker="#pick_peer">pick_peer/4</seealso> -and subsequent callbacks take place just as if <seealso -marker="diameter#call">diameter:call/4</seealso> had been called +added to the request and &pick_peer; +and subsequent callbacks take place just as if &mod_call; had been called explicitly. The End-to-End Identifier of the incoming request is preserved in the header of the relayed request.</p> <p> The returned <c>Opts</c> should not specify <c>detach</c>. -A subsequent <seealso marker="#handle_answer">handle_answer/4</seealso> +A subsequent &handle_answer; callback for the relayed request must return its first 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. Any other return value (for example, from a -<seealso marker="#handle_error">handle_error/4</seealso> callback) +&handle_error; callback) causes the request to be answered with 3002 (DIAMETER_UNABLE_TO_DELIVER).</p> </item> |