proton
0
Main Page
Related Pages
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
proton-c
include
proton
message.h
Go to the documentation of this file.
1
#ifndef PROTON_MESSAGE_H
2
#define PROTON_MESSAGE_H 1
3
4
/*
5
*
6
* Licensed to the Apache Software Foundation (ASF) under one
7
* or more contributor license agreements. See the NOTICE file
8
* distributed with this work for additional information
9
* regarding copyright ownership. The ASF licenses this file
10
* to you under the Apache License, Version 2.0 (the
11
* "License"); you may not use this file except in compliance
12
* with the License. You may obtain a copy of the License at
13
*
14
* http://www.apache.org/licenses/LICENSE-2.0
15
*
16
* Unless required by applicable law or agreed to in writing,
17
* software distributed under the License is distributed on an
18
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19
* KIND, either express or implied. See the License for the
20
* specific language governing permissions and limitations
21
* under the License.
22
*
23
*/
24
25
#include <
proton/import_export.h
>
26
#include <
proton/types.h
>
27
#include <
proton/codec.h
>
28
#include <
proton/error.h
>
29
#include <sys/types.h>
30
#include <
proton/type_compat.h
>
31
32
#ifdef __cplusplus
33
extern
"C"
{
34
#endif
35
36
/** @file
37
* Message API for encoding/decoding AMQP Messages.
38
*
39
* @defgroup message Message
40
* @{
41
*/
42
43
/**
44
* An AMQP Message object.
45
*
46
* An AMQP Message object is a mutable holder of message content that
47
* may be used to generate and encode or decode and access AMQP
48
* formatted message data.
49
*/
50
typedef
struct
pn_message_t
pn_message_t
;
51
52
/**
53
* Encoding format for message content.
54
*/
55
typedef
enum
{
56
PN_DATA
,
/**< Raw binary data. Not all messages can be encoded this way.*/
57
PN_TEXT
,
/**< Raw text. Not all messages can be encoded this way.*/
58
PN_AMQP
,
/**< AMQP formatted data. All messages can be encoded this way.*/
59
PN_JSON
/**< JSON formatted data. Not all messages can be encoded with full fidelity way.*/
60
}
pn_format_t
;
61
62
/**
63
* Default priority for messages.
64
*/
65
#define PN_DEFAULT_PRIORITY (4)
66
67
/**
68
* Construct a new ::pn_message_t.
69
*
70
* Every message that is constructed must be freed using
71
* ::pn_message_free().
72
*
73
* @return pointer to a new ::pn_message_t
74
*/
75
PN_EXTERN
pn_message_t
*
pn_message
(
void
);
76
77
/**
78
* Free a previously constructed ::pn_message_t.
79
*
80
* @param[in] msg pointer to a ::pn_message_t or NULL
81
*/
82
PN_EXTERN
void
pn_message_free
(
pn_message_t
*msg);
83
84
/**
85
* Clears the content of a ::pn_message_t.
86
*
87
* When pn_message_clear returns, the supplied ::pn_message_t will be
88
* emptied of all content and effectively returned to the same state
89
* as if it was just created.
90
*
91
* @param[in] msg pointer to the ::pn_message_t to be cleared
92
*/
93
PN_EXTERN
void
pn_message_clear
(
pn_message_t
*msg);
94
95
/**
96
* Access the error code of a message.
97
*
98
* Every operation on a message that can result in an error will set
99
* the message's error code in case of error. The pn_message_errno()
100
* call will access the error code of the most recent failed
101
* operation.
102
*
103
* @param[in] msg a message
104
* @return the message's error code
105
*/
106
PN_EXTERN
int
pn_message_errno
(
pn_message_t
*msg);
107
108
/**
109
* Access the error information for a message.
110
*
111
* Every operation on a message that can result in an error will
112
* update the error information held by its error descriptor should
113
* that operation fail. The pn_message_error() call will access the
114
* error information of the most recent failed operation. The pointer
115
* returned by this call is valid until the message is freed.
116
*
117
* @param[in] msg a message
118
* @return the message's error descriptor
119
*/
120
PN_EXTERN
pn_error_t
*
pn_message_error
(
pn_message_t
*msg);
121
122
/**
123
* Get the inferred flag for a message.
124
*
125
* The inferred flag for a message indicates how the message content
126
* is encoded into AMQP sections. If inferred is true then binary and
127
* list values in the body of the message will be encoded as AMQP DATA
128
* and AMQP SEQUENCE sections, respectively. If inferred is false,
129
* then all values in the body of the message will be encoded as AMQP
130
* VALUE sections regardless of their type. Use
131
* ::pn_message_set_inferred to set the value.
132
*
133
* @param[in] msg a message object
134
* @return the value of the inferred flag for the message
135
*/
136
PN_EXTERN
bool
pn_message_is_inferred
(
pn_message_t
*msg);
137
138
/**
139
* Set the inferred flag for a message.
140
*
141
* See ::pn_message_is_inferred() for a description of what the
142
* inferred flag is.
143
*
144
* @param[in] msg a message object
145
* @param[in] inferred the new value of the inferred flag
146
* @return zero on success or an error code on failure
147
*/
148
PN_EXTERN
int
pn_message_set_inferred
(
pn_message_t
*msg,
bool
inferred);
149
150
// standard message headers and properties
151
152
/**
153
* Get the durable flag for a message.
154
*
155
* The durable flag indicates that any parties taking responsibility
156
* for the message must durably store the content.
157
*
158
* @param[in] msg a message object
159
* @return the value of the durable flag
160
*/
161
PN_EXTERN
bool
pn_message_is_durable
(
pn_message_t
*msg);
162
163
/**
164
* Set the durable flag for a message.
165
*
166
* See ::pn_message_is_durable() for a description of the durable
167
* flag.
168
*
169
* @param[in] msg a message object
170
* @param[in] durable the new value of the durable flag
171
* @return zero on success or an error code on failure
172
*/
173
PN_EXTERN
int
pn_message_set_durable
(
pn_message_t
*msg,
bool
durable);
174
175
/**
176
* Get the priority for a message.
177
*
178
* The priority of a message impacts ordering guarantees. Within a
179
* given ordered context, higher priority messages may jump ahead of
180
* lower priority messages.
181
*
182
* @param[in] msg a message object
183
* @return the message priority
184
*/
185
PN_EXTERN
uint8_t
pn_message_get_priority
(
pn_message_t
*msg);
186
187
/**
188
* Set the priority for a message.
189
*
190
* See ::pn_message_get_priority() for details on message priority.
191
*
192
* @param[in] msg a message object
193
* @param[in] priority the new priority for the message
194
* @return zero on success or an error code on failure
195
*/
196
PN_EXTERN
int
pn_message_set_priority
(
pn_message_t
*msg, uint8_t priority);
197
198
/**
199
* Get the ttl for a message.
200
*
201
* The ttl for a message determines how long a message is considered
202
* live. When a message is held for retransmit, the ttl is
203
* decremented. Once the ttl reaches zero, the message is considered
204
* dead. Once a message is considered dead it may be dropped. Use
205
* ::pn_message_set_ttl() to set the ttl for a message.
206
*
207
* @param[in] msg a message object
208
* @return the ttl in milliseconds
209
*/
210
PN_EXTERN
pn_millis_t
pn_message_get_ttl
(
pn_message_t
*msg);
211
212
/**
213
* Set the ttl for a message.
214
*
215
* See ::pn_message_get_ttl() for a detailed description of message ttl.
216
*
217
* @param[in] msg a message object
218
* @param[in] ttl the new value for the message ttl
219
* @return zero on success or an error code on failure
220
*/
221
PN_EXTERN
int
pn_message_set_ttl
(
pn_message_t
*msg,
pn_millis_t
ttl);
222
223
/**
224
* Get the first acquirer flag for a message.
225
*
226
* When set to true, the first acquirer flag for a message indicates
227
* that the recipient of the message is the first recipient to acquire
228
* the message, i.e. there have been no failed delivery attempts to
229
* other acquirers. Note that this does not mean the message has not
230
* been delivered to, but not acquired, by other recipients.
231
*
232
* @param[in] msg a message object
233
* @return the first acquirer flag for the message
234
*/
235
PN_EXTERN
bool
pn_message_is_first_acquirer
(
pn_message_t
*msg);
236
237
/**
238
* Set the first acquirer flag for a message.
239
*
240
* See ::pn_message_is_first_acquirer() for details on the first
241
* acquirer flag.
242
*
243
* @param[in] msg a message object
244
* @param[in] first the new value for the first acquirer flag
245
* @return zero on success or an error code on failure
246
*/
247
PN_EXTERN
int
pn_message_set_first_acquirer
(
pn_message_t
*msg,
bool
first);
248
249
/**
250
* Get the delivery count for a message.
251
*
252
* The delivery count field tracks how many attempts have been made to
253
* delivery a message. Use ::pn_message_set_delivery_count() to set
254
* the delivery count for a message.
255
*
256
* @param[in] msg a message object
257
* @return the delivery count for the message
258
*/
259
PN_EXTERN
uint32_t
pn_message_get_delivery_count
(
pn_message_t
*msg);
260
261
/**
262
* Set the delivery count for a message.
263
*
264
* See ::pn_message_get_delivery_count() for details on what the
265
* delivery count means.
266
*
267
* @param[in] msg a message object
268
* @param[in] count the new delivery count
269
* @return zero on success or an error code on failure
270
*/
271
PN_EXTERN
int
pn_message_set_delivery_count
(
pn_message_t
*msg, uint32_t count);
272
273
/**
274
* Get/set the id for a message.
275
*
276
* The message id provides a globally unique identifier for a message.
277
* A message id can be an a string, an unsigned long, a uuid or a
278
* binary value. This operation returns a pointer to a ::pn_data_t
279
* that can be used to access and/or modify the value of the message
280
* id. The pointer is valid until the message is freed. See
281
* ::pn_data_t for details on how to get/set the value.
282
*
283
* @param[in] msg a message object
284
* @return pointer to a ::pn_data_t holding the id
285
*/
286
PN_EXTERN
pn_data_t
*
pn_message_id
(
pn_message_t
*msg);
287
288
/**
289
* Get the id for a message.
290
*
291
* The message id provides a globally unique identifier for a message.
292
* A message id can be an a string, an unsigned long, a uuid or a
293
* binary value. This operation returns the value of the id using the
294
* ::pn_atom_t descriminated union. See ::pn_atom_t for details on how
295
* to access the value.
296
*
297
* @param[in] msg a message object
298
* @return the message id
299
*/
300
PN_EXTERN
pn_atom_t
pn_message_get_id
(
pn_message_t
*msg);
301
302
/**
303
* Set the id for a message.
304
*
305
* See ::pn_message_get_id() for more details on the meaning of the
306
* message id. Note that only string, unsigned long, uuid, or binary
307
* values are permitted.
308
*
309
* @param[in] msg a message object
310
* @param[in] id the new value of the message id
311
* @return zero on success or an error code on failure
312
*/
313
PN_EXTERN
int
pn_message_set_id
(
pn_message_t
*msg,
pn_atom_t
id
);
314
315
/**
316
* Get the user id for a message.
317
*
318
* The pointer referenced by the ::pn_bytes_t struct will be valid
319
* until any one of the following operations occur:
320
*
321
* - ::pn_message_free()
322
* - ::pn_message_clear()
323
* - ::pn_message_set_user_id()
324
*
325
* @param[in] msg a message object
326
* @return a pn_bytes_t referencing the message's user_id
327
*/
328
PN_EXTERN
pn_bytes_t
pn_message_get_user_id
(
pn_message_t
*msg);
329
330
/**
331
* Set the user id for a message.
332
*
333
* This operation copies the bytes referenced by the provided
334
* ::pn_bytes_t struct.
335
*
336
* @param[in] msg a message object
337
* @param[in] user_id the new user_id for the message
338
* @return zero on success or an error code on failure
339
*/
340
PN_EXTERN
int
pn_message_set_user_id
(
pn_message_t
*msg,
pn_bytes_t
user_id);
341
342
/**
343
* Get the address for a message.
344
*
345
* This operation will return NULL if no address has been set or if
346
* the address has been set to NULL. The pointer returned by this
347
* operation is valid until any one of the following operations occur:
348
*
349
* - ::pn_message_free()
350
* - ::pn_message_clear()
351
* - ::pn_message_set_address()
352
*
353
* @param[in] msg a message object
354
* @return a pointer to the address of the message (or NULL)
355
*/
356
PN_EXTERN
const
char
*
pn_message_get_address
(
pn_message_t
*msg);
357
358
/**
359
* Set the address for a message.
360
*
361
* The supplied address pointer must either be NULL or reference a NUL
362
* terminated string. When the pointer is NULL, the address of the
363
* message is set to NULL. When the pointer is non NULL, the contents
364
* are copied into the message.
365
*
366
* @param[in] msg a message object
367
* @param[in] address a pointer to the new address (or NULL)
368
* @return zero on success or an error code on failure
369
*/
370
PN_EXTERN
int
pn_message_set_address
(
pn_message_t
*msg,
const
char
*address);
371
372
/**
373
* Get the subject for a message.
374
*
375
* This operation will return NULL if no subject has been set or if
376
* the subject has been set to NULL. The pointer returned by this
377
* operation is valid until any one of the following operations occur:
378
*
379
* - ::pn_message_free()
380
* - ::pn_message_clear()
381
* - ::pn_message_set_subject()
382
*
383
* @param[in] msg a message object
384
* @return a pointer to the subject of the message (or NULL)
385
*/
386
PN_EXTERN
const
char
*
pn_message_get_subject
(
pn_message_t
*msg);
387
388
/**
389
* Set the subject for a message.
390
*
391
* The supplied subject pointer must either be NULL or reference a NUL
392
* terminated string. When the pointer is NULL, the subject is set to
393
* NULL. When the pointer is non NULL, the contents are copied into
394
* the message.
395
*
396
* @param[in] msg a message object
397
* @param[in] subject a pointer to the new subject (or NULL)
398
* @return zero on success or an error code on failure
399
*/
400
PN_EXTERN
int
pn_message_set_subject
(
pn_message_t
*msg,
const
char
*subject);
401
402
/**
403
* Get the reply_to for a message.
404
*
405
* This operation will return NULL if no reply_to has been set or if
406
* the reply_to has been set to NULL. The pointer returned by this
407
* operation is valid until any one of the following operations occur:
408
*
409
* - ::pn_message_free()
410
* - ::pn_message_clear()
411
* - ::pn_message_set_reply_to()
412
*
413
* @param[in] msg a message object
414
* @return a pointer to the reply_to of the message (or NULL)
415
*/
416
PN_EXTERN
const
char
*
pn_message_get_reply_to
(
pn_message_t
*msg);
417
418
/**
419
* Set the reply_to for a message.
420
*
421
* The supplied reply_to pointer must either be NULL or reference a NUL
422
* terminated string. When the pointer is NULL, the reply_to is set to
423
* NULL. When the pointer is non NULL, the contents are copied into
424
* the message.
425
*
426
* @param[in] msg a message object
427
* @param[in] reply_to a pointer to the new reply_to (or NULL)
428
* @return zero on success or an error code on failure
429
*/
430
PN_EXTERN
int
pn_message_set_reply_to
(
pn_message_t
*msg,
const
char
*reply_to);
431
432
/**
433
* Get/set the correlation id for a message.
434
*
435
* A correlation id can be an a string, an unsigned long, a uuid or a
436
* binary value. This operation returns a pointer to a ::pn_data_t
437
* that can be used to access and/or modify the value of the
438
* correlation id. The pointer is valid until the message is freed.
439
* See ::pn_data_t for details on how to get/set the value.
440
*
441
* @param[in] msg a message object
442
* @return pointer to a ::pn_data_t holding the correlation id
443
*/
444
PN_EXTERN
pn_data_t
*
pn_message_correlation_id
(
pn_message_t
*msg);
445
446
/**
447
* Get the correlation id for a message.
448
*
449
* A correlation id can be an a string, an unsigned long, a uuid or a
450
* binary value. This operation returns the value of the id using the
451
* ::pn_atom_t descriminated union. See ::pn_atom_t for details on how
452
* to access the value.
453
*
454
* @param[in] msg a message object
455
* @return the message id
456
*/
457
PN_EXTERN
pn_atom_t
pn_message_get_correlation_id
(
pn_message_t
*msg);
458
459
/**
460
* Set the correlation id for a message.
461
*
462
* See ::pn_message_get_correlation_id() for more details on the
463
* meaning of the correlation id. Note that only string, unsigned
464
* long, uuid, or binary values are permitted.
465
*
466
* @param[in] msg a message object
467
* @param[in] id the new value of the message id
468
* @return zero on success or an error code on failure
469
*/
470
PN_EXTERN
int
pn_message_set_correlation_id
(
pn_message_t
*msg,
pn_atom_t
id
);
471
472
/**
473
* Get the content_type for a message.
474
*
475
* This operation will return NULL if no content_type has been set or if
476
* the content_type has been set to NULL. The pointer returned by this
477
* operation is valid until any one of the following operations occur:
478
*
479
* - ::pn_message_free()
480
* - ::pn_message_clear()
481
* - ::pn_message_set_content_type()
482
*
483
* @param[in] msg a message object
484
* @return a pointer to the content_type of the message (or NULL)
485
*/
486
PN_EXTERN
const
char
*
pn_message_get_content_type
(
pn_message_t
*msg);
487
488
/**
489
* Set the content_type for a message.
490
*
491
* The supplied content_type pointer must either be NULL or reference a NUL
492
* terminated string. When the pointer is NULL, the content_type is set to
493
* NULL. When the pointer is non NULL, the contents are copied into
494
* the message.
495
*
496
* @param[in] msg a message object
497
* @param[in] type a pointer to the new content_type (or NULL)
498
* @return zero on success or an error code on failure
499
*/
500
PN_EXTERN
int
pn_message_set_content_type
(
pn_message_t
*msg,
const
char
*type);
501
502
/**
503
* Get the content_encoding for a message.
504
*
505
* This operation will return NULL if no content_encoding has been set or if
506
* the content_encoding has been set to NULL. The pointer returned by this
507
* operation is valid until any one of the following operations occur:
508
*
509
* - ::pn_message_free()
510
* - ::pn_message_clear()
511
* - ::pn_message_set_content_encoding()
512
*
513
* @param[in] msg a message object
514
* @return a pointer to the content_encoding of the message (or NULL)
515
*/
516
PN_EXTERN
const
char
*
pn_message_get_content_encoding
(
pn_message_t
*msg);
517
518
/**
519
* Set the content_encoding for a message.
520
*
521
* The supplied content_encoding pointer must either be NULL or reference a NUL
522
* terminated string. When the pointer is NULL, the content_encoding is set to
523
* NULL. When the pointer is non NULL, the contents are copied into
524
* the message.
525
*
526
* @param[in] msg a message object
527
* @param[in] encoding a pointer to the new content_encoding (or NULL)
528
* @return zero on success or an error code on failure
529
*/
530
PN_EXTERN
int
pn_message_set_content_encoding
(
pn_message_t
*msg,
const
char
*encoding);
531
532
/**
533
* Get the expiry time for a message.
534
*
535
* A zero value for the expiry time indicates that the message will
536
* never expire. This is the default value.
537
*
538
* @param[in] msg a message object
539
* @return the expiry time for the message
540
*/
541
PN_EXTERN
pn_timestamp_t
pn_message_get_expiry_time
(
pn_message_t
*msg);
542
543
/**
544
* Set the expiry time for a message.
545
*
546
* See ::pn_message_get_expiry_time() for more details.
547
*
548
* @param[in] msg a message object
549
* @param[in] time the new expiry time for the message
550
* @return zero on success or an error code on failure
551
*/
552
PN_EXTERN
int
pn_message_set_expiry_time
(
pn_message_t
*msg,
pn_timestamp_t
time);
553
554
/**
555
* Get the creation time for a message.
556
*
557
* A zero value for the creation time indicates that the creation time
558
* has not been set. This is the default value.
559
*
560
* @param[in] msg a message object
561
* @return the creation time for the message
562
*/
563
PN_EXTERN
pn_timestamp_t
pn_message_get_creation_time
(
pn_message_t
*msg);
564
565
/**
566
* Set the creation time for a message.
567
*
568
* See ::pn_message_get_creation_time() for more details.
569
*
570
* @param[in] msg a message object
571
* @param[in] time the new creation time for the message
572
* @return zero on success or an error code on failure
573
*/
574
PN_EXTERN
int
pn_message_set_creation_time
(
pn_message_t
*msg,
pn_timestamp_t
time);
575
576
/**
577
* Get the group_id for a message.
578
*
579
* This operation will return NULL if no group_id has been set or if
580
* the group_id has been set to NULL. The pointer returned by this
581
* operation is valid until any one of the following operations occur:
582
*
583
* - ::pn_message_free()
584
* - ::pn_message_clear()
585
* - ::pn_message_set_group_id()
586
*
587
* @param[in] msg a message object
588
* @return a pointer to the group_id of the message (or NULL)
589
*/
590
PN_EXTERN
const
char
*
pn_message_get_group_id
(
pn_message_t
*msg);
591
592
/**
593
* Set the group_id for a message.
594
*
595
* The supplied group_id pointer must either be NULL or reference a NUL
596
* terminated string. When the pointer is NULL, the group_id is set to
597
* NULL. When the pointer is non NULL, the contents are copied into
598
* the message.
599
*
600
* @param[in] msg a message object
601
* @param[in] group_id a pointer to the new group_id (or NULL)
602
* @return zero on success or an error code on failure
603
*/
604
PN_EXTERN
int
pn_message_set_group_id
(
pn_message_t
*msg,
const
char
*group_id);
605
606
/**
607
* Get the group sequence for a message.
608
*
609
* The group sequence of a message identifies the relative ordering of
610
* messages within a group. The default value for the group sequence
611
* of a message is zero.
612
*
613
* @param[in] msg a message object
614
* @return the group sequence for the message
615
*/
616
PN_EXTERN
pn_sequence_t
pn_message_get_group_sequence
(
pn_message_t
*msg);
617
618
/**
619
* Set the group sequence for a message.
620
*
621
* See ::pn_message_get_group_sequence() for details on what the group
622
* sequence means.
623
*
624
* @param[in] msg a message object
625
* @param[in] n the new group sequence for the message
626
* @return zero on success or an error code on failure
627
*/
628
PN_EXTERN
int
pn_message_set_group_sequence
(
pn_message_t
*msg,
pn_sequence_t
n);
629
630
/**
631
* Get the reply_to_group_id for a message.
632
*
633
* This operation will return NULL if no reply_to_group_id has been set or if
634
* the reply_to_group_id has been set to NULL. The pointer returned by this
635
* operation is valid until any one of the following operations occur:
636
*
637
* - ::pn_message_free()
638
* - ::pn_message_clear()
639
* - ::pn_message_set_reply_to_group_id()
640
*
641
* @param[in] msg a message object
642
* @return a pointer to the reply_to_group_id of the message (or NULL)
643
*/
644
PN_EXTERN
const
char
*
pn_message_get_reply_to_group_id
(
pn_message_t
*msg);
645
646
/**
647
* Set the reply_to_group_id for a message.
648
*
649
* The supplied reply_to_group_id pointer must either be NULL or reference a NUL
650
* terminated string. When the pointer is NULL, the reply_to_group_id is set to
651
* NULL. When the pointer is non NULL, the contents are copied into
652
* the message.
653
*
654
* @param[in] msg a message object
655
* @param[in] reply_to_group_id a pointer to the new reply_to_group_id (or NULL)
656
* @return zero on success or an error code on failure
657
*/
658
PN_EXTERN
int
pn_message_set_reply_to_group_id
(
pn_message_t
*msg,
const
char
*reply_to_group_id);
659
660
/**
661
* @deprecated
662
*/
663
PN_EXTERN
pn_format_t
pn_message_get_format
(
pn_message_t
*message);
664
665
/**
666
* @deprecated
667
*/
668
PN_EXTERN
int
pn_message_set_format
(
pn_message_t
*message,
pn_format_t
format);
669
670
/**
671
* @deprecated Use ::pn_message_body() instead.
672
*/
673
PN_EXTERN
int
pn_message_load
(
pn_message_t
*message,
const
char
*data,
size_t
size);
674
675
/**
676
* @deprecated Use ::pn_message_body() instead.
677
*/
678
PN_EXTERN
int
pn_message_load_data
(
pn_message_t
*message,
const
char
*data,
size_t
size);
679
680
/**
681
* @deprecated Use ::pn_message_body() instead.
682
*/
683
PN_EXTERN
int
pn_message_load_text
(
pn_message_t
*message,
const
char
*data,
size_t
size);
684
685
/**
686
* @deprecated Use ::pn_message_body() instead.
687
*/
688
PN_EXTERN
int
pn_message_load_amqp
(
pn_message_t
*message,
const
char
*data,
size_t
size);
689
690
/**
691
* @deprecated Use ::pn_message_body() instead.
692
*/
693
PN_EXTERN
int
pn_message_load_json
(
pn_message_t
*message,
const
char
*data,
size_t
size);
694
695
/**
696
* @deprecated Use ::pn_message_body() instead.
697
*/
698
PN_EXTERN
int
pn_message_save
(
pn_message_t
*message,
char
*data,
size_t
*size);
699
700
/**
701
* @deprecated Use ::pn_message_body() instead.
702
*/
703
PN_EXTERN
int
pn_message_save_data
(
pn_message_t
*message,
char
*data,
size_t
*size);
704
705
/**
706
* @deprecated Use ::pn_message_body() instead.
707
*/
708
PN_EXTERN
int
pn_message_save_text
(
pn_message_t
*message,
char
*data,
size_t
*size);
709
710
/**
711
* @deprecated Use ::pn_message_body() instead.
712
*/
713
PN_EXTERN
int
pn_message_save_amqp
(
pn_message_t
*message,
char
*data,
size_t
*size);
714
715
/**
716
* @deprecated Use ::pn_message_body() instead.
717
*/
718
PN_EXTERN
int
pn_message_save_json
(
pn_message_t
*message,
char
*data,
size_t
*size);
719
720
/**
721
* Get/set the delivery instructions for a message.
722
*
723
* This operation returns a pointer to a ::pn_data_t representing the
724
* content of the delivery instructions section of a message. The
725
* pointer is valid until the message is freed and may be used to both
726
* access and modify the content of the delivery instructions section
727
* of a message.
728
*
729
* The ::pn_data_t must either be empty or consist of a symbol keyed
730
* map in order to be considered valid delivery instructions.
731
*
732
* @param[in] msg a message object
733
* @return a pointer to the delivery instructions
734
*/
735
PN_EXTERN
pn_data_t
*
pn_message_instructions
(
pn_message_t
*msg);
736
737
/**
738
* Get/set the annotations for a message.
739
*
740
* This operation returns a pointer to a ::pn_data_t representing the
741
* content of the annotations section of a message. The pointer is
742
* valid until the message is freed and may be used to both access and
743
* modify the content of the annotations section of a message.
744
*
745
* The ::pn_data_t must either be empty or consist of a symbol keyed
746
* map in order to be considered valid message annotations.
747
*
748
* @param[in] msg a message object
749
* @return a pointer to the message annotations
750
*/
751
PN_EXTERN
pn_data_t
*
pn_message_annotations
(
pn_message_t
*msg);
752
753
/**
754
* Get/set the properties for a message.
755
*
756
* This operation returns a pointer to a ::pn_data_t representing the
757
* content of the properties section of a message. The pointer is
758
* valid until the message is freed and may be used to both access and
759
* modify the content of the properties section of a message.
760
*
761
* The ::pn_data_t must either be empty or consist of a string keyed
762
* map in order to be considered valid message properties.
763
*
764
* @param[in] msg a message object
765
* @return a pointer to the message properties
766
*/
767
PN_EXTERN
pn_data_t
*
pn_message_properties
(
pn_message_t
*msg);
768
769
/**
770
* Get/set the body of a message.
771
*
772
* This operation returns a pointer to a ::pn_data_t representing the
773
* body of a message. The pointer is valid until the message is freed
774
* and may be used to both access and modify the content of the
775
* message body.
776
*
777
* @param[in] msg a message object
778
* @return a pointer to the message body
779
*/
780
PN_EXTERN
pn_data_t
*
pn_message_body
(
pn_message_t
*msg);
781
782
/**
783
* Decode/load message content from AMQP formatted binary data.
784
*
785
* Upon invoking this operation, any existing message content will be
786
* cleared and replaced with the content from the provided binary
787
* data.
788
*
789
* @param[in] msg a message object
790
* @param[in] bytes the start of the encoded AMQP data
791
* @param[in] size the size of the encoded AMQP data
792
* @return zero on success or an error code on failure
793
*/
794
PN_EXTERN
int
pn_message_decode
(
pn_message_t
*msg,
const
char
*bytes,
size_t
size);
795
796
/**
797
* Encode/save message content as AMQP formatted binary data.
798
*
799
* If the buffer space provided is insufficient to store the content
800
* held in the message, the operation will fail and return a
801
* ::PN_OVERFLOW error code.
802
*
803
* @param[in] msg a message object
804
* @param[in] bytes the start of empty buffer space
805
* @param[in] size the amount of empty buffer space
806
* @param[out] size the amount of data written
807
* @return zero on success or an error code on failure
808
*/
809
PN_EXTERN
int
pn_message_encode
(
pn_message_t
*msg,
char
*bytes,
size_t
*size);
810
811
/**
812
* @deprecated
813
*/
814
PN_EXTERN
ssize_t
pn_message_data
(
char
*dst,
size_t
available,
const
char
*src,
size_t
size);
815
816
/** @}
817
*/
818
819
#ifdef __cplusplus
820
}
821
#endif
822
823
#endif
/* message.h */
Generated on Mon Jun 2 2014 22:59:05 for proton by
1.8.1.2