Message

## Macros

#define | PN_DEFAULT_PRIORITY (4)
| Default priority for messages. More...

## Typedefs

typedef struct pn_message_t | pn_message_t
| An AMQP Message object. More...

## Functions

PN_EXTERN pn_message_t * | pn_message (void)
| Construct a new pn_message_t. More...
PN_EXTERN void | pn_message_free (pn_message_t *msg)
| Free a previously constructed pn_message_t. More...
PN_EXTERN void | pn_message_clear (pn_message_t *msg)
| Clears the content of a pn_message_t. More...
PN_EXTERN int | pn_message_errno (pn_message_t *msg)
| Access the error code of a message. More...
PN_EXTERN pn_error_t * | pn_message_error (pn_message_t *msg)
| Access the error information for a message. More...
PN_EXTERN bool | pn_message_is_inferred (pn_message_t *msg)
| Get the inferred flag for a message. More...
PN_EXTERN int | pn_message_set_inferred (pn_message_t *msg, bool inferred)
| Set the inferred flag for a message. More...
PN_EXTERN bool | pn_message_is_durable (pn_message_t *msg)
| Get the durable flag for a message. More...
PN_EXTERN int | pn_message_set_durable (pn_message_t *msg, bool durable)
| Set the durable flag for a message. More...
PN_EXTERN uint8_t | pn_message_get_priority (pn_message_t *msg)
| Get the priority for a message. More...
PN_EXTERN int | pn_message_set_priority (pn_message_t *msg, uint8_t priority)
| Set the priority for a message. More...
PN_EXTERN pn_millis_t | pn_message_get_ttl (pn_message_t *msg)
| Get the ttl for a message. More...
PN_EXTERN int | pn_message_set_ttl (pn_message_t *msg, pn_millis_t ttl)
| Set the ttl for a message. More...
PN_EXTERN bool | pn_message_is_first_acquirer (pn_message_t *msg)
| Get the first acquirer flag for a message. More...
PN_EXTERN int | pn_message_set_first_acquirer (pn_message_t *msg, bool first)
| Set the first acquirer flag for a message. More...
PN_EXTERN uint32_t | pn_message_get_delivery_count (pn_message_t *msg)
| Get the delivery count for a message. More...
PN_EXTERN int | pn_message_set_delivery_count (pn_message_t *msg, uint32_t count)
| Set the delivery count for a message. More...
PN_EXTERN pn_data_t * | pn_message_id (pn_message_t *msg)
| Get/set the id for a message. More...
PN_EXTERN pn_atom_t | pn_message_get_id (pn_message_t *msg)
| Get the id for a message. More...
PN_EXTERN int | pn_message_set_id (pn_message_t *msg, pn_atom_t id)
| Set the id for a message. More...
PN_EXTERN pn_bytes_t | pn_message_get_user_id (pn_message_t *msg)
| Get the user id for a message. More...
PN_EXTERN int | pn_message_set_user_id (pn_message_t *msg, pn_bytes_t user_id)
| Set the user id for a message. More...
PN_EXTERN const char * | pn_message_get_address (pn_message_t *msg)
| Get the address for a message. More...
PN_EXTERN int | pn_message_set_address (pn_message_t *msg, const char *address)
| Set the address for a message. More...
PN_EXTERN const char * | pn_message_get_subject (pn_message_t *msg)
| Get the subject for a message. More...
PN_EXTERN int | pn_message_set_subject (pn_message_t *msg, const char *subject)
| Set the subject for a message. More...
PN_EXTERN const char * | pn_message_get_reply_to (pn_message_t *msg)
| Get the reply_to for a message. More...
PN_EXTERN int | pn_message_set_reply_to (pn_message_t *msg, const char *reply_to)
| Set the reply_to for a message. More...
PN_EXTERN pn_data_t * | pn_message_correlation_id (pn_message_t *msg)
| Get/set the correlation id for a message. More...
PN_EXTERN pn_atom_t | pn_message_get_correlation_id (pn_message_t *msg)
| Get the correlation id for a message. More...
PN_EXTERN int | pn_message_set_correlation_id (pn_message_t *msg, pn_atom_t id)
| Set the correlation id for a message. More...
PN_EXTERN const char * | pn_message_get_content_type (pn_message_t *msg)
| Get the content_type for a message. More...
PN_EXTERN int | pn_message_set_content_type (pn_message_t *msg, const char *type)
| Set the content_type for a message. More...
PN_EXTERN const char * | pn_message_get_content_encoding (pn_message_t *msg)
| Get the content_encoding for a message. More...
PN_EXTERN int | pn_message_set_content_encoding (pn_message_t *msg, const char *encoding)
| Set the content_encoding for a message. More...
PN_EXTERN pn_timestamp_t | pn_message_get_expiry_time (pn_message_t *msg)
| Get the expiry time for a message. More...
PN_EXTERN int | pn_message_set_expiry_time (pn_message_t *msg, pn_timestamp_t time)
| Set the expiry time for a message. More...
PN_EXTERN pn_timestamp_t | pn_message_get_creation_time (pn_message_t *msg)
| Get the creation time for a message. More...
PN_EXTERN int | pn_message_set_creation_time (pn_message_t *msg, pn_timestamp_t time)
| Set the creation time for a message. More...
PN_EXTERN const char * | pn_message_get_group_id (pn_message_t *msg)
| Get the group_id for a message. More...
PN_EXTERN int | pn_message_set_group_id (pn_message_t *msg, const char *group_id)
| Set the group_id for a message. More...
PN_EXTERN pn_sequence_t | pn_message_get_group_sequence (pn_message_t *msg)
| Get the group sequence for a message. More...
PN_EXTERN int | pn_message_set_group_sequence (pn_message_t *msg, pn_sequence_t n)
| Set the group sequence for a message. More...
PN_EXTERN const char * | pn_message_get_reply_to_group_id (pn_message_t *msg)
| Get the reply_to_group_id for a message. More...
PN_EXTERN int | pn_message_set_reply_to_group_id (pn_message_t *msg, const char *reply_to_group_id)
| Set the reply_to_group_id for a message. More...
PN_EXTERN pn_data_t * | pn_message_instructions (pn_message_t *msg)
| Get/set the delivery instructions for a message. More...
PN_EXTERN pn_data_t * | pn_message_annotations (pn_message_t *msg)
| Get/set the annotations for a message. More...
PN_EXTERN pn_data_t * | pn_message_properties (pn_message_t *msg)
| Get/set the properties for a message. More...
PN_EXTERN pn_data_t * | pn_message_body (pn_message_t *msg)
| Get/set the body of a message. More...
PN_EXTERN int | pn_message_decode (pn_message_t *msg, const char *bytes, size_t size)
| Decode/load message content from AMQP formatted binary data. More...
PN_EXTERN int | pn_message_encode (pn_message_t *msg, char *bytes, size_t *size)
| Encode/save message content as AMQP formatted binary data. More...
PN_EXTERN int | pn_message_data (pn_message_t *msg, pn_data_t *data)
| Save message content into a pn_data_t object data. More...

