Qpid Proton C API  0.33.0
Messenger

Deprecated - Use the Proactor API or Qpid Proton C++. More...

Macros

#define PN_CUMULATIVE
 Indicates that an accept or reject should operate cumulatively.
 
#define PN_FLAGS_CHECK_ROUTES
 Messenger flag to indicate that a call \ to pn_messenger_start should check that \ any defined routes are valid.
 
#define PN_FLAGS_ALLOW_INSECURE_MECHS
 Messenger flag to indicate that the PLAIN \ mechanism is allowed on an unencrypted \ connection.
 

Typedefs

typedef struct pn_messenger_t pn_messenger_t
 A pn_messenger_t provides a high level interface for sending and receiving messages (See pn_message_t). More...
 
typedef struct pn_subscription_t pn_subscription_t
 A subscription is a request for incoming messages.
 
typedef int64_t pn_tracker_t
 Trackers provide a lightweight handle used to track the status of incoming and outgoing deliveries.
 

Enumerations

enum  pn_status_t {
  PN_STATUS_UNKNOWN, PN_STATUS_PENDING, PN_STATUS_ACCEPTED, PN_STATUS_REJECTED,
  PN_STATUS_RELEASED, PN_STATUS_MODIFIED, PN_STATUS_ABORTED, PN_STATUS_SETTLED
}
 Describes all the possible states for a message associated with a given tracker. More...
 

Functions

pn_messenger_tpn_messenger (const char *name)
 Construct a new pn_messenger_t with the given name. More...
 
const char * pn_messenger_name (pn_messenger_t *messenger)
 Get the name of a messenger. More...
 
int pn_messenger_set_certificate (pn_messenger_t *messenger, const char *certificate)
 Sets the path that will be used to get the certificate that will be used to identify this messenger to its peers. More...
 
const char * pn_messenger_get_certificate (pn_messenger_t *messenger)
 Get the certificate path. More...
 
int pn_messenger_set_private_key (pn_messenger_t *messenger, const char *private_key)
 Set path to the private key that was used to sign the certificate. More...
 
const char * pn_messenger_get_private_key (pn_messenger_t *messenger)
 Gets the private key file for a messenger. More...
 
int pn_messenger_set_password (pn_messenger_t *messenger, const char *password)
 Sets the private key password for a messenger. More...
 
const char * pn_messenger_get_password (pn_messenger_t *messenger)
 Gets the private key file password for a messenger. More...
 
int pn_messenger_set_trusted_certificates (pn_messenger_t *messenger, const char *cert_db)
 Sets the trusted certificates database for a messenger. More...
 
const char * pn_messenger_get_trusted_certificates (pn_messenger_t *messenger)
 Gets the trusted certificates database for a messenger. More...
 
int pn_messenger_set_timeout (pn_messenger_t *messenger, int timeout)
 Set the default timeout for a messenger. More...
 
int pn_messenger_get_timeout (pn_messenger_t *messenger)
 Gets the timeout for a messenger object. More...
 
bool pn_messenger_is_blocking (pn_messenger_t *messenger)
 Check if a messenger is in blocking mode. More...
 
int pn_messenger_set_blocking (pn_messenger_t *messenger, bool blocking)
 Enable or disable blocking behavior for a messenger during calls to pn_messenger_send and pn_messenger_recv. More...
 
bool pn_messenger_is_passive (pn_messenger_t *messenger)
 Check if a messenger is in passive mode. More...
 
int pn_messenger_set_passive (pn_messenger_t *messenger, bool passive)
 Set the passive mode for a messenger. More...
 
void pn_messenger_free (pn_messenger_t *messenger)
 Frees a Messenger. More...
 
int pn_messenger_errno (pn_messenger_t *messenger)
 Get the code for a messenger's most recent error. More...
 
pn_error_tpn_messenger_error (pn_messenger_t *messenger)
 Get a messenger's error object. More...
 
int pn_messenger_get_outgoing_window (pn_messenger_t *messenger)
 Get the size of a messenger's outgoing window. More...
 
int pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window)
 Set the size of a messenger's outgoing window. More...
 
int pn_messenger_get_incoming_window (pn_messenger_t *messenger)
 Get the size of a messenger's incoming window. More...
 
int pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window)
 Set the size of a messenger's incoming window. More...
 
int pn_messenger_start (pn_messenger_t *messenger)
 Currently a no-op placeholder. More...
 
int pn_messenger_stop (pn_messenger_t *messenger)
 Stops a messenger. More...
 
bool pn_messenger_stopped (pn_messenger_t *messenger)
 Returns true if a messenger is in the stopped state. More...
 
pn_subscription_tpn_messenger_subscribe (pn_messenger_t *messenger, const char *source)
 Subscribes a messenger to messages from the specified source. More...
 
pn_subscription_tpn_messenger_subscribe_ttl (pn_messenger_t *messenger, const char *source, pn_seconds_t timeout)
 Subscribes a messenger to messages from the specified source with the given timeout for the subscription's lifetime. More...
 
