1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
/**
* 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
*/
}
|