## Detailed Description

## Macro Definition Documentation

## PN_DEFAULT_PRIORITY

#define PN_DEFAULT_PRIORITY (4)

Default priority for messages.

## Typedef Documentation

## pn_message_t

typedef struct pn_message_t pn_message_t

An AMQP Message object.

An AMQP Message object is a mutable holder of message content that may be used to generate and encode or decode and access AMQP formatted message data.

## Function Documentation

## pn_message()

PN_EXTERN pn_message_t* pn_message | ( | void |  | ) |

Construct a new pn_message_t.

Every message that is constructed must be freed using pn_message_free().

Returns
  pointer to a new pn_message_t

## pn_message_annotations()

PN_EXTERN pn_data_t* pn_message_annotations | ( | pn_message_t * | msg | ) |

Get/set the annotations for a message.

This operation returns a pointer to a pn_data_t representing the content of the annotations section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the annotations section of a message.

The pn_data_t must either be empty or consist of a symbol keyed map in order to be considered valid message annotations.

Parameters

  [in] | msg | a message object

Returns
  a pointer to the message annotations

## pn_message_body()

PN_EXTERN pn_data_t* pn_message_body | ( | pn_message_t * | msg | ) |

Get/set the body of a message.

This operation returns a pointer to a pn_data_t representing the body of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the message body.

