From e70a331569b2d161d976950d209989a5dc06a2bc Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Wed, 29 Aug 2012 02:23:28 +0200 Subject: Assorted doc improvements --- lib/diameter/doc/src/diameter.xml | 457 ++++++++++++---------------- lib/diameter/doc/src/diameter_app.xml | 13 +- lib/diameter/doc/src/diameter_transport.xml | 62 ++-- 3 files changed, 241 insertions(+), 291 deletions(-) (limited to 'lib') 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.

-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.

@@ -61,17 +61,15 @@ marker="diameter_app">diameter_app(3) callback modules as specified in the service configuration.

-Beware the difference between diameter application and -Diameter application. +Beware the difference between diameter (not capitalised) and +Diameter (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.

+api is defined here, the latter to Diameter protocol in the sense of +RFC 3588.

-The diameter application must be started before calling functions in -this module.

+The diameter application must be started before calling most functions +in this module.

 @@ -100,10 +98,9 @@ Defined in diameter_dict(4)

A name identifying a Diameter application in -service configuration passed to start_service/2 and passed to -call/4 when sending requests -belonging to the application.

+service configuration. +Passed to call/4 when sending requests +defined by the application.

 @@ -121,19 +118,14 @@ ExtraArgs = list() A module implementing the callback interface defined in diameter_app(3), 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 call/4, in which case -the call-specific arguments are appended to any specified with the -callback module.

+those are are appended to any module-specific extra arguments.

Specifying a #diameter_callback{} record allows individual functions to be configured in place of the usual diameter_app(3) callbacks, with -default implementations provided by module diameter_callback -unless otherwise specified. +marker="diameter_app">diameter_app(3) callbacks. See that module for details.

@@ -143,9 +135,8 @@ See that module for details.

-Options defining a Diameter application as configured in an -application option passed to -start_service/2.

+Options defining a Diameter application. +Has one the following types.

@@ -154,7 +145,8 @@ Options defining a Diameter application as configured in an

An unique identifier for the application in the scope of the service. -Optional, defaults to the value of the dictionary option.

+Defaults to the value of the dictionary option if +unspecified.

 {dictionary, atom()} @@ -170,20 +162,20 @@ marker="diameter_dict">diameter_dict(4).

{module, application_module()}

-A callback module with which messages of the Diameter application are +The callback module with which messages of the Diameter application are handled. See diameter_app(3) for -information on the required interface and semantics.

+the required interface and semantics.

 {state, term()}

The initial callback state. -Defaults to the value of the alias option if unspecified. -The prevailing state is passed to certain +The prevailing state is passed to some diameter_app(3) -callbacks, which can then return a new state.

+callbacks, which can then return a new state. +Defaults to the value of the alias option if unspecified.

 {call_mutates_state, true|false} @@ -191,19 +183,18 @@ callbacks, which can then return a new state.

Specifies whether or not the pick_peer/4 -application callback (following from a call to -call/4) -can modifiy state, +application callback can modify the application state, Defaults to false if unspecified.

+

-Note that pick_peer callbacks are -serialized when these are allowed to modify state, which is a +pick_peer 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.

+state but a server or agent that responds to incoming request should +probably avoid it.

+ {answer_errors, callback|report|discard} @@ -214,9 +205,9 @@ decode errors are handled. If callback then errors result in a handle_answer/4 callback in the same fashion as for handle_request/3, in the -errors field of the diameter_packet record passed into -the callback. +marker="diameter_app#handle_request">handle_request/3, with +errors communicated in the errors field of the +#diameter_packet{} record passed to the callback. If report then an answer containing errors is discarded without a callback and a warning report is written to the log. If discard then an answer containing errors is silently @@ -240,7 +231,8 @@ Defaults to report if unspecified.

Options available to call/4 when -sending an outgoing Diameter request.

+sending an outgoing Diameter request. +Has one of the following types.

@@ -249,7 +241,7 @@ sending an outgoing Diameter request.

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.

@@ -299,120 +291,55 @@ to fail.

-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.

+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.

{'Origin-Host', DiameterIdentity()} - -

-Value of the Origin-Host AVP in outgoing messages.

- - {'Origin-Realm', DiameterIdentity()} - -

-Value of the Origin-Realm AVP in outgoing messages.

- - {'Host-IP-Address', [Address()]}

-Values of Host-IP-Address AVPs. -Optional.

- -

-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.

+An address list is available to the start function of a +transport module, 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.

 {'Vendor-Id', Unsigned32()} - -

-Value of the Vendor-Id AVP sent in an outgoing capabilities -exchange message.

- - {'Product-Name', UTF8String()} - -

-Value of the Product-Name AVP sent in an outgoing capabilities -exchange message.

- - {'Origin-State-Id', Unsigned32()}

-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.

- -

+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 0 (zero) is equivalent to not setting a value as documented in RFC 3588. The function origin_state_id/0 -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.

 {'Supported-Vendor-Id', [Unsigned32()]} - -

-Values of Supported-Vendor-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.

- - {'Auth-Application-Id', [Unsigned32()]} - -

-Values of Auth-Application-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.

- - {'Inband-Security-Id', [Unsigned32()]}

-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).

