|
proton
0
|
|
proton
0
|
Macros | |
| #define | PN_CUMULATIVE (0x1) |
| Indicates that an accept or reject should operate cumulatively. More... | |
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. More... | |
| typedef int64_t | pn_tracker_t |
| Trackers provide a lightweight handle used to track the status of incoming and outgoing deliveries. More... | |
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 } |
| Describes all the possible states for a message associated with a given tracker. More... | |
Functions | |
| PN_EXTERN pn_messenger_t * | pn_messenger (const char *name) |
| Construct a new pn_messenger_t with the given name. More... | |
| PN_EXTERN const char * | pn_messenger_name (pn_messenger_t *messenger) |
| Get the name of a messenger. More... | |
| 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. More... | |
| PN_EXTERN const char * | pn_messenger_get_certificate (pn_messenger_t *messenger) |
| Get the certificate path. More... | |
| 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. More... | |
| PN_EXTERN const char * | pn_messenger_get_private_key (pn_messenger_t *messenger) |
| Gets the private key file for a messenger. More... | |
| PN_EXTERN int | pn_messenger_set_password (pn_messenger_t *messenger, const char *password) |
| Sets the private key password for a messenger. More... | |
| PN_EXTERN const char * | pn_messenger_get_password (pn_messenger_t *messenger) |
| Gets the private key file password for a messenger. More... | |
| PN_EXTERN int | pn_messenger_set_trusted_certificates (pn_messenger_t *messenger, const char *cert_db) |
| Sets the trusted certificates database for a messenger. More... | |
| PN_EXTERN const char * | pn_messenger_get_trusted_certificates (pn_messenger_t *messenger) |
| Gets the trusted certificates database for a messenger. More... | |
| PN_EXTERN int | pn_messenger_set_timeout (pn_messenger_t *messenger, int timeout) |
| Set the default timeout for a messenger. More... | |
| PN_EXTERN int | pn_messenger_get_timeout (pn_messenger_t *messenger) |
| Gets the timeout for a messenger object. More... | |
| PN_EXTERN bool | pn_messenger_is_blocking (pn_messenger_t *messenger) |
| Check if a messenger is in blocking mode. More... | |
| 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. More... | |
| PN_EXTERN bool | pn_messenger_is_passive (pn_messenger_t *messenger) |
| Check if a messenger is in passive mode. More... | |
| PN_EXTERN int | pn_messenger_set_passive (pn_messenger_t *messenger, bool passive) |
| Set the passive mode for a messenger. More... | |
| PN_EXTERN void | pn_messenger_free (pn_messenger_t *messenger) |
| Frees a Messenger. More... | |
| PN_EXTERN int | pn_messenger_errno (pn_messenger_t *messenger) |
| Get the code for a messenger's most recent error. More... | |
| PN_EXTERN pn_error_t * | pn_messenger_error (pn_messenger_t *messenger) |
| Get a messenger's error object. More... | |
| PN_EXTERN int | pn_messenger_get_outgoing_window (pn_messenger_t *messenger) |
| Get the size of a messenger's outgoing window. More... | |
| PN_EXTERN int | pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window) |
| Set the size of a messenger's outgoing window. More... | |
| PN_EXTERN int | pn_messenger_get_incoming_window (pn_messenger_t *messenger) |
| Get the size of a messenger's incoming window. More... | |
| PN_EXTERN int | pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window) |
| Set the size of a messenger's incoming window. More... | |
| PN_EXTERN int | pn_messenger_start (pn_messenger_t *messenger) |
| Currently a no-op placeholder. More... | |
| PN_EXTERN int | pn_messenger_stop (pn_messenger_t *messenger) |
| Stops a messenger. More... | |
| PN_EXTERN bool | pn_messenger_stopped (pn_messenger_t *messenger) |
| Returns true if a messenger is in the stopped state. More... | |
| PN_EXTERN pn_subscription_t * | pn_messenger_subscribe (pn_messenger_t *messenger, const char *source) |
| Subscribes a messenger to messages from the specified source. More... | |
| PN_EXTERN 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. More... | |
| PN_EXTERN 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. More... | |
| PN_EXTERN void * | pn_subscription_get_context (pn_subscription_t *sub) |
| Get a subscription's application context. More... | |
| PN_EXTERN void | pn_subscription_set_context (pn_subscription_t *sub, void *context) |
| Set an application context for a subscription. More... | |
| PN_EXTERN const char * | pn_subscription_address (pn_subscription_t *sub) |
| Get the source address of a subscription. More... | |
| PN_EXTERN int | pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg) |
| Puts a message onto the messenger's outgoing queue. More... | |
| PN_EXTERN pn_status_t | pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker) |
| Track the status of a delivery. More... | |
| PN_EXTERN pn_delivery_t * | pn_messenger_delivery (pn_messenger_t *messenger, pn_tracker_t tracker) |
| Get delivery information about a delivery. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| PN_EXTERN int | pn_messenger_work (pn_messenger_t *messenger, int timeout) |
| Sends or receives any outstanding messages queued for a messenger. More... | |
| PN_EXTERN int | pn_messenger_interrupt (pn_messenger_t *messenger) |
| Interrupt a messenger object that may be blocking in another thread. More... | |
| PN_EXTERN int | pn_messenger_send (pn_messenger_t *messenger, int n) |
| Send messages from a messenger's outgoing queue. More... | |
| PN_EXTERN int | pn_messenger_recv (pn_messenger_t *messenger, int limit) |
| Retrieve messages into a messenger's incoming queue. More... | |
| PN_EXTERN int | pn_messenger_receiving (pn_messenger_t *messenger) |
| Get the capacity of the incoming message queue of a messenger. More... | |
| 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. More... | |
| 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(). More... | |
| 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(). More... | |
| PN_EXTERN int | pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
| Signal successful processing of message(s). More... | |
| PN_EXTERN int | pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
| Signal unsuccessful processing of message(s). More... | |
| PN_EXTERN 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. More... | |
| PN_EXTERN int | pn_messenger_outgoing (pn_messenger_t *messenger) |
| Get the number of messages in the outgoing message queue of a messenger. More... | |
| PN_EXTERN int | pn_messenger_incoming (pn_messenger_t *messenger) |
| Get the number of messages in the incoming message queue of a messenger. More... | |
| 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. More... | |
| PN_EXTERN int | pn_messenger_rewrite (pn_messenger_t *messenger, const char *pattern, const char *address) |
| Rewrite message addresses prior to transmission. More... | |
| PN_EXTERN pn_selectable_t * | pn_messenger_selectable (pn_messenger_t *messenger) |
| Extract selectables from a passive messenger. More... | |
| PN_EXTERN pn_timestamp_t | pn_messenger_deadline (pn_messenger_t *messenger) |
| Get the nearest deadline for selectables associated with a messenger. More... | |
| #define PN_CUMULATIVE (0x1) |
Indicates that an accept or reject should operate cumulatively.
| 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).
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.
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:
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.
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.
| 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.
| enum 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. |
| 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.
| [in] | name | the name of the messenger or NULL |
| 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.
| [in] | messenger | a messenger object |
| [in] | tracker | an incoming tracker |
| [in] | flags | 0 or PN_CUMULATIVE |
| 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.
| [in] | messenger | the messenger |
| [in] | tracker | the tracker identifying the delivery |
| PN_EXTERN pn_timestamp_t pn_messenger_deadline | ( | pn_messenger_t * | messenger | ) |
Get the nearest deadline for selectables associated with a messenger.
| [in] | messenger | a messenger object |
| PN_EXTERN 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.
| [in] | messenger | the messenger |
| [in] | tracker | the tracker identifying the delivery |
| 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.
| [in] | messenger | the messenger to check for errors |
| 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.
| [in] | messenger | the messenger to check for errors |
| PN_EXTERN void pn_messenger_free | ( | pn_messenger_t * | messenger | ) |
Frees a Messenger.
| [in] | messenger | the 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.
| [in] | messenger | a messenger object |
| [out] | message | upon return contains the message from the head of the queue |
| 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.
| [in] | messenger | the messenger |
| 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.
| [in] | messenger | a messenger object |
| PN_EXTERN 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.
| [in] | messenger | the messenger to get the link from |
| [in] | address | the link address that identifies the link to receive |
| [in] | sender | true if the link is a sender, false if the link is a receiver |
| 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.
| [in] | messenger | a messenger object |
| PN_EXTERN const char* pn_messenger_get_password | ( | pn_messenger_t * | messenger | ) |
Gets the private key file password for a messenger.
| [in] | messenger | a messenger object |
| PN_EXTERN const char* pn_messenger_get_private_key | ( | pn_messenger_t * | messenger | ) |
Gets the private key file for a messenger.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | a messenger object |
| PN_EXTERN const char* pn_messenger_get_trusted_certificates | ( | pn_messenger_t * | messenger | ) |
Gets the trusted certificates database for a messenger.
| [in] | messenger | a messenger object |
| PN_EXTERN int pn_messenger_incoming | ( | pn_messenger_t * | messenger | ) |
Get the number of messages in the incoming message queue of a messenger.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | the Messenger to interrupt |
| PN_EXTERN bool pn_messenger_is_blocking | ( | pn_messenger_t * | messenger | ) |
Check if a messenger is in blocking mode.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | a messenger object |
| PN_EXTERN const char* pn_messenger_name | ( | pn_messenger_t * | messenger | ) |
Get the name of a messenger.
| [in] | messenger | a messenger object |
| PN_EXTERN int pn_messenger_outgoing | ( | pn_messenger_t * | messenger | ) |
Get the number of messages in the outgoing message queue of a messenger.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | the 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.
| [in] | messenger | a messenger object |
| [in] | msg | a message to put on the messenger's outgoing queue |
| 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 (
| [in] | messenger | the 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.
| [in] | messenger | the messenger |
| [in] | limit | the maximum number of messages to receive or -1 to to receive as many messages as it can buffer internally. |
| 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.
| [in] | messenger | a messenger object |
| [in] | tracker | an incoming tracker |
| [in] | flags | 0 or PN_CUMULATIVE |
| 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.
| [in] | messenger | a messenger object |
| [in] | pattern | a glob pattern to select messages |
| [in] | address | an address indicating outgoing address rewrite |
| 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");
| [in] | messenger | the Messenger |
| [in] | pattern | a glob pattern |
| [in] | address | an address indicating alternative routing |
| 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.
| [in] | messenger | a messenger object |
| 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.
| [in] | messenger | a messenger object |
| [in] | n | the number of messages to send |
| 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.
| [in] | messenger | a messenger object |
| [in] | blocking | the value of the blocking flag |
| 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.
| [in] | messenger | the messenger |
| [in] | certificate | a path to a certificate file |
| 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.
| [in] | messenger | a messenger object |
| [in] | window | the number of deliveries to track |
| 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.
| [in] | messenger | a messenger object |
| [in] | window | the number of deliveries to track |
| 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.
| [in] | messenger | a messenger object |
| [in] | passive | true to enable passive mode, false to disable passive mode |
| PN_EXTERN int pn_messenger_set_password | ( | pn_messenger_t * | messenger, |
| const char * | password | ||
| ) |
Sets the private key password for a messenger.
| [in] | messenger | a messenger object |
| [in] | password | the password for the private key file |
| 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
| [in] | messenger | a messenger object |
| [in] | private_key | a path to a private key file |
| 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.
| [in] | messenger | a messenger object |
| [in] | timeout | a new timeout for the messenger, in milliseconds |
| 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.
| [in] | messenger | a messenger object |
| [in] | cert_db | a path to the certificates database |
| 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.
| [in] | messenger | the Messenger |
| [in] | tracker | identifies a delivery |
| [in] | flags | 0 or PN_CUMULATIVE |
| 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.
| [in] | messenger | the messenger to start |
| 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.
| [in] | messenger | the messenger |
| [in] | tracker | the tracker identifying 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.
| [in] | messenger | the messenger to stop |
| 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.
| [in] | messenger | the 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.
| [in] | messenger | the messenger to subscribe |
| [in] | source |
| PN_EXTERN 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.
| [in] | messenger | the messenger to subscribe |
| [in] | source | |
| [in] | timeout | the maximum time to keep the subscription alive once the link is closed. |
| PN_EXTERN 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.
| [in] | messenger | a messenger object |
| [in] | tracker | a tracker object |
| 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.
| [in] | messenger | the Messenger |
| [in] | timeout | the maximum time to block in milliseconds, -1 == forever, 0 == do not block |
| PN_EXTERN const char* pn_subscription_address | ( | pn_subscription_t * | sub | ) |
Get the source address of a subscription.
| [in] | sub | a subscription object |
| PN_EXTERN void* pn_subscription_get_context | ( | pn_subscription_t * | sub | ) |
Get a subscription's application context.
See pn_subscription_set_context().
| [in] | sub | a subscription object |
| PN_EXTERN void pn_subscription_set_context | ( | pn_subscription_t * | sub, |
| void * | context | ||
| ) |
Set an application context for a subscription.
| [in] | sub | a subscription object |
| [in] | context | the application context for the subscription |
1.8.6
