From 439dd4b95017a9966dd0cf1f090a9b00da831fe4 Mon Sep 17 00:00:00 2001
From: Anders Svensson
Basic usage consists of creating a representation of a
-locally implemented Diameter node and its capabilities with
@@ -90,7 +90,7 @@ in this module.
Types corresponding to RFC 3588 AVP Data Formats.
-Defined in
A name identifying a Diameter application in
service configuration.
-Passed to
-A module implementing the callback interface defined in
Specifying a
An unique identifier for the application in the scope of the @@ -156,17 +155,15 @@ unspecified.
The name of an encode/decode module for the Diameter messages defined by the application. These modules are generated from a specification file whose format is -documented in
The callback module with which messages of the Diameter application are
handled.
-See
The initial callback state.
The prevailing state is passed to some
-
-Specifies whether or not the
-
Determines the manner in which incoming answer messages containing
decode errors are handled.
-If
-Options available to
A filter to apply to the list of available peers before passing them to
-the
The number of milliseconds after which the request should @@ -269,21 +263,17 @@ Defaults to 5000.
-Causes
-An invalid option will cause
An address list is available to the start function of a @@ -312,24 +302,23 @@ Host-IP-Address need not be specified if the transport start function returns an address list.
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
Inband-Security-Id defaults to the empty list, which is equivalent to a @@ -338,9 +327,9 @@ If 1 (= TLS) is specified then TLS is selected if the CER/CEA received from the peer offers it.
-Applying an
-A filter passed to
Matches only those peers whose
Matches only those peers whose
-Matches only those peers for which the specified
Matches only those peers not matched by the specified filter.
Matches only those peers matched by each filter in the specified list.
Matches only those peers matched by at least one filter in the @@ -477,15 +461,12 @@ that matches no peer.
The
An event message sent to processes that have subscribed to these using
-
The
-Ref =@@ -546,7 +527,8 @@ connectivity.transport_ref() -Peer =diameter_app:peer() -Config = {connect|listen, [transport_opt() ]} +Ref = &transport_ref; +Peer = &app_peer; +Config = {connect|listen, [&transport_opt;]} Pkt = #diameter_packet{}
Note that a single
-Ref =transport_ref() -Opts = [transport_opt() ] +Ref = &transport_ref; +Opts = [&transport_opt;]
A connecting transport is attempting to establish/reestablish a
-transport connection with a peer following
-Ref =transport_ref() -Config = {connect|listen, [transport_opt() ]} +Ref = &transport_ref; +Config = {connect|listen, [&transport_opt;]}
@@ -589,7 +569,7 @@ Result = ResultCode | {capabilities_cb, CB, ResultCode|discard}
Caps = #diameter_caps{}
Pkt = #diameter_packet{}
ResultCode = integer()
-CB =
@@ -620,8 +600,7 @@ indicated result code.
-An expected CER was not received within
-An expected CEA was not received within
-Ref =@@ -694,8 +672,7 @@ info fields of forms other than the above.transport_ref() -PeerRef =diameter_app:peer_ref() +Ref = &transport_ref; +PeerRef = &app_peer_ref; From, To = initial | okay | suspect | down | reopen Config = {connect|listen, [transport_opt()]}
-The name of a service as passed to
-An option passed to
Defines a Diameter application supported by the service.
-A service must configure one
Specifies a constant value
@@ -798,13 +769,12 @@ Defaults to{0,32} .transport_opt() -An option passed to
add_transport/2 . +An option passed to &add_transport;. Has one of the following types.- + {applications, [ application_alias() ]}{applications, [&application_alias;]} The list of Diameter applications to which the transport should be @@ -814,7 +784,7 @@ Applications not configured on the service in question are ignored.
- + {capabilities, [ capability() ]}{capabilities, [&capability;]} AVP's used to construct outgoing CER/CEA messages. @@ -824,19 +794,17 @@ question.
Specifying a capability as a transport option may be particularly appropriate for Inband-Security-Id, in case -TLS is desired over TCP as implemented by -
+TLS is desired over TCP as implemented by &man_tcp;.diameter_tcp(3) .- + {capabilities_cb, evaluable() }{capabilities_cb, &evaluable;} 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
and +Applied to the transport_ref() &transport_ref; and#diameter_caps{} record of the connection.@@ -871,23 +839,22 @@ Equivalent to returning
3010 , DIAMETER_UNKNOWN_PEER.Returning anything but
ok or a 2xxx series result code causes the transport connection to be broken. -Multiplecapabilities_cb +Multiple &capabilities_cb; options can be specified, in which case the corresponding callbacks are applied until either all returnok or one does not.- + {capx_timeout, - Unsigned32() }{capx_timeout, &dict_Unsigned32;} 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. +governed by &watchdog_timer; or +&reconnect_timer; expiry. For a listening transport, the peer determines the timing.@@ -895,21 +862,19 @@ Defaults to 10000.
- + {disconnect_cb, evaluable() }{disconnect_cb, &evaluable;} - -
A callback invoked prior to terminating the transport process of a transport connection having watchdog state
OKAY . Applied toReason=transport|service|application and the -and - transport_ref() + diameter_app:peer() &transport_ref; and +&app_peer; in question,Reason indicating whether the the diameter application is being stopped, the service in question is being stopped -atstop_service/1 or -the transport in question is being removed atremove_transport/2 , +at &stop_service; or +the transport in question is being removed at &remove_transport;, respectively.@@ -934,8 +899,7 @@ Defaults to
rebooting forReason=service|application andgoaway forReason=transport .+ {timeout, - Unsigned32() }{timeout, &dict_Unsigned32;} The number of milliseconds after which the transport process is @@ -966,7 +930,7 @@ Equivalent to not having configured the callback.
-Multiple
disconnect_cb +Multiple &disconnect_cb; options can be specified, in which case the corresponding callbacks are applied until one of them returns a value other thanignore . @@ -981,7 +945,7 @@ Defaults to a single callback returningdpr .{reconnect_timer, Tc} -Tc =Unsigned32() +Tc = &dict_Unsigned32;@@ -989,8 +953,7 @@ For a connecting transport, the RFC 3588 Tc timer, in milliseconds. 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 +connection it's &watchdog_timer; that determines the frequency of reconnection attempts, as required by RFC 3539.@@ -1000,8 +963,7 @@ regarded as an initial connection rather than a reestablishment, causing the RFC 3539 state machine to pass to state OKAY rather than REOPEN. Note that these semantics are not governed by the RFC and -that a listening transport's
reconnect_timer should be greater +that a listening transport's &reconnect_timer; should be greater than its peer's Tw plus jitter.@@ -1011,13 +973,11 @@ transport.
- {transport_config, term()} + {transport_config, term(), Unsigned32() }{transport_config, term(), &dict_Unsigned32;} -A term passed as the third argument to the
@@ -1044,17 +1004,15 @@ To listen on both SCTP and TCP, define one transport for each.start/3 function of -the relevanttransport_module in order to +A term passed as the third argument to the &transport_start; function of +the relevant &transport_module; in order to start a transport process. Defaults to the empty list if unspecified.{transport_module, atom()} -A module implementing a transport process as defined in
diameter_transport(3) . +A module implementing a transport process as defined in &man_transport;. Defaults todiameter_tcp if unspecified.-Multiple
transport_module andtransport_config +Multipletransport_module and &transport_config; options are allowed. The order of these is significant in this case (and only in this case), atransport_module being paired with the first -transport_config +&transport_config; following it in the options list, or the default value for trailing modules. Transport starts will be attempted with each of the @@ -1066,7 +1024,7 @@ corresponding timeout (see below) or all fail.{watchdog_timer, TwInit} - @@ -1099,8 +1055,7 @@ marker="#remove_transport">remove_transport/2.
-TwInit =@@ -1088,10 +1046,8 @@ Defaults to 30000 if unspecified.Unsigned32() +TwInit = &dict_Unsigned32; | {M,F,A}Unrecognized options are silently ignored but are returned unmodified -by
+by &service_info; and can be referred to +in predicate functions passed to &remove_transport;.service_info/2 and can be referred to -in predicate functions passed toremove_transport/2 .transport_ref() = reference() - @@ -1118,9 +1073,9 @@ identifies the configuration. -> {ok, Ref} | {error, Reason}
-An reference returned by
add_transport/2 that +An reference returned by &add_transport; that identifies the configuration.Add transport capability to a service. - SvcName = -service_name() Opt = -transport_opt() Ref = +transport_ref() SvcName = &service_name; +Opt = &transport_opt; +Ref = &transport_ref; Reason = term() @@ -1139,8 +1094,7 @@ one peer, an listening transport potentially with many. The diameter application takes responsibility for exchanging CER/CEA with the peer. Upon successful completion of capabilities exchange the service -calls each relevant application module's peer_up/3 callback +calls each relevant application module's &app_peer_up; 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 @@ -1169,11 +1123,11 @@ its transports.call(SvcName, App, Request, [Opt]) -> Answer | ok | {error, Reason} Send a Diameter request message. - SvcName = -service_name() App = -application_alias() Request = +diameter_app:message() SvcName = &service_name; +App = &application_alias; +Request = &app_message; Answer = term() -Opt = +call_opt() Opt = &call_opt; @@ -1182,37 +1136,29 @@ Send a Diameter request message.
App specifies the Diameter application in which the request is defined and callbacks to the corresponding callback module -will follow as described below and indiameter_app(3) . +will follow as described below and in &man_app;. Unless thedetach 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. +&app_handle_answer; callback. In the error case, whether or not the error is returned directly -by diameter or from ahandle_error/4 +by diameter or from a &app_handle_error; callback depends on whether or not the outgoing request is successfully encoded for transmission to the peer, the cases being documented below.If there are no suitable peers, or if -
+Otherwise &app_pick_peer; is followed by a +&app_prepare_request; callback, the message is encoded and then sent.pick_peer/4 +&app_pick_peer; rejects them by returningfalse , then{error,no_connection} is returned. -Otherwisepick_peer/4 -is followed by a -prepare_request/3 -callback, the message is encoded and then sent.There are several error cases which may prevent an answer from being received and passed to a -
+&app_handle_answer; callback:handle_answer/4 -callback:@@ -1227,16 +1173,14 @@ is returned.
If the request is successfully encoded and sent but the answer times out then a -
+&app_handle_error; callback takes place withhandle_error/4 -callback takes place withReason = timeout .Reason = timeout .If the request is successfully encoded and sent but the service in question is stopped before an answer is received then a -
+&app_handle_error; callback takes place withhandle_error/4 -callback takes place withReason = cancel .Reason = cancel .- @@ -1245,18 +1189,11 @@ If the transport connection with the peer goes down after the request has been sent but before an answer has been received then an attempt is made to resend the request to an alternate peer. If no such peer is available, or if the subsequent -
pick_peer/4 -callback rejects the candidates, then a -handle_error/4 -callback takes place withReason = failover . -If a peer is selected then a -prepare_retransmit/3 +&app_pick_peer; callback rejects the candidates, then a +&app_handle_error; callback takes place withReason = failover . +If a peer is selected then a &app_prepare_retransmit; callback takes place, after which the semantics are the same as -following an initial --prepare_request/3 -callback. +following an initial &app_prepare_request; callback.- @@ -1290,7 +1227,7 @@ transport connection.
- origin_state_id() -> +Unsigned32() origin_state_id() -> &dict_Unsigned32; Returns a reasonable Origin-State-Id. @@ -1299,7 +1236,7 @@ outgoing messages.
The value returned is the number of seconds since 19680120T031408Z, -the first value that can be encoded as a Diameter
, +the first value that can be encoded as a Diameter Time() &dict_Time; , at the time the diameter application was started.@@ -1312,11 +1249,11 @@ at the time the diameter application was started. remove_transport(SvcName, Pred) -> ok | {error, Reason} Remove previously added transports. - SvcName = -service_name() Pred = Fun | MFA | +transport_ref() | list() | true | falseSvcName = &service_name; +Pred = Fun | MFA | &transport_ref; | list() | true | false - Fun = fun(( -transport_ref() , connect|listen, list()) -> boolean())| fun(( +transport_ref() , list()) -> boolean())Fun = fun((&transport_ref;, connect|listen, list()) -> boolean()) +| fun((&transport_ref;, list()) -> boolean()) | fun((list()) -> boolean()) MFA = {atom(), atom(), list()} Reason = term() @@ -1329,8 +1266,7 @@ Remove previously added transports.Pred determines which transports to remove. An arity-3-valuedPred removes all transports for whichPred(Ref, Type, Opts) returnstrue , whereType and -Opts are as passed toadd_transport/2 andRef is +Opts are as passed to &add_transport; andRef is as returned by it. The remaining forms are equivalent to an arity-3 fun as follows. @@ -1348,8 +1284,7 @@ Pred = {M,F,A}: fun(Ref, Type, Opts) -> apply(M, F, [Ref, Type, Opts | A]) end Removing a transport causes the corresponding transport processes to be terminated. Whether or not a DPR message is sent to a peer is -controlled by -value ofdisconnect_cb +controlled by value of &disconnect_cb; configured on the transport.@@ -1362,7 +1297,7 @@ configured on the transport. service_info(SvcName, Info) -> term() Return information about a started service. - @@ -1393,15 +1328,13 @@ returned.SvcName = +service_name() SvcName = &service_name; Info = Item | [Info] Item = atom() 'Firmware-Revision' -Return a capability value as configured with
+Return a capability value as configured with &start_service;.start_service/2 .applications - @@ -1409,16 +1342,14 @@ marker="#start_service">start_service/2.
-Return the list of applications as configured with
start_service/2 . +Return the list of applications as configured with &start_service;.Return a tagged list of all capabilities values as configured with -
+&start_service;.start_service/2 .transport Return a list containing one entry for each of the service's transport -as configured with
add_transport/2 . +as configured with &add_transport;. 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 @@ -1473,20 +1404,15 @@ An example return value with for a client service with Origin-Host
-Here
A listening transport presents its information slightly differently
-since there may be multiple accepted connections for the same
Return a
Return transport configuration associated with a single peer, as
-passed to
@@ -1690,10 +1613,10 @@ Return the list of started services.
@@ -1730,8 +1653,8 @@ file, not by calling
A service defines a locally-implemented Diameter node, specifying the
capabilities to be advertised during capabilities exchange.
-Transports are added to a service using
Stopping a service causes all associated transport connections to be
broken.
-A DPR message with be sent as in the case of
-Stopping a transport does not remove any associated transports:
-
-Subscribe to
@@ -1831,7 +1751,7 @@ reception of all related events.
@@ -1848,9 +1768,7 @@ Unsubscribe to event messages from a service.
-
-A diameter service as started by
-
-
-
The representation of a Diameter message as passed to
-
A tuple representing a Diameter peer connection.
@@ -188,13 +184,9 @@ A tuple representing a Diameter peer connection.
The state maintained by the application callback functions
-
@@ -238,11 +230,8 @@ new peer_ref().
There is no requirement that a callback return before incoming
-requests are received:
Invoked to signal that a peer connection is no longer available
-following a previous call to
-Invoked as a consequence of a call to
A callback that returns a peer() will be followed by a
-
Returning
The return values
The return value
@@ -371,16 +349,15 @@ to modify the outgoing request.
Many implementations may simply want to return
-A returned
-A returned
Returning
Invoked to return a request for encoding and retransmission.
-Has the same role as
Returning
Invoked when an answer message is received from a peer.
-The return value is returned from
The decoded answer record and undecoded binary are in the
-For any given call to
By default, an incoming answer message that cannot be successfully
decoded causes the request process to fail, causing
-
Invoked when an error occurs before an answer message is received
in response to an outgoing request.
-The return value is returned from
Reason
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
-The argument
#diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = [@@ -580,8 +539,8 @@ TheUnsigned32() | {Unsigned32() , #diameter_avp{}}], + errors = [&dict_Unsigned32; | {&dict_Unsigned32;, #diameter_avp{}}], bin = binary(), transport_data = term()}
The semantics of each of the possible return values are as follows.
Send the specified answer message to the peer.
-In the case of a
The returned
-
-A diameter service as configured with
@@ -639,9 +638,7 @@ Values of these types are not currently parsed by diameter.
-
-The start function required by
The only diameter_sctp-specific argument is the options list.
@@ -115,16 +116,13 @@ diameter_sctp uses the
-
-The start function required by
The only diameter_tcp-specific argument is the options list.
@@ -115,10 +116,8 @@ Note that the option
-
-A module specified as a
Start a transport process.
-Called by diameter as a consequence of a call to
-Ref is the value that was returned from the call to
-
The start function should use the
-