- -

+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.

 {'Acct-Application-Id', [Unsigned32()]} - -

-Values of Acct-Application-Id AVPs sent in an outgoing -capabilities exchange message. -Optional, defaults to the empty list.

- - {'Vendor-Specific-Application-Id', [Grouped()]} - -

-Values of Vendor-Specific-Application-Id AVPs sent in -an outgoing capabilities exchange message. -Optional, defaults to the empty list.

- - {'Firmware-Revision', Unsigned32()} - -

-Value of the Firmware-Revision AVP sent in an outgoing capabilities -exchange message. -Optional.

- @@ -444,11 +371,13 @@ eval(F) -> Applying an evaluable() E to an argument list A is meant in the sense of eval([E|A]).

+

-Beware of using local funs (that is, fun expressions not of the -form fun Module: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.

+Beware of using fun expressions of the form fun Name/Arity (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.

+ @@ -501,14 +430,14 @@ specified value, or all peers if the atom any.

Matches only those peers whose Origin-Realm has the -value, or all peers if the atom any.

+specified value, or all peers if the atom any.

 {eval, evaluable()}

Matches only those peers for which the specified #evaluable() returns +marker="#evaluable">evaluable() returns true on the connection's diameter_caps record. Any other return value or exception is equivalent to false.

 @@ -522,20 +451,21 @@ Matches only those peers not matched by the specified filter.

{all, [peer_filter()]}

-Matches only those peers matched by each filter of the specified list.

+Matches only those peers matched by each filter in the specified list.

 {any, [peer_filter()]}

-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.

 +

-Note that the host and realm filters examine the +The host and realm filters examine the outgoing request as passed to call/4, assuming that this is a record- or list-valued diameter_app:message(), and that @@ -543,11 +473,12 @@ the message contains at most one of each AVP. If this is not the case then the {host|realm, DiameterIdentity()} 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.

+

-An invalid filter is equivalent to {any, []}, a filter +An invalid filter is equivalent to {any,[]}, a filter that matches no peer.

@@ -556,12 +487,12 @@ that matches no peer.

service_event() = #diameter_event{}

-Event message sent to processes that have subscribed using subscribe/1.

+An event message sent to processes that have subscribed to these using +subscribe/1.

-The info field of the event record can be one of the -following.

+The info field of the event record can have one of the +following types.

@@ -578,19 +509,19 @@ Pkt = #diameter_packet{}

The RFC 3539 watchdog state machine has -transitioned into (up) or out of (down) the open +transitioned into (up) or out of (down) the OKAY state. -If a diameter_packet record is present in an up 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 #diameter_packet{} record is present in an up 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.

-Note that a single up/down event for a given peer corresponds to -as many peer_up/peer_down -callbacks as there are Diameter applications that have been negotiated -during capablilities exchange. +Note that a single up/down event for a given peer +corresponds to one peer_up/peer_down +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.

@@ -605,8 +536,10 @@ Opts = [transport_opt()]

A connecting transport is attempting to establish/reestablish a -transport connection with a peer following reconnect_timer or -watchdog_timer expiry.

+transport connection with a peer following reconnect_timer or +watchdog_timer +expiry.

 {closed, Ref, Reason, Config} @@ -617,8 +550,8 @@ Config = {connect|listen, [transport_opt()

-Capabilities exchange has failed. Reason can be one of -the following.

+Capabilities exchange has failed. +Reason can have one of the following types.

@@ -635,11 +568,11 @@ CB = evaluable()

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. +Caps contains pairs of values for the the local node and remote +peer. +Pkt contains the CER in question. In the case of rejection by a capabilities callback, the tuple -indicates the rejecting callback.

+contains the rejecting callback.

{'CER', Caps, {ResultCode, Pkt}} @@ -653,9 +586,8 @@ Pkt = #diameter_packet{}

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.

+Caps contains only values for the the local node. +Pkt contains the CER in question.

{'CEA', Result, Caps, Pkt} @@ -671,11 +603,11 @@ ResultCode = integer() An incoming CEA has been rejected for the indicated reason. An integer-valued Result 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. +Caps contains pairs of values for the the local node and remote +peer. +Pkt contains the CEA in question. In the case of rejection by a capabilities callback, the tuple -indicates the rejecting callback.

+contains the rejecting callback.

{'CEA', Caps, Pkt} @@ -686,9 +618,9 @@ Pkt = #diameter_packet{}

-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.

+An incoming CEA contained errors and has been rejected. +Caps contains only values for the the local node. +Pkt contains the CEA in question.

 @@ -732,9 +664,9 @@ that is somewhat unique.

service_opt()

-Options accepted by start_service/2. -Can be any capability() tuple as +Can be any capability() as well as the following.

@@ -745,17 +677,15 @@ well as the following.

Defines a Diameter application supported by the service.

-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 application_alias() to -call/4, while for an +A service must configure one application for each Diameter +application it intends to support. +For an outgoing Diameter request, the relevant application_alias() is +passed to call/4, 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 dictionary file defining the -application.

+header determines the application, the identifier being specified in +the application's dictionary +file.

 @@ -766,8 +696,9 @@ application.

transport_opt()

-Options accepted by add_transport/2.

+An option passed to add_transport/2. +Has one of the following types.

{transport_module, atom()} @@ -777,10 +708,6 @@ A module implementing a transport process as defined in diameter_transport(3). Defaults to diameter_tcp if unspecified.

-

-The interface required of a transport module is documented in diameter_transport(3).

-

Multiple transport_module and transport_config options are allowed. @@ -790,7 +717,7 @@ a transport_module 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 transport_config below) or all fail.

+corresponding timeout (see below) or all fail.

 {transport_config, term()} @@ -824,28 +751,24 @@ To listen on both SCTP and TCP, define one transport for each.

{applications, [application_alias()]}

-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.

+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.

 {capabilities, [capability()]}

AVP's used to construct outgoing CER/CEA messages. -Any AVP specified takes precedence over a corresponding value specified -for the service in question.

+Values take precedence over any specified on the service in +question.

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 -diameter_tcp(3) but -not over SCTP as implemented by -diameter_sctp(3).

+diameter_tcp(3).

 {capabilities_cb, evaluable()} @@ -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 add_transport/2) and -diameter_caps record of the connection. +Applied to the relevant transport_ref() and the +#diameter_caps{} record of the connection. Returning ok accepts the connection. Returning integer() causes an incoming CER to be answered with the specified Result-Code. @@ -871,6 +794,8 @@ code causes the transport connection to be broken.

Multiple capabilities_cb options can be specified, in which case the corresponding callbacks are applied until either all return ok or one does not.

+ + {watchdog_timer, TwInit} @@ -892,6 +817,8 @@ the callback.

An integer value must be at least 6000 as required by RFC 3539. Defaults to 30000 if unspecified.

+ + {reconnect_timer, Tc} @@ -902,7 +829,7 @@ Tc = Unsigned32()

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 before 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.

+that a listening transport's reconnect_timer should be greater +than its peer's Tw plus jitter.

Defaults to 30000 for a connecting transport and 60000 for a listening @@ -954,12 +881,12 @@ identifies the configuration.

-add_transport(SvcName, {connect|listen, Options}) +add_transport(SvcName, {connect|listen, [Opt]}) -> {ok, Ref} | {error, Reason} Add transport capability to a service. SvcName = service_name() -Options = [transport_opt()] +Opt = transport_opt() Ref = transport_ref() Reason = term() @@ -984,16 +911,20 @@ marker="diameter_app#peer_up">peer_up/3 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.

+handling of DWR/DWA and required by RFC 3539, as well as for DPR/DPA.

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.

+ + +

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.

+its transports.

+ @@ -1002,48 +933,47 @@ transports.

-call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason} +call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason} Send a Diameter request message. SvcName = service_name() App = application_alias() Request = diameter_app:message() Answer = term() -Options = [call_opt()] +Opt = call_opt()

