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