Parameters

  [in] | msg | a message object

Returns
  a pointer to the message body

## pn_message_clear()

PN_EXTERN void pn_message_clear | ( | pn_message_t * | msg | ) |

Clears the content of a pn_message_t.

When pn_message_clear returns, the supplied pn_message_t will be emptied of all content and effectively returned to the same state as if it was just created.

Parameters

  [in] | msg | pointer to the pn_message_t to be cleared

## pn_message_correlation_id()

PN_EXTERN pn_data_t* pn_message_correlation_id | ( | pn_message_t * | msg | ) |

Get/set the correlation id for a message.

A correlation id can be an a string, an unsigned long, a uuid or a binary value. This operation returns a pointer to a pn_data_t that can be used to access and/or modify the value of the correlation id. The pointer is valid until the message is freed. See pn_data_t for details on how to get/set the value.

Parameters

  [in] | msg | a message object

Returns
  pointer to a pn_data_t holding the correlation id

## pn_message_data()

PN_EXTERN int pn_message_data | ( | pn_message_t * | msg,
|  | pn_data_t * | data
| ) |  |

Save message content into a pn_data_t object data.

The data object will first be cleared.

## pn_message_decode()

PN_EXTERN int pn_message_decode | ( | pn_message_t * | msg,
|  | const char * | bytes,
|  | size_t | size
| ) |  |

Decode/load message content from AMQP formatted binary data.

Upon invoking this operation, any existing message content will be cleared and replaced with the content from the provided binary data.

Parameters

  [in] | msg | a message object
  [in] | bytes | the start of the encoded AMQP data
  [in] | size | the size of the encoded AMQP data

Returns
  zero on success or an error code on failure

## pn_message_encode()

PN_EXTERN int pn_message_encode | ( | pn_message_t * | msg,
|  | char * | bytes,
|  | size_t * | size
| ) |  |

Encode/save message content as AMQP formatted binary data.

If the buffer space provided is insufficient to store the content held in the message, the operation will fail and return a PN_OVERFLOW error code.

Parameters

  [in] | msg | a message object
  [in] | bytes | the start of empty buffer space
  [in] | size | the amount of empty buffer space
  [out] | size | the amount of data written

Returns
  zero on success or an error code on failure

## pn_message_errno()

PN_EXTERN int pn_message_errno | ( | pn_message_t * | msg | ) |

Access the error code of a message.

Every operation on a message that can result in an error will set the message's error code in case of error. The pn_message_errno() call will access the error code of the most recent failed operation.

Parameters

  [in] | msg | a message

Returns
  the message's error code

## pn_message_error()

PN_EXTERN pn_error_t* pn_message_error | ( | pn_message_t * | msg | ) |

Access the error information for a message.

Every operation on a message that can result in an error will update the error information held by its error descriptor should that operation fail. The pn_message_error() call will access the error information of the most recent failed operation. The pointer returned by this call is valid until the message is freed.

Parameters

  [in] | msg | a message

Returns
  the message's error descriptor

## pn_message_free()

PN_EXTERN void pn_message_free | ( | pn_message_t * | msg | ) |

Free a previously constructed pn_message_t.

Parameters

  [in] | msg | pointer to a pn_message_t or NULL

## pn_message_get_address()

