messaging_handler

Handler for Proton messaging events. More...

#include <messaging_handler.hpp>

Public Member Functions
virtual void	on_container_start (container &)
	The container event loop is starting.
virtual void	on_container_stop (container &)
	The container event loop is stopping.
virtual void	on_message (delivery &, message &)
	A message is received.
virtual void	on_sendable (sender &)
	A message can be sent.
virtual void	on_transport_open (transport &)
	The underlying network transport is open.
virtual void	on_transport_close (transport &)
	The final event for a connection: there will be no more reconnect attempts and no more event functions.
virtual void	on_transport_error (transport &)
	Unexpected disconnect, transport::error() provides details; if reconnect_options are enabled there may be an automatic re-connect.
virtual void	on_connection_open (connection &)
	The remote peer opened the connection: called once on initial open, and again on each successful automatic re-connect (see reconnect_options).
virtual void	on_connection_close (connection &)
	The remote peer closed the connection.
virtual void	on_connection_error (connection &)
	The remote peer indicated a fatal error, connection::error() provides details.
virtual void	on_session_open (session &)
	The remote peer opened the session.
virtual void	on_session_close (session &)
	The remote peer closed the session.
virtual void	on_session_error (session &)
	The remote peer closed the session with an error condition.
virtual void	on_receiver_open (receiver &)
	The remote peer opened the link.
virtual void	on_receiver_detach (receiver &)
	The remote peer detached the link.
virtual void	on_receiver_close (receiver &)
	The remote peer closed the link.
virtual void	on_receiver_error (receiver &)
	The remote peer closed the link with an error condition.
virtual void	on_sender_open (sender &)
	The remote peer opened the link.
virtual void	on_sender_detach (sender &)
	The remote peer detached the link.
virtual void	on_sender_close (sender &)
	The remote peer closed the link.
virtual void	on_sender_error (sender &)
	The remote peer closed the link with an error condition.
virtual void	on_tracker_accept (tracker &)
	The receiving peer accepted a transfer.
virtual void	on_tracker_reject (tracker &)
	The receiving peer rejected a transfer.
virtual void	on_tracker_release (tracker &)
	The receiving peer released a transfer.
virtual void	on_tracker_settle (tracker &)
	The receiving peer settled a transfer.
virtual void	on_delivery_settle (delivery &)
	The sending peer settled a transfer.
virtual void	on_sender_drain_start (sender &)
	Unsettled API - The receiving peer has requested a drain of remaining credit.
virtual void	on_receiver_drain_finish (receiver &)
	Unsettled API - The credit outstanding at the time of the drain request has been consumed or returned.
virtual void	on_connection_wake (connection &)
	Unsettled API - An event that can be triggered from another thread.
virtual void	on_error (const error_condition &)
	Fallback error handling.
virtual void	on_session_transaction_declared (session &)
	Unsettled API - Transaction lifecycle and messaging callbacks.
virtual void	on_session_transaction_committed (session &)
	Unsettled API - Called when a local transaction is discharged successfully.
virtual void	on_session_transaction_aborted (session &)
	Unsettled API - Called when a local transaction is discharged unsuccessfully (aborted).
virtual void	on_session_transaction_error (session &)
	Unsettled API - Called when a local transaction declare fails.
virtual void	on_transactional_accept (tracker &)
	Unsettled API - Called when a transactioned delivery is provisionally accepted.
virtual void	on_transactional_reject (tracker &)
	Unsettled API - Called when a transactioned delivery is provisionally rejected.
virtual void	on_transactional_release (tracker &)
	Unsettled API - Called when a transactioned delivery is provisionally released.
virtual void	on_container_quiescent (container &)
	Unsettled API - Called when the container is quiescent.

Detailed Description

Handler for Proton messaging events.

Subclass and override the event-handling member functions.

Thread-safety: A thread-safe handler can use the objects passed as arguments, and other objects belonging to the same proton::connection. It must not use objects belonging to a different connection. See Multithreading and proton::work_queue for safe ways to communicate between connections. Thread-safe handlers can also be used in single-threaded code.

Single-threaded only: An application is single-threaded if it calls container::run() exactly once, and only makes make proton calls from handler functions. Single-threaded handler functions can use objects belonging to another connection, but must call connection::wake() on the other connection before returning. Such a handler is not thread-safe.

Overview of connection life-cycle and automatic re-connect

See the documentation of individual event functions for more details.

on_connection_open() - The remote peer opened the connection: called once on initial open, and again on each successful automatic re-connect (see reconnect_options).

on_transport_error() - Unexpected disconnect, transport::error() provides details; if reconnect_options are enabled there may be an automatic re-connect.

on_connection_error() - The remote peer indicated a fatal error, connection::error() provides details.

on_connection_close() - The remote peer closed the connection.

on_transport_close() - The final event for a connection: there will be no more reconnect attempts and no more event functions.

See also

reconnect_options

Examples