-Send a Diameter request message and possibly return the answer or error.

+Send a Diameter request message.

-App identifies the Diameter application in which the request is +App specifies the Diameter application in which the request is defined and callbacks to the corresponding callback module will follow as described below and in diameter_app(3). -Unless the detach 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 detach 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 handle_answer/4 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 handle_error/4 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.

If there are no suitable peers, or if pick_peer/4 -rejects them by returning 'false', then {error, no_connection} +rejects them by returning false, then {error,no_connection} is returned. Otherwise pick_peer/4 is followed by a prepare_request/3 -callback, the message is encoded and sent.

+callback, the message is encoded and then sent.

There are several error cases which may prevent an @@ -1056,7 +986,7 @@ callback:

If the initial encode of the outgoing request -fails, then the request process fails and {error, encode} +fails, then the request process fails and {error,encode} is returned.

 @@ -1073,7 +1003,7 @@ callback takes place with Reason = timeout.

If the request is successfully encoded and sent but the service in question is stopped before an answer is received then a handle_error/4 -callback takes place Reason = cancel.

+callback takes place with Reason = cancel.

@@ -1100,7 +1030,7 @@ callback.

If an encode error takes place during retransmission then the request process fails and -{error, failure} is returned.

+{error,failure} is returned.

 @@ -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 -{error, encode} or {error, failure} +{error,encode} or {error,failure} is returned depending on whether or not there has been an attempt to send the request over the transport.

 @@ -1116,9 +1046,9 @@ attempt to send the request over the transport.