pn_link_tpn_messenger_get_link (pn_messenger_t *messenger, const char *address, bool sender)
 Get a link based on link name and whether the link is a sender or receiver. More...
 
void * pn_subscription_get_context (pn_subscription_t *sub)
 Get a subscription's application context. More...
 
void pn_subscription_set_context (pn_subscription_t *sub, void *context)
 Set an application context for a subscription. More...
 
const char * pn_subscription_address (pn_subscription_t *sub)
 Get the source address of a subscription. More...
 
int pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg)
 Puts a message onto the messenger's outgoing queue. More...
 
pn_status_t pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker)
 Track the status of a delivery. More...
 
pn_delivery_tpn_messenger_delivery (pn_messenger_t *messenger, pn_tracker_t tracker)
 Get delivery information about a delivery. More...
 
bool pn_messenger_buffered (pn_messenger_t *messenger, pn_tracker_t tracker)
 Check if the delivery associated with a given tracker is still waiting to be sent. More...
 
int pn_messenger_settle (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 Frees a Messenger from tracking the status associated with a given tracker. More...
 
pn_tracker_t pn_messenger_outgoing_tracker (pn_messenger_t *messenger)
 Get a tracker for the outgoing message most recently given to pn_messenger_put. More...
 
int pn_messenger_work (pn_messenger_t *messenger, int timeout)
 Sends or receives any outstanding messages queued for a messenger. More...
 
int pn_messenger_interrupt (pn_messenger_t *messenger)
 Interrupt a messenger object that may be blocking in another thread. More...
 
int pn_messenger_send (pn_messenger_t *messenger, int n)
 Send messages from a messenger's outgoing queue. More...
 
int pn_messenger_recv (pn_messenger_t *messenger, int limit)
 Retrieve messages into a messenger's incoming queue. More...
 
int pn_messenger_receiving (pn_messenger_t *messenger)
 Get the capacity of the incoming message queue of a messenger. More...
 
int pn_messenger_get (pn_messenger_t *messenger, pn_message_t *message)
 Get the next message from the head of a messenger's incoming queue. More...
 
pn_tracker_t pn_messenger_incoming_tracker (pn_messenger_t *messenger)
 Get a tracker for the message most recently retrieved by pn_messenger_get(). More...
 
pn_subscription_tpn_messenger_incoming_subscription (pn_messenger_t *messenger)
 Get the subscription of the message most recently retrieved by pn_messenger_get(). More...
 
int pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 Signal successful processing of message(s). More...
 
int pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 Signal unsuccessful processing of message(s). More...
 
pn_link_tpn_messenger_tracker_link (pn_messenger_t *messenger, pn_tracker_t tracker)
 Get link for the message referenced by the given tracker. More...
 
int pn_messenger_outgoing (pn_messenger_t *messenger)
 Get the number of messages in the outgoing message queue of a messenger. More...
 
int pn_messenger_incoming (pn_messenger_t *messenger)
 Get the number of messages in the incoming message queue of a messenger. More...
 
int pn_messenger_route (pn_messenger_t *messenger, const char *pattern, const char *address)
 Adds a routing rule to a Messenger's internal routing table. More...
 
int pn_messenger_rewrite (pn_messenger_t *messenger, const char *pattern, const char *address)
 Rewrite message addresses prior to transmission. More...
 
pn_selectable_t * pn_messenger_selectable (pn_messenger_t *messenger)
 Extract selectables from a passive messenger. More...
 
pn_timestamp_t pn_messenger_deadline (pn_messenger_t *messenger)
 Get the nearest deadline for selectables associated with a messenger. More...
 
int pn_messenger_set_flags (pn_messenger_t *messenger, const int flags)
 Sets control flags to enable additional function for the Messenger. More...
 
int pn_messenger_get_flags (pn_messenger_t *messenger)
 Gets the flags for a Messenger. More...
 
int pn_messenger_set_snd_settle_mode (pn_messenger_t *messenger, const pn_snd_settle_mode_t mode)
 Set the local sender settle mode for the underlying link. More...
 
int pn_messenger_set_rcv_settle_mode (pn_messenger_t *messenger, const pn_rcv_settle_mode_t mode)
 Set the local receiver settle mode for the underlying link. More...
 
void pn_messenger_set_tracer (pn_messenger_t *messenger, pn_tracer_t tracer)
 Set the tracer associated with a messenger. More...
 
pn_millis_t pn_messenger_get_remote_idle_timeout (pn_messenger_t *messenger, const char *address)
 Gets the remote idle timeout for the specified remote service address. More...
 
int pn_messenger_set_ssl_peer_authentication_mode (pn_messenger_t *messenger, const pn_ssl_verify_mode_t mode)
 Sets the SSL peer authentication mode required when a trust certificate is used. More...
 

Detailed Description

Deprecated - Use the Proactor API or Qpid Proton C++.

Typedef Documentation

◆ pn_messenger_t

A pn_messenger_t provides a high level interface for sending and receiving messages (See pn_message_t).

Every messenger contains a single logical queue of incoming messages and a single logical queue of outgoing messages. The messages in these queues may be destined for, or originate from, a variety of addresses.

The messenger interface is single-threaded. All methods except one (pn_messenger_interrupt()) are intended to be used by one thread at a time.

Address Syntax

An address has the following form::

[ amqp[s]:// ] [user[:password]@] domain [/[name]]

Where domain can be one of::

host | host:port | ip | ip:port | name

The following are valid examples of addresses:

Sending & Receiving Messages

The messenger API works in conjunction with the pn_message_t API. A pn_message_t is a mutable holder of message content.

The pn_messenger_put() operation copies content from the supplied pn_message_t to the outgoing queue, and may send queued messages if it can do so without blocking. The pn_messenger_send() operation blocks until it has sent the requested number of messages, or until a timeout interrupts the attempt.

pn_messenger_t *messenger = pn_messenger(NULL); pn_message_t *message = pn_message(); char subject[1024]; for (int i = 0; i < 3; i++) { pn_message_set_address(message, "amqp://host/queue"); sprintf(subject, "Hello World! %i", i); pn_message_set_subject(message, subject); pn_messenger_put(messenger, message) pn_messenger_send(messenger);

Similarly, the pn_messenger_recv() method receives messages into the incoming queue, and may block as it attempts to receive up to the requested number of messages, or until the timeout is reached. It may receive fewer than the requested number. The pn_messenger_get() method pops the eldest message off the incoming queue and copies its content into the supplied pn_message_t object. It will not block.

pn_messenger_t *messenger = pn_messenger(NULL); pn_message_t *message = pn_message() pn_messenger_recv(messenger): while (pn_messenger_incoming(messenger) > 0) { pn_messenger_get(messenger, message); printf("%s", message.subject); }

Output: Hello World 0 Hello World 1 Hello World 2

The blocking flag allows you to turn off blocking behavior entirely, in which case pn_messenger_send() and pn_messenger_recv() will do whatever they can without blocking, and then return. You can then look at the number of incoming and outgoing messages to see how much outstanding work still remains.

Authentication Mechanisms

The messenger API authenticates using some specific mechanisms. In prior versions of Proton the only authentication mechanism available was the PLAIN mechanism which transports the user's password over the network unencrypted. The Proton versions 0.10 and newer support other more secure mechanisms which avoid sending the users's password over the network unencrypted. For backwards compatibility the 0.10 version of the messenger API will also allow the use of the unencrypted PLAIN mechanism. From the 0.11 version and onwards you will need to set the flag PN_FLAGS_ALLOW_INSECURE_MECHS to carry on using the unencrypted PLAIN mechanism.

The code for this looks like:

... pn_messenger_set_flags(messenger, PN_FLAGS_ALLOW_INSECURE_MECHS); ...

Note that the use of the PLAIN mechanism over an SSL connection is allowed as the password is not sent unencrypted.

Enumeration Type Documentation

◆ pn_status_t

Describes all the possible states for a message associated with a given tracker.

Enumerator
PN_STATUS_UNKNOWN 

The tracker is unknown.

PN_STATUS_PENDING 

The message is in flight.

For outgoing messages, use pn_messenger_buffered to see if it has been sent or not.

PN_STATUS_ACCEPTED 

The message was accepted.

PN_STATUS_REJECTED 

The message was rejected.

PN_STATUS_RELEASED 

The message was released.

PN_STATUS_MODIFIED 

The message was modified.

PN_STATUS_ABORTED 

The message was aborted.

PN_STATUS_SETTLED 

The remote party has settled the message.

Function Documentation

◆ pn_messenger()

pn_messenger_t* pn_messenger ( const char *  name)

Construct a new pn_messenger_t with the given name.

The name is global. If a NULL name is supplied, a UUID based name will be chosen.

Parameters
[in]namethe name of the messenger or NULL
Returns
pointer to a new pn_messenger_t

◆ pn_messenger_name()

const char* pn_messenger_name ( pn_messenger_t messenger)

Get the name of a messenger.

Parameters
[in]messengera messenger object
Returns
the name of the messenger

◆ pn_messenger_set_certificate()

int pn_messenger_set_certificate ( pn_messenger_t messenger,
const char *  certificate 
)

Sets the path that will be used to get the certificate that will be used to identify this messenger to its peers.

The validity of the path is not checked by this function.

Parameters
[in]messengerthe messenger
[in]certificatea path to a certificate file
Returns
an error code of zero if there is no error

◆ pn_messenger_get_certificate()

const char* pn_messenger_get_certificate ( pn_messenger_t messenger)

Get the certificate path.

This value may be set by pn_messenger_set_certificate. The default certificate path is null.

Parameters
[in]messengerthe messenger
Returns
the certificate file path

◆ pn_messenger_set_private_key()

int pn_messenger_set_private_key ( pn_messenger_t messenger,
const char *  private_key 
)

Set path to the private key that was used to sign the certificate.

See pn_messenger_set_certificate

Parameters
[in]messengera messenger object
[in]private_keya path to a private key file
Returns
an error code of zero if there is no error

◆ pn_messenger_get_private_key()

const char* pn_messenger_get_private_key ( pn_messenger_t messenger)

Gets the private key file for a messenger.

Parameters
[in]messengera messenger object
Returns
the messenger's private key file path

◆ pn_messenger_set_password()

int pn_messenger_set_password ( pn_messenger_t messenger,
const char *  password 
)

Sets the private key password for a messenger.

Parameters
[in]messengera messenger object
[in]passwordthe password for the private key file
Returns
an error code of zero if there is no error

◆ pn_messenger_get_password()

const char* pn_messenger_get_password ( pn_messenger_t messenger)

Gets the private key file password for a messenger.

Parameters
[in]messengera messenger object
Returns
password for the private key file

◆ pn_messenger_set_trusted_certificates()

int pn_messenger_set_trusted_certificates ( pn_messenger_t messenger,
const char *  cert_db 
)

Sets the trusted certificates database for a messenger.

The messenger will use this database to validate the certificate provided by the peer.

Parameters
[in]messengera messenger object
[in]cert_dba path to the certificates database
Returns
an error code of zero if there is no error

◆ pn_messenger_get_trusted_certificates()

const char* pn_messenger_get_trusted_certificates ( pn_messenger_t messenger)

Gets the trusted certificates database for a messenger.

Parameters
[in]messengera messenger object
Returns
path to the trusted certificates database

◆ pn_messenger_set_timeout()

int pn_messenger_set_timeout ( pn_messenger_t messenger,
int  timeout 
)

Set the default timeout for a messenger.

Any messenger call that blocks during execution will stop blocking and return control when this timeout is reached, if you have set it to a value greater than zero. The timeout is expressed in milliseconds.

Parameters
[in]messengera messenger object
[in]timeouta new timeout for the messenger, in milliseconds
Returns
an error code or zero if there is no error

◆ pn_messenger_get_timeout()

int pn_messenger_get_timeout ( pn_messenger_t messenger)

Gets the timeout for a messenger object.

See pn_messenger_set_timeout() for details.

Parameters
[in]messengera messenger object
Returns
the timeout for the messenger, in milliseconds

◆ pn_messenger_is_blocking()

bool pn_messenger_is_blocking ( pn_messenger_t messenger)

Check if a messenger is in blocking mode.

Parameters
[in]messengera messenger object
Returns
true if blocking has been enabled, false otherwise

◆ pn_messenger_set_blocking()

int pn_messenger_set_blocking ( pn_messenger_t messenger,
bool  blocking 
)

Enable or disable blocking behavior for a messenger during calls to pn_messenger_send and pn_messenger_recv.

Parameters
[in]messengera messenger object
[in]blockingthe value of the blocking flag
Returns
an error code or zero if there is no error

◆ pn_messenger_is_passive()

bool pn_messenger_is_passive ( pn_messenger_t messenger)

Check if a messenger is in passive mode.

A messenger that is in passive mode will never attempt to perform I/O internally, but instead will make all internal file descriptors accessible through pn_messenger_selectable() to be serviced externally. This can be useful for integrating messenger into an external event loop.

Parameters
[in]messengera messenger object
Returns
true if the messenger is in passive mode, false otherwise

◆ pn_messenger_set_passive()

int pn_messenger_set_passive ( pn_messenger_t messenger,
bool  passive 
)

Set the passive mode for a messenger.

See pn_messenger_is_passive() for details on passive mode.

Parameters
[in]messengera messenger object
[in]passivetrue to enable passive mode, false to disable passive mode
Returns
an error code or zero on success

◆ pn_messenger_free()

void pn_messenger_free ( pn_messenger_t messenger)

Frees a Messenger.

Parameters
[in]messengerthe messenger to free (or NULL), no longer valid on return

◆ pn_messenger_errno()

int pn_messenger_errno ( pn_messenger_t messenger)

Get the code for a messenger's most recent error.

The error code is initialized to zero at messenger creation. The error number is "sticky" i.e. error codes are not reset to 0 at the end of successful API calls. You can use pn_messenger_error to access the messenger's error object and clear explicitly if desired.

Parameters
[in]messengerthe messenger to check for errors
Returns
an error code or zero if there is no error
See also
error.h

◆ pn_messenger_error()

pn_error_t* pn_messenger_error ( pn_messenger_t messenger)

Get a messenger's error object.

Returns a pointer to a pn_error_t that is valid until the messenger is freed. The pn_error_* API allows you to access the text, error number, and lets you set or clear the error code explicitly.

Parameters
[in]messengerthe messenger to check for errors
Returns
a pointer to the messenger's error descriptor
See also
error.h

◆ pn_messenger_get_outgoing_window()

int pn_messenger_get_outgoing_window ( pn_messenger_t messenger)

Get the size of a messenger's outgoing window.

The size of the outgoing window limits the number of messages whose status you can check with a tracker. A message enters this window when you call pn_messenger_put on the message. For example, if your outgoing window size is 10, and you call pn_messenger_put 12 times, new status information will no longer be available for the first 2 messages.

The default outgoing window size is 0.

Parameters
[in]messengera messenger object
Returns
the outgoing window for the messenger

◆ pn_messenger_set_outgoing_window()

int pn_messenger_set_outgoing_window ( pn_messenger_t messenger,
int  window 
)

Set the size of a messenger's outgoing window.

See pn_messenger_get_outgoing_window() for details.

Parameters
[in]messengera messenger object
[in]windowthe number of deliveries to track
Returns
an error or zero on success
See also
error.h

◆ pn_messenger_get_incoming_window()

int pn_messenger_get_incoming_window ( pn_messenger_t messenger)

Get the size of a messenger's incoming window.

The size of a messenger's incoming window limits the number of messages that can be accepted or rejected using trackers. Messages do not enter this window when they have been received (pn_messenger_recv) onto you incoming queue. Messages only enter this window only when you access them using pn_messenger_get. If your incoming window size is N, and you get N+1 messages without explicitly accepting or rejecting the oldest message, then it will be implicitly accepted when it falls off the edge of the incoming window.

The default incoming window size is 0.

Parameters
[in]messengera messenger object
Returns
the incoming window for the messenger

◆ pn_messenger_set_incoming_window()

int pn_messenger_set_incoming_window ( pn_messenger_t messenger,
int  window 
)

Set the size of a messenger's incoming window.

See pn_messenger_get_incoming_window() for details.

Parameters
[in]messengera messenger object
[in]windowthe number of deliveries to track
Returns
an error or zero on success
See also
error.h

◆ pn_messenger_start()

int pn_messenger_start ( pn_messenger_t messenger)

Currently a no-op placeholder.

For future compatibility, do not send or receive messages before starting the messenger.

Parameters
[in]messengerthe messenger to start
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_stop()

int pn_messenger_stop ( pn_messenger_t messenger)

Stops a messenger.

Stopping a messenger will perform an orderly shutdown of all underlying connections. This may require some time. If the messenger is in non blocking mode (see pn_messenger_is_blocking), this operation will return PN_INPROGRESS if it cannot finish immediately. In that case, you can use pn_messenger_stopped() to determine when the messenger has finished stopping.

Parameters
[in]messengerthe messenger to stop
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_stopped()

bool pn_messenger_stopped ( pn_messenger_t messenger)

Returns true if a messenger is in the stopped state.

This function does not block.

Parameters
[in]messengerthe messenger to stop

◆ pn_messenger_subscribe()

pn_subscription_t* pn_messenger_subscribe ( pn_messenger_t messenger,
const char *  source 
)

Subscribes a messenger to messages from the specified source.

Parameters
[in]messengerthe messenger to subscribe
[in]source
Returns
a subscription

◆ pn_messenger_subscribe_ttl()

pn_subscription_t* pn_messenger_subscribe_ttl ( pn_messenger_t messenger,
const char *  source,
pn_seconds_t  timeout 
)

Subscribes a messenger to messages from the specified source with the given timeout for the subscription's lifetime.

Parameters
[in]messengerthe messenger to subscribe
[in]source
[in]timeoutthe maximum time to keep the subscription alive once the link is closed.
Returns
a subscription

◆ pn_messenger_get_link()

pn_link_t* pn_messenger_get_link ( pn_messenger_t messenger,
const char *  address,
bool  sender 
)

Get a link based on link name and whether the link is a sender or receiver.

Parameters
[in]messengerthe messenger to get the link from
[in]addressthe link address that identifies the link to receive
[in]sendertrue if the link is a sender, false if the link is a receiver
Returns
a link, or NULL if no link matches the address / sender parameters

◆ pn_subscription_get_context()

void* pn_subscription_get_context ( pn_subscription_t sub)

Get a subscription's application context.

See pn_subscription_set_context().

Parameters
[in]suba subscription object
Returns
the subscription's application context

◆ pn_subscription_set_context()

void pn_subscription_set_context ( pn_subscription_t sub,
void *  context 
)

Set an application context for a subscription.

Parameters
[in]suba subscription object
[in]contextthe application context for the subscription

◆ pn_subscription_address()

const char* pn_subscription_address ( pn_subscription_t sub)

Get the source address of a subscription.

Parameters
[in]suba subscription object
Returns
the subscription's source address

◆ pn_messenger_put()

int pn_messenger_put ( pn_messenger_t messenger,
pn_message_t msg 
)

Puts a message onto the messenger's outgoing queue.

The message may also be sent if transmission would not cause blocking. This call will not block.

Parameters
[in]messengera messenger object
[in]msga message to put on the messenger's outgoing queue
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_status()

pn_status_t pn_messenger_status ( pn_messenger_t messenger,
pn_tracker_t  tracker 
)

Track the status of a delivery.

Get the current status of the delivery associated with the supplied tracker. This may return PN_STATUS_UNKOWN if the tracker has fallen outside the incoming/outgoing tracking windows of the messenger.

Parameters
[in]messengerthe messenger
[in]trackerthe tracker identifying the delivery
Returns
a status code for the delivery

◆ pn_messenger_delivery()

pn_delivery_t* pn_messenger_delivery ( pn_messenger_t messenger,
pn_tracker_t  tracker 
)

Get delivery information about a delivery.

Returns the delivery information associated with the supplied tracker. This may return NULL if the tracker has fallen outside the incoming/outgoing tracking windows of the messenger.

Parameters
[in]messengerthe messenger
[in]trackerthe tracker identifying the delivery
Returns
a pn_delivery_t representing the delivery.

◆ pn_messenger_buffered()

bool pn_messenger_buffered ( pn_messenger_t messenger,
pn_tracker_t  tracker 
)

Check if the delivery associated with a given tracker is still waiting to be sent.

Note that returning false does not imply that the delivery was actually sent over the wire.

Parameters
[in]messengerthe messenger
[in]trackerthe tracker identifying the delivery
Returns
true if the delivery is still buffered

◆ pn_messenger_settle()

int pn_messenger_settle ( pn_messenger_t messenger,
pn_tracker_t  tracker,
int  flags 
)

Frees a Messenger from tracking the status associated with a given tracker.

Use the PN_CUMULATIVE flag to indicate everything up to (and including) the given tracker.

Parameters
[in]messengerthe Messenger
[in]trackeridentifies a delivery
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_outgoing_tracker()

pn_tracker_t pn_messenger_outgoing_tracker ( pn_messenger_t messenger)

Get a tracker for the outgoing message most recently given to pn_messenger_put.

This tracker may be used with pn_messenger_status to determine the delivery status of the message, as long as the message is still within your outgoing window.

Parameters
[in]messengerthe messenger
Returns
a pn_tracker_t or an undefined value if pn_messenger_get has never been called for the given messenger

◆ pn_messenger_work()

int pn_messenger_work ( pn_messenger_t messenger,
int  timeout 
)

Sends or receives any outstanding messages queued for a messenger.

This will block for the indicated timeout.

Parameters
[in]messengerthe Messenger
[in]timeoutthe maximum time to block in milliseconds, -1 == forever, 0 == do not block
Returns
0 if no work to do, < 0 if error, or 1 if work was done.

◆ pn_messenger_interrupt()

int pn_messenger_interrupt ( pn_messenger_t messenger)

Interrupt a messenger object that may be blocking in another thread.

The messenger interface is single-threaded. This is the only messenger function intended to be concurrently called from another thread. It will interrupt any messenger function which is currently blocking and cause it to return with a status of PN_INTR.

Parameters
[in]messengerthe Messenger to interrupt

◆ pn_messenger_send()

int pn_messenger_send ( pn_messenger_t messenger,
int  n 
)

Send messages from a messenger's outgoing queue.

If a messenger is in blocking mode (see pn_messenger_is_blocking()), this operation will block until N messages have been sent from the outgoing queue. A value of -1 for N means "all messages in the outgoing queue". See below for a full definition of what sent from the outgoing queue means.

Any blocking will end once the messenger's configured timeout (if any) has been reached. When this happens an error code of PN_TIMEOUT is returned.

If the messenger is in non blocking mode, this call will return an error code of PN_INPROGRESS if it is unable to send the requested number of messages without blocking.

A message is considered to be sent from the outgoing queue when its status has been fully determined. This does not necessarily mean the message was successfully sent to the final recipient though, for example of the receiver rejects the message, the final status will be PN_STATUS_REJECTED. Similarly, if a message is sent to an invalid address, it may be removed from the outgoing queue without ever even being transmitted. In this case the final status will be PN_STATUS_ABORTED.

Parameters
[in]messengera messenger object
[in]nthe number of messages to send
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_recv()

int pn_messenger_recv ( pn_messenger_t messenger,
int  limit 
)

Retrieve messages into a messenger's incoming queue.

Instructs a messenger to receive up to limit messages into the incoming message queue of a messenger. If limit is -1, the messenger will receive as many messages as it can buffer internally. If the messenger is in blocking mode, this call will block until at least one message is available in the incoming queue.

Each call to pn_messenger_recv replaces the previous receive operation, so pn_messenger_recv(messenger, 0) will cancel any outstanding receive.

After receiving messages onto your incoming queue use pn_messenger_get() to access message content.

Parameters
[in]messengerthe messenger
[in]limitthe maximum number of messages to receive or -1 to to receive as many messages as it can buffer internally.
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_receiving()

int pn_messenger_receiving ( pn_messenger_t messenger)

Get the capacity of the incoming message queue of a messenger.

Note this count does not include those messages already available on the incoming queue (

See also
pn_messenger_incoming()). Rather it returns the number of incoming queue entries available for receiving messages.
Parameters
[in]messengerthe messenger

◆ pn_messenger_get()

int pn_messenger_get ( pn_messenger_t messenger,
pn_message_t message 
)

Get the next message from the head of a messenger's incoming queue.

The get operation copies the message data from the head of the messenger's incoming queue into the provided pn_message_t object. If provided pn_message_t pointer is NULL, the head message will be discarded. This operation will return PN_EOS if there are no messages left on the incoming queue.

Parameters
[in]messengera messenger object
[out]messageupon return contains the message from the head of the queue
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_incoming_tracker()

pn_tracker_t pn_messenger_incoming_tracker ( pn_messenger_t messenger)

Get a tracker for the message most recently retrieved by pn_messenger_get().

A tracker for an incoming message allows you to accept or reject the associated message. It can also be used for cumulative accept/reject operations for the associated message and all prior messages as well.

Parameters
[in]messengera messenger object
Returns
a pn_tracker_t or an undefined value if pn_messenger_get has never been called for the given messenger

◆ pn_messenger_incoming_subscription()

pn_subscription_t* pn_messenger_incoming_subscription ( pn_messenger_t messenger)

Get the subscription of the message most recently retrieved by pn_messenger_get().

This operation will return NULL if pn_messenger_get() has never been successfully called.

Parameters
[in]messengera messenger object
Returns
a pn_subscription_t or NULL

◆ pn_messenger_accept()

int pn_messenger_accept ( pn_messenger_t messenger,
pn_tracker_t  tracker,
int  flags 
)

Signal successful processing of message(s).

With no flags this operation will signal the sender that the message referenced by the tracker was accepted. If the PN_CUMULATIVE flag is set, this operation will also reject all pending messages prior to the message indicated by the tracker.

Note that when a message is accepted or rejected multiple times, either explicitly, or implicitly through use of the PN_CUMULATIVE flag, only the first outcome applies. For example if a sequence of three messages are received: M1, M2, M3, and M2 is rejected, and M3 is cumulatively accepted, M2 will remain rejected and only M1 and M3 will be considered accepted.

Parameters
[in]messengera messenger object
[in]trackeran incoming tracker
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_reject()

int pn_messenger_reject ( pn_messenger_t messenger,
pn_tracker_t  tracker,
int  flags 
)

Signal unsuccessful processing of message(s).

With no flags this operation will signal the sender that the message indicated by the tracker was rejected. If the PN_CUMULATIVE flag is used this operation will also reject all pending messages prior to the message indicated by the tracker.

Note that when a message is accepted or rejected multiple times, either explicitly, or implicitly through use of the PN_CUMULATIVE flag, only the first outcome applies. For example if a sequence of three messages are received: M1, M2, M3, and M2 is accepted, and M3 is cumulatively rejected, M2 will remain accepted and only M1 and M3 will be considered rejected.

Parameters
[in]messengera messenger object
[in]trackeran incoming tracker
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_tracker_link()

pn_link_t* pn_messenger_tracker_link ( pn_messenger_t messenger,
pn_tracker_t  tracker 
)

Get link for the message referenced by the given tracker.

Parameters
[in]messengera messenger object
[in]trackera tracker object
Returns
a pn_link_t or NULL if the link could not be determined.

◆ pn_messenger_outgoing()

int pn_messenger_outgoing ( pn_messenger_t messenger)

Get the number of messages in the outgoing message queue of a messenger.

Parameters
[in]messengera messenger object
Returns
the outgoing queue depth

◆ pn_messenger_incoming()

int pn_messenger_incoming ( pn_messenger_t messenger)

Get the number of messages in the incoming message queue of a messenger.

Parameters
[in]messengera messenger object
Returns
the incoming queue depth

◆ pn_messenger_route()

int pn_messenger_route ( pn_messenger_t messenger,
const char *  pattern,
const char *  address 
)

Adds a routing rule to a Messenger's internal routing table.

The route procedure may be used to influence how a messenger will internally treat a given address or class of addresses. Every call to the route procedure will result in messenger appending a routing rule to its internal routing table.

Whenever a message is presented to a messenger for delivery, it will match the address of this message against the set of routing rules in order. The first rule to match will be triggered, and instead of routing based on the address presented in the message, the messenger will route based on the address supplied in the rule.

The pattern matching syntax supports two types of matches, a '' will match any character except a '/', and a '*' will match any character including a '/'.

A routing address is specified as a normal AMQP address, however it may additionally use substitution variables from the pattern match that triggered the rule.

Any message sent to "foo" will be routed to "amqp://foo.com":

pn_messenger_route("foo", "amqp://foo.com");

Any message sent to "foobar" will be routed to "amqp://foo.com/bar":

pn_messenger_route("foobar", "amqp://foo.com/bar");

Any message sent to bar/<path> will be routed to the corresponding path within the amqp://bar.com domain:

pn_messenger_route("bar/*", "amqp://bar.com/$1");

Route all messages over TLS:

pn_messenger_route("amqp:*", "amqps:$1")

Supply credentials for foo.com:

pn_messenger_route("amqp://foo.com/*", "amqp://user:password@foo.com/$1");

Supply credentials for all domains:

pn_messenger_route("amqp://*", "amqp://user:password@$1");

Route all addresses through a single proxy while preserving the original destination:

pn_messenger_route("amqp://%/*", "amqp://user:password@proxy/$1/$2");

Route any address through a single broker:

pn_messenger_route("*", "amqp://user:password@broker/$1");

Parameters
[in]messengerthe Messenger
[in]patterna glob pattern
[in]addressan address indicating alternative routing
Returns
an error code or zero on success
See also
error.h

◆ pn_messenger_rewrite()

int pn_messenger_rewrite ( pn_messenger_t messenger,
const char *  pattern,
const char *  address 
)

Rewrite message addresses prior to transmission.

This operation is similar to pn_messenger_route, except that the destination of the message is determined before the message address is rewritten.

The outgoing address is only rewritten after routing has been finalized. If a message has an outgoing address of "amqp://0.0.0.0:5678", and a rewriting rule that changes its outgoing address to "foo", it will still arrive at the peer that is listening on "amqp://0.0.0.0:5678", but when it arrives there, the receiver will see its outgoing address as "foo".

The default rewrite rule removes username and password from addresses before they are transmitted.

Parameters
[in]messengera messenger object
[in]patterna glob pattern to select messages
[in]addressan address indicating outgoing address rewrite
Returns
an error code or zero on success

◆ pn_messenger_selectable()

pn_selectable_t* pn_messenger_selectable ( pn_messenger_t messenger)

Extract selectables from a passive messenger.

A messenger that is in passive mode (see pn_messenger_is_passive()) will never attempt to perform any I/O internally, but instead make its internal file descriptors available for external processing via the pn_messenger_selectable() operation.

An application wishing to perform I/O on behalf of a passive messenger must extract all available selectables by calling this operation until it returns NULL. The selectable interface may then be used by the application to perform I/O outside the messenger.

All selectables returned by this operation must be serviced until they reach a terminal state and then freed. See pn_selectable_is_terminal() for more details.

By default any given selectable will only ever be returned once by this operation, however if the selectable's registered flag is set to true (see pn_selectable_set_registered()), then the selectable will be returned whenever its interest set may have changed.

Parameters
[in]messengera messenger object
Returns
the next selectable, or NULL if there are none left

◆ pn_messenger_deadline()

pn_timestamp_t pn_messenger_deadline ( pn_messenger_t messenger)

Get the nearest deadline for selectables associated with a messenger.

Parameters
[in]messengera messenger object
Returns
the nearest deadline

◆ pn_messenger_set_flags()

int pn_messenger_set_flags ( pn_messenger_t messenger,
const int  flags 
)

Sets control flags to enable additional function for the Messenger.

Parameters
[in]messengerthe messenger
[in]flags0 or PN_FLAGS_CHECK_ROUTES
Returns
an error code of zero if there is no error

◆ pn_messenger_get_flags()

int pn_messenger_get_flags ( pn_messenger_t messenger)

Gets the flags for a Messenger.

Parameters
[in]messengerthe messenger
Returns
The flags set for the messenger

◆ pn_messenger_set_snd_settle_mode()

int pn_messenger_set_snd_settle_mode ( pn_messenger_t messenger,
const pn_snd_settle_mode_t  mode 
)

Set the local sender settle mode for the underlying link.

Parameters
[in]messengerthe messenger
[in]modethe sender settle mode

◆ pn_messenger_set_rcv_settle_mode()

int pn_messenger_set_rcv_settle_mode ( pn_messenger_t messenger,
const pn_rcv_settle_mode_t  mode 
)

Set the local receiver settle mode for the underlying link.

Parameters
[in]messengerthe messenger
[in]modethe receiver settle mode

◆ pn_messenger_set_tracer()

void pn_messenger_set_tracer ( pn_messenger_t messenger,
pn_tracer_t  tracer 
)

Set the tracer associated with a messenger.

Parameters
[in]messengera messenger object
[in]tracerthe tracer callback

◆ pn_messenger_get_remote_idle_timeout()

pn_millis_t pn_messenger_get_remote_idle_timeout ( pn_messenger_t messenger,
const char *  address 
)

Gets the remote idle timeout for the specified remote service address.

Parameters
[in]messengera messenger object
[in]addressof remote service whose idle timeout is required
Returns
the timeout in milliseconds or -1 if an error occurs

◆ pn_messenger_set_ssl_peer_authentication_mode()

int pn_messenger_set_ssl_peer_authentication_mode ( pn_messenger_t messenger,
const pn_ssl_verify_mode_t  mode 
)

Sets the SSL peer authentication mode required when a trust certificate is used.

Parameters
[in]messengera messenger object
[in]modethe mode required (see pn_ssl_verify_mode_t enum for valid values)
Returns
0 if successful or -1 if an error occurs