Message

A mutable holder of application content. More...

Macros
#define	PN_DEFAULT_PRIORITY
	Default priority for messages.

Typedefs
typedef struct pn_message_t	pn_message_t
	An AMQP Message object.

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

Detailed Description

A mutable holder of application content.

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_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

Examples

direct.c, receive.c, and send.c.

pn_message_free()

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

Examples

direct.c, receive.c, and send.c.

pn_message_clear()

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

Examples

send.c.

pn_message_errno()

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_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

Examples

direct.c, and send.c.

pn_message_is_inferred()

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_set_inferred()

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_is_durable()

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_set_durable()

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_get_priority()

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_set_priority()

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_get_ttl()

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_set_ttl()

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_is_first_acquirer()

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_set_first_acquirer()

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_get_delivery_count()

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_set_delivery_count()

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_id()

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_get_id()

pn_msgid_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 discriminated 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_set_id()

int pn_message_set_id	(	pn_message_t *	msg,
		pn_msgid_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

Examples

direct.c, and send.c.

pn_message_get_user_id()

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_set_user_id()

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

pn_message_get_address()

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_set_address()

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_get_subject()

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_set_subject()

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_get_reply_to()

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_set_reply_to()

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_correlation_id()

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_get_correlation_id()

pn_msgid_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 discriminated 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_set_correlation_id()

int pn_message_set_correlation_id	(	pn_message_t *	msg,
		pn_msgid_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_get_content_type()

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_set_content_type()

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_get_content_encoding()

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_set_content_encoding()

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_get_expiry_time()

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_set_expiry_time()

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_get_creation_time()

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_set_creation_time()

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_get_group_id()

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_set_group_id()

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_get_group_sequence()

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_set_group_sequence()

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_get_reply_to_group_id()

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_set_reply_to_group_id()

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_instructions()

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_annotations()

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_properties()

pn_data_t * pn_message_properties

(

pn_message_t *

msg

)

Get and 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_body()

pn_data_t * pn_message_body

(

pn_message_t *

msg

)

Get and 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

Examples

direct.c, receive.c, and send.c.

pn_message_decode()

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

Examples

direct.c, and receive.c.

pn_message_encode()

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

Encode a message 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,out]	size	the amount of empty buffer space. On return size holds the amount of data written

Returns

zero on success or an error code on failure

pn_message_encode2()

ssize_t pn_message_encode2	(	pn_message_t *	msg,
		pn_rwbytes_t *	buf
	)

Unsettled API: Encode a message, allocating space if necessary

Parameters

[in]	msg	A message object.
[in,out]	buf	Used to encode msg. If buf->start == NULL memory is allocated with malloc(). If buf->size is not large enough, buffer is expanded with realloc(). On return buf holds the address and size of the final buffer. buf->size may be larger than the length of the encoded message.

Returns

The length of the encoded message or an error code (<0). On error pn_message_error(msg) will provide more information.

pn_message_send()

ssize_t pn_message_send	(	pn_message_t *	msg,
		pn_link_t *	sender,
		pn_rwbytes_t *	buf
	)

Unsettled API

Encode and send a message on a sender link.

Performs the following steps:

• call pn_message_encode2() to encode the message to a buffer
• call pn_link_send() to send the encoded message bytes
• call pn_link_advance() to indicate the message is complete

Note: you must create a delivery for the message before calling pn_message_send() see pn_delivery()

Parameters

[in]	msg	A message object.
[in]	sender	A sending link.
[in,out]	buf	See pn_message_encode2. If buf == NULL then any memory needed for encoding will be allocated and freed by pn_message_send().

Returns

The length of the encoded message or an error code (<0). On error pn_message_error(msg) will provide more information.

Examples

direct.c, and send.c.

pn_message_data()

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.