-Note that {error, encode} is the only return value which +Note that {error,encode} is the only return value which guarantees that the request has not been sent over the -transport.

+transport connection.

 @@ -1167,7 +1097,7 @@ An arity-3-valued Pred removes all transports for which Pred(Ref, Type, Opts) returns true, where Type and Opts are as passed to add_transport/2 and Ref is -as returned by the corresponding call. +as returned by it. The remaining forms are equivalent to an arity-3 fun as follows.

@@ -1183,7 +1113,7 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end

Removing a transport causes all associated transport connections to be broken. -A base application DPR message with +A DPR message with Disconnect-Cause DO_NOT_WANT_TO_TALK_TO_YOU 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.

-service_info(SvcName, Item) -> term() +service_info(SvcName, Info) -> term() Return information about a started service. SvcName = service_name() +Info = Item | [Info] +Item = atom()

@@ -1224,16 +1156,14 @@ Return information about a started service. 'Firmware-Revision'

-Return a capability value as configured on the service at start_service/2. -Note that all capabilities are returned in a tagged list with the -capabilities item.

+Return a capability value as configured with start_service/2.

applications

-Return the list of applications configured on the service at start_service/2.

@@ -1241,22 +1171,22 @@ marker="#start_service">start_service/2. capabilities

-Return a tagged list of all capabilities values configured on the service -at start_service/2.

 transport

