C AMQP Protocol Engine API  0.7
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Messenger

Macros

#define PN_CUMULATIVE   (0x1)
 

Typedefs

typedef struct pn_messenger_t pn_messenger_t
 
typedef struct pn_subscription_t pn_subscription_t
 
typedef int64_t pn_tracker_t
 

Enumerations

enum  pn_status_t {
  PN_STATUS_UNKNOWN = 0, PN_STATUS_PENDING = 1, PN_STATUS_ACCEPTED = 2, PN_STATUS_REJECTED = 3,
  PN_STATUS_RELEASED = 4, PN_STATUS_MODIFIED = 5, PN_STATUS_ABORTED = 6, PN_STATUS_SETTLED = 7
}
 

Functions

PN_EXTERN pn_messenger_tpn_messenger (const char *name)
 
PN_EXTERN const char * pn_messenger_name (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_certificate (pn_messenger_t *messenger, const char *certificate)
 
PN_EXTERN const char * pn_messenger_get_certificate (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_private_key (pn_messenger_t *messenger, const char *private_key)
 
PN_EXTERN const char * pn_messenger_get_private_key (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_password (pn_messenger_t *messenger, const char *password)
 
PN_EXTERN const char * pn_messenger_get_password (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_trusted_certificates (pn_messenger_t *messenger, const char *cert_db)
 
PN_EXTERN const char * pn_messenger_get_trusted_certificates (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_timeout (pn_messenger_t *messenger, int timeout)
 
PN_EXTERN int pn_messenger_get_timeout (pn_messenger_t *messenger)
 
PN_EXTERN bool pn_messenger_is_blocking (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_blocking (pn_messenger_t *messenger, bool blocking)
 
PN_EXTERN bool pn_messenger_is_passive (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_passive (pn_messenger_t *messenger, bool passive)
 
PN_EXTERN void pn_messenger_free (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_errno (pn_messenger_t *messenger)
 
PN_EXTERN pn_error_tpn_messenger_error (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_get_outgoing_window (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window)
 
PN_EXTERN int pn_messenger_get_incoming_window (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window)
 
PN_EXTERN int pn_messenger_start (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_stop (pn_messenger_t *messenger)
 
PN_EXTERN bool pn_messenger_stopped (pn_messenger_t *messenger)
 
PN_EXTERN pn_subscription_tpn_messenger_subscribe (pn_messenger_t *messenger, const char *source)
 
PN_EXTERN void * pn_subscription_get_context (pn_subscription_t *sub)
 
PN_EXTERN void pn_subscription_set_context (pn_subscription_t *sub, void *context)
 
PN_EXTERN const char * pn_subscription_address (pn_subscription_t *sub)
 
PN_EXTERN int pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg)
 
PN_EXTERN pn_status_t pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker)
 
PN_EXTERN bool pn_messenger_buffered (pn_messenger_t *messenger, pn_tracker_t tracker)
 
PN_EXTERN int pn_messenger_settle (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 
PN_EXTERN pn_tracker_t pn_messenger_outgoing_tracker (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_work (pn_messenger_t *messenger, int timeout)
 
PN_EXTERN int pn_messenger_interrupt (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_send (pn_messenger_t *messenger, int n)
 
PN_EXTERN int pn_messenger_recv (pn_messenger_t *messenger, int limit)
 
PN_EXTERN int pn_messenger_receiving (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_get (pn_messenger_t *messenger, pn_message_t *message)
 
PN_EXTERN pn_tracker_t pn_messenger_incoming_tracker (pn_messenger_t *messenger)
 
PN_EXTERN pn_subscription_tpn_messenger_incoming_subscription (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 
PN_EXTERN int pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 
PN_EXTERN int pn_messenger_outgoing (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_incoming (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_route (pn_messenger_t *messenger, const char *pattern, const char *address)
 
PN_EXTERN int pn_messenger_rewrite (pn_messenger_t *messenger, const char *pattern, const char *address)
 
PN_EXTERN pn_selectable_tpn_messenger_selectable (pn_messenger_t *messenger)
 
PN_EXTERN pn_timestamp_t pn_messenger_deadline (pn_messenger_t *messenger)
 

Detailed Description

Macro Definition Documentation

#define PN_CUMULATIVE   (0x1)

Indicates that an accept or reject should operate cumulatively.

Typedef Documentation

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 conjuction 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.

A subscription is a request for incoming messages.

Todo:
currently the subscription API is under developed, this should allow more explicit control over subscription properties and behaviour
typedef int64_t pn_tracker_t

Trackers provide a lightweight handle used to track the status of incoming and outgoing deliveries.

Enumeration Type Documentation

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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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 essage 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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 succesfully called.

Parameters
[in]messengera messenger object
Returns
a pn_subscription_t or NULL
PN_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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 pn_selectable_t 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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_EXTERN 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