PN_EXTERN const char* pn_message_get_address | ( | pn_message_t * | msg | ) |

Get the address for a message.

This operation will return NULL if no address has been set or if the address has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_address()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the address of the message (or NULL)

## pn_message_get_content_encoding()

PN_EXTERN const char* pn_message_get_content_encoding | ( | pn_message_t * | msg | ) |

Get the content_encoding for a message.

This operation will return NULL if no content_encoding has been set or if the content_encoding has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_content_encoding()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the content_encoding of the message (or NULL)

## pn_message_get_content_type()

PN_EXTERN const char* pn_message_get_content_type | ( | pn_message_t * | msg | ) |

Get the content_type for a message.

This operation will return NULL if no content_type has been set or if the content_type has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_content_type()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the content_type of the message (or NULL)

## pn_message_get_correlation_id()

PN_EXTERN pn_atom_t pn_message_get_correlation_id | ( | pn_message_t * | msg | ) |

Get the correlation id for a message.

A correlation id can be an a string, an unsigned long, a uuid or a binary value. This operation returns the value of the id using the pn_atom_t descriminated union. See pn_atom_t for details on how to access the value.

Parameters

  [in] | msg | a message object

Returns
  the message id

## pn_message_get_creation_time()

PN_EXTERN pn_timestamp_t pn_message_get_creation_time | ( | pn_message_t * | msg | ) |

Get the creation time for a message.

A zero value for the creation time indicates that the creation time has not been set. This is the default value.

Parameters

  [in] | msg | a message object

Returns
  the creation time for the message

## pn_message_get_delivery_count()

PN_EXTERN uint32_t pn_message_get_delivery_count | ( | pn_message_t * | msg | ) |

Get the delivery count for a message.

The delivery count field tracks how many attempts have been made to delivery a message. Use pn_message_set_delivery_count() to set the delivery count for a message.

Parameters

  [in] | msg | a message object

Returns
  the delivery count for the message

## pn_message_get_expiry_time()

PN_EXTERN pn_timestamp_t pn_message_get_expiry_time | ( | pn_message_t * | msg | ) |

Get the expiry time for a message.

A zero value for the expiry time indicates that the message will never expire. This is the default value.

Parameters

  [in] | msg | a message object

Returns
  the expiry time for the message

## pn_message_get_group_id()

PN_EXTERN const char* pn_message_get_group_id | ( | pn_message_t * | msg | ) |

Get the group_id for a message.

This operation will return NULL if no group_id has been set or if the group_id has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_group_id()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the group_id of the message (or NULL)

## pn_message_get_group_sequence()

PN_EXTERN pn_sequence_t pn_message_get_group_sequence | ( | pn_message_t * | msg | ) |

Get the group sequence for a message.

The group sequence of a message identifies the relative ordering of messages within a group. The default value for the group sequence of a message is zero.

Parameters

  [in] | msg | a message object

Returns
  the group sequence for the message

## pn_message_get_id()

PN_EXTERN pn_atom_t pn_message_get_id | ( | pn_message_t * | msg | ) |

Get the id for a message.

The message id provides a globally unique identifier for a message. A message id can be an a string, an unsigned long, a uuid or a binary value. This operation returns the value of the id using the pn_atom_t descriminated union. See pn_atom_t for details on how to access the value.

Parameters

  [in] | msg | a message object

Returns
  the message id

## pn_message_get_priority()

PN_EXTERN uint8_t pn_message_get_priority | ( | pn_message_t * | msg | ) |

Get the priority for a message.

The priority of a message impacts ordering guarantees. Within a given ordered context, higher priority messages may jump ahead of lower priority messages.

Parameters

  [in] | msg | a message object

Returns
  the message priority

## pn_message_get_reply_to()

PN_EXTERN const char* pn_message_get_reply_to | ( | pn_message_t * | msg | ) |

Get the reply_to for a message.

