Debian Codegraph @

src/vendor/azure-uamqp-c/devdoc/amqp_management_requirements.md

raw
1 # amqp_management requirements
2
3 ## Overview
4
5 `amqp_management` is module that implements the AMQP management draft specification portion that refers to operations (request/response pattern).
6
7 ##Exposed API
8
9 ```c
10 #define AMQP_MANAGEMENT_EXECUTE_OPERATION_RESULT_VALUES \
11 AMQP_MANAGEMENT_EXECUTE_OPERATION_OK, \
12 AMQP_MANAGEMENT_EXECUTE_OPERATION_ERROR, \
13 AMQP_MANAGEMENT_EXECUTE_OPERATION_FAILED_BAD_STATUS, \
14 AMQP_MANAGEMENT_EXECUTE_OPERATION_INSTANCE_CLOSED
15
16 DEFINE_ENUM(AMQP_MANAGEMENT_EXECUTE_OPERATION_RESULT, AMQP_MANAGEMENT_EXECUTE_OPERATION_RESULT_VALUES)
17
18 #define AMQP_MANAGEMENT_OPEN_RESULT_VALUES \
19 AMQP_MANAGEMENT_OPEN_OK, \
20 AMQP_MANAGEMENT_OPEN_ERROR, \
21 AMQP_MANAGEMENT_OPEN_CANCELLED
22
23 DEFINE_ENUM(AMQP_MANAGEMENT_OPEN_RESULT, AMQP_MANAGEMENT_OPEN_RESULT_VALUES)
24
25 typedef struct AMQP_MANAGEMENT_INSTANCE_TAG* AMQP_MANAGEMENT_HANDLE;
26 typedef void(*ON_AMQP_MANAGEMENT_OPEN_COMPLETE)(void* context, AMQP_MANAGEMENT_OPEN_RESULT open_result);
27 typedef void(*ON_AMQP_MANAGEMENT_ERROR)(void* context);
28 typedef void(*ON_AMQP_MANAGEMENT_EXECUTE_OPERATION_COMPLETE)(void* context, AMQP_MANAGEMENT_EXECUTE_OPERATION_RESULT execute_operation_result, unsigned int status_code, const char* status_description, MESSAGE_HANDLE message);
29
30 MOCKABLE_FUNCTION(, AMQP_MANAGEMENT_HANDLE, amqp_management_create, SESSION_HANDLE, session, const char*, management_node);
31 MOCKABLE_FUNCTION(, void, amqp_management_destroy, AMQP_MANAGEMENT_HANDLE, amqp_management);
32 MOCKABLE_FUNCTION(, int, amqp_management_open_async, AMQP_MANAGEMENT_HANDLE, amqp_management, ON_AMQP_MANAGEMENT_OPEN_COMPLETE, on_amqp_management_open_complete, void*, on_amqp_management_open_complete_context, ON_AMQP_MANAGEMENT_ERROR, on_amqp_management_error, void*, on_amqp_management_error_context);
33 MOCKABLE_FUNCTION(, int, amqp_management_close, AMQP_MANAGEMENT_HANDLE, amqp_management);
34 MOCKABLE_FUNCTION(, ASYNC_OPERATION_HANDLE, amqp_management_execute_operation_async, AMQP_MANAGEMENT_HANDLE, amqp_management, const char*, operation, const char*, type, const char*, locales, MESSAGE_HANDLE, message, ON_AMQP_MANAGEMENT_EXECUTE_OPERATION_COMPLETE, on_execute_operation_complete, void*, context);
35 MOCKABLE_FUNCTION(, void, amqp_management_set_trace, AMQP_MANAGEMENT_HANDLE, amqp_management, bool, trace_on);
36 MOCKABLE_FUNCTION(, int, amqp_management_set_override_status_code_key_name, AMQP_MANAGEMENT_HANDLE, amqp_management, const char*, override_status_code_key_name);
37 MOCKABLE_FUNCTION(, int, amqp_management_set_override_status_description_key_name, AMQP_MANAGEMENT_HANDLE, amqp_management, const char*, override_status_description_key_name);
38 ```
39
40 ### amqp_management_create
41
42 ```c
43 AMQP_MANAGEMENT_HANDLE amqp_management_create(SESSION_HANDLE session, const char* management_node);
44 ```
45
46 **SRS_AMQP_MANAGEMENT_01_001: [** `amqp_management_create` shall create a new CBS instance and on success return a non-NULL handle to it. **]**
47
48 **SRS_AMQP_MANAGEMENT_01_002: [** If `session` or `management_node` is NULL then `amqp_management_create` shall fail and return NULL. **]**
49
50 **SRS_AMQP_MANAGEMENT_01_030: [** If `management_node` is an empty string, then `amqp_management_create` shall fail and return NULL. **]**
51
52 **SRS_AMQP_MANAGEMENT_01_003: [** `amqp_management_create` shall create a singly linked list for pending operations by calling `singlylinkedlist_create`. **]**
53
54 **SRS_AMQP_MANAGEMENT_01_181: [** `amqp_management_create` shall set the status code key name to be used for parsing the status code to `statusCode`. **]**
55
56 **SRS_AMQP_MANAGEMENT_01_182: [** `amqp_management_create` shall set the status description key name to be used for parsing the status description to `statusDescription`. **]**
57
58 **SRS_AMQP_MANAGEMENT_01_004: [** If `singlylinkedlist_create` fails, `amqp_management_create` shall fail and return NULL. **]**
59
60 **SRS_AMQP_MANAGEMENT_01_005: [** If allocating memory for the new handle fails, `amqp_management_create` shall fail and return NULL. **]**
61
62 **SRS_AMQP_MANAGEMENT_01_006: [** `amqp_management_create` shall create a sender link by calling `link_create`. **]**
63
64 **SRS_AMQP_MANAGEMENT_01_007: [** The `session` argument shall be set to `session`. **]**
65
66 **SRS_AMQP_MANAGEMENT_01_008: [** The `name` argument shall be constructed by concatenating the `management_node` value with `-sender`. **]**
67
68 **SRS_AMQP_MANAGEMENT_01_009: [** The `role` argument shall be `role_sender`. **]**
69
70 **SRS_AMQP_MANAGEMENT_01_010: [** The `source` argument shall be a value created by calling `messaging_create_source` with `management_node` as argument. **]**
71
72 **SRS_AMQP_MANAGEMENT_01_011: [** The `target` argument shall be a value created by calling `messaging_create_target` with `management_node` as argument. **]**
73
74 **SRS_AMQP_MANAGEMENT_01_012: [** If `messaging_create_source` fails then `amqp_management_create` shall fail and return NULL. **]**
75
76 **SRS_AMQP_MANAGEMENT_01_013: [** If `messaging_create_target` fails then `amqp_management_create` shall fail and return NULL. **]**
77
78 **SRS_AMQP_MANAGEMENT_01_014: [** If `link_create` fails when creating the sender link then `amqp_management_create` shall fail and return NULL. **]**
79
80 **SRS_AMQP_MANAGEMENT_01_015: [** `amqp_management_create` shall create a receiver link by calling `link_create`. **]**
81
82 **SRS_AMQP_MANAGEMENT_01_016: [** The `session` argument shall be set to `session`. **]**
83
84 **SRS_AMQP_MANAGEMENT_01_017: [** The `name` argument shall be constructed by concatenating the `management_node` value with `-receiver`. **]**
85
86 **SRS_AMQP_MANAGEMENT_01_018: [** The `role` argument shall be `role_receiver`. **]**
87
88 **SRS_AMQP_MANAGEMENT_01_019: [** The `source` argument shall be the value created by calling `messaging_create_source`. **]**
89
90 **SRS_AMQP_MANAGEMENT_01_020: [** The `target` argument shall be the value created by calling `messaging_create_target`. **]**
91
92 **SRS_AMQP_MANAGEMENT_01_021: [** If `link_create` fails when creating the receiver link then `amqp_management_create` shall fail and return NULL. **]**
93
94 **SRS_AMQP_MANAGEMENT_01_022: [** `amqp_management_create` shall create a message sender by calling `messagesender_create` and passing to it the sender link handle. **]**
95
96 **SRS_AMQP_MANAGEMENT_01_023: [** `amqp_management_create` shall create a message receiver by calling `messagereceiver_create` and passing to it the receiver link handle. **]**
97
98 **SRS_AMQP_MANAGEMENT_01_031: [** If `messagesender_create` fails then `amqp_management_create` shall fail and return NULL. **]**
99
100 **SRS_AMQP_MANAGEMENT_01_032: [** If `messagereceiver_create` fails then `amqp_management_create` shall fail and return NULL. **]**
101
102 **SRS_AMQP_MANAGEMENT_01_033: [** If any other error occurs `amqp_management_create` shall fail and return NULL. **]**
103
104 ### amqp_management_destroy
105
106 ```c
107 void amqp_management_destroy(AMQP_MANAGEMENT_HANDLE amqp_management);
108 ```
109
110 **SRS_AMQP_MANAGEMENT_01_024: [** `amqp_management_destroy` shall free all the resources allocated by `amqp_management_create`. **]**
111
112 **SRS_AMQP_MANAGEMENT_01_025: [** If `amqp_management` is NULL, `amqp_management_destroy` shall do nothing. **]**
113
114 **SRS_AMQP_MANAGEMENT_01_026: [** `amqp_management_destroy` shall free the singly linked list by calling `singlylinkedlist_destroy`. **]**
115
116 **SRS_AMQP_MANAGEMENT_01_027: [** `amqp_management_destroy` shall free the sender and receiver links by calling `link_destroy`. **]**
117
118 **SRS_AMQP_MANAGEMENT_01_028: [** `amqp_management_destroy` shall free the message sender by calling `messagesender_destroy`. **]**
119
120 **SRS_AMQP_MANAGEMENT_01_029: [** `amqp_management_destroy` shall free the message receiver by calling `messagereceiver_destroy`. **]**
121
122 **SRS_AMQP_MANAGEMENT_01_034: [** If the AMQP management instance is OPEN or OPENING, `amqp_management_destroy` shall also perform all actions that would be done by `amqp_management_close`. **]**
123
124 ### amqp_management_open_async
125
126 ```c
127 int amqp_management_open_async(AMQP_MANAGEMENT_HANDLE amqp_management, ON_AMQP_MANAGEMENT_OPEN_COMPLETE on_amqp_management_open_complete, void* on_amqp_management_open_complete_context, ON_AMQP_MANAGEMENT_ERROR on_amqp_management_error, void* on_amqp_management_error_context);
128 ```
129
130 **SRS_AMQP_MANAGEMENT_01_036: [** `amqp_management_open_async` shall start opening the AMQP management instance and save the callbacks so that they can be called when opening is complete. **]**
131
132 **SRS_AMQP_MANAGEMENT_01_037: [** On success it shall return 0. **]**
133
134 **SRS_AMQP_MANAGEMENT_01_038: [** If `amqp_management`, `on_amqp_management_open_complete` or `on_amqp_management_error` is NULL, `amqp_management_open_async` shall fail and return a non-zero value. **]**
135
136 **SRS_AMQP_MANAGEMENT_01_044: [** `on_amqp_management_open_complete_context` and `on_amqp_management_error_context` shall be allowed to be NULL. **]**
137
138 **SRS_AMQP_MANAGEMENT_01_039: [** `amqp_management_open_async` shall open the message sender by calling `messagesender_open`. **]**
139
140 **SRS_AMQP_MANAGEMENT_01_040: [** `amqp_management_open_async` shall open the message receiver by calling `messagereceiver_open`. **]**
141
142 **SRS_AMQP_MANAGEMENT_01_041: [** If `messagesender_open` fails, `amqp_management_open_async` shall fail and return a non-zero value. **]**
143
144 **SRS_AMQP_MANAGEMENT_01_042: [** If `messagereceiver_open` fails, `amqp_management_open_async` shall fail and return a non-zero value. **]**
145
146 **SRS_AMQP_MANAGEMENT_01_043: [** If the AMQP management instance is already OPEN or OPENING, `amqp_management_open_async` shall fail and return a non-zero value. **]**
147
148 ### amqp_management_close
149
150 ```c
151 int amqp_management_close(AMQP_MANAGEMENT_HANDLE amqp_management);
152 ```
153
154 **SRS_AMQP_MANAGEMENT_01_045: [** `amqp_management_close` shall close the AMQP management instance. **]**
155
156 **SRS_AMQP_MANAGEMENT_01_046: [** On success it shall return 0. **]**
157
158 **SRS_AMQP_MANAGEMENT_01_047: [** If `amqp_management` is NULL, `amqp_management_close` shall fail and return a non-zero value. **]**
159
160 **SRS_AMQP_MANAGEMENT_01_048: [** `amqp_management_close` on an AMQP management instance that is OPENING shall trigger the `on_amqp_management_open_complete` callback with `AMQP_MANAGEMENT_OPEN_CANCELLED`, while
161 also passing the context passed in `amqp_management_open_async`. **]**
162
163 **SRS_AMQP_MANAGEMENT_01_049: [** `amqp_management_close` on an AMQP management instance that is not OPEN, shall fail and return a non-zero value. **]**
164
165 **SRS_AMQP_MANAGEMENT_01_050: [** `amqp_management_close` shall close the message sender by calling `messagesender_close`. **]**
166
167 **SRS_AMQP_MANAGEMENT_01_051: [** `amqp_management_close` shall close the message receiver by calling `messagereceiver_close`. **]**
168
169 **SRS_AMQP_MANAGEMENT_01_052: [** If `messagesender_close` fails, `amqp_management_close` shall fail and return a non-zero value. **]**
170
171 **SRS_AMQP_MANAGEMENT_01_053: [** If `messagereceiver_close` fails, `amqp_management_close` shall fail and return a non-zero value. **]**
172
173 **SRS_AMQP_MANAGEMENT_01_054: [** All pending operations shall be indicated complete with the code `AMQP_MANAGEMENT_EXECUTE_OPERATION_INSTANCE_CLOSED`. **]**
174
175 ### amqp_management_execute_operation_async
176
177 ```c
178 ASYNC_OPERATION_HANDLE amqp_management_execute_operation_async(AMQP_MANAGEMENT_HANDLE amqp_management, const char* operation, const char* type, const char* locales, MESSAGE_HANDLE message, ON_AMQP_MANAGEMENT_EXECUTE_OPERATION_COMPLETE on_execute_operation_complete, void* on_execute_operation_complete_context);
179 ```
180
181 **SRS_AMQP_MANAGEMENT_01_055: [** `amqp_management_execute_operation_async` shall start an AMQP management operation. **]**
182
183 **SRS_AMQP_MANAGEMENT_01_056: [** On success it shall return an `ASYNC_OPERATION_HANDLE`. **]**
184
185 **SRS_AMQP_MANAGEMENT_09_004: [** The `ASYNC_OPERATION_HANDLE` cancel function shall cancel the underlying send async operation, remove this operation from the pending list, destroy this async operation. **]**
186
187 **SRS_AMQP_MANAGEMENT_01_057: [** If `amqp_management`, `operation`, `type` or `on_execute_operation_complete` is NULL, `amqp_management_execute_operation_async` shall fail and return NULL. **]**
188
189 **SRS_AMQP_MANAGEMENT_01_105: [** `on_execute_operation_complete_context` shall be allowed to be NULL. **]**
190
191 **SRS_AMQP_MANAGEMENT_01_102: [** If `message` is NULL, a new message shall be created by calling `message_create`. **]**
192
193 **SRS_AMQP_MANAGEMENT_01_103: [** Otherwise the existing message shall be cloned by using `message_clone` before being modified accordingly and used for the pending operation. **]**
194
195 **SRS_AMQP_MANAGEMENT_01_081: [** If `amqp_management_execute_operation_async` is called when not OPEN, it shall fail and return `NULL`. **]**
196
197 **SRS_AMQP_MANAGEMENT_01_104: [** If `amqp_management_execute_operation_async` is called when the AMQP management is in error, it shall fail and return a non-zero value. **]**
198
199 **SRS_AMQP_MANAGEMENT_01_082: [** `amqp_management_execute_operation_async` shall obtain the application properties from the message by calling `message_get_application_properties`. **]**
200
201 **SRS_AMQP_MANAGEMENT_01_083: [** If no application properties were set on the message, a new application properties instance shall be created by calling `amqpvalue_create_map`; **]**
202
203 **SRS_AMQP_MANAGEMENT_01_084: [** For each of the arguments `operation`, `type` and `locales` an AMQP value of type string shall be created by calling `amqpvalue_create_string` in order to be used as key in the application properties map. **]**
204
205 **SRS_AMQP_MANAGEMENT_01_085: [** For each of the arguments `operation`, `type` and `locales` an AMQP value of type string containing the argument value shall be created by calling `amqpvalue_create_string` in order to be used as value in the application properties map. **]**
206
207 **SRS_AMQP_MANAGEMENT_01_093: [** If `locales` is NULL, no key/value pair shall be added for it in the application properties map. **]**
208
209 **SRS_AMQP_MANAGEMENT_01_086: [** The key/value pairs for `operation`, `type` and `locales` shall be added to the application properties map by calling `amqpvalue_set_map_value`. **]**
210
211 **SRS_AMQP_MANAGEMENT_01_087: [** The application properties obtained after adding the key/value pairs shall be set on the message by calling `message_set_application_properties`. **]**
212
213 **SRS_AMQP_MANAGEMENT_01_101: [** After setting the application properties, the application properties instance shall be freed by `amqpvalue_destroy`. **]**
214
215 **SRS_AMQP_MANAGEMENT_01_090: [** If any APIs used to create and set the application properties on the message fails, `amqp_management_execute_operation_async` shall fail and return NULL. **]**
216
217 **SRS_AMQP_MANAGEMENT_01_094: [** In order to set the message Id on the message, the properties shall be obtained by calling `message_get_properties`. **]**
218
219 **SRS_AMQP_MANAGEMENT_01_099: [** If the properties were not set on the message, a new properties instance shall be created by calling `properties_create`. **]**
220
221 **SRS_AMQP_MANAGEMENT_01_095: [** A message Id with the next ulong value to be used shall be created by calling `amqpvalue_create_message_id_ulong`. **]**
222
223 **SRS_AMQP_MANAGEMENT_01_096: [** The message Id value shall be set on the properties by calling `properties_set_message_id`. **]**
224
225 **SRS_AMQP_MANAGEMENT_01_097: [** The properties thus modified to contain the message Id shall be set on the message by calling `message_set_properties`. **]**
226
227 **SRS_AMQP_MANAGEMENT_01_100: [** After setting the properties, the properties instance shall be freed by `properties_destroy`. **]**
228
229 **SRS_AMQP_MANAGEMENT_01_098: [** If any API fails while setting the message Id, `amqp_management_execute_operation_async` shall fail and return a non-zero value. **]**
230
231 **SRS_AMQP_MANAGEMENT_01_088: [** `amqp_management_execute_operation_async` shall send the message by calling `messagesender_send_async`. **]**
232
233 **SRS_AMQP_MANAGEMENT_01_166: [** The `on_message_send_complete` callback shall be passed to the `messagesender_send_async` call. **]**
234
235 **SRS_AMQP_MANAGEMENT_01_089: [** If `messagesender_send_async` fails, `amqp_management_execute_operation_async` shall fail and return NULL. **]**
236
237 **SRS_AMQP_MANAGEMENT_01_091: [** Once the request message has been sent, an entry shall be stored in the pending operations list by calling `singlylinkedlist_add`. **]**
238
239 **SRS_AMQP_MANAGEMENT_01_092: [** If `singlylinkedlist_add` fails then `amqp_management_execute_operation_async` shall fail and return a non-zero value. **]**
240
241 **SRS_AMQP_MANAGEMENT_01_106: [** The message Id set on the message properties shall start at 0. **]**
242
243 **SRS_AMQP_MANAGEMENT_01_107: [** The message Id set on the message properties shall be incremented with each operation. **]**
244
245 ### on_message_received
246
247 ```c
248 AMQP_VALUE on_message_received(const void* context, MESSAGE_HANDLE message)
249 ```
250
251 **SRS_AMQP_MANAGEMENT_01_108: [** When `on_message_received` is called with a NULL context, it shall do nothing and return NULL. **]**
252
253 **SRS_AMQP_MANAGEMENT_01_109: [** `on_message_received` shall obtain the application properties from the message by calling `message_get_application_properties`. **]**
254
255 **SRS_AMQP_MANAGEMENT_01_110: [** `on_message_received` shall obtain the message properties from the message by calling `message_get_properties`. **]**
256
257 **SRS_AMQP_MANAGEMENT_01_111: [** `on_message_received` shall obtain the correlation Id from the message properties by using `properties_get_correlation_id`. **]**
258
259 **SRS_AMQP_MANAGEMENT_01_112: [** `on_message_received` shall check if the correlation Id matches the stored message Id of any pending operation. **]**
260
261 **SRS_AMQP_MANAGEMENT_01_113: [** If obtaining the application properties or message properties fails, an error shall be indicated by calling `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
262
263 **SRS_AMQP_MANAGEMENT_01_114: [** If obtaining the correlation Id fails, an error shall be indicated by calling `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
264
265 **SRS_AMQP_MANAGEMENT_01_115: [** Iterating through the pending operations shall be done by using `singlylinkedlist_get_head_item` and `singlylinkedlist_get_next_item` until the enm of the pending operations singly linked list is reached. **]**
266
267 **SRS_AMQP_MANAGEMENT_01_116: [** Each pending operation item value shall be obtained by calling `singlylinkedlist_item_get_value`. **]**
268
269 **SRS_AMQP_MANAGEMENT_01_117: [** If iterating through the pending operations list fails, an error shall be indicated by calling `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
270
271 **SRS_AMQP_MANAGEMENT_01_118: [** If no pending operation is found matching the correlation Id, an error shall be indicated by calling `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
272
273 **SRS_AMQP_MANAGEMENT_01_119: [** `on_message_received` shall obtain the application properties map by calling `amqpvalue_get_inplace_described_value`. **]**
274
275 **SRS_AMQP_MANAGEMENT_01_120: [** An AMQP value used to lookup the status code shall be created by calling `amqpvalue_create_string` with the status code key name (`statusCode`) as argument. **]**
276
277 **SRS_AMQP_MANAGEMENT_01_121: [** The status code shall be looked up in the application properties by using `amqpvalue_get_map_value`. **]**
278
279 **SRS_AMQP_MANAGEMENT_01_133: [** The status code value shall be extracted from the value found in the map by using `amqpvalue_get_int`. **]**
280
281 **SRS_AMQP_MANAGEMENT_01_122: [** If status code is not found an error shall be indicated to the consumer by calling the `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
282
283 **SRS_AMQP_MANAGEMENT_01_123: [** An AMQP value used to lookup the status description shall be created by calling `amqpvalue_create_string` with the status description key name (`statusDescription`) as argument. **]**
284
285 **SRS_AMQP_MANAGEMENT_01_124: [** The status description shall be looked up in the application properties by using `amqpvalue_get_map_value`. **]**
286
287 **SRS_AMQP_MANAGEMENT_01_125: [** If status description is not found, NULL shall be passed to the user callback as `status_description` argument. **]**
288
289 **SRS_AMQP_MANAGEMENT_01_134: [** The status description value shall be extracted from the value found in the map by using `amqpvalue_get_string`. **]**
290
291 **SRS_AMQP_MANAGEMENT_01_132: [** If any functions manipulating AMQP values, application properties, etc., fail, an error shall be indicated to the consumer by calling the `on_amqp_management_error` and passing the `on_amqp_management_error_context` to it. **]**
292
293 **SRS_AMQP_MANAGEMENT_01_126: [** If a corresponding correlation Id is found in the pending operations list, the callback associated with the pending operation shall be called. **]**
294
295 **SRS_AMQP_MANAGEMENT_01_166: [** The `message` shall be passed as argument to the callback. **]**
296
297 **SRS_AMQP_MANAGEMENT_01_127: [** If the operation succeeded the result callback argument shall be `AMQP_MANAGEMENT_EXECUTE_OPERATION_OK`. **]**
298
299 **SRS_AMQP_MANAGEMENT_01_128: [** If the status indicates that the operation failed, the result callback argument shall be `AMQP_MANAGEMENT_EXECUTE_OPERATION_FAILED_BAD_STATUS`. **]**
300
301 **SRS_AMQP_MANAGEMENT_01_129: [** After calling the callback, the pending operation shall be removed from the pending operations list by calling `singlylinkedlist_remove`. **]**
302
303 **SRS_AMQP_MANAGEMENT_01_130: [** The `on_message_received` shall call `messaging_delivery_accepted` and return the created delivery AMQP value. **]**
304
305 **SRS_AMQP_MANAGEMENT_01_131: [** All temporary values like AMQP values used as keys shall be freed before exiting the callback. **]**
306
307 **SRS_AMQP_MANAGEMENT_01_135: [** When an error occurs in creating AMQP values (for status code, etc.) `on_message_received` shall call `messaging_delivery_released` and return the created delivery AMQP value. **]**
308
309 **SRS_AMQP_MANAGEMENT_01_136: [** When `on_message_received` fails due to errors in parsing the response message `on_message_received` shall call `messaging_delivery_rejected` and return the created delivery AMQP value. **]**
310
311 ### on_message_send_complete
312
313 ```c
314 void on_message_send_complete(void* context, MESSAGE_SEND_RESULT send_result, AMQP_VALUE delivery_state)
315 ```
316
317 **SRS_AMQP_MANAGEMENT_01_167: [** When `on_message_send_complete` is called with a NULL context it shall return. **]**
318
319 **SRS_AMQP_MANAGEMENT_01_170: [** If `send_result` is `MESSAGE_SEND_OK`, `on_message_send_complete` shall return. **]**
320
321 **SRS_AMQP_MANAGEMENT_01_172: [** If `send_result` is different then `MESSAGE_SEND_OK`: **]**
322
323 **SRS_AMQP_MANAGEMENT_01_168: [** - `context` shall be used as a LIST_ITEM_HANDLE containing the pending operation. **]**
324
325 **SRS_AMQP_MANAGEMENT_01_169: [** - `on_message_send_complete` shall obtain the pending operation by calling `singlylinkedlist_item_get_value`. **]**
326
327 **SRS_AMQP_MANAGEMENT_01_171: [** - `on_message_send_complete` shall removed the pending operation from the pending operations list. **]**
328
329 **SRS_AMQP_MANAGEMENT_01_173: [** - The callback associated with the pending operation shall be called with `AMQP_MANAGEMENT_EXECUTE_OPERATION_ERROR`. **]**
330
331 **SRS_AMQP_MANAGEMENT_01_174: [** If any error occurs in removing the pending operation from the list `on_amqp_management_error` callback shall be invoked while passing the `on_amqp_management_error_context` as argument. **]**
332
333 ### on_message_sender_state_changed
334
335 ```c
336 void on_message_sender_state_changed(void* context, MESSAGE_SENDER_STATE new_state, MESSAGE_SENDER_STATE previous_state)
337 ```
338
339 **SRS_AMQP_MANAGEMENT_01_137: [** When `on_message_sender_state_changed` is called with NULL `context`, it shall do nothing. **]**
340
341 **SRS_AMQP_MANAGEMENT_01_138: [** When `on_message_sender_state_changed` is called and the `new_state` is different than `previous_state`, the following actions shall be taken: **]**
342
343 **SRS_AMQP_MANAGEMENT_01_139: [** For the current state of AMQP management being `OPENING`: **]**
344
345 **SRS_AMQP_MANAGEMENT_01_140: [** - If `new_state` is `MESSAGE_SENDER_STATE_IDLE`, `MESSAGE_SENDER_STATE_CLOSING` or `MESSAGE_SENDER_STATE_ERROR`, the `on_amqp_management_open_complete` callback shall be called with `AMQP_MANAGEMENT_OPEN_ERROR`, while also passing the context passed in `amqp_management_open_async`. **]**
346
347 **SRS_AMQP_MANAGEMENT_01_141: [** - If `new_state` is `MESSAGE_SENDER_STATE_OPEN` and the message receiver already indicated its state as `MESSAGE_RECEIVER_STATE_OPEN`, the `on_amqp_management_open_complete` callback shall be called with `AMQP_MANAGEMENT_OPEN_OK`, while also passing the context passed in `amqp_management_open_async`. **]**
348
349 **SRS_AMQP_MANAGEMENT_01_142: [** - If `new_state` is `MESSAGE_SENDER_STATE_OPEN` and the message receiver did not yet indicate its state as `MESSAGE_RECEIVER_STATE_OPEN`, the `on_amqp_management_open_complete` callback shall not be called.**]**
350
351 **SRS_AMQP_MANAGEMENT_01_165: [** - If `new_state` is `MESSAGE_SENDER_STATE_OPEING` the transition shall be ignored. **]**
352
353 **SRS_AMQP_MANAGEMENT_01_144: [** For the current state of AMQP management being `OPEN`: **]**
354
355 **SRS_AMQP_MANAGEMENT_01_143: [** - If `new_state` is `MESSAGE_SENDER_STATE_IDLE`, `MESSAGE_SENDER_STATE_OPENING`, `MESSAGE_SENDER_STATE_CLOSING` or `MESSAGE_SENDER_STATE_ERROR` the `on_amqp_management_error` callback shall be invoked while passing the `on_amqp_management_error_context` as argument. **]**
356
357 **SRS_AMQP_MANAGEMENT_01_145: [** - If `new_state` is `MESSAGE_SENDER_STATE_OPEN`, `on_message_sender_state_changed` shall do nothing. **]**
358
359 **SRS_AMQP_MANAGEMENT_09_001: [** For the current state of AMQP management being `CLOSING`: **]**
360
361 **SRS_AMQP_MANAGEMENT_09_002: [** - If `new_state` is `MESSAGE_SENDER_STATE_OPEN`, `MESSAGE_SENDER_STATE_OPENING`, `MESSAGE_SENDER_STATE_ERROR` the `on_amqp_management_error` callback shall be invoked while passing the `on_amqp_management_error_context` as argument. **]**
362
363 **SRS_AMQP_MANAGEMENT_09_003: [** - If `new_state` is `MESSAGE_SENDER_STATE_CLOSING` or `MESSAGE_SENDER_STATE_IDLE`, `on_message_sender_state_changed` shall do nothing. **]**
364
365 **SRS_AMQP_MANAGEMENT_01_146: [** For the current state of AMQP management being `ERROR`: **]**
366
367 **SRS_AMQP_MANAGEMENT_01_147: [** - All state transitions shall be ignored. **]**
368
369 **SRS_AMQP_MANAGEMENT_01_148: [** When no state change is detected, `on_message_sender_state_changed` shall do nothing. **]**
370
371 ### on_message_receiver_state_changed
372
373 ```c
374 void on_message_receiver_state_changed(void* context, MESSAGE_RECEIVER_STATE new_state, MESSAGE_RECEIVER_STATE previous_state)
375 ```
376
377 **SRS_AMQP_MANAGEMENT_01_149: [** When `on_message_receiver_state_changed` is called with NULL `context`, it shall do nothing. **]**
378
379 **SRS_AMQP_MANAGEMENT_01_150: [** When `on_message_receiver_state_changed` is called and the `new_state` is different than `previous_state`, the following actions shall be taken: **]**
380
381 **SRS_AMQP_MANAGEMENT_01_151: [** For the current state of AMQP management being `OPENING`: **]**
382
383 **SRS_AMQP_MANAGEMENT_01_152: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_IDLE`, `MESSAGE_RECEIVER_STATE_CLOSING` or `MESSAGE_RECEIVER_STATE_ERROR`, the `on_amqp_management_open_complete` callback shall be called with `AMQP_MANAGEMENT_OPEN_ERROR`, while also passing the context passed in `amqp_management_open_async`. **]**
384
385 **SRS_AMQP_MANAGEMENT_01_153: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_OPEN` and the message sender already indicated its state as `MESSAGE_SENDER_STATE_OPEN`, the `on_amqp_management_open_complete` callback shall be called with `AMQP_MANAGEMENT_OPEN_OK`, while also passing the context passed in `amqp_management_open_async`. **]**
386
387 **SRS_AMQP_MANAGEMENT_01_154: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_OPEN` and the message sender did not yet indicate its state as `MESSAGE_SENDER_STATE_OPEN`, the `on_amqp_management_open_complete` callback shall not be called. **]**
388
389 **SRS_AMQP_MANAGEMENT_01_164: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_OPEING` the transition shall be ignored. **]**
390
391 **SRS_AMQP_MANAGEMENT_01_155: [** For the current state of AMQP management being `OPEN`: **]**
392
393 **SRS_AMQP_MANAGEMENT_01_156: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_IDLE`, `MESSAGE_RECEIVER_STATE_OPENING`, `MESSAGE_RECEIVER_STATE_CLOSING` or `MESSAGE_RECEIVER_STATE_ERROR` the `on_amqp_management_error` callback shall be invoked while passing the `on_amqp_management_error_context` as argument. **]**
394
395 **SRS_AMQP_MANAGEMENT_01_157: [** - If `new_state` is `MESSAGE_RECEIVER_STATE_OPEN`, `on_message_receiver_state_changed` shall do nothing. **]**
396
397 **SRS_AMQP_MANAGEMENT_01_158: [** For the current state of AMQP management being `ERROR`: **]**
398
399 **SRS_AMQP_MANAGEMENT_01_159: [** - All state transitions shall be ignored. **]**
400
401 **SRS_AMQP_MANAGEMENT_01_160: [** When no state change is detected, `on_message_receiver_state_changed` shall do nothing. **]**
402
403 ### amqp_management_set_trace
404
405 ```c
406 void amqp_management_set_trace(AMQP_MANAGEMENT_HANDLE amqp_management, bool trace_on);
407 ```
408
409 **SRS_AMQP_MANAGEMENT_01_161: [** `amqp_management_set_trace` shall call `messagesender_set_trace` to enable/disable tracing on the message sender. **]**
410
411 **SRS_AMQP_MANAGEMENT_01_162: [** `amqp_management_set_trace` shall call `messagereceiver_set_trace` to enable/disable tracing on the message receiver. **]**
412
413 **SRS_AMQP_MANAGEMENT_01_163: [** If `amqp_management` is NULL, `amqp_management_set_trace` shal do nothing. **]**
414
415 ### amqp_management_set_override_status_code_key_name
416
417 ```c
418 int amqp_management_set_override_status_code_key_name(AMQP_MANAGEMENT_HANDLE amqp_management, const char* override_status_code_key_name);
419 ```
420
421 **SRS_AMQP_MANAGEMENT_01_167: [** `amqp_management_set_override_status_code_key_name` shall set the status code key name used to parse the status code from the reply messages to `override_status_code_key_name`. **]**
422
423 This is in order to allow endpoints like CBS to use values different than what is in the AMQP Management WD.
424
425 **SRS_AMQP_MANAGEMENT_01_168: [** `amqp_management_set_override_status_code_key_name` shall copy the `override_status_code_key_name` string. **]**
426
427 **SRS_AMQP_MANAGEMENT_01_169: [** `amqp_management_set_override_status_code_key_name` shall free any string previously used for the status code key name. **]**
428
429 **SRS_AMQP_MANAGEMENT_01_170: [** On success, `amqp_management_set_override_status_code_key_name` shall return 0. **]**
430
431 **SRS_AMQP_MANAGEMENT_01_171: [** If `amqp_management` is NULL, `amqp_management_set_override_status_code_key_name` shall fail and return a non-zero value. **]**
432
433 **SRS_AMQP_MANAGEMENT_01_172: [** If `override_status_code_key_name` is NULL, `amqp_management_set_override_status_code_key_name` shall fail and return a non-zero value. **]**
434
435 **SRS_AMQP_MANAGEMENT_01_173: [** If any error occurs in copying the `override_status_code_key_name` string, `amqp_management_set_override_status_code_key_name` shall fail and return a non-zero value. **]**
436
437 ### amqp_management_set_override_status_description_key_name
438
439 ```c
440 int amqp_management_set_override_status_description_key_name(AMQP_MANAGEMENT_HANDLE amqp_management, const char* override_status_description_key_name);
441 ```
442
443 **SRS_AMQP_MANAGEMENT_01_174: [** `amqp_management_set_override_status_description_key_name` shall set the status description key name used to parse the status description from the reply messages to `over ride_status_description_key_name`.**]**
444
445 This is in order to allow endpoints like CBS to use values different than what is in the AMQP Management WD.
446
447 **SRS_AMQP_MANAGEMENT_01_175: [** `amqp_management_set_override_status_description_key_name` shall copy the `override_status_description_key_name` string. **]**
448
449 **SRS_AMQP_MANAGEMENT_01_176: [** `amqp_management_set_override_status_description_key_name` shall free any string previously used for the status description key name. **]**
450
451 **SRS_AMQP_MANAGEMENT_01_177: [** On success, `amqp_management_set_override_status_description_key_name` shall return 0. **]**
452
453 **SRS_AMQP_MANAGEMENT_01_178: [** If `amqp_management` is NULL, `amqp_management_set_override_status_description_key_name` shall fail and return a non-zero value. **]**
454
455 **SRS_AMQP_MANAGEMENT_01_179: [** If `override_status_description_key_name` is NULL, `amqp_management_set_override_status_description_key_name` shall fail and return a non-zero value. **]**
456
457 **SRS_AMQP_MANAGEMENT_01_180: [** If any error occurs in copying the `override_status_description_key_name` string, `amqp_management_set_override_status_description_key_name` shall fail and return a non-zero value. **]**
458
459 ### Relevant sections from the AMQP Management spec
460
461 Request Messages
462
463 **SRS_AMQP_MANAGEMENT_01_058: [** Request messages have the following application-properties: **]**
464
465 Key Value Type Mandatory? Description
466
467 **SRS_AMQP_MANAGEMENT_01_059: [** operation string Yes The management operation to be performed. **]** This is case-sensitive.
468
469 **SRS_AMQP_MANAGEMENT_01_061: [** type string Yes The Manageable Entity Type of the Manageable Entity to be managed. **]** This is case-sensitive.
470
471 **SRS_AMQP_MANAGEMENT_01_063: [** locales string No A list of locales that the sending peer permits for incoming informational text in response messages. **]**
472 **SRS_AMQP_MANAGEMENT_01_064: [** The value MUST be of the form (presented in the augmented BNF defined in section 2 of [RFC2616]) **]**:
473 **SRS_AMQP_MANAGEMENT_01_065: [** `#Language-­Tag` where Language-Tag is defined in [BCP47] **]**.
474 This list MUST be ordered in decreasing level of preference. The receiving partner will choose the first (most preferred) incoming locale from those which it supports. If none of the requested locales are supported, "en-US" MUST be chosen. Note that "en-US" need not be supplied in this list as it is always the fallback. The string is not case-sensitive.
475 Other application-properties MAY provide additional context. If an application-property is not recognized then it MUST be ignored.
476
477 3.2 Response Messages
478
479 **SRS_AMQP_MANAGEMENT_01_068: [** The correlation-id of the response message MUST be the correlation-id from the request message (if present) **]**, **SRS_AMQP_MANAGEMENT_01_069: [** else the message-id from the request message. **]**
480 **SRS_AMQP_MANAGEMENT_01_070: [** Response messages have the following application-properties: **]**
481
482 Key Value Type Mandatory? Description
483
484 **SRS_AMQP_MANAGEMENT_01_071: [** statusCode integer Yes HTTP response code [RFC2616] **]**
485
486 **SRS_AMQP_MANAGEMENT_01_072: [** statusDescription string No Description of the status. **]**
487
488 **SRS_AMQP_MANAGEMENT_01_073: [** The type and contents of the body are operation-specific. **]**
489
490 3.2.1 Successful Operations
491
492 **SRS_AMQP_MANAGEMENT_01_074: [** Successful operations MUST result in a statusCode in the 2xx range as defined in Section 10.2 of [RFC2616]. **]**
493 Further details including the form of the body are provided in the definition of each operation.
494
495 3.2.2 Unsuccessful Operations
496
497 **SRS_AMQP_MANAGEMENT_01_075: [** Unsuccessful operations MUST NOT result in a statusCode in the 2xx range as defined in Section 10.2 of [RFC2616]. **]**
498 The following error status code SHOULD be used for the following common failure scenarios:
499
500 statusCode Label Meaning
501
502 501 Not Implemented The operation is not supported.
503 404 Not Found The Manageable Entity on which to perform the operation could not be found
504
505 Further details of operation-specific codes are provided in the definition of each operation.
506 The status description of a response to an unsuccessful operation SHOULD provide further information on the nature of the failure.
507
508 The form of the body of a response to an unsuccessful operation is unspecified and MAY be implementation-dependent.
509 **SRS_AMQP_MANAGEMENT_01_080: [** Clients SHOULD ignore the body of response message if the statusCode is not in the 2xx range. **]**