messaging_handler Class Reference

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

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 Multi-threading 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

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_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.

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

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

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()
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 8 Oct 2019 for Qpid Proton C++ by  doxygen 1.6.1