This operation will return NULL if no reply_to has been set or if the reply_to has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_reply_to()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the reply_to of the message (or NULL)

## pn_message_get_reply_to_group_id()

PN_EXTERN const char* pn_message_get_reply_to_group_id | ( | pn_message_t * | msg | ) |

Get the reply_to_group_id for a message.

This operation will return NULL if no reply_to_group_id has been set or if the reply_to_group_id has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_reply_to_group_id()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the reply_to_group_id of the message (or NULL)

## pn_message_get_subject()

PN_EXTERN const char* pn_message_get_subject | ( | pn_message_t * | msg | ) |

Get the subject for a message.

This operation will return NULL if no subject has been set or if the subject has been set to NULL. The pointer returned by this operation is valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_subject()

Parameters

  [in] | msg | a message object

Returns
  a pointer to the subject of the message (or NULL)

## pn_message_get_ttl()

PN_EXTERN pn_millis_t pn_message_get_ttl | ( | pn_message_t * | msg | ) |

Get the ttl for a message.

The ttl for a message determines how long a message is considered live. When a message is held for retransmit, the ttl is decremented. Once the ttl reaches zero, the message is considered dead. Once a message is considered dead it may be dropped. Use pn_message_set_ttl() to set the ttl for a message.

Parameters

  [in] | msg | a message object

Returns
  the ttl in milliseconds

## pn_message_get_user_id()

PN_EXTERN pn_bytes_t pn_message_get_user_id | ( | pn_message_t * | msg | ) |

Get the user id for a message.

The pointer referenced by the pn_bytes_t struct will be valid until any one of the following operations occur:

- pn_message_free()
- pn_message_clear()
- pn_message_set_user_id()

Parameters

  [in] | msg | a message object

Returns
  a pn_bytes_t referencing the message's user_id

## pn_message_id()

PN_EXTERN pn_data_t* pn_message_id | ( | pn_message_t * | msg | ) |

Get/set the id for a message.

The message id provides a globally unique identifier for a message. A message id can be an a string, an unsigned long, a uuid or a binary value. This operation returns a pointer to a pn_data_t that can be used to access and/or modify the value of the message id. The pointer is valid until the message is freed. See pn_data_t for details on how to get/set the value.

Parameters

  [in] | msg | a message object

Returns
  pointer to a pn_data_t holding the id

## pn_message_instructions()

PN_EXTERN pn_data_t* pn_message_instructions | ( | pn_message_t * | msg | ) |

Get/set the delivery instructions for a message.

This operation returns a pointer to a pn_data_t representing the content of the delivery instructions section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the delivery instructions section of a message.

The pn_data_t must either be empty or consist of a symbol keyed map in order to be considered valid delivery instructions.

Parameters

  [in] | msg | a message object

Returns
  a pointer to the delivery instructions

## pn_message_is_durable()

PN_EXTERN bool pn_message_is_durable | ( | pn_message_t * | msg | ) |

Get the durable flag for a message.

The durable flag indicates that any parties taking responsibility for the message must durably store the content.

Parameters

  [in] | msg | a message object

Returns
  the value of the durable flag

## pn_message_is_first_acquirer()

PN_EXTERN bool pn_message_is_first_acquirer | ( | pn_message_t * | msg | ) |

Get the first acquirer flag for a message.

When set to true, the first acquirer flag for a message indicates that the recipient of the message is the first recipient to acquire the message, i.e. there have been no failed delivery attempts to other acquirers. Note that this does not mean the message has not been delivered to, but not acquired, by other recipients.

Parameters

  [in] | msg | a message object

Returns
  the first acquirer flag for the message

## pn_message_is_inferred()

PN_EXTERN bool pn_message_is_inferred | ( | pn_message_t * | msg | ) |

Get the inferred flag for a message.

