diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 149 |
1 files changed, 124 insertions, 25 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index b7669b760b..379e9f0738 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -16,7 +16,7 @@ <header> <copyright> -<year>2011</year><year>2012</year> +<year>2011</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -69,8 +69,8 @@ Incoming Diameter requests are communicated as callbacks to a specified in the service configuration.</p> <p> -Beware the difference between <em>diameter</em> (not capitalised) and -<em>Diameter</em> (capitalised). +Beware the difference between <em>diameter</em> (not capitalized) and +<em>Diameter</em> (capitalized). The former refers to the Erlang application named diameter whose main api is defined here, the latter to Diameter protocol in the sense of &the_rfc;.</p> @@ -188,7 +188,7 @@ Defaults to the value of the <c>alias</c> option if unspecified.</p> <item> <p> Specifies whether or not the &app_pick_peer; -application callback can modify the application state, +application callback can modify the application state. Defaults to <c>false</c> if unspecified.</p> <note> @@ -206,11 +206,13 @@ probably avoid it.</p> <item> <p> Determines the manner in which incoming answer messages containing -decode errors are handled. +decode errors are handled.</p> + +<p> If <c>callback</c> then errors result in a &app_handle_answer; callback in the same fashion as for &app_handle_request;, with errors communicated in the <c>errors</c> field of the -<c>#diameter_packet{}</c> record passed to the callback. +<c>#diameter_packet{}</c> passed to the callback. If <c>report</c> then an answer containing errors is discarded without a callback and a warning report is written to the log. If <c>discard</c> then an answer containing errors is silently @@ -224,6 +226,39 @@ question is as if a callback had taken place and returned Defaults to <c>report</c> if unspecified.</p> </item> +<tag><c>{request_errors, answer_3xxx|answer|callback}</c></tag> +<item> +<p> +Determines the manner in which incoming requests are handled when an +error other than 3007, DIAMETER_APPLICATION_UNSUPPORTED (which cannot +be associated with an application callback module), is detected.</p> + +<p> +If <c>answer_3xxx</c> then requests are answered without a +&app_handle_request; callback taking place. +If <c>answer</c> then even 5xxx errors are answered without a +callback unless the connection in question has configured the RFC 3588 +common dictionary as noted below. +If <c>callback</c> then a &app_handle_request; callback always takes +place and the return value determines the answer sent to the peer.</p> + +<p> +Defaults to <c>answer_3xxx</c> if unspecified.</p> + +<note> +<p> +Answers sent by diameter set the E-bit in the Diameter Header. +Since RFC 3588 allowed only 3xxx result codes in an +<c>answer-message</c>, <c>answer</c> has the same semantics as +<c>answer_3xxx</c> if the peer connection in question has configured +the RFC 3588 common dictionary, <c>diameter_gen_base_rfc3588</c>. +RFC 6733 allows both 3xxx and 5xxx result codes in an +<c>answer-message</c> so a connection configured with the RFC 6733 +common dictionary, <c>diameter_gen_base_rfc6733</c>, does +distinguish between <c>answer_3xxx</c> and <c>answer</c>.</p> +</note> +</item> + </taglist> <marker id="call_opt"/> @@ -488,16 +523,23 @@ candidates list.</p> <marker id="service_event"/> </item> - -<tag><c>service_event() = #diameter_event{}</c></tag> +<tag><c>service_event() = #diameter_event{service = &service_name;, + info = &service_event_info;}</c></tag> <item> <p> An event message sent to processes that have subscribed to these using &subscribe;.</p> +<marker id="service_event_info"/> +</item> + +<tag><c>service_event_info() = term()</c></tag> + +<item> + <p> -The <c>info</c> field of the event record can have one of the -following types.</p> +The <c>info</c> field of a &service_event; record. +Can have one of the following types.</p> <taglist> @@ -527,16 +569,16 @@ Pkt = #diameter_packet{} The RFC 3539 watchdog state machine has transitioned into (<c>up</c>) or out of (<c>down</c>) the OKAY state. -If a <c>#diameter_packet{}</c> record is present in an <c>up</c> event +If a <c>#diameter_packet{}</c> is present in an <c>up</c> event then there has been a capabilties exchange on a newly established transport connection and the record contains the received CER or CEA. Otherwise a connection has reestablished without the loss or connectivity.</p> <p> -Note that a single <c>up</c>/<c>down</c> event for a given peer -corresponds to one &app_peer_up;/&app_peer_down; -callback for each of the Diameter applications negotiated during +Note that a single <c>up</c> or <c>down</c> event for a given peer +corresponds to multiple &app_peer_up; or &app_peer_down; +callbacks, one for each of the Diameter applications negotiated during capablilities exchange. That is, the event communicates connectivity with the peer as a whole while the callbacks communicate connectivity with @@ -582,7 +624,7 @@ CB = &evaluable; <p> An incoming CER has been answered with the indicated result code or discarded. -<c>Caps</c> contains pairs of values for the the local node and remote +<c>Caps</c> contains pairs of values for the local node and remote peer. <c>Pkt</c> contains the CER in question. In the case of rejection by a capabilities callback, the tuple @@ -600,7 +642,7 @@ Pkt = #diameter_packet{} <p> An incoming CER contained errors and has been answered with the indicated result code. -<c>Caps</c> contains only values for the the local node. +<c>Caps</c> contains only values for the local node. <c>Pkt</c> contains the CER in question.</p> </item> @@ -624,7 +666,7 @@ ResultCode = integer() An incoming CEA has been rejected for the indicated reason. An integer-valued <c>Result</c> indicates the result code sent by the peer. -<c>Caps</c> contains pairs of values for the the local node and remote +<c>Caps</c> contains pairs of values for the local node and remote peer. <c>Pkt</c> contains the CEA in question. In the case of rejection by a capabilities callback, the tuple @@ -640,7 +682,7 @@ Pkt = #diameter_packet{} <p> An incoming CEA contained errors and has been rejected. -<c>Caps</c> contains only values for the the local node. +<c>Caps</c> contains only values for the local node. <c>Pkt</c> contains the CEA in question.</p> </item> @@ -667,11 +709,14 @@ Config = {connect|listen, [transport_opt()]} An RFC 3539 watchdog state machine has changed state.</p> </item> -</taglist> - +<tag><c>any()</c></tag> +<item> <p> For forward compatibility, a subscriber should be prepared to receive info fields of forms other than the above.</p> +</item> + +</taglist> <marker id="service_name"/> </item> @@ -709,6 +754,15 @@ passed to &call;, while for an incoming request the application identifier in the message header determines the application, the identifier being specified in the application's &dictionary; file.</p> + +<warning> +<p> +The capabilities advertised by a node must match its configured +applications. In particular, <c>application</c> configuration must +be matched by corresponding &capability; configuration, of +Application-Id AVP's in particular.</p> +</warning> + </item> <tag><c>{restrict_connections, false @@ -787,6 +841,16 @@ The list of Diameter applications to which the transport should be restricted. Defaults to all applications configured on the service in question. Applications not configured on the service in question are ignored.</p> + +<warning> +<p> +The capabilities advertised by a node must match its configured +applications. +In particular, setting <c>applications</c> on a transport typically +implies having to set matching Application-Id AVP's in a +&capabilities; tuple.</p> +</warning> + </item> <marker id="capabilities"/> @@ -858,9 +922,8 @@ case the corresponding callbacks are applied until either all return The number of milliseconds after which a transport process having an established transport connection will be terminated if the expected capabilities exchange message (CER or CEA) is not received from the peer. -For a connecting transport, the timing reconnection attempts is -governed by &watchdog_timer; or -&reconnect_timer; expiry. +For a connecting transport, the timing of reconnection attempts is +governed by &watchdog_timer; or &reconnect_timer; expiry. For a listening transport, the peer determines the timing.</p> <p> @@ -877,7 +940,7 @@ transport connection having watchdog state <c>OKAY</c>. Applied to <c>Reason=transport|service|application</c> and the <c>&transport_ref;</c> and <c>&app_peer;</c> -in question, <c>Reason</c> indicating whether the the diameter +in question, <c>Reason</c> indicating whether the diameter application is being stopped, the service in question is being stopped at &stop_service; or the transport in question is being removed at &remove_transport;, @@ -947,6 +1010,42 @@ configured them.</p> Defaults to a single callback returning <c>dpr</c>.</p> </item> +<marker id="length_errors"/> +<tag><c>{length_errors, exit|handle|discard}</c></tag> +<item> +<p> +Specifies how to deal with errors in the Message Length field of the +Diameter Header in an incoming message. +An error in this context is that the length is not at least 20 bytes +(the length of a Header), is not a multiple of 4 (a valid length) or +is not the length of the message in question, as received over the +transport interface documented in &man_transport;.</p> + +<p> +If <c>exit</c> then a warning report is emitted and the parent of the +transport process in question exits, which causes the transport +process itself to exit as described in &man_transport;. +If <c>handle</c> then the message is processed as usual, a resulting +&app_handle_request; or &app_handle_answer; callback (if one takes +place) indicating the <c>5015</c> error (DIAMETER_INVALID_MESSAGE_LENGTH). +If <c>discard</c> then the message in question is silently discarded.</p> + +<p> +Defaults to <c>exit</c>.</p> + +<note> +<p> +The default value reflects the fact that a transport module for a +stream-oriented transport like TCP may not be able to recover from a +message length error since such a transport must use the Message +Length header to divide the incoming byte stream into individual +Diameter messages. +An invalid length leaves it with no reliable way to rediscover message +boundaries, which may result in the failure of subsequent messages. +See &man_tcp; for the behaviour of that module.</p> +</note> +</item> + <marker id="reconnect_timer"/> <tag><c>{reconnect_timer, Tc}</c></tag> <item> @@ -1733,7 +1832,7 @@ a service.</p> It is not an error to subscribe to events from a service that does not yet exist. Doing so before adding transports is required to guarantee the -reception of all related events.</p> +reception of all transport-related events.</p> </desc> </func> |