Qpid Proton C API  0.37.0
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. More...
 

Functions

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

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]msgpointer 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]msgpointer 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]msga 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]msga 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]msga 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]msga message object
[in]inferredthe 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]msga 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]msga message object
[in]durablethe 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]msga 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]msga message object
[in]prioritythe 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]msga 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]msga message object
[in]ttlthe 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]msga 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]msga message object
[in]firstthe 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]msga 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]msga message object
[in]countthe 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]msga 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]msga 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]msga message object
[in]idthe 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:

Parameters
[in]msga 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]msga message object
[in]user_idthe 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:

Parameters
[in]msga 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]msga message object
[in]addressa 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:

Parameters
[in]msga 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]msga message object
[in]subjecta 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:

Parameters
[in]msga 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]msga message object
[in]reply_toa 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]msga 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]msga 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]msga message object
[in]idthe 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:

Parameters
[in]msga 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]msga message object
[in]typea 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:

Parameters
[in]msga 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]msga message object
[in]encodinga 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]msga 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]msga message object
[in]timethe 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]msga 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]msga message object
[in]timethe 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:

Parameters
[in]msga 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]msga message object
[in]group_ida 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]msga 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]msga message object
[in]nthe 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:

Parameters
[in]msga 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]msga message object
[in]reply_to_group_ida 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]msga 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]msga 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]msga 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]msga 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]msga message object
[in]bytesthe start of the encoded AMQP data
[in]sizethe 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]msga message object
[in]bytesthe start of empty buffer space
[in,out]sizethe 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]msgA message object.
[in,out]bufUsed 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:

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

Parameters
[in]msgA message object.
[in]senderA sending link.
[in,out]bufSee 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.