00001 #ifndef PROTON_MESSAGE_H 00002 #define PROTON_MESSAGE_H 1 00003 00004 /* 00005 * 00006 * Licensed to the Apache Software Foundation (ASF) under one 00007 * or more contributor license agreements. See the NOTICE file 00008 * distributed with this work for additional information 00009 * regarding copyright ownership. The ASF licenses this file 00010 * to you under the Apache License, Version 2.0 (the 00011 * "License"); you may not use this file except in compliance 00012 * with the License. You may obtain a copy of the License at 00013 * 00014 * http://www.apache.org/licenses/LICENSE-2.0 00015 * 00016 * Unless required by applicable law or agreed to in writing, 00017 * software distributed under the License is distributed on an 00018 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00019 * KIND, either express or implied. See the License for the 00020 * specific language governing permissions and limitations 00021 * under the License. 00022 * 00023 */ 00024 00025 #include <proton/import_export.h> 00026 #include <proton/types.h> 00027 #include <proton/codec.h> 00028 #include <proton/error.h> 00029 #include <proton/type_compat.h> 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif 00034 00035 /** @file 00036 * Message API for encoding/decoding AMQP Messages. 00037 * 00038 * @defgroup message Message 00039 * @{ 00040 */ 00041 00042 /** 00043 * An AMQP Message object. 00044 * 00045 * An AMQP Message object is a mutable holder of message content that 00046 * may be used to generate and encode or decode and access AMQP 00047 * formatted message data. 00048 */ 00049 typedef struct pn_message_t pn_message_t; 00050 00051 /** 00052 * Default priority for messages. 00053 */ 00054 #define PN_DEFAULT_PRIORITY (4) 00055 00056 /** 00057 * Construct a new ::pn_message_t. 00058 * 00059 * Every message that is constructed must be freed using 00060 * ::pn_message_free(). 00061 * 00062 * @return pointer to a new ::pn_message_t 00063 */ 00064 PN_EXTERN pn_message_t * pn_message(void); 00065 00066 /** 00067 * Free a previously constructed ::pn_message_t. 00068 * 00069 * @param[in] msg pointer to a ::pn_message_t or NULL 00070 */ 00071 PN_EXTERN void pn_message_free(pn_message_t *msg); 00072 00073 /** 00074 * Clears the content of a ::pn_message_t. 00075 * 00076 * When pn_message_clear returns, the supplied ::pn_message_t will be 00077 * emptied of all content and effectively returned to the same state 00078 * as if it was just created. 00079 * 00080 * @param[in] msg pointer to the ::pn_message_t to be cleared 00081 */ 00082 PN_EXTERN void pn_message_clear(pn_message_t *msg); 00083 00084 /** 00085 * Access the error code of a message. 00086 * 00087 * Every operation on a message that can result in an error will set 00088 * the message's error code in case of error. The pn_message_errno() 00089 * call will access the error code of the most recent failed 00090 * operation. 00091 * 00092 * @param[in] msg a message 00093 * @return the message's error code 00094 */ 00095 PN_EXTERN int pn_message_errno(pn_message_t *msg); 00096 00097 /** 00098 * Access the error information for a message. 00099 * 00100 * Every operation on a message that can result in an error will 00101 * update the error information held by its error descriptor should 00102 * that operation fail. The pn_message_error() call will access the 00103 * error information of the most recent failed operation. The pointer 00104 * returned by this call is valid until the message is freed. 00105 * 00106 * @param[in] msg a message 00107 * @return the message's error descriptor 00108 */ 00109 PN_EXTERN pn_error_t *pn_message_error(pn_message_t *msg); 00110 00111 /** 00112 * Get the inferred flag for a message. 00113 * 00114 * The inferred flag for a message indicates how the message content 00115 * is encoded into AMQP sections. If inferred is true then binary and 00116 * list values in the body of the message will be encoded as AMQP DATA 00117 * and AMQP SEQUENCE sections, respectively. If inferred is false, 00118 * then all values in the body of the message will be encoded as AMQP 00119 * VALUE sections regardless of their type. Use 00120 * ::pn_message_set_inferred to set the value. 00121 * 00122 * @param[in] msg a message object 00123 * @return the value of the inferred flag for the message 00124 */ 00125 PN_EXTERN bool pn_message_is_inferred(pn_message_t *msg); 00126 00127 /** 00128 * Set the inferred flag for a message. 00129 * 00130 * See ::pn_message_is_inferred() for a description of what the 00131 * inferred flag is. 00132 * 00133 * @param[in] msg a message object 00134 * @param[in] inferred the new value of the inferred flag 00135 * @return zero on success or an error code on failure 00136 */ 00137 PN_EXTERN int pn_message_set_inferred(pn_message_t *msg, bool inferred); 00138 00139 // standard message headers and properties 00140 00141 /** 00142 * Get the durable flag for a message. 00143 * 00144 * The durable flag indicates that any parties taking responsibility 00145 * for the message must durably store the content. 00146 * 00147 * @param[in] msg a message object 00148 * @return the value of the durable flag 00149 */ 00150 PN_EXTERN bool pn_message_is_durable (pn_message_t *msg); 00151 00152 /** 00153 * Set the durable flag for a message. 00154 * 00155 * See ::pn_message_is_durable() for a description of the durable 00156 * flag. 00157 * 00158 * @param[in] msg a message object 00159 * @param[in] durable the new value of the durable flag 00160 * @return zero on success or an error code on failure 00161 */ 00162 PN_EXTERN int pn_message_set_durable (pn_message_t *msg, bool durable); 00163 00164 /** 00165 * Get the priority for a message. 00166 * 00167 * The priority of a message impacts ordering guarantees. Within a 00168 * given ordered context, higher priority messages may jump ahead of 00169 * lower priority messages. 00170 * 00171 * @param[in] msg a message object 00172 * @return the message priority 00173 */ 00174 PN_EXTERN uint8_t pn_message_get_priority (pn_message_t *msg); 00175 00176 /** 00177 * Set the priority for a message. 00178 * 00179 * See ::pn_message_get_priority() for details on message priority. 00180 * 00181 * @param[in] msg a message object 00182 * @param[in] priority the new priority for the message 00183 * @return zero on success or an error code on failure 00184 */ 00185 PN_EXTERN int pn_message_set_priority (pn_message_t *msg, uint8_t priority); 00186 00187 /** 00188 * Get the ttl for a message. 00189 * 00190 * The ttl for a message determines how long a message is considered 00191 * live. When a message is held for retransmit, the ttl is 00192 * decremented. Once the ttl reaches zero, the message is considered 00193 * dead. Once a message is considered dead it may be dropped. Use 00194 * ::pn_message_set_ttl() to set the ttl for a message. 00195 * 00196 * @param[in] msg a message object 00197 * @return the ttl in milliseconds 00198 */ 00199 PN_EXTERN pn_millis_t pn_message_get_ttl (pn_message_t *msg); 00200 00201 /** 00202 * Set the ttl for a message. 00203 * 00204 * See ::pn_message_get_ttl() for a detailed description of message ttl. 00205 * 00206 * @param[in] msg a message object 00207 * @param[in] ttl the new value for the message ttl 00208 * @return zero on success or an error code on failure 00209 */ 00210 PN_EXTERN int pn_message_set_ttl (pn_message_t *msg, pn_millis_t ttl); 00211 00212 /** 00213 * Get the first acquirer flag for a message. 00214 * 00215 * When set to true, the first acquirer flag for a message indicates 00216 * that the recipient of the message is the first recipient to acquire 00217 * the message, i.e. there have been no failed delivery attempts to 00218 * other acquirers. Note that this does not mean the message has not 00219 * been delivered to, but not acquired, by other recipients. 00220 * 00221 * @param[in] msg a message object 00222 * @return the first acquirer flag for the message 00223 */ 00224 PN_EXTERN bool pn_message_is_first_acquirer (pn_message_t *msg); 00225 00226 /** 00227 * Set the first acquirer flag for a message. 00228 * 00229 * See ::pn_message_is_first_acquirer() for details on the first 00230 * acquirer flag. 00231 * 00232 * @param[in] msg a message object 00233 * @param[in] first the new value for the first acquirer flag 00234 * @return zero on success or an error code on failure 00235 */ 00236 PN_EXTERN int pn_message_set_first_acquirer (pn_message_t *msg, bool first); 00237 00238 /** 00239 * Get the delivery count for a message. 00240 * 00241 * The delivery count field tracks how many attempts have been made to 00242 * delivery a message. Use ::pn_message_set_delivery_count() to set 00243 * the delivery count for a message. 00244 * 00245 * @param[in] msg a message object 00246 * @return the delivery count for the message 00247 */ 00248 PN_EXTERN uint32_t pn_message_get_delivery_count (pn_message_t *msg); 00249 00250 /** 00251 * Set the delivery count for a message. 00252 * 00253 * See ::pn_message_get_delivery_count() for details on what the 00254 * delivery count means. 00255 * 00256 * @param[in] msg a message object 00257 * @param[in] count the new delivery count 00258 * @return zero on success or an error code on failure 00259 */ 00260 PN_EXTERN int pn_message_set_delivery_count (pn_message_t *msg, uint32_t count); 00261 00262 /** 00263 * Get/set the id for a message. 00264 * 00265 * The message id provides a globally unique identifier for a message. 00266 * A message id can be an a string, an unsigned long, a uuid or a 00267 * binary value. This operation returns a pointer to a ::pn_data_t 00268 * that can be used to access and/or modify the value of the message 00269 * id. The pointer is valid until the message is freed. See 00270 * ::pn_data_t for details on how to get/set the value. 00271 * 00272 * @param[in] msg a message object 00273 * @return pointer to a ::pn_data_t holding the id 00274 */ 00275 PN_EXTERN pn_data_t * pn_message_id (pn_message_t *msg); 00276 00277 /** 00278 * Get the id for a message. 00279 * 00280 * The message id provides a globally unique identifier for a message. 00281 * A message id can be an a string, an unsigned long, a uuid or a 00282 * binary value. This operation returns the value of the id using the 00283 * ::pn_atom_t descriminated union. See ::pn_atom_t for details on how 00284 * to access the value. 00285 * 00286 * @param[in] msg a message object 00287 * @return the message id 00288 */ 00289 PN_EXTERN pn_atom_t pn_message_get_id (pn_message_t *msg); 00290 00291 /** 00292 * Set the id for a message. 00293 * 00294 * See ::pn_message_get_id() for more details on the meaning of the 00295 * message id. Note that only string, unsigned long, uuid, or binary 00296 * values are permitted. 00297 * 00298 * @param[in] msg a message object 00299 * @param[in] id the new value of the message id 00300 * @return zero on success or an error code on failure 00301 */ 00302 PN_EXTERN int pn_message_set_id (pn_message_t *msg, pn_atom_t id); 00303 00304 /** 00305 * Get the user id for a message. 00306 * 00307 * The pointer referenced by the ::pn_bytes_t struct will be valid 00308 * until any one of the following operations occur: 00309 * 00310 * - ::pn_message_free() 00311 * - ::pn_message_clear() 00312 * - ::pn_message_set_user_id() 00313 * 00314 * @param[in] msg a message object 00315 * @return a pn_bytes_t referencing the message's user_id 00316 */ 00317 PN_EXTERN pn_bytes_t pn_message_get_user_id (pn_message_t *msg); 00318 00319 /** 00320 * Set the user id for a message. 00321 * 00322 * This operation copies the bytes referenced by the provided 00323 * ::pn_bytes_t struct. 00324 * 00325 * @param[in] msg a message object 00326 * @param[in] user_id the new user_id for the message 00327 * @return zero on success or an error code on failure 00328 */ 00329 PN_EXTERN int pn_message_set_user_id (pn_message_t *msg, pn_bytes_t user_id); 00330 00331 /** 00332 * Get the address for a message. 00333 * 00334 * This operation will return NULL if no address has been set or if 00335 * the address has been set to NULL. The pointer returned by this 00336 * operation is valid until any one of the following operations occur: 00337 * 00338 * - ::pn_message_free() 00339 * - ::pn_message_clear() 00340 * - ::pn_message_set_address() 00341 * 00342 * @param[in] msg a message object 00343 * @return a pointer to the address of the message (or NULL) 00344 */ 00345 PN_EXTERN const char * pn_message_get_address (pn_message_t *msg); 00346 00347 /** 00348 * Set the address for a message. 00349 * 00350 * The supplied address pointer must either be NULL or reference a NUL 00351 * terminated string. When the pointer is NULL, the address of the 00352 * message is set to NULL. When the pointer is non NULL, the contents 00353 * are copied into the message. 00354 * 00355 * @param[in] msg a message object 00356 * @param[in] address a pointer to the new address (or NULL) 00357 * @return zero on success or an error code on failure 00358 */ 00359 PN_EXTERN int pn_message_set_address (pn_message_t *msg, const char *address); 00360 00361 /** 00362 * Get the subject for a message. 00363 * 00364 * This operation will return NULL if no subject has been set or if 00365 * the subject has been set to NULL. The pointer returned by this 00366 * operation is valid until any one of the following operations occur: 00367 * 00368 * - ::pn_message_free() 00369 * - ::pn_message_clear() 00370 * - ::pn_message_set_subject() 00371 * 00372 * @param[in] msg a message object 00373 * @return a pointer to the subject of the message (or NULL) 00374 */ 00375 PN_EXTERN const char * pn_message_get_subject (pn_message_t *msg); 00376 00377 /** 00378 * Set the subject for a message. 00379 * 00380 * The supplied subject pointer must either be NULL or reference a NUL 00381 * terminated string. When the pointer is NULL, the subject is set to 00382 * NULL. When the pointer is non NULL, the contents are copied into 00383 * the message. 00384 * 00385 * @param[in] msg a message object 00386 * @param[in] subject a pointer to the new subject (or NULL) 00387 * @return zero on success or an error code on failure 00388 */ 00389 PN_EXTERN int pn_message_set_subject (pn_message_t *msg, const char *subject); 00390 00391 /** 00392 * Get the reply_to for a message. 00393 * 00394 * This operation will return NULL if no reply_to has been set or if 00395 * the reply_to has been set to NULL. The pointer returned by this 00396 * operation is valid until any one of the following operations occur: 00397 * 00398 * - ::pn_message_free() 00399 * - ::pn_message_clear() 00400 * - ::pn_message_set_reply_to() 00401 * 00402 * @param[in] msg a message object 00403 * @return a pointer to the reply_to of the message (or NULL) 00404 */ 00405 PN_EXTERN const char * pn_message_get_reply_to (pn_message_t *msg); 00406 00407 /** 00408 * Set the reply_to for a message. 00409 * 00410 * The supplied reply_to pointer must either be NULL or reference a NUL 00411 * terminated string. When the pointer is NULL, the reply_to is set to 00412 * NULL. When the pointer is non NULL, the contents are copied into 00413 * the message. 00414 * 00415 * @param[in] msg a message object 00416 * @param[in] reply_to a pointer to the new reply_to (or NULL) 00417 * @return zero on success or an error code on failure 00418 */ 00419 PN_EXTERN int pn_message_set_reply_to (pn_message_t *msg, const char *reply_to); 00420 00421 /** 00422 * Get/set the correlation id for a message. 00423 * 00424 * A correlation id can be an a string, an unsigned long, a uuid or a 00425 * binary value. This operation returns a pointer to a ::pn_data_t 00426 * that can be used to access and/or modify the value of the 00427 * correlation id. The pointer is valid until the message is freed. 00428 * See ::pn_data_t for details on how to get/set the value. 00429 * 00430 * @param[in] msg a message object 00431 * @return pointer to a ::pn_data_t holding the correlation id 00432 */ 00433 PN_EXTERN pn_data_t * pn_message_correlation_id (pn_message_t *msg); 00434 00435 /** 00436 * Get the correlation id for a message. 00437 * 00438 * A correlation id can be an a string, an unsigned long, a uuid or a 00439 * binary value. This operation returns the value of the id using the 00440 * ::pn_atom_t descriminated union. See ::pn_atom_t for details on how 00441 * to access the value. 00442 * 00443 * @param[in] msg a message object 00444 * @return the message id 00445 */ 00446 PN_EXTERN pn_atom_t pn_message_get_correlation_id (pn_message_t *msg); 00447 00448 /** 00449 * Set the correlation id for a message. 00450 * 00451 * See ::pn_message_get_correlation_id() for more details on the 00452 * meaning of the correlation id. Note that only string, unsigned 00453 * long, uuid, or binary values are permitted. 00454 * 00455 * @param[in] msg a message object 00456 * @param[in] id the new value of the message id 00457 * @return zero on success or an error code on failure 00458 */ 00459 PN_EXTERN int pn_message_set_correlation_id (pn_message_t *msg, pn_atom_t id); 00460 00461 /** 00462 * Get the content_type for a message. 00463 * 00464 * This operation will return NULL if no content_type has been set or if 00465 * the content_type has been set to NULL. The pointer returned by this 00466 * operation is valid until any one of the following operations occur: 00467 * 00468 * - ::pn_message_free() 00469 * - ::pn_message_clear() 00470 * - ::pn_message_set_content_type() 00471 * 00472 * @param[in] msg a message object 00473 * @return a pointer to the content_type of the message (or NULL) 00474 */ 00475 PN_EXTERN const char * pn_message_get_content_type (pn_message_t *msg); 00476 00477 /** 00478 * Set the content_type for a message. 00479 * 00480 * The supplied content_type pointer must either be NULL or reference a NUL 00481 * terminated string. When the pointer is NULL, the content_type is set to 00482 * NULL. When the pointer is non NULL, the contents are copied into 00483 * the message. 00484 * 00485 * @param[in] msg a message object 00486 * @param[in] type a pointer to the new content_type (or NULL) 00487 * @return zero on success or an error code on failure 00488 */ 00489 PN_EXTERN int pn_message_set_content_type (pn_message_t *msg, const char *type); 00490 00491 /** 00492 * Get the content_encoding for a message. 00493 * 00494 * This operation will return NULL if no content_encoding has been set or if 00495 * the content_encoding has been set to NULL. The pointer returned by this 00496 * operation is valid until any one of the following operations occur: 00497 * 00498 * - ::pn_message_free() 00499 * - ::pn_message_clear() 00500 * - ::pn_message_set_content_encoding() 00501 * 00502 * @param[in] msg a message object 00503 * @return a pointer to the content_encoding of the message (or NULL) 00504 */ 00505 PN_EXTERN const char * pn_message_get_content_encoding (pn_message_t *msg); 00506 00507 /** 00508 * Set the content_encoding for a message. 00509 * 00510 * The supplied content_encoding pointer must either be NULL or reference a NUL 00511 * terminated string. When the pointer is NULL, the content_encoding is set to 00512 * NULL. When the pointer is non NULL, the contents are copied into 00513 * the message. 00514 * 00515 * @param[in] msg a message object 00516 * @param[in] encoding a pointer to the new content_encoding (or NULL) 00517 * @return zero on success or an error code on failure 00518 */ 00519 PN_EXTERN int pn_message_set_content_encoding (pn_message_t *msg, const char *encoding); 00520 00521 /** 00522 * Get the expiry time for a message. 00523 * 00524 * A zero value for the expiry time indicates that the message will 00525 * never expire. This is the default value. 00526 * 00527 * @param[in] msg a message object 00528 * @return the expiry time for the message 00529 */ 00530 PN_EXTERN pn_timestamp_t pn_message_get_expiry_time (pn_message_t *msg); 00531 00532 /** 00533 * Set the expiry time for a message. 00534 * 00535 * See ::pn_message_get_expiry_time() for more details. 00536 * 00537 * @param[in] msg a message object 00538 * @param[in] time the new expiry time for the message 00539 * @return zero on success or an error code on failure 00540 */ 00541 PN_EXTERN int pn_message_set_expiry_time (pn_message_t *msg, pn_timestamp_t time); 00542 00543 /** 00544 * Get the creation time for a message. 00545 * 00546 * A zero value for the creation time indicates that the creation time 00547 * has not been set. This is the default value. 00548 * 00549 * @param[in] msg a message object 00550 * @return the creation time for the message 00551 */ 00552 PN_EXTERN pn_timestamp_t pn_message_get_creation_time (pn_message_t *msg); 00553 00554 /** 00555 * Set the creation time for a message. 00556 * 00557 * See ::pn_message_get_creation_time() for more details. 00558 * 00559 * @param[in] msg a message object 00560 * @param[in] time the new creation time for the message 00561 * @return zero on success or an error code on failure 00562 */ 00563 PN_EXTERN int pn_message_set_creation_time (pn_message_t *msg, pn_timestamp_t time); 00564 00565 /** 00566 * Get the group_id for a message. 00567 * 00568 * This operation will return NULL if no group_id has been set or if 00569 * the group_id has been set to NULL. The pointer returned by this 00570 * operation is valid until any one of the following operations occur: 00571 * 00572 * - ::pn_message_free() 00573 * - ::pn_message_clear() 00574 * - ::pn_message_set_group_id() 00575 * 00576 * @param[in] msg a message object 00577 * @return a pointer to the group_id of the message (or NULL) 00578 */ 00579 PN_EXTERN const char * pn_message_get_group_id (pn_message_t *msg); 00580 00581 /** 00582 * Set the group_id for a message. 00583 * 00584 * The supplied group_id pointer must either be NULL or reference a NUL 00585 * terminated string. When the pointer is NULL, the group_id is set to 00586 * NULL. When the pointer is non NULL, the contents are copied into 00587 * the message. 00588 * 00589 * @param[in] msg a message object 00590 * @param[in] group_id a pointer to the new group_id (or NULL) 00591 * @return zero on success or an error code on failure 00592 */ 00593 PN_EXTERN int pn_message_set_group_id (pn_message_t *msg, const char *group_id); 00594 00595 /** 00596 * Get the group sequence for a message. 00597 * 00598 * The group sequence of a message identifies the relative ordering of 00599 * messages within a group. The default value for the group sequence 00600 * of a message is zero. 00601 * 00602 * @param[in] msg a message object 00603 * @return the group sequence for the message 00604 */ 00605 PN_EXTERN pn_sequence_t pn_message_get_group_sequence (pn_message_t *msg); 00606 00607 /** 00608 * Set the group sequence for a message. 00609 * 00610 * See ::pn_message_get_group_sequence() for details on what the group 00611 * sequence means. 00612 * 00613 * @param[in] msg a message object 00614 * @param[in] n the new group sequence for the message 00615 * @return zero on success or an error code on failure 00616 */ 00617 PN_EXTERN int pn_message_set_group_sequence (pn_message_t *msg, pn_sequence_t n); 00618 00619 /** 00620 * Get the reply_to_group_id for a message. 00621 * 00622 * This operation will return NULL if no reply_to_group_id has been set or if 00623 * the reply_to_group_id has been set to NULL. The pointer returned by this 00624 * operation is valid until any one of the following operations occur: 00625 * 00626 * - ::pn_message_free() 00627 * - ::pn_message_clear() 00628 * - ::pn_message_set_reply_to_group_id() 00629 * 00630 * @param[in] msg a message object 00631 * @return a pointer to the reply_to_group_id of the message (or NULL) 00632 */ 00633 PN_EXTERN const char * pn_message_get_reply_to_group_id (pn_message_t *msg); 00634 00635 /** 00636 * Set the reply_to_group_id for a message. 00637 * 00638 * The supplied reply_to_group_id pointer must either be NULL or reference a NUL 00639 * terminated string. When the pointer is NULL, the reply_to_group_id is set to 00640 * NULL. When the pointer is non NULL, the contents are copied into 00641 * the message. 00642 * 00643 * @param[in] msg a message object 00644 * @param[in] reply_to_group_id a pointer to the new reply_to_group_id (or NULL) 00645 * @return zero on success or an error code on failure 00646 */ 00647 PN_EXTERN int pn_message_set_reply_to_group_id (pn_message_t *msg, const char *reply_to_group_id); 00648 00649 /** 00650 * Get/set the delivery instructions for a message. 00651 * 00652 * This operation returns a pointer to a ::pn_data_t representing the 00653 * content of the delivery instructions section of a message. The 00654 * pointer is valid until the message is freed and may be used to both 00655 * access and modify the content of the delivery instructions section 00656 * of a message. 00657 * 00658 * The ::pn_data_t must either be empty or consist of a symbol keyed 00659 * map in order to be considered valid delivery instructions. 00660 * 00661 * @param[in] msg a message object 00662 * @return a pointer to the delivery instructions 00663 */ 00664 PN_EXTERN pn_data_t *pn_message_instructions(pn_message_t *msg); 00665 00666 /** 00667 * Get/set the annotations for a message. 00668 * 00669 * This operation returns a pointer to a ::pn_data_t representing the 00670 * content of the annotations section of a message. The pointer is 00671 * valid until the message is freed and may be used to both access and 00672 * modify the content of the annotations section of a message. 00673 * 00674 * The ::pn_data_t must either be empty or consist of a symbol keyed 00675 * map in order to be considered valid message annotations. 00676 * 00677 * @param[in] msg a message object 00678 * @return a pointer to the message annotations 00679 */ 00680 PN_EXTERN pn_data_t *pn_message_annotations(pn_message_t *msg); 00681 00682 /** 00683 * Get/set the properties for a message. 00684 * 00685 * This operation returns a pointer to a ::pn_data_t representing the 00686 * content of the properties section of a message. The pointer is 00687 * valid until the message is freed and may be used to both access and 00688 * modify the content of the properties section of a message. 00689 * 00690 * The ::pn_data_t must either be empty or consist of a string keyed 00691 * map in order to be considered valid message properties. 00692 * 00693 * @param[in] msg a message object 00694 * @return a pointer to the message properties 00695 */ 00696 PN_EXTERN pn_data_t *pn_message_properties(pn_message_t *msg); 00697 00698 /** 00699 * Get/set the body of a message. 00700 * 00701 * This operation returns a pointer to a ::pn_data_t representing the 00702 * body of a message. The pointer is valid until the message is freed 00703 * and may be used to both access and modify the content of the 00704 * message body. 00705 * 00706 * @param[in] msg a message object 00707 * @return a pointer to the message body 00708 */ 00709 PN_EXTERN pn_data_t *pn_message_body(pn_message_t *msg); 00710 00711 /** 00712 * Decode/load message content from AMQP formatted binary data. 00713 * 00714 * Upon invoking this operation, any existing message content will be 00715 * cleared and replaced with the content from the provided binary 00716 * data. 00717 * 00718 * @param[in] msg a message object 00719 * @param[in] bytes the start of the encoded AMQP data 00720 * @param[in] size the size of the encoded AMQP data 00721 * @return zero on success or an error code on failure 00722 */ 00723 PN_EXTERN int pn_message_decode(pn_message_t *msg, const char *bytes, size_t size); 00724 00725 /** 00726 * Encode/save message content as AMQP formatted binary data. 00727 * 00728 * If the buffer space provided is insufficient to store the content 00729 * held in the message, the operation will fail and return a 00730 * ::PN_OVERFLOW error code. 00731 * 00732 * @param[in] msg a message object 00733 * @param[in] bytes the start of empty buffer space 00734 * @param[in] size the amount of empty buffer space 00735 * @param[out] size the amount of data written 00736 * @return zero on success or an error code on failure 00737 */ 00738 PN_EXTERN int pn_message_encode(pn_message_t *msg, char *bytes, size_t *size); 00739 00740 /** 00741 * Save message content into a pn_data_t object data. The data object will first be cleared. 00742 */ 00743 PN_EXTERN int pn_message_data(pn_message_t *msg, pn_data_t *data); 00744 00745 /** @} 00746 */ 00747 00748 #ifdef __cplusplus 00749 } 00750 #endif 00751 00752 #endif /* message.h */