messaging_handler Class Reference

A handler for Proton messaging events. More...

#include <messaging_handler.hpp>

List of all members.

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 underlying network transport has closed.
virtual void on_transport_error (transport &)
 The underlying network transport has closed with an error condition.
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.
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.

Detailed Description

A handler for Proton messaging events.

Subclass and override the event-handling member functions.

Event handling functions can always use the objects passed as arguments.

Note:
A handler function **must not** use proton objects that are not accessible via the arguments passed without taking extra care. For example an on_message() handler called for connection "A" cannot simply call sender::send() on a proton::sender belonging to connection "B".

Thread-safety**: To be safe for both single- and multi-threaded use, a handler **must not** directly use objects belonging to another connection. See mt_page and proton::work_queue for safe ways to communicate. We recommend writing safe handlers to avoid mysterious failures if the handler is ever used in a multi-threaded container.

Single-threaded only**: An application is single-threaded if it calls container::run() exactly once, and does not make proton calls from any other thread. In this case a handler can use objects belonging to another connection, but it must call connection::wake() on the other connection before returning. Such a handler will fail mysteriously if the container is run with multiple threads.

#### Close and error handling

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

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


Member Function Documentation

virtual void on_container_start ( container  )  [virtual]

The container event loop is starting.

This is the first event received after calling `containerrun()`.

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.

virtual void on_transport_error ( transport  )  [virtual]

The underlying network transport has closed with an error condition.

virtual void on_sender_drain_start ( sender  )  [virtual]

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

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.

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 `connectionwake()`. 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 `protonwork_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 `connectionwake()`.

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

Generated on 17 Jan 2019 for Qpid Proton C++ by  doxygen 1.6.1