The inferred flag for a message indicates how the message content is encoded into AMQP sections. If inferred is true then binary and list values in the body of the message will be encoded as AMQP DATA and AMQP SEQUENCE sections, respectively. If inferred is false, then all values in the body of the message will be encoded as AMQP VALUE sections regardless of their type. Use pn_message_set_inferred to set the value.

Parameters

  [in] | msg | a message object

Returns
  the value of the inferred flag for the message

## pn_message_properties()

PN_EXTERN pn_data_t* pn_message_properties | ( | pn_message_t * | msg | ) |

Get/set the properties for a message.

This operation returns a pointer to a pn_data_t representing the content of the properties section of a message. The pointer is valid until the message is freed and may be used to both access and modify the content of the properties section of a message.

The pn_data_t must either be empty or consist of a string keyed map in order to be considered valid message properties.

Parameters

  [in] | msg | a message object

Returns
  a pointer to the message properties

## pn_message_set_address()

PN_EXTERN int pn_message_set_address | ( | pn_message_t * | msg,
|  | const char * | address
| ) |  |

Set the address for a message.

The supplied address pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the address of the message is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | address | a pointer to the new address (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_content_encoding()

PN_EXTERN int pn_message_set_content_encoding | ( | pn_message_t * | msg,
|  | const char * | encoding
| ) |  |

Set the content_encoding for a message.

The supplied content_encoding pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the content_encoding is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | encoding | a pointer to the new content_encoding (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_content_type()

PN_EXTERN int pn_message_set_content_type | ( | pn_message_t * | msg,
|  | const char * | type
| ) |  |

Set the content_type for a message.

The supplied content_type pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the content_type is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | type | a pointer to the new content_type (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_correlation_id()

PN_EXTERN int pn_message_set_correlation_id | ( | pn_message_t * | msg,
|  | pn_atom_t | id
| ) |  |

Set the correlation id for a message.

See pn_message_get_correlation_id() for more details on the meaning of the correlation id. Note that only string, unsigned long, uuid, or binary values are permitted.

Parameters

  [in] | msg | a message object
  [in] | id | the new value of the message id

Returns
  zero on success or an error code on failure

## pn_message_set_creation_time()

PN_EXTERN int pn_message_set_creation_time | ( | pn_message_t * | msg,
|  | pn_timestamp_t | time
| ) |  |

Set the creation time for a message.

See pn_message_get_creation_time() for more details.

Parameters

  [in] | msg | a message object
  [in] | time | the new creation time for the message

Returns
  zero on success or an error code on failure

## pn_message_set_delivery_count()

PN_EXTERN int pn_message_set_delivery_count | ( | pn_message_t * | msg,
|  | uint32_t | count
| ) |  |

Set the delivery count for a message.

See pn_message_get_delivery_count() for details on what the delivery count means.

Parameters

  [in] | msg | a message object
  [in] | count | the new delivery count

Returns
  zero on success or an error code on failure

## pn_message_set_durable()

PN_EXTERN int pn_message_set_durable | ( | pn_message_t * | msg,
|  | bool | durable
| ) |  |

Set the durable flag for a message.

See pn_message_is_durable() for a description of the durable flag.

Parameters

  [in] | msg | a message object
  [in] | durable | the new value of the durable flag

Returns
  zero on success or an error code on failure

## pn_message_set_expiry_time()

PN_EXTERN int pn_message_set_expiry_time | ( | pn_message_t * | msg,
|  | pn_timestamp_t | time
| ) |  |

Set the expiry time for a message.

See pn_message_get_expiry_time() for more details.

Parameters

  [in] | msg | a message object
  [in] | time | the new expiry time for the message

Returns
  zero on success or an error code on failure

## pn_message_set_first_acquirer()

PN_EXTERN int pn_message_set_first_acquirer | ( | pn_message_t * | msg,
|  | bool | first
| ) |  |

Set the first acquirer flag for a message.

See pn_message_is_first_acquirer() for details on the first acquirer flag.

Parameters

  [in] | msg | a message object
  [in] | first | the new value for the first acquirer flag

Returns
  zero on success or an error code on failure

## pn_message_set_group_id()

PN_EXTERN int pn_message_set_group_id | ( | pn_message_t * | msg,
|  | const char * | group_id
| ) |  |

Set the group_id for a message.

The supplied group_id pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the group_id is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | group_id | a pointer to the new group_id (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_group_sequence()

PN_EXTERN int pn_message_set_group_sequence | ( | pn_message_t * | msg,
|  | pn_sequence_t | n
| ) |  |

Set the group sequence for a message.

See pn_message_get_group_sequence() for details on what the group sequence means.

Parameters

  [in] | msg | a message object
  [in] | n | the new group sequence for the message

Returns
  zero on success or an error code on failure

## pn_message_set_id()

PN_EXTERN int pn_message_set_id | ( | pn_message_t * | msg,
|  | pn_atom_t | id
| ) |  |

Set the id for a message.

See pn_message_get_id() for more details on the meaning of the message id. Note that only string, unsigned long, uuid, or binary values are permitted.

Parameters

  [in] | msg | a message object
  [in] | id | the new value of the message id

Returns
  zero on success or an error code on failure

## pn_message_set_inferred()

PN_EXTERN int pn_message_set_inferred | ( | pn_message_t * | msg,
|  | bool | inferred
| ) |  |

Set the inferred flag for a message.

See pn_message_is_inferred() for a description of what the inferred flag is.

Parameters

  [in] | msg | a message object
  [in] | inferred | the new value of the inferred flag

Returns
  zero on success or an error code on failure

## pn_message_set_priority()

PN_EXTERN int pn_message_set_priority | ( | pn_message_t * | msg,
|  | uint8_t | priority
| ) |  |

Set the priority for a message.

See pn_message_get_priority() for details on message priority.

Parameters

  [in] | msg | a message object
  [in] | priority | the new priority for the message

Returns
  zero on success or an error code on failure

## pn_message_set_reply_to()

PN_EXTERN int pn_message_set_reply_to | ( | pn_message_t * | msg,
|  | const char * | reply_to
| ) |  |

Set the reply_to for a message.

The supplied reply_to pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the reply_to is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | reply_to | a pointer to the new reply_to (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_reply_to_group_id()

PN_EXTERN int pn_message_set_reply_to_group_id | ( | pn_message_t * | msg,
|  | const char * | reply_to_group_id
| ) |  |

Set the reply_to_group_id for a message.

The supplied reply_to_group_id pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the reply_to_group_id is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | reply_to_group_id | a pointer to the new reply_to_group_id (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_subject()

PN_EXTERN int pn_message_set_subject | ( | pn_message_t * | msg,
|  | const char * | subject
| ) |  |

Set the subject for a message.

The supplied subject pointer must either be NULL or reference a NUL terminated string. When the pointer is NULL, the subject is set to NULL. When the pointer is non NULL, the contents are copied into the message.

Parameters

  [in] | msg | a message object
  [in] | subject | a pointer to the new subject (or NULL)

Returns
  zero on success or an error code on failure

## pn_message_set_ttl()

PN_EXTERN int pn_message_set_ttl | ( | pn_message_t * | msg,
|  | pn_millis_t | ttl
| ) |  |

Set the ttl for a message.

See pn_message_get_ttl() for a detailed description of message ttl.

Parameters

  [in] | msg | a message object
  [in] | ttl | the new value for the message ttl

Returns
  zero on success or an error code on failure

## pn_message_set_user_id()

PN_EXTERN int pn_message_set_user_id | ( | pn_message_t * | msg,
|  | pn_bytes_t | user_id
| ) |  |

Set the user id for a message.

This operation copies the bytes referenced by the provided pn_bytes_t struct.

Parameters

  [in] | msg | a message object
  [in] | user_id | the new user_id for the message

Returns
  zero on success or an error code on failure