Loading...
Searching...
No Matches
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.

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

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

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

- proton/messaging_handler.hpp