diff options
Diffstat (limited to 'lib/diameter/doc/src/diameter.xml')
| -rw-r--r-- | lib/diameter/doc/src/diameter.xml | 457 |
1 files changed, 202 insertions, 255 deletions
diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 2abfbff209..fdd18929df 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -43,8 +43,8 @@ under the License. <description> <p> -This module provides the interface with which a user -creates a service that sends and receives messages using the +This module provides the interface with which a user can +implement a Diameter node that sends and receives messages using the Diameter protocol as defined in RFC 3588.</p> <p> @@ -61,17 +61,15 @@ marker="diameter_app">diameter_app(3)</seealso> callback modules as specified in the service configuration.</p> <p> -Beware the difference between <em>diameter application</em> and -<em>Diameter application</em>. +Beware the difference between <em>diameter</em> (not capitalised) and +<em>Diameter</em> (capitalised). The former refers to the Erlang application named diameter whose main -api is defined here, the latter to an application of the Diameter -protocol in the sense of RFC 3588. -More generally, capitalized Diameter refers to the RFC -and diameter to this implementation.</p> +api is defined here, the latter to Diameter protocol in the sense of +RFC 3588.</p> <p> -The diameter application must be started before calling functions in -this module.</p> +The diameter application must be started before calling most functions +in this module.</p> </description> @@ -100,10 +98,9 @@ Defined in <seealso marker="diameter_dict#DATA_TYPES">diameter_dict(4)</seealso> <item> <p> A name identifying a Diameter application in -service configuration passed to <seealso -marker="#start_service">start_service/2</seealso> and passed to -<seealso marker="#call">call/4</seealso> when sending requests -belonging to the application.</p> +service configuration. +Passed to <seealso marker="#call">call/4</seealso> when sending requests +defined by the application.</p> <marker id="application_module"/> </item> @@ -121,19 +118,14 @@ ExtraArgs = list() A module implementing the callback interface defined in <seealso marker="diameter_app">diameter_app(3)</seealso>, along with any extra arguments to be appended to those documented for the interface. -Any extra arguments are appended to the documented list of arguments for -each function. -Note that additional arguments specific to an outgoing request be +Note that extra arguments specific to an outgoing request can be specified to <seealso marker="#call">call/4</seealso>, in which case -the call-specific arguments are appended to any specified with the -callback module.</p> +those are are appended to any module-specific extra arguments.</p> <p> Specifying a <c>#diameter_callback{}</c> record allows individual functions to be configured in place of the usual <seealso -marker="diameter_app">diameter_app(3)</seealso> callbacks, with -default implementations provided by module <c>diameter_callback</c> -unless otherwise specified. +marker="diameter_app">diameter_app(3)</seealso> callbacks. See that module for details.</p> <marker id="application_opt"/> @@ -143,9 +135,8 @@ See that module for details.</p> <item> <p> -Options defining a Diameter application as configured in an -<c>application</c> option passed to -<seealso marker="#start_service">start_service/2</seealso>.</p> +Options defining a Diameter application. +Has one the following types.</p> <taglist> @@ -154,7 +145,8 @@ Options defining a Diameter application as configured in an <p> An unique identifier for the application in the scope of the service. -Optional, defaults to the value of the <c>dictionary</c> option.</p> +Defaults to the value of the <c>dictionary</c> option if +unspecified.</p> </item> <tag><c>{dictionary, atom()}</c></tag> @@ -170,20 +162,20 @@ marker="diameter_dict">diameter_dict(4)</seealso>.</p> <tag><c>{module, <seealso marker="#application_module">application_module()</seealso>}</c></tag> <item> <p> -A callback module with which messages of the Diameter application are +The callback module with which messages of the Diameter application are handled. See <seealso marker="diameter_app">diameter_app(3)</seealso> for -information on the required interface and semantics.</p> +the required interface and semantics.</p> </item> <tag><c>{state, term()}</c></tag> <item> <p> The initial callback state. -Defaults to the value of the <c>alias</c> option if unspecified. -The prevailing state is passed to certain +The prevailing state is passed to some <seealso marker="diameter_app">diameter_app(3)</seealso> -callbacks, which can then return a new state.</p> +callbacks, which can then return a new state. +Defaults to the value of the <c>alias</c> option if unspecified.</p> </item> <tag><c>{call_mutates_state, true|false}</c></tag> @@ -191,19 +183,18 @@ callbacks, which can then return a new state.</p> <p> Specifies whether or not the <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> -application callback (following from a call to -<seealso marker="#call">call/4</seealso>) -can modifiy state, +application callback can modify the application state, Defaults to <c>false</c> if unspecified.</p> +<note> <p> -Note that <seealso -marker="diameter_app#pick_peer">pick_peer</seealso> callbacks are -serialized when these are allowed to modify state, which is a +<seealso marker="diameter_app#pick_peer">pick_peer</seealso> callbacks +are serialized when these are allowed to modify state, which is a potential performance bottleneck. A simple Diameter client may suffer no ill effects from using mutable -state but a server or agent that responds to incoming request but -sending its own requests should probably avoid it.</p> +state but a server or agent that responds to incoming request should +probably avoid it.</p> +</note> </item> <tag><c>{answer_errors, callback|report|discard}</c></tag> @@ -214,9 +205,9 @@ decode errors are handled. If <c>callback</c> then errors result in a <seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> callback in the same fashion as for <seealso -marker="diameter_app#handle_request">handle_request/3</seealso>, in the -<c>errors</c> field of the <c>diameter_packet</c> record passed into -the callback. +marker="diameter_app#handle_request">handle_request/3</seealso>, with +errors communicated in the <c>errors</c> field of the +<c>#diameter_packet{}</c> record 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 @@ -240,7 +231,8 @@ Defaults to <c>report</c> if unspecified.</p> <p> Options available to <seealso marker="#call">call/4</seealso> when -sending an outgoing Diameter request.</p> +sending an outgoing Diameter request. +Has one of the following types.</p> <taglist> @@ -249,7 +241,7 @@ sending an outgoing Diameter request.</p> <p> Extra arguments to append to callbacks to the callback module in question. -These are appended to any extra arguments configured with the callback +These are appended to any extra arguments configured on the callback itself. Multiple options append to the argument list.</p> </item> @@ -299,120 +291,55 @@ to fail.</p> <item> <p> -AVP values used in outgoing CER/CEA messages during capabilities exchange. -Can be configured both on a service and a transport, the latter taking -precedence over the former.</p> +AVP values sent in outgoing CER or CEA messages during capabilities +exchange. +Can be configured both on a service and a transport, values specified +on the latter taking precedence over any specified on the former. +Has one of the following types.</p> <taglist> <tag><c>{'Origin-Host', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag> -<item> -<p> -Value of the Origin-Host AVP in outgoing messages.</p> -</item> - <tag><c>{'Origin-Realm', <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c></tag> -<item> -<p> -Value of the Origin-Realm AVP in outgoing messages.</p> -</item> - <tag><c>{'Host-IP-Address', [<seealso marker="diameter_dict#DATA_TYPES">Address()</seealso>]}</c></tag> <item> <p> -Values of Host-IP-Address AVPs. -Optional.</p> - -<p> -The list of addresses is available to the start function of a -transport module, which either uses them as is or returns a new list -in order for the correct list of addresses to be sent in capabilities -exchange messages.</p> +An address list is available to the start function of a +<seealso marker="diameter_transport">transport module</seealso>, which +can return a new list for use in the subsequent CER or CEA. +Host-IP-Address need not be specified if the transport start function +returns an address list.</p> </item> <tag><c>{'Vendor-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag> -<item> -<p> -Value of the Vendor-Id AVP sent in an outgoing capabilities -exchange message.</p> -</item> - <tag><c>{'Product-Name', <seealso marker="#UTF8String">UTF8String()</seealso>}</c></tag> -<item> -<p> -Value of the Product-Name AVP sent in an outgoing capabilities -exchange message.</p> -</item> - <tag><c>{'Origin-State-Id', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag> <item> <p> -Value of Origin-State-Id to be included in outgoing messages sent by -diameter itself. -In particular, the AVP will be included in CER/CEA and DWR/DWA messages. -Optional.</p> - -<p> +Origin-State-Id is optional but will be included in outgoing messages +sent by diameter itself: CER/CEA, DWR/DWA and DPR/DPA. Setting a value of <c>0</c> (zero) is equivalent to not setting a value as documented in RFC 3588. The function <seealso marker="#origin_state_id">origin_state_id/0</seealso> -can be used as to retrieve a value that is set when the diameter +can be used as to retrieve a value that is computed when the diameter application is started.</p> </item> <tag><c>{'Supported-Vendor-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag> -<item> -<p> -Values of Supported-Vendor-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.</p> -</item> - <tag><c>{'Auth-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag> -<item> -<p> -Values of Auth-Application-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.</p> -</item> - <tag><c>{'Inband-Security-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag> <item> <p> -Values of Inband-Security-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list, which is equivalent to a -list containing only 0 (= NO_INBAND_SECURITY).</p> - -<p> +Inband-Security-Id defaults to the empty list, which is equivalent to a +list containing only 0 (= NO_INBAND_SECURITY). If 1 (= TLS) is specified then TLS is selected if the CER/CEA received from the peer offers it.</p> </item> <tag><c>{'Acct-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>]}</c></tag> -<item> -<p> -Values of Acct-Application-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.</p> -</item> - <tag><c>{'Vendor-Specific-Application-Id', [<seealso marker="diameter_dict#DATA_TYPES">Grouped()</seealso>]}</c></tag> -<item> -<p> -Values of Vendor-Specific-Application-Id AVPs sent in -an outgoing capabilities exchange message. -Optional, defaults to the empty list.</p> -</item> - <tag><c>{'Firmware-Revision', <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso>}</c></tag> -<item> -<p> -Value of the Firmware-Revision AVP sent in an outgoing capabilities -exchange message. -Optional.</p> -</item> </taglist> @@ -444,11 +371,13 @@ eval(F) -> Applying an evaluable() <c>E</c> to an argument list <c>A</c> is meant in the sense of <c>eval([E|A])</c>.</p> +<warning> <p> -Beware of using local funs (that is, fun expressions not of the -form <c>fun Module:Name/Arity</c>) in situations in which the fun is -not short-lived and code is to be upgraded at runtime since any -processes retaining such a fun will have a reference to old code.</p> +Beware of using fun expressions of the form <c>fun Name/Arity</c> (not +fun Mod:Name/Arity) in situations in which the fun is not short-lived +and code is to be upgraded at runtime since any processes retaining +such a fun will have a reference to old code.</p> +</warning> <marker id="peer_filter"/> </item> @@ -501,14 +430,14 @@ specified value, or all peers if the atom <c>any</c>.</p> <item> <p> Matches only those peers whose <c>Origin-Realm</c> has the -value, or all peers if the atom <c>any</c>.</p> +specified value, or all peers if the atom <c>any</c>.</p> </item> <tag><c>{eval, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag> <item> <p> Matches only those peers for which the specified <seealso -marker="evaluable">#evaluable()</seealso> returns +marker="#evaluable">evaluable()</seealso> returns <c>true</c> on the connection's <c>diameter_caps</c> record. Any other return value or exception is equivalent to <c>false</c>.</p> </item> @@ -522,20 +451,21 @@ Matches only those peers not matched by the specified filter.</p> <tag><c>{all, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag> <item> <p> -Matches only those peers matched by each filter of the specified list.</p> +Matches only those peers matched by each filter in the specified list.</p> </item> <tag><c>{any, [<seealso marker="#peer_filter">peer_filter()</seealso>]}</c></tag> <item> <p> -Matches only those peers matched by at least one filter of the +Matches only those peers matched by at least one filter in the specified list.</p> </item> </taglist> +<note> <p> -Note that the <c>host</c> and <c>realm</c> filters examine the +The <c>host</c> and <c>realm</c> filters examine the outgoing request as passed to <seealso marker="#call">call/4</seealso>, assuming that this is a record- or list-valued <seealso marker="diameter_app#message">diameter_app:message()</seealso>, and that @@ -543,11 +473,12 @@ the message contains at most one of each AVP. If this is not the case then the <c>{host|realm, <seealso marker="diameter_dict#DATA_TYPES">DiameterIdentity()</seealso>}</c> filters must be used to achieve the desired result. -Note also that an empty host/realm (which should not be typical) +An empty host/realm (which should not be typical) is equivalent to an unspecified one for the purposes of filtering.</p> +</note> <p> -An invalid filter is equivalent to <c>{any, []}</c>, a filter +An invalid filter is equivalent to <c>{any,[]}</c>, a filter that matches no peer.</p> <marker id="service_event"/> @@ -556,12 +487,12 @@ that matches no peer.</p> <tag><c>service_event() = #diameter_event{}</c></tag> <item> <p> -Event message sent to processes that have subscribed using <seealso -marker="#subscribe">subscribe/1</seealso>.</p> +An event message sent to processes that have subscribed to these using +<seealso marker="#subscribe">subscribe/1</seealso>.</p> <p> -The <c>info</c> field of the event record can be one of the -following.</p> +The <c>info</c> field of the event record can have one of the +following types.</p> <taglist> @@ -578,19 +509,19 @@ Pkt = #diameter_packet{} <p> The RFC 3539 watchdog state machine has -transitioned into (<c>up</c>) or out of (<c>down</c>) the open +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> tuple -then there has been an exchange of capabilities exchange messages and -the record contains the received CER or CEA, otherwise the -connection has reestablished without the loss or transport +If a <c>#diameter_packet{}</c> record 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 up/down event for a given peer corresponds to -as many <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso> -callbacks as there are Diameter applications that have been negotiated -during capablilities exchange. +Note that a single <c>up</c>/<c>down</c> event for a given peer +corresponds to one <seealso marker="diameter_app#peer_up">peer_up/peer_down</seealso> +callback 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 respect to individual Diameter applications.</p> @@ -605,8 +536,10 @@ Opts = [<seealso marker="#transport_opt">transport_opt()</seealso>] <p> A connecting transport is attempting to establish/reestablish a -transport connection with a peer following <c>reconnect_timer</c> or -<c>watchdog_timer</c> expiry.</p> +transport connection with a peer following <seealso +marker="#reconnect_timer">reconnect_timer</seealso> or +<seealso marker="#watchdog_timer">watchdog_timer</seealso> +expiry.</p> </item> <tag><c>{closed, Ref, Reason, Config}</c></tag> @@ -617,8 +550,8 @@ Config = {connect|listen, [<seealso marker="#transport_opt">transport_opt()</see </code> <p> -Capabilities exchange has failed. <c>Reason</c> can be one of -the following.</p> +Capabilities exchange has failed. +<c>Reason</c> can have one of the following types.</p> <taglist> @@ -635,11 +568,11 @@ CB = <seealso marker="#evaluable">evaluable()</seealso> <p> An incoming CER has been answered with the indicated result code or discarded. -The capabilities record contains pairs of values for the the local -node and remote peer. -The packet record contains the CER in question. +<c>Caps</c> contains pairs of values for the 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 -indicates the rejecting callback.</p> +contains the rejecting callback.</p> </item> <tag><c>{'CER', Caps, {ResultCode, Pkt}}</c></tag> @@ -653,9 +586,8 @@ Pkt = #diameter_packet{} <p> An incoming CER contained errors and has been answered with the indicated result code. -The capabilities record contains only values for the the local -node. -The packet record contains the CER in question.</p> +<c>Caps</c> contains only values for the the local node. +<c>Pkt</c> contains the CER in question.</p> </item> <tag><c>{'CEA', Result, Caps, Pkt}</c></tag> @@ -671,11 +603,11 @@ 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. -The capabilities record contains pairs of values for the the local -node and remote peer. -The packet record contains the CEA in question. +<c>Caps</c> contains pairs of values for the 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 -indicates the rejecting callback.</p> +contains the rejecting callback.</p> </item> <tag><c>{'CEA', Caps, Pkt}</c></tag> @@ -686,9 +618,9 @@ Pkt = #diameter_packet{} </code> <p> -An incoming CER contained errors and has been rejected. -The capabilities record contains only values for the the local node. -The packet record contains the CEA in question.</p> +An incoming CEA contained errors and has been rejected. +<c>Caps</c> contains only values for the the local node. +<c>Pkt</c> contains the CEA in question.</p> </item> </taglist> @@ -732,9 +664,9 @@ that is somewhat unique.</p> <tag><c>service_opt()</c></tag> <item> <p> -Options accepted by <seealso +An option passed to <seealso marker="#start_service">start_service/2</seealso>. -Can be any <seealso marker="#capability"><c>capability()</c></seealso> tuple as +Can be any <seealso marker="#capability">capability()</seealso> as well as the following.</p> <taglist> @@ -745,17 +677,15 @@ well as the following.</p> Defines a Diameter application supported by the service.</p> <p> -A service must define one application for each Diameter application it -intends to support. -For an outgoing Diameter request, the application is specified by -passing the desired application's <seealso -marker="#application_alias"><c>application_alias()</c></seealso> to -<seealso marker="#call">call/4</seealso>, while for an +A service must configure one <c>application</c> for each Diameter +application it intends to support. +For an outgoing Diameter request, the relevant <seealso +marker="#application_alias">application_alias()</seealso> is +passed to <seealso marker="#call">call/4</seealso>, while for an incoming request the application identifier in the message -header determines the application (and callback module), the -application identifier being specified in the <seealso -marker="diameter_dict">dictionary</seealso> file defining the -application.</p> +header determines the application, the identifier being specified in +the application's <seealso marker="diameter_dict">dictionary</seealso> +file.</p> </item> </taglist> @@ -766,8 +696,9 @@ application.</p> <tag><c>transport_opt()</c></tag> <item> <p> -Options accepted by <seealso -marker="#add_transport">add_transport/2</seealso>.</p> +An option passed to <seealso +marker="#add_transport">add_transport/2</seealso>. +Has one of the following types.</p> <taglist> <tag><c>{transport_module, atom()}</c></tag> @@ -778,10 +709,6 @@ marker="diameter_transport">diameter_transport(3)</seealso>. Defaults to <c>diameter_tcp</c> if unspecified.</p> <p> -The interface required of a transport module is documented in <seealso -marker="diameter_transport">diameter_transport(3)</seealso>.</p> - -<p> Multiple <c>transport_module</c> and <c>transport_config</c> options are allowed. The order of these is significant in this case (and only in this case), @@ -790,7 +717,7 @@ a <c>transport_module</c> being paired with the first default value for trailing modules. Transport starts will be attempted with each of the modules in order until one establishes a connection within the -corresponding timeout (see <c>transport_config</c> below) or all fail.</p> +corresponding timeout (see below) or all fail.</p> </item> <tag><c>{transport_config, term()}</c></tag> @@ -824,28 +751,24 @@ To listen on both SCTP and TCP, define one transport for each.</p> <tag><c>{applications, [<seealso marker="#application_alias">application_alias()</seealso>]}</c></tag> <item> <p> -The list of Diameter applications to which usage of the transport -should be restricted. -Defaults to all applications configured on the service -in question. -Must only specify applications defined on the service to which -the transport is added.</p> +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> </item> <tag><c>{capabilities, [<seealso marker="#capability">capability()</seealso>]}</c></tag> <item> <p> AVP's used to construct outgoing CER/CEA messages. -Any AVP specified takes precedence over a corresponding value specified -for the service in question.</p> +Values take precedence over any specified on the service in +question.</p> <p> Specifying a capability as a transport option -may be particularly appropriate for Inband-Security-Id in case +may be particularly appropriate for Inband-Security-Id, in case TLS is desired over TCP as implemented by -<seealso marker="diameter_tcp">diameter_tcp(3)</seealso> but -not over SCTP as implemented by -<seealso marker="diameter_sctp">diameter_sctp(3)</seealso>.</p> +<seealso marker="diameter_tcp">diameter_tcp(3)</seealso>.</p> </item> <tag><c>{capabilities_cb, <seealso marker="#evaluable">evaluable()</seealso>}</c></tag> @@ -854,9 +777,9 @@ not over SCTP as implemented by A callback invoked upon reception of CER/CEA during capabilities exchange in order to ask whether or not the connection should be accepted. -Applied to the transport reference (as returned by <seealso -marker="#add_transport">add_transport/2</seealso>) and -<c>diameter_caps</c> record of the connection. +Applied to the relevant <seealso +marker="#transport_ref">transport_ref()</seealso> and the +<c>#diameter_caps{}</c> record of the connection. Returning <c>ok</c> accepts the connection. Returning <c>integer()</c> causes an incoming CER to be answered with the specified Result-Code. @@ -871,6 +794,8 @@ code causes the transport connection to be broken.</p> Multiple <c>capabilities_cb</c> options can be specified, in which case the corresponding callbacks are applied until either all return <c>ok</c> or one does not.</p> + +<marker id="watchdog_timer"/> </item> <tag><c>{watchdog_timer, TwInit}</c></tag> @@ -892,6 +817,8 @@ the callback.</p> <p> An integer value must be at least 6000 as required by RFC 3539. Defaults to 30000 if unspecified.</p> + +<marker id="reconnect_timer"/> </item> <tag><c>{reconnect_timer, Tc}</c></tag> @@ -902,7 +829,7 @@ Tc = <seealso marker="diameter_dict#DATA_TYPES">Unsigned32()</seealso> <p> For a connecting transport, the RFC 3588 Tc timer, in milliseconds. -Note that this timer determines the frequency with which the transport +Note that this timer determines the frequency with which a transport will attempt to establish a connection with its peer only <em>before</em> an initial connection is established: once there is an initial connection it's watchdog_timer that determines the frequency of @@ -915,8 +842,8 @@ regarded as an initial connection rather than a reestablishment, causing the RFC 3539 state machine to pass to state OPEN rather than REOPEN. Note that these semantics are not goverened by the RFC and -that a listening transport's reconnect_timer should be greater than its -peer's Tc plus jitter.</p> +that a listening transport's <c>reconnect_timer</c> should be greater +than its peer's Tw plus jitter.</p> <p> Defaults to 30000 for a connecting transport and 60000 for a listening @@ -954,12 +881,12 @@ identifies the configuration.</p> <!-- ===================================================================== --> <func> -<name>add_transport(SvcName, {connect|listen, Options}) +<name>add_transport(SvcName, {connect|listen, [Opt]}) -> {ok, Ref} | {error, Reason}</name> <fsummary>Add transport capability to a service.</fsummary> <type> <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v> -<v>Options = [<seealso marker="#transport_opt">transport_opt()</seealso>]</v> +<v>Opt = <seealso marker="#transport_opt">transport_opt()</seealso></v> <v>Ref = <seealso marker="#transport_ref">transport_ref()</seealso></v> <v>Reason = term()</v> </type> @@ -984,16 +911,20 @@ marker="diameter_app#peer_up">peer_up/3</seealso> callback after which the caller can exchange Diameter messages with the peer over the transport. In addition to CER/CEA, the service takes responsibility for the -handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.</p> +handling of DWR/DWA and required by RFC 3539, as well as for DPR/DPA.</p> <p> The returned reference uniquely identifies the transport within the scope of the service. Note that the function returns before a transport connection has been -established. +established.</p> + +<note> +<p> It is not an error to add a transport to a service that has not yet been configured: a service can be started after configuring -transports.</p> +its transports.</p> +</note> <marker id="call"/> </desc> @@ -1002,48 +933,47 @@ transports.</p> <!-- ===================================================================== --> <func> -<name>call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason}</name> +<name>call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason}</name> <fsummary>Send a Diameter request message.</fsummary> <type> <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v> <v>App = <seealso marker="#application_alias">application_alias()</seealso></v> <v>Request = <seealso marker="diameter_app#message">diameter_app:message()</seealso></v> <v>Answer = term()</v> -<v>Options = [<seealso marker="#call_opt">call_opt()</seealso>]</v> +<v>Opt = <seealso marker="#call_opt">call_opt()</seealso></v> </type> <desc> <p> -Send a Diameter request message and possibly return the answer or error.</p> +Send a Diameter request message.</p> <p> -<c>App</c> identifies the Diameter application in which the request is +<c>App</c> specifies the Diameter application in which the request is defined and callbacks to the corresponding callback module will follow as described below and in <seealso marker="diameter_app">diameter_app(3)</seealso>. -Unless the <c>detach</c> option has been specified to cause an earlier -return, the call returns either when an answer message is received -from the peer or an error occurs. -In the case of an answer, the return value is as returned by a +Unless the <c>detach</c> option is specified, the call returns either +when an answer message is received from the peer or an error occurs. +In the answer case, the return value is as returned by a <seealso marker="diameter_app#handle_answer">handle_answer/4</seealso> callback. -In the case of an error, whether or not the error is returned directly +In the error case, whether or not the error is returned directly by diameter or from a <seealso marker="diameter_app#handle_error">handle_error/4</seealso> callback depends on whether or not the outgoing request is -successfully encoded for transmission from the peer, the cases being +successfully encoded for transmission to the peer, the cases being documented below.</p> <p> If there are no suitable peers, or if <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> -rejects them by returning 'false', then <c>{error, no_connection}</c> +rejects them by returning <c>false</c>, then <c>{error,no_connection}</c> is returned. Otherwise <seealso marker="diameter_app#pick_peer">pick_peer/4</seealso> is followed by a <seealso marker="diameter_app#prepare_request">prepare_request/3</seealso> -callback, the message is encoded and sent.</p> +callback, the message is encoded and then sent.</p> <p> There are several error cases which may prevent an @@ -1056,7 +986,7 @@ callback:</p> <item> <p> If the initial encode of the outgoing request -fails, then the request process fails and <c>{error, encode}</c> +fails, then the request process fails and <c>{error,encode}</c> is returned.</p> </item> @@ -1073,7 +1003,7 @@ callback takes place with <c>Reason = timeout</c>.</p> If the request is successfully encoded and sent but the service in question is stopped before an answer is received then a <seealso marker="diameter_app#handle_error">handle_error/4</seealso> -callback takes place <c>Reason = cancel</c>.</p> +callback takes place with <c>Reason = cancel</c>.</p> </item> <item> @@ -1100,7 +1030,7 @@ callback.</p> <p> If an encode error takes place during retransmission then the request process fails and -<c>{error, failure}</c> is returned.</p> +<c>{error,failure}</c> is returned.</p> </item> <item> @@ -1108,7 +1038,7 @@ retransmission then the request process fails and If an application callback made in processing the request fails (pick_peer, prepare_request, prepare_retransmit, handle_answer or handle_error) then either -<c>{error, encode}</c> or <c>{error, failure}</c> +<c>{error,encode}</c> or <c>{error,failure}</c> is returned depending on whether or not there has been an attempt to send the request over the transport.</p> </item> @@ -1116,9 +1046,9 @@ attempt to send the request over the transport.</p> </list> <p> -Note that <c>{error, encode}</c> is the only return value which +Note that <c>{error,encode}</c> is the only return value which guarantees that the request has <em>not</em> been sent over the -transport.</p> +transport connection.</p> <marker id="origin_state_id"/> </desc> @@ -1167,7 +1097,7 @@ An arity-3-valued <c>Pred</c> removes all transports for which <c>Pred(Ref, Type, Opts)</c> returns <c>true</c>, where <c>Type</c> and <c>Opts</c> are as passed to <seealso marker="#add_transport">add_transport/2</seealso> and <c>Ref</c> is -as returned by the corresponding call. +as returned by it. The remaining forms are equivalent to an arity-3 fun as follows.</p> <code> @@ -1183,7 +1113,7 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end <p> Removing a transport causes all associated transport connections to be broken. -A base application DPR message with +A DPR message with Disconnect-Cause <c>DO_NOT_WANT_TO_TALK_TO_YOU</c> will be sent to each connected peer before disassociating the transport configuration from the service and terminating the transport upon reception of @@ -1198,10 +1128,12 @@ DPA or timeout.</p> <!-- ===================================================================== --> <func> -<name>service_info(SvcName, Item) -> term()</name> +<name>service_info(SvcName, Info) -> term()</name> <fsummary>Return information about a started service.</fsummary> <type> <v>SvcName = <seealso marker="#service_name">service_name()</seealso></v> +<v>Info = Item | [Info]</v> +<v>Item = atom()</v> </type> <desc> <p> @@ -1224,16 +1156,14 @@ Return information about a started service. <tag><c>'Firmware-Revision'</c></tag> <item> <p> -Return a capability value as configured on the service at <seealso -marker="#start_service">start_service/2</seealso>. -Note that all capabilities are returned in a tagged list with the -<c>capabilities</c> item.</p> +Return a capability value as configured with <seealso +marker="#start_service">start_service/2</seealso>.</p> </item> <tag><c>applications</c></tag> <item> <p> -Return the list of applications configured on the service at <seealso +Return the list of applications as configured with <seealso marker="#start_service">start_service/2</seealso>. </p> </item> @@ -1241,22 +1171,22 @@ marker="#start_service">start_service/2</seealso>. <tag><c>capabilities</c></tag> <item> <p> -Return a tagged list of all capabilities values configured on the service -at <seealso +Return a tagged list of all capabilities values as configured with +<seealso marker="#start_service">start_service/2</seealso>.</p> </item> <tag><c>transport</c></tag> <item> <p> -Return a list containing one entry for every transport configured on -the service with <seealso +Return a list containing one entry for each of the service's transport +as configured with <seealso marker="#add_transport">add_transport/2</seealso>. Each entry is a tagged list containing both configuration and information about established peer connections. An example return value with for a client service with Origin-Host -"client.example.com" configured with a single transport connected to "server.example.com" -might look as follows.</p> +"client.example.com" configured with a single transport connected to +"server.example.com" might look as follows.</p> <code> [[{ref,#Ref<0.0.0.93>}, @@ -1306,21 +1236,20 @@ might look as follows.</p> </code> <p> -Here <c>ref</c> is the <seealso -marker="#transport_ref">transport_ref()</seealso> of the service's -transport and <c>options</c> are as were passed to <seealso +Here <c>ref</c> is a <seealso +marker="#transport_ref">transport_ref()</seealso> and <c>options</c> +the corresponding <seealso +marker="#transport_opt">transport_opt()</seealso> list passed to <seealso marker="#add_transport">add_transport/2</seealso>. The <c>watchdog</c> entry shows the state of a connection's RFC 3539 watchdog state machine. The <c>peer</c> entry identifies the <seealso marker="diameter_app#peer_ref">diameter_app:peer_ref()</seealso> for -which there will have been a <seealso -marker="diameter_app#peer_up">peer_up</seealso> callback for the -Diameter applications negotiated during capabilities exchange, which -are identified by the <c>apps</c> entry, <c>common</c> in this case -being the <seealso -marker="#application_alias">application_alias()</seealso> of this -application with Application Id 0. +which there will have been <seealso +marker="diameter_app#peer_up">peer_up</seealso> callbacks for the +Diameter applications identified by the <c>apps</c> entry, +<c>common</c> being the <seealso +marker="#application_alias">application_alias()</seealso>. The <c>caps</c> entry identifies the capabilities sent by the local node and received from the peer during capabilities exchange. The <c>port</c> entry displays socket-level information about the @@ -1353,7 +1282,7 @@ connection might look as follows.</p> {port,3868}]}]}, {accept,[[{watchdog,{<0.56.0>,{1346,171481,226895},okay}}, {peer,{<0.58.0>,{1346,171491,999511}}}, - {apps,[{0,server}]}, + {apps,[{0,common}]}, {caps,[{origin_host,{"server.example.com","client.example.com"}}, {origin_realm,{"example.com","example.com"}}, {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}}, @@ -1419,7 +1348,7 @@ A return value for the server above might look as follows.</p> {port,3868}]}]}, {watchdog,{<0.56.0>,{1346,171481,226895},okay}}, {peer,{<0.58.0>,{1346,171491,999511}}}, - {apps,[{0,server}]}, + {apps,[{0,common}]}, {caps,[{origin_host,{"server.example.com","client.example.com"}}, {origin_realm,{"example.com","example.com"}}, {host_ip_address,{[{127,0,0,1}],[{127,0,0,1}]}}, @@ -1481,6 +1410,12 @@ The Diameter-level statistics returned by <c>transport</c> and </taglist> +<p> +Requesting info for an unknown service causes <c>undefined</c> to be +returned. +Requesting a list of items causes a tagged list to be +returned.</p> + <marker id="services"/> </desc> </func> @@ -1554,8 +1489,7 @@ Start a diameter service.</p> <p> A service defines a locally-implemented Diameter node, specifying the -capabilities of the node to be used during capabilities exchange and -the Diameter applications that it supports. +capabilities to be advertised during capabilities exchange. Transports are added to a service using <seealso marker="#add_transport">add_transport/2</seealso>. </p> @@ -1599,6 +1533,19 @@ Stop the diameter application.</p> <p> Stop a diameter service.</p> +<p> +Stopping a service causes all associated transport connections to be +broken. +A DPR message with be sent as in the case of <seealso +marker="#remove_transport">remove_transport/2</seealso>.</p> + +<note> +<p> +Stopping a transport does not remove any associated transports: +<seealso marker="#remove_transport">remove_transport/2</seealso> must +be called to remove transport configuration.</p> +</note> + <marker id="subscribe"/> </desc> </func> @@ -1614,7 +1561,7 @@ Stop a diameter service.</p> <desc> <p> Subscribe to <seealso -marker="#service_event"><c>service_event()</c></seealso> messages from +marker="#service_event">service_event()</seealso> messages from a service.</p> <p> |