-Return a list containing one entry for every transport configured on -the service with add_transport/2. 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.

+"client.example.com" configured with a single transport connected to +"server.example.com" might look as follows.

[[{ref,#Ref<0.0.0.93>}, @@ -1306,21 +1236,20 @@ might look as follows.

-Here ref is the transport_ref() of the service's -transport and options are as were passed to ref is a transport_ref() and options +the corresponding transport_opt() list passed to add_transport/2. The watchdog entry shows the state of a connection's RFC 3539 watchdog state machine. The peer entry identifies the diameter_app:peer_ref() for -which there will have been a peer_up callback for the -Diameter applications negotiated during capabilities exchange, which -are identified by the apps entry, common in this case -being the application_alias() of this -application with Application Id 0. +which there will have been peer_up callbacks for the +Diameter applications identified by the apps entry, +common being the application_alias(). The caps entry identifies the capabilities sent by the local node and received from the peer during capabilities exchange. The port entry displays socket-level information about the @@ -1353,7 +1282,7 @@ connection might look as follows.

{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.

{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 transport and +

+Requesting info for an unknown service causes undefined to be +returned. +Requesting a list of items causes a tagged list to be +returned.

+ @@ -1554,8 +1489,7 @@ Start a diameter service.

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 add_transport/2.

@@ -1599,6 +1533,19 @@ Stop the diameter application.

Stop a diameter service.

+

+Stopping a service causes all associated transport connections to be +broken. +A DPR message with be sent as in the case of remove_transport/2.

+ + +

+Stopping a transport does not remove any associated transports: +remove_transport/2 must +be called to remove transport configuration.

+ + @@ -1614,7 +1561,7 @@ Stop a diameter service.

Subscribe to service_event() messages from +marker="#service_event">service_event() messages from a service.

diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index 6e5c957eec..f6d53808f5 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -140,8 +140,8 @@ list of {FieldName, FieldValue} pairs.

A third representation allows a message to be specified as a list -whose head is a diameter_header record and whose tail is a list -of diameter_avp records. +whose head is a #diameter_header{} record and whose tail is a list +of #diameter_avp{} records. This representation is used by diameter itself when relaying requests as directed by the return value of a handle_request/3 @@ -158,10 +158,9 @@ are sent exactly as specified.

packet() = #diameter_packet{}

-A container for incoming and outgoing Diameters message that's passed +A container for incoming and outgoing Diameter messages that's passed through encode/decode and transport. -Fields of a packet() record should not be set in return values except -as documented.

+Fields should not be set in return values except as documented.

 @@ -356,7 +355,7 @@ Extra arguments passed to diameter:call/4 can be used to communicate transport data to the callback. A returned packet() can also set the header field to a -diameter_header record in order to specify values that should +#diameter_header{} 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. @@ -603,7 +602,7 @@ header of the relayed request.

The returned Opts should not specify detach. A subsequent handle_answer/4 callback for the relayed request must return its first -argument, the diameter_packet record containing the answer +argument, the #diameter_packet{} record containing the answer message. Note that the extra option can be specified to supply arguments that can distinguish the relay case from others if so desired. diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index 4ed02e3881..4890333669 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -93,16 +93,19 @@ It should not link to the parent. It should exit if its transport connection with its peer is lost.

-Transport processes for a given service are started sequentially.

- -

-The start function should use the 'Host-IP-Address' list on the service, -namely Svc#diameter_service.host_ip_address, and/or +The capabilities in the #diameter_service{} record are as +passed to diameter:start_service/2 and +diameter:add_transport/2, +values passed to the latter overriding those passed to the former. +The start function should use the Host-IP-Address list and/or Opts to select an appropriate list of local IP addresses, -and should return this list if different from the service addresses. -The returned list is used to populate 'Host-IP-Address' AVPs in outgoing -capabilities exchange messages, the service addresses being used -otherwise.

+and should return this list if different from the +#diameter_service{} addresses. +The returned list is used to populate Host-IP-Address AVPs in +outgoing capabilities exchange messages, the +#diameter_service{} addresses being used otherwise.

 @@ -129,9 +132,10 @@ diameter.

An outbound Diameter message. -Packet can be either binary() (the message to be sent) -or a #diameter_packet{} whose transport_data field -containes a value other than undefined.

+Packet can be either binary() (the message to be sent) +or a #diameter_packet{} record whose transport_data +field contains a value other than undefined and whose bin field +contains the binary to send.

 {diameter, {close, Pid}} @@ -140,7 +144,7 @@ containes a value other than undefined.

A request to close the transport connection. The transport process should terminate after closing the connection. -Pid is the pid() of the parent process.

+Pid is the pid() of the parent process.

{diameter, {tls, Ref, Type, Bool}} @@ -148,17 +152,17 @@ Pid is the pid() of the parent process.

Indication of whether or not capabilities exchange has selected inband security using TLS. -Ref is a reference() that must be included in the +Ref is a reference() that must be included in the {diameter, {tls, Ref}} reply message to the transport's parent process (see below). -Type is either connect or accept depending on +Type is either connect or accept depending on whether the process has been started for a connecting or listening transport respectively. -Bool is a boolean() indicating whether or not the transport connection -should be upgraded to TLS.

+Bool is a boolean() indicating whether or not the transport +connection should be upgraded to TLS.

-If TLS is requested (Bool = true) then a connecting process should +If TLS is requested (Bool = true) then a connecting process should initiate a TLS handshake with the peer and an accepting process should prepare to accept a handshake. A successful handshake should be followed by a {diameter, {tls, Ref}} @@ -182,18 +186,18 @@ to its parent.

{diameter, {self(), connected}}

-Inform the parent that the transport process with Type = accept has +Inform the parent that the transport process with Type=accept has established a connection with the peer. -Not sent if the transport process has Type = connect.

+Not sent if the transport process has Type=connect.

 {diameter, {self(), connected, Remote}}

-Inform the parent that the transport process with Type = connect +Inform the parent that the transport process with Type=connect has established a connection with a peer. -Not sent if the transport process has Type = accept. -Remote is an arbitrary term that uniquely identifies the remote +Not sent if the transport process has Type=accept. +Remote is an arbitrary term that uniquely identifies the remote endpoint to which the transport has connected.

 @@ -201,14 +205,14 @@ endpoint to which the transport has connected.

An inbound Diameter message. -Packet can be either binary() (the message to be sent) -or #diameter_packet{} -whose packet field contains a binary(). -Any value (other than undefined) set in +Packet can be either binary() (the received message) +or a #diameter_packet{} record +whose bin field contains the received binary(). +Any value (other than undefined) set in the transport_data field will be passed back with a corresponding answer message in the case that the inbound message is a request unless the sender sets another value. -How the transport_data is used/interpreted is up to the +How transport_data is used/interpreted is up to the transport module.

 @@ -216,7 +220,7 @@ transport module.

Acknowledgment of a successful TLS handshake. -Ref is the reference() received in the +Ref is the reference() received in the {diameter, {tls, Ref, Type, Bool}} message in response to which the reply is sent. A transport must exit if a handshake is not successful.

-- cgit v1.2.3