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
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 Thu Jul 10 2014 02:10:59 for proton by
1.8.3.1