diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter_app.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter_app.xml | 445 |
1 files changed, 223 insertions, 222 deletions
diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 4a4b212787..f4db625c71 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -1,5 +1,13 @@ <?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> +<!DOCTYPE erlref SYSTEM "erlref.dtd" [ + <!ENTITY message '<seealso marker="#message">message()</seealso>'> + <!ENTITY dict + '<seealso marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>'> + <!ENTITY % also SYSTEM "seealso.ent" > + <!ENTITY % here SYSTEM "seehere.ent" > + %also; + %here; +]> <erlref> <header> @@ -41,15 +49,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 +66,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 +96,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> <!-- ===================================================================== --> @@ -112,7 +115,8 @@ and, for the call-specific callbacks, any extra arguments passed to <item> <p> 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 @@ -123,39 +127,17 @@ mandatory values as the bare value.</p> <marker id="message"/> -<tag><c>message() = record() | list()</c></tag> +<tag><c>message() = &codec_message;</c></tag> <item> <p> The representation of a Diameter message as passed to -<seealso marker="diameter#call">diameter:call/4</seealso>. -The record representation is as outlined in -<seealso -marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>: -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 specified in the relevant dictionary file) and whose tail is a -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. -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> -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 (since relays agents must handle arbitrary request): messages -are sent exactly as specified.</p> +&mod_call; or returned from a &handle_request; callback.</p> </item> <marker id="packet"/> -<tag><c>packet() = #diameter_packet{}</c></tag> +<tag><c>packet() = &codec_packet;</c></tag> <item> <p> A container for incoming and outgoing Diameter messages that's passed @@ -168,13 +150,12 @@ Fields should not be set in return values except as documented.</p> <tag><c>peer_ref() = term()</c></tag> <item> <p> -A term identifying a transport connection with a Diameter peer. -Should be treated opaquely.</p> +A term identifying a transport connection with a Diameter peer.</p> </item> <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> @@ -186,13 +167,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 @@ -213,18 +190,33 @@ 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> -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.</p> +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 <c>OKAY</c> and Diameter +messages can be both sent and received.</p> + +<note> +<p> +A watchdog state machine can reach state <c>OKAY</c> from state +<c>SUSPECT</c> without a new capabilities exchange taking place. +A new transport connection (and capabilities exchange) results in a +new peer_ref().</p> +</note> + +<note> +<p> +There is no requirement that a callback return before incoming +requests are received: &handle_request; callbacks must be +handled independently of &peer_up; and &peer_down;.</p> +</note> -<marker id="peer_down"/> </desc> </func> @@ -232,88 +224,87 @@ 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 = <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 when a transport connection has been lost following a previous -call to <seealso marker="#peer_up">peer_up/3</seealso>.</p> +Invoked to signal that a peer connection is no longer available +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 &pick_peer; callbacks.</p> -<marker id="pick_peer"/> </desc> </func> <func> -<name>Mod:pick_peer(Candidates, Reserved, SvcName, State) - -> {ok, Peer} | {Peer, NewState} | false</name> +<name>Mod:pick_peer(Candidates, _Reserved, SvcName, State) + -> Selection | false</name> <fsummary>Select a target peer for an outgoing request.</fsummary> <type> -<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> +<v>Candidates = [&peer;]</v> +<v>SvcName = &mod_service_name;</v> +<v>State = NewState = &state;</v> +<v>Selection = {ok, Peer} | {Peer, NewState}</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 -peer for an outgoing request, the return value indicating the selected -peer.</p> +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> <p> -The candidate peers list will only include those -which are selected by any <c>filter</c> option specified in the call to -<seealso marker="diameter#call">diameter:call/4</seealso>, 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 <c>filter</c> option in +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> -The return values <c>false</c> and <c>{false, State}</c> are -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 <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> -or <seealso marker="#handle_error">handle_error/4</seealso> depending +A callback that returns a peer() will be followed by a +&prepare_request; +callback and, if the latter indicates that the request should be sent, +by either &handle_answer; +or &handle_error; 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 <seealso -marker="#pick_peer">pick_peer/4</seealso> callback takes place to -select an alternate peer.</p> - -<p> -Note that there is no guarantee that a <seealso -marker="#pick_peer">pick_peer/4</seealso> callback to select -an alternate peer will be followed by any additional callbacks, only -that the initial <seealso -marker="#pick_peer">pick_peer/4</seealso> will be, since a +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 &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 &mod_call;.</p> + +<p> +The return values <c>false</c> and <c>{false, State}</c> (that is, +<c>NewState = State</c>) are equivalent, as are <c>{ok, Peer}</c> and +<c>{Peer, State}</c>.</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>. +The return value <c>{Peer, NewState}</c> is only allowed if +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"/> </desc> </func> @@ -322,74 +313,81 @@ 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>Action = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</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, &packet; | &message;}</v> +<v>Discard = {discard, Reason} | discard</v> +<v>PostF = &mod_evaluable;}</v> </type> <desc> <p> Invoked to return a request for encoding and transport. -Allows the sender to access the selected peer's capabilities -in order to set (for example) <c>Destination-Host</c> and/or -<c>Destination-Realm</c> in the outgoing request, although the -callback need not be limited to this usage. +Allows the sender to use the selected peer's capabilities +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 request to be encoded in its +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 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 <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. +to pass information to the transport process. +Extra arguments passed to &mod_call; can be used to +communicate transport (or any other) data to the callback.</p> + +<p> +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 +the header record contained in <c>Packet</c>. A returned <c>length</c>, <c>cmd_code</c> or <c>application_id</c> is ignored.</p> <p> +A returned <c>PostF</c> will be evaluated on any encoded +<c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field +containing the encoded binary. +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> -<marker id="prepare_retransmit"/> </desc> </func> <func> -<name>Mod:prepare_retransmit(Packet, SvcName, Peer) -> Result</name> +<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>Result = {send, <seealso marker="#packet">packet()</seealso> | <seealso marker="#message">message()</seealso>} | {discard, Reason} | discard</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, &packet; | &message;}</v> +<v>Discard = {discard, Reason} | discard</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 -<c>prepare_request/3</c>.</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> -<marker id="handle_answer"/> </desc> </func> @@ -397,51 +395,43 @@ 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 the call to <seealso -marker="diameter#call">diameter:call/4</seealso> for which the -callback takes place unless the <c>detach</c> option was -specified.</p> +The return value is returned from &mod_call; unless the +<c>detach</c> option was specified.</p> <p> -The decoded answer record is in the <c>msg</c> field of the argument -<seealso marker="#packet">packet()</seealso>, -the undecoded binary in the <c>packet</c> field. +The decoded answer record and undecoded binary are in the <c>msg</c> +and <c>bin</c> fields of the argument +&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> -before the request was passed to the transport.</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 -call to the handle_answer callback of the application in question: 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 <c>handle_answer/4</c> or <c>handle_error/4</c> is -called for any given request.</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 in question to fail, causing the -relevant call to <seealso -marker="diameter#call">diameter:call/4</seealso> -to return <c>{error, failure} (unless the <c>detach</c> option was -specified)</c>. -In particular, there is no <c>handle_error/4</c> callback in this +decoded causes the request process to fail, causing +&mod_call; +to return <c>{error, failure}</c> unless the <c>detach</c> option was +specified. +In particular, there is no &handle_error; callback in this case. -Application configuration may change this behaviour as described for -<seealso -marker="diameter#start_service">diameter:start_service/2</seealso>.</p> +The &mod_application_opt; +<c>answer_errors</c> can be set to change this behaviour.</p> -<marker id="handle_error"/> </desc> </func> @@ -450,30 +440,26 @@ 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 = <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 from -a peer in response to an outgoing request. -The return value is returned from the call to <seealso -marker="diameter#call">diameter:call/4</seealso> for which the -callback takes place (unless the <c>detach</c> option was -specified).</p> +Invoked when an error occurs before an answer message is received +in response to an outgoing request. +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 required time. +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 been lost but that not alternate node was available, -possibly because a <seealso marker="#pick_peer">pick_peer/4</seealso> -callback returned false.</p> +been sent has become unavailable and that not alternate peer was +not selected.</p> -<marker id="handle_request"/> </desc> </func> @@ -481,54 +467,54 @@ callback returned false.</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>Action = Reply | {relay, [Opt]} | discard | {eval, Action, PostF}</v> -<v>Reply = {reply, <seealso marker="#message">message()</seealso>} +<v>Peer = &peer;</v> +<v>Action = Reply + | {relay, [Opt]} + | discard + | {eval|eval_packet, Action, PostF}</v> +<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 -marker="diameter_dict#MESSAGE_RECORDS">dictionary</seealso> declares +whose corresponding dictionary declares 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> -<code> +<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()} -</code> +</pre> <p> -The <c>msg</c> field will be <c>undefined</c> only in case the request has +The <c>msg</c> field will be <c>undefined</c> in case the request has been received in the relay application. Otherwise it contains the record representing the request as outlined -in <seealso -marker="diameter_dict#MESSAGE_RECORDS">diameter_dict(4)</seealso>.</p> +in &dict;.</p> <p> 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 @@ -538,19 +524,24 @@ 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 <seealso marker="#packet">packet()</seealso> containing any answer message -sent back to the transport process unless another value is explicitly -specified.</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="#message">message()</seealso>}</c></tag> +<tag><c>{reply, &packet; | &message;}</c></tag> <item> <p> -Send the specified answer message to the peer.</p> +Send the specified answer message to the peer. +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 +preserved in the outgoing answer, appropriate values otherwise +being set by diameter.</p> </item> <tag><c>{protocol_error, 3000..3999}</c></tag> @@ -559,15 +550,15 @@ Send the specified answer message to the peer.</p> Send an answer message to the peer containing the specified protocol error. Equivalent to</p> -<code> +<pre> {reply, ['answer-message' | Avps] -</code> +</pre> <p> where <c>Avps</c> sets the Origin-Host, Origin-Realm, the specified Result-Code and (if the request sent one) Session-Id AVP's.</p> <p> -Note that RFC 3588 mandates that only answers with a 3xxx series +Note that &the_rfc; mandates that only answers with a 3xxx series Result-Code (protocol errors) may set the E bit. Returning a non-3xxx value in a <c>protocol_error</c> tuple will cause the request process in question to fail.</p> @@ -580,37 +571,47 @@ 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> <tag><c>discard</c></tag> <item> <p> -Discard the request.</p> +Discard the request. +No answer message is sent to the peer.</p> </item> <tag><c>{eval, Action, PostF}</c></tag> <item> <p> Handle the request as if <c>Action</c> has been returned and then -evaluate <c>PostF</c> in the request process.</p> +evaluate <c>PostF</c> in the request process. +The return value is ignored.</p> +</item> + +<tag><c>{eval_packet, Action, PostF}</c></tag> +<item> +<p> +Like <c>eval</c> but evaluate <c>PostF</c> on any encoded +<c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field +containing the encoded binary. +The return value is ignored.</p> </item> </taglist> |