messaging_handler

A 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. More...
virtual void	on_container_stop (container &)
	The container event loop is stopping. More...
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 underlying network transport has closed.
virtual void	on_transport_error (transport &)
	The underlying network transport has closed with an error condition. More...
virtual void	on_connection_open (connection &)
	The remote peer opened the connection.
virtual void	on_connection_close (connection &)
	The remote peer closed the connection.
virtual void	on_connection_error (connection &)
	The remote peer closed the connection with an error condition.
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. More...
virtual void	on_receiver_drain_finish (receiver &)
	Unsettled API - The credit outstanding at the time of the drain request has been consumed or returned. More...
virtual void	on_connection_wake (connection &)
	Unsettled API - An event that can be triggered from another thread. More...
virtual void	on_error (const error_condition &)
	Fallback error handling.

Detailed Description

A handler for Proton messaging events.

Subclass and override the event-handling member functions.

Close and error handling

There are several objects that have on_X_close and on_X_error functions. They are called as follows:

• If X is closed cleanly, with no error status, then on_X_close is called.
• If X is closed with an error, then on_X_error is called, followed by on_X_close. The error condition is also available in on_X_close from X::error().

By default, if you do not implement on_X_error, it will call on_error. If you do not implement on_error it will throw a proton::error exception, which may not be what you want but does help to identify forgotten error handling quickly.

Resource cleanup

Every on_X_open event is paired with an on_X_close event which can clean up any resources created by the open handler. In particular this is still true if an error is reported with an on_X_error event. The error-handling logic doesn't have to manage resource clean up. It can assume that the close event will be along to handle it.

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, and simple_send.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, helloworld.cpp, multithreaded_client.cpp, scheduled_send.cpp, scheduled_send_03.cpp, server.cpp, simple_recv.cpp, and simple_send.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_error()

virtual void on_transport_error ( transport &  )

virtual

The underlying network transport has closed with an error condition.

on_sender_drain_start()

virtual void on_sender_drain_start ( sender &  )

virtual

Unsettled API - The receiving peer has requested a drain of remaining credit.

on_receiver_drain_finish()

virtual void on_receiver_drain_finish ( receiver &  )

virtual

Unsettled API - The credit outstanding at the time of the drain request has been consumed or returned.

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

---

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

• proton/messaging_handler.hpp