broker.cpp, client.cpp, direct_recv.cpp, direct_send.cpp, helloworld.cpp, multithreaded_client.cpp, multithreaded_client_flow_control.cpp, scheduled_send.cpp, scheduled_send_03.cpp, server.cpp, server_direct.cpp, service_bus.cpp, simple_recv.cpp, simple_send.cpp, tracing_client.cpp, and tracing_server.cpp.

Member Function Documentation

on_container_start()

virtual void on_container_start ( container & )

virtual

The container event loop is starting.

This is the first event received after calling container::run().

Examples

client.cpp, direct_recv.cpp, direct_send.cpp, helloworld.cpp, multithreaded_client.cpp, scheduled_send.cpp, scheduled_send_03.cpp, server.cpp, server_direct.cpp, simple_recv.cpp, simple_send.cpp, tracing_client.cpp, and tracing_server.cpp.

on_container_stop()

virtual void on_container_stop ( container & )

virtual

The container event loop is stopping.

This is the last event received before the container event loop stops.

on_transport_close()

virtual void on_transport_close ( transport & )

virtual

The final event for a connection: there will be no more reconnect attempts and no more event functions.

Called exactly once regardless of how many times the connection was re-connected, whether it failed due to transport or connection errors or was closed without error.

This is a good place to do per-connection clean-up. transport::connection() is always valid at this point.

Examples

broker.cpp, direct_send.cpp, and simple_send.cpp.

on_transport_error()

virtual void on_transport_error ( transport & )

virtual

Unexpected disconnect, transport::error() provides details; if reconnect_options are enabled there may be an automatic re-connect.

If there is a successful automatic reconnect, on_connection_open() will be called again.

transport::connection() is always valid at this point.

Calling connection::close() will cancel automatic re-connect and force the transport to close immediately, see on_transport_close()

on_connection_open()

virtual void on_connection_open ( connection & )

virtual

The remote peer opened the connection: called once on initial open, and again on each successful automatic re-connect (see reconnect_options).

connection::reconnected() is false for the initial call, true for any subsequent calls due to reconnect.

Note

You can use the initial call to open initial session, sender and receiver endpoints. All active endpoints are automatically re-opened after an automatic re-connect so you should take care not to open them again, for example:

if (!c.reconnected()) {
    // Do initial per-connection setup here.
    // Open initial senders/receivers if needed.
} else {
    // Handle a successful reconnect here.
    // NOTE: Don't re-open active senders/receivers
}

For a server on_connection_open() is called when a client attempts to open a connection. The server can call connection::open() to accept or connection::close(const error_condition&) to reject.

See also

reconnect_options, on_transport_error()

Examples

broker.cpp, helloworld.cpp, multithreaded_client.cpp, service_bus.cpp, and simple_send.cpp.

on_connection_close()

virtual void on_connection_close ( connection & )

virtual

The remote peer closed the connection.

If there was a connection error, this is called immediately after on_connection_error() and connection::error() is set

on_connection_error()

virtual void on_connection_error ( connection & )

virtual

The remote peer indicated a fatal error, connection::error() provides details.

A connection error is an application problem, for example an illegal action or a lack of resources. There will be no automatic re-connect attempts, on_connection_close() will be called immediately after.

Note

A connection close with the special error condition amqp:connection-forced is treated as a transport error, not a connection error, see on_transport_error()

on_connection_wake()

virtual void on_connection_wake ( connection & )

virtual

Unsettled API - An event that can be triggered from another thread.

This event is triggered by a call to connection::wake(). It is used to notify the application that something needs attention.

Thread-safety - The application handler and the triggering thread must use some form of thread-safe state or communication to tell the handler what it needs to do. See proton::work_queue for an easier way to execute code safely in the handler thread.

Note

Spurious calls to on_connection_wake() can occur without any application call to connection::wake().

on_session_transaction_declared()

virtual void on_session_transaction_declared ( session & )

virtual

Unsettled API - Transaction lifecycle and messaging callbacks.

See also

transactions_page

Called when a local transaction is declared.

on_session_transaction_aborted()

virtual void on_session_transaction_aborted ( session & )

virtual

Unsettled API - Called when a local transaction is discharged unsuccessfully (aborted).

This is either due to an explicit abort or a failure during commit. In either case any action taken under the transaction is as if it never happened.

on_session_transaction_error()

virtual void on_session_transaction_error ( session & )

virtual

Unsettled API - Called when a local transaction declare fails.

A failed transaction commit is reported as aborted, as it has the same effect.

on_transactional_accept()

virtual void on_transactional_accept ( tracker & )

virtual

Unsettled API - Called when a transactioned delivery is provisionally accepted.

This means that if the transaction successfully commits the delivery will be accepted. If the transaction aborts the delivery will be as if it never happened.

on_transactional_reject()

virtual void on_transactional_reject ( tracker & )

virtual

Unsettled API - Called when a transactioned delivery is provisionally rejected.

This means that if the transaction successfully commits the delivery will be rejected.

on_transactional_release()

virtual void on_transactional_release ( tracker & )

virtual

Unsettled API - Called when a transactioned delivery is provisionally released.

This means that if the transaction successfully commits the delivery will be released (including modifying the delivery count).

---

The documentation for this class was generated from the following file:

• proton/messaging_handler.hpp