235 lines
8.9 KiB
C++
235 lines
8.9 KiB
C++
/**
|
|
* 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 <cstdint>
|
|
#include <stddef.h>
|
|
|
|
/**
|
|
* 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
|
|
*/
|
|
}
|
|
|