*

peer_up/3 and peer_down/3 signal the attainment or loss of connectivity with a Diameter peer.

*

pick_peer/4, prepare_request/3, prepare_retransmit/3, handle_answer/4 and handle_error/4 are (or may be) called as a consequence of a call to diameter:call/4 to send an outgoing Diameter request message.

*

handle_request/3 is called in response to an incoming Diameter request message.

capabilities() = #diameter_caps{}:

A record containing the identities of the local Diameter node and the remote Diameter peer having an established transport connection, as well as the capabilities as determined by capabilities exchange. Each field of the record is a 2-tuple consisting of values for the (local) host and (remote) peer. Optional or possibly multiple values are encoded as lists of values, mandatory values as the bare value.

message() = diameter_codec:message():

The representation of a Diameter message as passed to diameter:call/4 or returned from a handle_request/3 callback.

packet() = diameter_codec:packet():

A container for incoming and outgoing Diameter messages that's passed through encode/decode and transport. Fields should not be set in return values except as documented.

peer_ref() = term():

A term identifying a transport connection with a Diameter peer.

peer() = {peer_ref(), capabilities()}:

A tuple representing a Diameter peer connection.

state() = term():

The state maintained by the application callback functions peer_up/3, peer_down/3 and (optionally) pick_peer/4. The initial state is configured in the call to diameter:start_service/2 that configures the application on a service. Callback functions returning a state are evaluated in a common service-specific process while those not returning state are evaluated in a request-specific process.

Types:

Invoked to signal the availability of a peer connection on the local Erlang node. In particular, capabilities exchange with the peer has indicated support for the application in question, the RFC 3539 watchdog state machine for the connection has reached state OKAY and Diameter messages can be both sent and received.

Types:

Invoked to signal that a peer connection on the local Erlang node is no longer available following a previous call to peer_up/3. In particular, that the RFC 3539 watchdog state machine for the connection has left state OKAY and the peer will no longer be a candidate in pick_peer/4 callbacks.

Types:

Invoked as a consequence of a call to diameter:call/4 to select a destination peer for an outgoing request. The return value indicates the selected peer.

The candidate lists contain only those peers that have advertised support for the Diameter application in question during capabilities exchange, that have not be excluded by a filter option in the call to diameter:call/4 and whose watchdog state machine is in the OKAY state. The order of the elements is unspecified except that any peers whose Origin-Host and Origin-Realm matches that of the outgoing request (in the sense of a {filter, {all, [host, realm]}} option to diameter:call/4) will be placed at the head of the list. LocalCandidates contains peers whose transport process resides on the local Erlang node while RemoteCandidates contains peers that have been communicated from other nodes by services of the same name.

A callback that returns a peer() will be followed by a prepare_request/3 callback and, if the latter indicates that the request should be sent, by either handle_answer/4 or handle_error/4 depending on whether or not an answer message is received from the peer. If the transport becomes unavailable after prepare_request/3 then a new pick_peer/4 callback may take place to failover to an alternate peer, after which prepare_retransmit/3 takes the place of prepare_request/3 in resending the request. There is no guarantee that a pick_peer/4 callback to select an alternate peer will be followed by any additional callbacks since a retransmission to an alternate peer is abandoned if an answer is received from a previously selected peer.

The return values false and {false, State} (that is, NewState = State) are equivalent, as are {ok, Peer} and {Peer, State}.

Types:

Invoked to return a request for encoding and transport. Allows the sender to use the selected peer's capabilities to modify the outgoing request. Many implementations may simply want to return {send, Packet}

A returned packet() should set the request to be encoded in its msg field and can set the transport_data field in order to pass information to the transport process. Extra arguments passed to diameter:call/4 can be used to communicate transport (or any other) data to the callback.

A returned packet() can set the header field to a #diameter_header{} to specify values that should be preserved in the outgoing request, values otherwise being those in the header record contained in Packet. A returned length, cmd_code or application_id is ignored.

A returned PostF will be evaluated on any encoded #diameter_packet{} prior to transmission, the bin field containing the encoded binary. The return value is ignored.

Returning {discard, Reason} causes the request to be aborted and the diameter:call/4 for which the callback has taken place to return {error, Reason}. Returning discard is equivalent to returning {discard, discarded}.

Types:

Invoked to return a request for encoding and retransmission. Has the same role as prepare_request/3 in the case that a peer connection is lost an an alternate peer selected but the argument packet() is as returned by the initial prepare_request/3.

Returning {discard, Reason} causes the request to be aborted and a handle_error/4 callback to take place with Reason as initial argument. Returning discard is equivalent to returning {discard, discarded}.

Types:

Invoked when an answer message is received from a peer. The return value is returned from diameter:call/4 unless the detach option was specified.

The decoded answer record and undecoded binary are in the msg and bin fields of the argument packet() respectively. Request is the outgoing request message as was returned from prepare_request/3 or prepare_retransmit/3.

For any given call to diameter:call/4 there is at most one handle_answer/4 callback: any duplicate answer (due to retransmission or otherwise) is discarded. Similarly, only one of handle_answer/4 or handle_error/4 is called.

By default, an incoming answer message that cannot be successfully decoded causes the request process to fail, causing diameter:call/4 to return {error, failure} unless the detach option was specified. In particular, there is no handle_error/4 callback in this case. The diameter:application_opt() answer_errors can be set to change this behaviour.

Types:

Invoked when an error occurs before an answer message is received in response to an outgoing request. The return value is returned from diameter:call/4 unless the detach option was specified.

Reason timeout indicates that an answer message has not been received within the time specified with the corresponding diameter:call_opt(). Reason failover indicates that the transport connection to the peer to which the request has been sent has become unavailable and that not alternate peer was not selected.

Types:

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 diameter:start_service/2) is determined by the Application Identifier in the header of the incoming request message, the selected module being the one whose corresponding dictionary declares itself as defining either the application in question or the Relay application.

The argument packet() has the following signature.

#diameter_packet{header = #diameter_header{},
                 avps   = [#diameter_avp{}],
                 msg    = record() | undefined,
                 errors = [Unsigned32() | {Unsigned32(), #diameter_avp{}}],
                 bin    = binary(),
                 transport_data = term()}

The msg field will be undefined in case the request has been received in the relay application. Otherwise it contains the record representing the request as outlined in diameter_dict(4).

The errors field specifies any results codes identifying errors found while decoding the request. This is used to set Result-Code and/or Failed-AVP in a returned answer unless the callback returns a #diameter_packet{} whose errors field is set to either a non-empty list of its own, in which case this list is used instead, or the atom false to disable any setting of Result-Code and Failed-AVP. Note that the errors detected by diameter are of the 3xxx and 5xxx series, Protocol Errors and Permanent Failures respectively. The errors list is empty if the request has been received in the relay application.

The transport_data field contains an arbitrary term passed into diameter from the transport module in question, or the atom undefined if the transport specified no data. The term is preserved if a message() is returned but must be set explicitly in a returned packet().

The semantics of each of the possible return values are as follows.

{reply, ['answer-message' | Avps]