Debian Codegraph @

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

raw
1 # message requirements
2
3 ## Overview
4
5 `message` is module that stores AMQP messages per the Messaging layer in the AMQP ISO.
6
7 ## Exposed API
8
9 ```C
10 typedef enum MESSAGE_BODY_TYPE_TAG
11 {
12 MESSAGE_BODY_TYPE_NONE,
13 MESSAGE_BODY_TYPE_DATA,
14 MESSAGE_BODY_TYPE_SEQUENCE,
15 MESSAGE_BODY_TYPE_VALUE
16 } MESSAGE_BODY_TYPE;
17
18 typedef struct MESSAGE_INSTANCE_TAG* MESSAGE_HANDLE;
19 typedef struct BINARY_DATA_TAG
20 {
21 const unsigned char* bytes;
22 size_t length;
23 } BINARY_DATA;
24
25 MOCKABLE_FUNCTION(, MESSAGE_HANDLE, message_create);
26 MOCKABLE_FUNCTION(, MESSAGE_HANDLE, message_clone, MESSAGE_HANDLE, source_message);
27 MOCKABLE_FUNCTION(, void, message_destroy, MESSAGE_HANDLE, message);
28 MOCKABLE_FUNCTION(, int, message_set_header, MESSAGE_HANDLE, message, HEADER_HANDLE, message_header);
29 MOCKABLE_FUNCTION(, int, message_get_header, MESSAGE_HANDLE, message, HEADER_HANDLE*, message_header);
30 MOCKABLE_FUNCTION(, int, message_set_delivery_annotations, MESSAGE_HANDLE, message, delivery_annotations, annotations);
31 MOCKABLE_FUNCTION(, int, message_get_delivery_annotations, MESSAGE_HANDLE, message, delivery_annotations*, annotations);
32 MOCKABLE_FUNCTION(, int, message_set_message_annotations, MESSAGE_HANDLE, message, message_annotations, annotations);
33 MOCKABLE_FUNCTION(, int, message_get_message_annotations, MESSAGE_HANDLE, message, message_annotations*, annotations);
34 MOCKABLE_FUNCTION(, int, message_set_properties, MESSAGE_HANDLE, message, PROPERTIES_HANDLE, properties);
35 MOCKABLE_FUNCTION(, int, message_get_properties, MESSAGE_HANDLE, message, PROPERTIES_HANDLE*, properties);
36 MOCKABLE_FUNCTION(, int, message_set_application_properties, MESSAGE_HANDLE, message, AMQP_VALUE, application_properties);
37 MOCKABLE_FUNCTION(, int, message_get_application_properties, MESSAGE_HANDLE, message, AMQP_VALUE*, application_properties);
38 MOCKABLE_FUNCTION(, int, message_set_footer, MESSAGE_HANDLE, message, annotations, footer);
39 MOCKABLE_FUNCTION(, int, message_get_footer, MESSAGE_HANDLE, message, annotations*, footer);
40 MOCKABLE_FUNCTION(, int, message_add_body_amqp_data, MESSAGE_HANDLE, message, BINARY_DATA, amqp_data);
41 MOCKABLE_FUNCTION(, int, message_get_body_amqp_data_in_place, MESSAGE_HANDLE, message, size_t, index, BINARY_DATA*, amqp_data);
42 MOCKABLE_FUNCTION(, int, message_get_body_amqp_data_count, MESSAGE_HANDLE, message, size_t*, count);
43 MOCKABLE_FUNCTION(, int, message_set_body_amqp_value, MESSAGE_HANDLE, message, AMQP_VALUE, body_amqp_value);
44 MOCKABLE_FUNCTION(, int, message_get_body_amqp_value_in_place, MESSAGE_HANDLE, message, AMQP_VALUE*, body_amqp_value);
45 MOCKABLE_FUNCTION(, int, message_add_body_amqp_sequence, MESSAGE_HANDLE, message, AMQP_VALUE, sequence);
46 MOCKABLE_FUNCTION(, int, message_get_body_amqp_sequence_in_place, MESSAGE_HANDLE, message, size_t, index, AMQP_VALUE*, sequence);
47 MOCKABLE_FUNCTION(, int, message_get_body_amqp_sequence_count, MESSAGE_HANDLE, message, size_t*, count);
48 MOCKABLE_FUNCTION(, int, message_get_body_type, MESSAGE_HANDLE, message, MESSAGE_BODY_TYPE*, body_type);
49 MOCKABLE_FUNCTION(, int, message_set_message_format, MESSAGE_HANDLE, message, uint32_t, message_format);
50 MOCKABLE_FUNCTION(, int, message_get_message_format, MESSAGE_HANDLE, message, uint32_t*, message_format);
51 ```
52
53 ### message_create
54
55 ```C
56 MOCKABLE_FUNCTION(, MESSAGE_HANDLE, message_create);
57 ```
58
59 **SRS_MESSAGE_01_001: [** `message_create` shall create a new AMQP message instance and on success it shall return a non-NULL handle for the newly created message instance. **]**
60 **SRS_MESSAGE_01_002: [** If allocating memory for the message fails, `message_create` shall fail and return NULL. **]**
61
62 ### message_clone
63
64 ```C
65 MOCKABLE_FUNCTION(, MESSAGE_HANDLE, message_clone, MESSAGE_HANDLE, source_message);
66 ```
67
68 **SRS_MESSAGE_01_003: [** `message_clone` shall clone a message entirely and on success return a non-NULL handle to the cloned message. **]**
69 **SRS_MESSAGE_01_062: [** If `source_message` is NULL, `message_clone` shall fail and return NULL. **]**
70 **SRS_MESSAGE_01_004: [** If allocating memory for the new cloned message fails, `message_clone` shall fail and return NULL. **]**
71 **SRS_MESSAGE_01_005: [** If a header exists on the source message it shall be cloned by using `header_clone`. **]**
72 **SRS_MESSAGE_01_006: [** If delivery annotations exist on the source message they shall be cloned by using `annotations_clone`. **]**
73 **SRS_MESSAGE_01_007: [** If message annotations exist on the source message they shall be cloned by using `annotations_clone`. **]**
74 **SRS_MESSAGE_01_008: [** If message properties exist on the source message they shall be cloned by using `properties_clone`. **]**
75 **SRS_MESSAGE_01_009: [** If application properties exist on the source message they shall be cloned by using `amqpvalue_clone`. **]**
76 **SRS_MESSAGE_01_010: [** If a footer exists on the source message it shall be cloned by using `annotations_clone`. **]**
77 **SRS_MESSAGE_01_011: [** If an AMQP data has been set as message body on the source message it shall be cloned by allocating memory for the binary payload. **]**
78 **SRS_MESSAGE_01_159: [** If an AMQP value has been set as message body on the source message it shall be cloned by calling `amqpvalue_clone`. **]**
79 **SRS_MESSAGE_01_160: [** If AMQP sequences are set as AMQP body they shall be cloned by calling `amqpvalue_clone`. **]**
80 **SRS_MESSAGE_01_012: [** If any cloning operation for the members of the source message fails, then `message_clone` shall fail and return NULL. **]**
81
82 ### message_destroy
83
84 ```C
85 MOCKABLE_FUNCTION(, void, message_destroy, MESSAGE_HANDLE, message);
86 ```
87
88 **SRS_MESSAGE_01_013: [** `message_destroy` shall free all resources allocated by the message instance identified by the `message` argument. **]**
89 **SRS_MESSAGE_01_014: [** If `message` is NULL, `message_destroy` shall do nothing. **]**
90 **SRS_MESSAGE_01_015: [** The message header shall be freed by calling `header_destroy`. **]**
91 **SRS_MESSAGE_01_016: [** The delivery annotations shall be freed by calling `annotations_destroy`. **]**
92 **SRS_MESSAGE_01_017: [** The message annotations shall be freed by calling `annotations_destroy`. **]**
93 **SRS_MESSAGE_01_018: [** The message properties shall be freed by calling `properties_destroy`. **]**
94 **SRS_MESSAGE_01_019: [** The application properties shall be freed by calling `amqpvalue_destroy`. **]**
95 **SRS_MESSAGE_01_020: [** The message footer shall be freed by calling `annotations_destroy`. **]**
96 **SRS_MESSAGE_01_021: [** If the message body is made of an AMQP value, the value shall be freed by calling `amqpvalue_destroy`. **]**
97 **SRS_MESSAGE_01_136: [** If the message body is made of several AMQP data items, they shall all be freed. **]**
98 **SRS_MESSAGE_01_136: [** If the message body is made of several AMQP sequences, they shall all be freed. **]**
99 **SRS_MESSAGE_01_137: [** Each sequence shall be freed by calling `amqpvalue_destroy`. **]**
100
101 ### message_set_header
102
103 ```C
104 MOCKABLE_FUNCTION(, int, message_set_header, MESSAGE_HANDLE, message, HEADER_HANDLE, message_header);
105 ```
106
107 **SRS_MESSAGE_01_022: [** `message_set_header` shall copy the contents of `message_header` as the header for the message instance identified by message. **]**
108 **SRS_MESSAGE_01_023: [** On success it shall return 0. **]**
109 **SRS_MESSAGE_01_024: [** If `message` is NULL, `message_set_header` shall fail and return a non-zero value. **]**
110 **SRS_MESSAGE_01_025: [** Cloning the header shall be done by calling `header_clone`. **]**
111 **SRS_MESSAGE_01_026: [** If `header_clone` fails, `message_set_header` shall fail and return a non-zero value. **]**
112 **SRS_MESSAGE_01_138: [** If setting the header fails, the previous value shall be preserved. **]**
113 **SRS_MESSAGE_01_139: [** If `message_header` is NULL, the previously stored header associated with `message` shall be freed. **]**
114
115 ### message_get_header
116
117 ```C
118 MOCKABLE_FUNCTION(, int, message_get_header, MESSAGE_HANDLE, message, HEADER_HANDLE*, message_header);
119 ```
120
121 **SRS_MESSAGE_01_027: [** `message_get_header` shall copy the contents of header for the message instance identified by `message` into the argument `message_header`. **]**
122 **SRS_MESSAGE_01_028: [** On success, `message_get_header` shall return 0.**]**
123 **SRS_MESSAGE_01_029: [** If `message` or `message_header` is NULL, `message_get_header` shall fail and return a non-zero value. **]**
124 **SRS_MESSAGE_01_030: [** Cloning the header shall be done by calling `header_clone`. **]**
125 **SRS_MESSAGE_01_031: [** If `header_clone` fails, `message_get_header` shall fail and return a non-zero value. **]**
126 **SRS_MESSAGE_01_143: [** If no header has been set, `message_get_header` shall set `message_header` to NULL. **]**
127
128 ### message_set_delivery_annotations
129
130 ```C
131 MOCKABLE_FUNCTION(, int, message_set_delivery_annotations, MESSAGE_HANDLE, message, delivery_annotations, annotations);
132 ```
133
134 **SRS_MESSAGE_01_032: [** `message_set_delivery_annotations` shall copy the contents of `annotations` as the delivery annotations for the message instance identified by `message`. **]**
135 **SRS_MESSAGE_01_033: [** On success it shall return 0. **]**
136 **SRS_MESSAGE_01_034: [** If `message` is NULL, `message_set_delivery_annotations` shall fail and return a non-zero value. **]**
137 **SRS_MESSAGE_01_035: [** Cloning the delivery annotations shall be done by calling `annotations_clone`. **]**
138 **SRS_MESSAGE_01_036: [** If `annotations_clone` fails, `message_set_delivery_annotations` shall fail and return a non-zero value. **]**
139 **SRS_MESSAGE_01_140: [** If setting the delivery annotations fails, the previous value shall be preserved. **]**
140 **SRS_MESSAGE_01_141: [** If `annotations` is NULL, the previously stored delivery annotations associated with `message` shall be freed. **]**
141
142 ### message_get_delivery_annotations
143
144 ```C
145 MOCKABLE_FUNCTION(, int, message_get_delivery_annotations, MESSAGE_HANDLE, message, delivery_annotations*, annotations);
146 ```
147
148 **SRS_MESSAGE_01_037: [** `message_get_delivery_annotations` shall copy the contents of delivery annotations for the message instance identified by `message` into the argument `annotations`. **]**
149 **SRS_MESSAGE_01_038: [** On success, `message_get_delivery_annotations` shall return 0. **]**
150 **SRS_MESSAGE_01_039: [** If `message` or `annotations` is NULL, `message_get_delivery_annotations` shall fail and return a non-zero value. **]**
151 **SRS_MESSAGE_01_040: [** Cloning the delivery annotations shall be done by calling `annotations_clone`. **]**
152 **SRS_MESSAGE_01_041: [** If `annotations_clone` fails, `message_get_delivery_annotations` shall fail and return a non-zero value. **]**
153 **SRS_MESSAGE_01_142: [** If no delivery annotations have been set, `message_get_delivery_annotations` shall set `annotations` to NULL. **]**
154
155 ### message_set_message_annotations
156
157 ```C
158 MOCKABLE_FUNCTION(, int, message_set_message_annotations, MESSAGE_HANDLE, message, message_annotations, annotations);
159 ```
160
161 **SRS_MESSAGE_01_042: [** `message_set_message_annotations` shall copy the contents of `annotations` as the message annotations for the message instance identified by `message`. **]**
162 **SRS_MESSAGE_01_043: [** On success it shall return 0. **]**
163 **SRS_MESSAGE_01_044: [** If `message` is NULL, `message_set_message_annotations` shall fail and return a non-zero value. **]**
164 **SRS_MESSAGE_01_045: [** Cloning the message annotations shall be done by calling `annotations_clone`. **]**
165 **SRS_MESSAGE_01_046: [** If `annotations_clone` fails, `message_set_message_annotations` shall fail and return a non-zero value. **]**
166 **SRS_MESSAGE_01_144: [** If setting the message annotations fails, the previous value shall be preserved. **]**
167 **SRS_MESSAGE_01_145: [** If `annotations` is NULL, the previously stored message annotations associated with `message` shall be freed. **]**
168
169 ### message_get_message_annotations
170
171 ```C
172 MOCKABLE_FUNCTION(, int, message_get_message_annotations, MESSAGE_HANDLE, message, message_annotations*, annotations);
173 ```
174
175 **SRS_MESSAGE_01_047: [** `message_get_message_annotations` shall copy the contents of message annotations for the message instance identified by `message` into the argument `annotations`. **]**
176 **SRS_MESSAGE_01_048: [** On success, `message_get_message_annotations` shall return 0. **]**
177 **SRS_MESSAGE_01_049: [** If `message` or `annotations` is NULL, `message_get_message_annotations` shall fail and return a non-zero value. **]**
178 **SRS_MESSAGE_01_050: [** Cloning the message annotations shall be done by calling `annotations_clone`. **]**
179 **SRS_MESSAGE_01_051: [** If `annotations_clone` fails, `message_get_message_annotations` shall fail and return a non-zero value. **]**
180 **SRS_MESSAGE_01_146: [** If no message annotations have been set, `message_get_message_annotations` shall set `annotations` to NULL. **]**
181
182 ### message_set_properties
183
184 ```C
185 MOCKABLE_FUNCTION(, int, message_set_properties, MESSAGE_HANDLE, message, PROPERTIES_HANDLE, properties);
186 ```
187
188 **SRS_MESSAGE_01_052: [** `message_set_properties` shall copy the contents of `properties` as the message properties for the message instance identified by `message`. **]**
189 **SRS_MESSAGE_01_053: [** On success it shall return 0. **]**
190 **SRS_MESSAGE_01_054: [** If `message` is NULL, `message_set_properties` shall fail and return a non-zero value. **]**
191 **SRS_MESSAGE_01_055: [** Cloning the message properties shall be done by calling `properties_clone`. **]**
192 **SRS_MESSAGE_01_056: [** If `properties_clone` fails, `message_set_properties` shall fail and return a non-zero value. **]**
193 **SRS_MESSAGE_01_063: [** If setting the message properties fails, the previous value shall be preserved. **]**
194 **SRS_MESSAGE_01_147: [** If `properties` is NULL, the previously stored message properties associated with `message` shall be freed. **]**
195
196 ### message_get_properties
197
198 ```C
199 MOCKABLE_FUNCTION(, int, message_get_properties, MESSAGE_HANDLE, message, PROPERTIES_HANDLE*, properties);
200 ```
201
202 **SRS_MESSAGE_01_057: [** `message_get_properties` shall copy the contents of message properties for the message instance identified by `message` into the argument `properties`. **]**
203 **SRS_MESSAGE_01_058: [** On success, `message_get_properties` shall return 0. **]**
204 **SRS_MESSAGE_01_059: [** If `message` or `properties` is NULL, `message_get_properties` shall fail and return a non-zero value. **]**
205 **SRS_MESSAGE_01_060: [** Cloning the message properties shall be done by calling `properties_clone`. **]**
206 **SRS_MESSAGE_01_061: [** If `properties_clone` fails, `message_get_properties` shall fail and return a non-zero value. **]**
207 **SRS_MESSAGE_01_148: [** If no message properties have been set, `message_get_properties` shall set `properties` to NULL. **]**
208
209 ### message_set_application_properties
210
211 ```C
212 MOCKABLE_FUNCTION(, int, message_set_application_properties, MESSAGE_HANDLE, message, AMQP_VALUE, application_properties);
213 ```
214
215 **SRS_MESSAGE_01_064: [** `message_set_application_properties` shall copy the contents of `application_properties` as the application properties for the message instance identified by `message`. **]**
216 **SRS_MESSAGE_01_065: [** On success it shall return 0. **]**
217 **SRS_MESSAGE_01_066: [** If `message` is NULL, `message_set_application_properties` shall fail and return a non-zero value. **]**
218 **SRS_MESSAGE_01_067: [** Cloning the message properties shall be done by calling `application_properties_clone`. **]**
219 **SRS_MESSAGE_01_068: [** If `application_properties_clone` fails, `message_set_application_properties` shall fail and return a non-zero value. **]**
220 **SRS_MESSAGE_01_069: [** If setting the application properties fails, the previous value shall be preserved. **]**
221 **SRS_MESSAGE_01_149: [** If `application_properties` is NULL, the previously stored application properties associated with `message` shall be freed. **]**
222
223 ### message_get_application_properties
224
225 ```C
226 MOCKABLE_FUNCTION(, int, message_get_application_properties, MESSAGE_HANDLE, message, AMQP_VALUE*, application_properties);
227 ```
228
229 **SRS_MESSAGE_01_070: [** `message_get_application_properties` shall copy the contents of application message properties for the message instance identified by `message` into the argument `application_properties`. **]**
230 **SRS_MESSAGE_01_071: [** On success, `message_get_application_properties` shall return 0. **]**
231 **SRS_MESSAGE_01_072: [** If `message` or `application_properties` is NULL, `message_get_application_properties` shall fail and return a non-zero value. **]**
232 **SRS_MESSAGE_01_073: [** Cloning the application properties shall be done by calling `application_properties_clone`. **]**
233 **SRS_MESSAGE_01_074: [** If `application_properties_clone` fails, `message_get_application_properties` shall fail and return a non-zero value. **]**
234 **SRS_MESSAGE_01_150: [** If no application properties have been set, `message_get_application_properties` shall set `application_properties` to NULL. **]**
235
236 ### message_set_footer
237
238 ```C
239 MOCKABLE_FUNCTION(, int, message_set_footer, MESSAGE_HANDLE, message, annotations, footer);
240 ```
241
242 **SRS_MESSAGE_01_075: [** `message_set_footer` shall copy the contents of `footer` as the footer contents for the message instance identified by `message`. **]**
243 **SRS_MESSAGE_01_076: [** On success it shall return 0. **]**
244 **SRS_MESSAGE_01_077: [** If `message` is NULL, `message_set_footer` shall fail and return a non-zero value. **]**
245 **SRS_MESSAGE_01_078: [** Cloning the footer shall be done by calling `annotations_clone`. **]**
246 **SRS_MESSAGE_01_079: [** If `annotations_clone` fails, `message_set_footer` shall fail and return a non-zero value. **]**
247 **SRS_MESSAGE_01_080: [** If setting the footer fails, the previous value shall be preserved. **]**
248 **SRS_MESSAGE_01_151: [** If `footer` is NULL, the previously stored footer associated with `message` shall be freed. **]**
249
250 ### message_get_footer
251
252 ```C
253 MOCKABLE_FUNCTION(, int, message_get_footer, MESSAGE_HANDLE, message, annotations*, footer);
254 ```
255
256 **SRS_MESSAGE_01_081: [** `message_get_footer` shall copy the contents of footer for the message instance identified by `message` into the argument `footer`. **]**
257 **SRS_MESSAGE_01_082: [** On success, `message_get_footer` shall return 0. **]**
258 **SRS_MESSAGE_01_083: [** If `message` or `footer` is NULL, `message_get_footer` shall fail and return a non-zero value. **]**
259 **SRS_MESSAGE_01_084: [** Cloning the footer shall be done by calling `annotations_clone`. **]**
260 **SRS_MESSAGE_01_085: [** If `annotations_clone` fails, `message_get_footer` shall fail and return a non-zero value. **]**
261 **SRS_MESSAGE_01_152: [** If no footer has been set, `message_get_footer` shall set `footer` to NULL. **]**
262
263 ### message_add_body_amqp_data
264
265 ```C
266 MOCKABLE_FUNCTION(, int, message_add_body_amqp_data, MESSAGE_HANDLE, message, BINARY_DATA, amqp_data);
267 ```
268
269 **SRS_MESSAGE_01_086: [** `message_add_body_amqp_data` shall add the contents of `amqp_data` to the list of AMQP data values for the body of the message identified by `message`. **]**
270 **SRS_MESSAGE_01_087: [** On success it shall return 0. **]**
271 **SRS_MESSAGE_01_088: [** If `message` is NULL, `message_add_body_amqp_data` shall fail and return a non-zero value. **]**
272 **SRS_MESSAGE_01_089: [** If the `bytes` member of `amqp_data` is NULL and the `size` member is non-zero, `message_add_body_amqp_data` shall fail and return a non-zero value. **]**
273 **SRS_MESSAGE_01_153: [** If allocating memory to store the added AMQP data fails, `message_add_body_amqp_data` shall fail and return a non-zero value. **]**
274 **SRS_MESSAGE_01_090: [** If adding the body AMQP data fails, the previous body content shall be preserved. **]**
275 **SRS_MESSAGE_01_091: [** If the body was already set to an AMQP value or a list of AMQP sequences, `message_add_body_amqp_data` shall fail and return a non-zero value. **]**
276
277 ### message_get_body_amqp_data_in_place
278
279 ```C
280 MOCKABLE_FUNCTION(, int, message_get_body_amqp_data_in_place, MESSAGE_HANDLE, message, size_t, index, BINARY_DATA*, amqp_data);
281 ```
282
283 **SRS_MESSAGE_01_092: [** `message_get_body_amqp_data_in_place` shall place the contents of the `index`th AMQP data for the message instance identified by `message` into the argument `amqp_data`, without copying the binary payload memory. **]**
284 **SRS_MESSAGE_01_093: [** On success, `message_get_body_amqp_data_in_place` shall return 0. **]**
285 **SRS_MESSAGE_01_094: [** If `message` or `amqp_data` is NULL, `message_get_body_amqp_data_in_place` shall fail and return a non-zero value. **]**
286 **SRS_MESSAGE_01_095: [** If `index` indicates an AMQP data entry that is out of bounds, `message_get_body_amqp_data_in_place` shall fail and return a non-zero value. **]**
287 **SRS_MESSAGE_01_096: [** If the body for `message` is not of type `MESSAGE_BODY_TYPE_DATA`, `message_get_body_amqp_data_in_place` shall fail and return a non-zero value. **]**
288
289 ### message_get_body_amqp_data_count
290
291 ```C
292 MOCKABLE_FUNCTION(, int, message_get_body_amqp_data_count, MESSAGE_HANDLE, message, size_t*, count);
293 ```
294
295 **SRS_MESSAGE_01_097: [** `message_get_body_amqp_data_count` shall fill in `count` the number of AMQP data chunks that are stored by the message identified by `message`. **]**
296 **SRS_MESSAGE_01_098: [** On success, `message_get_body_amqp_data_count` shall return 0. **]**
297 **SRS_MESSAGE_01_099: [** If `message` or `count` is NULL, `message_get_body_amqp_data_count` shall fail and return a non-zero value. **]**
298 **SRS_MESSAGE_01_100: [** If the body for `message` is not of type `MESSAGE_BODY_TYPE_DATA`, `message_get_body_amqp_data_count` shall fail and return a non-zero value. **]**
299
300 ### message_set_body_amqp_value
301
302 ```C
303 MOCKABLE_FUNCTION(, int, message_set_body_amqp_value, MESSAGE_HANDLE, message, AMQP_VALUE, body_amqp_value);
304 ```
305
306 **SRS_MESSAGE_01_101: [** `message_set_body_amqp_value` shall set the contents of body as being the AMQP value indicate by `body_amqp_value`. **]**
307 **SRS_MESSAGE_01_102: [** On success it shall return 0. **]**
308 **SRS_MESSAGE_01_103: [** If `message` or `body_amqp_value` is NULL, `message_set_body_amqp_value` shall fail and return a non-zero value. **]**
309 **SRS_MESSAGE_01_154: [** Cloning the amqp value shall be done by calling `amqpvalue_clone`. **]**
310 **SRS_MESSAGE_01_155: [** If `amqpvalue_clone` fails, `message_set_body_amqp_value` shall fail and return a non-zero value. **]**
311 **SRS_MESSAGE_01_104: [** If setting the body AMQP value fails, the previous value shall be preserved. **]**
312 **SRS_MESSAGE_01_105: [** If the body was already set to an AMQP data list or a list of AMQP sequences, `message_set_body_amqp_value` shall fail and return a non-zero value. **]**
313
314 ### message_get_body_amqp_value_in_place
315
316 ```C
317 MOCKABLE_FUNCTION(, int, message_get_body_amqp_value_in_place, MESSAGE_HANDLE, message, AMQP_VALUE*, body_amqp_value);
318 ```
319
320 **SRS_MESSAGE_01_106: [** `message_get_body_amqp_value_in_place` shall get the body AMQP value for the message instance identified by `message` in place (not cloning) into the `body_amqp_value` argument. **]**
321 **SRS_MESSAGE_01_107: [** On success, `message_get_body_amqp_value_in_place` shall return 0. **]**
322 **SRS_MESSAGE_01_108: [** If `message` or `body_amqp_value` is NULL, `message_get_body_amqp_value_in_place` shall fail and return a non-zero value. **]**
323 **SRS_MESSAGE_01_109: [** If the body for `message` is not of type `MESSAGE_BODY_TYPE_VALUE`, `message_get_body_amqp_value_in_place` shall fail and return a non-zero value. **]**
324
325 ### message_add_body_amqp_sequence
326
327 ```C
328 MOCKABLE_FUNCTION(, int, message_add_body_amqp_sequence, MESSAGE_HANDLE, message, AMQP_VALUE, sequence);
329 ```
330
331 **SRS_MESSAGE_01_110: [** `message_add_body_amqp_sequence` shall add the contents of `sequence` to the list of AMQP sequences for the body of the message identified by `message`. **]**
332 **SRS_MESSAGE_01_111: [** On success it shall return 0. **]**
333 **SRS_MESSAGE_01_156: [** The AMQP sequence shall be cloned by calling `amqpvalue_clone`. **]**
334 **SRS_MESSAGE_01_158: [** If allocating memory in order to store the sequence fails, `message_add_body_amqp_sequence` shall fail and return a non-zero value. **]**
335 **SRS_MESSAGE_01_157: [** If `amqpvalue_clone` fails, `message_add_body_amqp_sequence` shall fail and return a non-zero value. **]**
336 **SRS_MESSAGE_01_112: [** If `message` or `sequence` is NULL, `message_add_body_amqp_sequence` shall fail and return a non-zero value. **]**
337 **SRS_MESSAGE_01_114: [** If adding the AMQP sequence fails, the previous value shall be preserved. **]**
338 **SRS_MESSAGE_01_115: [** If the body was already set to an AMQP data list or an AMQP value, `message_add_body_amqp_sequence` shall fail and return a non-zero value. **]**
339
340 ### message_get_body_amqp_sequence_in_place
341
342 ```C
343 MOCKABLE_FUNCTION(, int, message_get_body_amqp_sequence_in_place, MESSAGE_HANDLE, message, size_t, index, AMQP_VALUE*, sequence);
344 ```
345
346 **SRS_MESSAGE_01_116: [** `message_get_body_amqp_sequence_in_place` shall return in `sequence` the content of the `index`th AMQP seuquence entry for the message instance identified by `message`. **]**
347 **SRS_MESSAGE_01_117: [** On success, `message_get_body_amqp_sequence_in_place` shall return 0. **]**
348 **SRS_MESSAGE_01_118: [** If `message` or `sequence` is NULL, `message_get_body_amqp_sequence_in_place` shall fail and return a non-zero value. **]**
349 **SRS_MESSAGE_01_119: [** If `index` indicates an AMQP sequence entry that is out of bounds, `message_get_body_amqp_sequence_in_place` shall fail and return a non-zero value. **]**
350 **SRS_MESSAGE_01_120: [** If the body for `message` is not of type `MESSAGE_BODY_TYPE_SEQUENCE`, `message_get_body_amqp_sequence_in_place` shall fail and return a non-zero value. **]**
351
352 ### message_get_body_amqp_sequence_count
353
354 ```C
355 MOCKABLE_FUNCTION(, int, message_get_body_amqp_sequence_count, MESSAGE_HANDLE, message, size_t*, count);
356 ```
357
358 **SRS_MESSAGE_01_121: [** `message_get_body_amqp_sequence_count` shall fill in `count` the number of AMQP sequences that are stored by the message identified by `message`. **]**
359 **SRS_MESSAGE_01_122: [** On success, `message_get_body_amqp_sequence_count` shall return 0. **]**
360 **SRS_MESSAGE_01_123: [** If `message` or `count` is NULL, `message_get_body_amqp_sequence_count` shall fail and return a non-zero value. **]**
361 **SRS_MESSAGE_01_124: [** If the body for `message` is not of type `MESSAGE_BODY_TYPE_SEQUENCE`, `message_get_body_amqp_sequence_count` shall fail and return a non-zero value. **]**
362
363 ### message_get_body_type
364
365 ```C
366 MOCKABLE_FUNCTION(, int, message_get_body_type, MESSAGE_HANDLE, message, MESSAGE_BODY_TYPE*, body_type);
367 ```
368
369 **SRS_MESSAGE_01_125: [** `message_get_body_type` shall fill in `body_type` the AMQP message body type. **]**
370 **SRS_MESSAGE_01_126: [** On success, `message_get_body_type` shall return 0. **]**
371 **SRS_MESSAGE_01_127: [** If `message` or `body_type` is NULL, `message_get_body_type` shall fail and return a non-zero value. **]**
372 **SRS_MESSAGE_01_128: [** If no body has been set on the message, `body_type` shall be `MESSAGE_BODY_TYPE_NONE`. **]**
373
374 ### message_set_message_format
375
376 ```C
377 MOCKABLE_FUNCTION(, int, message_set_message_format, MESSAGE_HANDLE, message, uint32_t, message_format);
378 ```
379
380 **SRS_MESSAGE_01_129: [** `message_set_message_format` shall set the message format for the message identified by `message`. **]**
381 **SRS_MESSAGE_01_130: [** On success, `message_set_message_format` shall return 0. **]**
382 **SRS_MESSAGE_01_131: [** If `message` is NULL, `message_set_message_format` shall fail and return a non-zero value. **]**
383
384
385 ### message_get_message_format
386
387 ```C
388 MOCKABLE_FUNCTION(, int, message_get_message_format, MESSAGE_HANDLE, message, uint32_t*, message_format);
389 ```
390
391 **SRS_MESSAGE_01_132: [** `message_get_message_format` shall get the message format for the message identified by `message` and return it in the `message_fomrat` argument. **]**
392 **SRS_MESSAGE_01_133: [** On success, `message_get_message_format` shall return 0. **]**
393 **SRS_MESSAGE_01_134: [** If `message` or `message_format` is NULL, `message_get_message_format` shall fail and return a non-zero value. **]**
394 **SRS_MESSAGE_01_135: [** By default a message on which `message_set_message_format` was not called shall have message format set to 0. **]**