/** * ConnectionHandler.h * * Interface that should be implemented by the caller of the library and * that is passed to the AMQP connection. This interface contains all sorts * of methods that are called when data needs to be sent, or when the * AMQP connection ends up in a broken state. * * @copyright 2014 - 2018 Copernica BV */ /** * Include guard */ #pragma once /** * Dependencies */ #include #include /** * Set up namespace */ namespace AMQP { /** * Forward declarations */ class Connection; /** * Class definition */ class ConnectionHandler { public: /** * Destructor */ virtual ~ConnectionHandler() = default; /** * When the connection is being set up, the client and server exchange * some information. This includes for example their name and version, * copyright statement and the operating system name. Nothing in this * exchange of information is very relevant for the actual AMQP protocol, * but by overriding this method you can read out the information that * was sent by the server, and you can decide which information you * want to send back that describe the client. In RabbitMQ's management * console the client-properties are visible on the "connections" tab, * which could be helpful in certain scenarios, like debugging. * * The read-only "server" parameter contains the information sent by * the server, while the "client" table may be filled with information * about your application. The AMQP protocol says that this table should * at least be filled with data for the "product", "version", "platform", * "copyright" and "information" keys. However, you do not have to * override this method, and even when you do, you do not have to ensure * that these properties are indeed set, because the AMQP-CPP library * takes care of filling in properties that were not explicitly set. * * @param connection The connection about which information is exchanged * @param server Properties sent by the server * @param client Properties that are to be sent back */ virtual void onProperties(Connection *connection, const Table &server, Table &client) { // make sure compilers dont complaint about unused parameters (void) connection; (void) server; (void) client; } /** * Method that is called when the heartbeat frequency is negotiated * between the server and the client durion connection setup. You * normally do not have to override this method, because in the default * implementation the suggested heartbeat is simply rejected by the client. * * However, if you want to enable heartbeats you can override this * method. You should "return interval" if you want to accept the * heartbeat interval that was suggested by the server, or you can * return an alternative value if you want a shorter or longer interval. * Return 0 if you want to disable heartbeats. * * If heartbeats are enabled, you yourself are responsible to send * out a heartbeat every *interval / 2* number of seconds by calling * the Connection::heartbeat() method. * * @param connection The connection that suggested a heartbeat interval * @param interval The suggested interval from the server * @return uint16_t The interval to use */ virtual uint16_t onNegotiate(Connection *connection, uint16_t interval) { // make sure compilers dont complain about unused parameters (void) connection; (void) interval; // default implementation, disable heartbeats return 0; } /** * Method that is called by AMQP-CPP when data has to be sent over the * network. You must implement this method and send the data over a * socket that is connected with RabbitMQ. * * Note that the AMQP library does no buffering by itself. This means * that this method should always send out all data or do the buffering * itself. * * @param connection The connection that created this output * @param buffer Data to send * @param size Size of the buffer */ virtual void onData(Connection *connection, const char *buffer, size_t size) = 0; /** * Method that is called when the AMQP-CPP library received a heartbeat * frame that was sent by the server to the client. * * You do not have to do anything here, the client sends back a heartbeat * frame automatically, but if you like, you can implement/override this * method if you want to be notified of such heartbeats * * @param connection The connection over which the heartbeat was received */ virtual void onHeartbeat(Connection *connection) { // make sure compilers dont complain about unused parameters (void) connection; } /** * When the connection ends up in an error state this method is called. * This happens when data comes in that does not match the AMQP protocol, * or when an error message was sent by the server to the client. * * After this method is called, the connection no longer is in a valid * state and can no longer be used. * * This method has an empty default implementation, although you are very * much advised to implement it. When an error occurs, the connection * is no longer usable, so you probably want to know. * * @param connection The connection that entered the error state * @param message Error message */ virtual void onError(Connection *connection, const char *message) { // make sure compilers dont complain about unused parameters (void) connection; (void) message; } /** * Method that is called when the login attempt succeeded. After this method * is called, the connection is ready to use, and the RabbitMQ server is * ready to receive instructions. * * According to the AMQP protocol, you must wait for the connection to become * ready (and this onConnected method to be called) before you can start * sending instructions to RabbitMQ. However, if you prematurely do send * instructions, this AMQP-CPP library caches all methods that you call * before the connection is ready and flushes them the moment the connection * has been set up, so technically there is no real reason to wait for this * method to be called before you send the first instructions. * * @param connection The connection that can now be used */ virtual void onReady(Connection *connection) { // make sure compilers dont complain about unused parameters (void) connection; } /** * Method that is called when the AMQP connection was closed. * * This is the counter part of a call to Connection::close() and it confirms * that the connection was _correctly_ closed. Note that this only applies * to the AMQP connection, the underlying TCP connection is not managed by * AMQP-CPP and is still active. * * @param connection The connection that was closed and that is now unusable */ virtual void onClosed(Connection *connection) { // make sure compilers dont complain about unused parameters (void) connection; } /** * Method that is called when the AMQP connection was blocked. * * This method is called, when the server connection gets blocked for the first * time due to the broker running low on a resource (memory or disk). For * example, when a RabbitMQ node detects that it is low on RAM, it sends a * notification to all connected publishing clients supporting this feature. * If before the connections are unblocked the node also starts running low on * disk space, another notification will not be sent. * * @param connection The connection that was blocked * @param reason Why was the connection blocked */ virtual void onBlocked(Connection *connection, const char *reason) { // make sure compilers dont complain about unused parameters (void) connection; } /** * Method that is called when the AMQP connection is no longer blocked. * * This method is called when all resource alarms have cleared and the * connection is fully unblocked. * * @param connection The connection that is no longer blocked */ virtual void onUnblocked(Connection *connection) { // make sure compilers dont complain about unused parameters (void) connection; } }; /** * End of namespace */ }