|
Qpid Proton C API 0.40.0
|
|
|
Qpid Proton C API 0.40.0
|
|
Deprecated - Use the Proactor API or Qpid Proton C++. 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). | |
| 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_t * | pn_messenger (const char *name) |
| Construct a new pn_messenger_t with the given name. | |
| const char * | pn_messenger_name (pn_messenger_t *messenger) |
| Get the name of a messenger. | |
| 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. | |
| const char * | pn_messenger_get_certificate (pn_messenger_t *messenger) |
| Get the certificate path. | |
| 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. | |
| const char * | pn_messenger_get_private_key (pn_messenger_t *messenger) |
| Gets the private key file for a messenger. | |
| int | pn_messenger_set_password (pn_messenger_t *messenger, const char *password) |
| Sets the private key password for a messenger. | |
| const char * | pn_messenger_get_password (pn_messenger_t *messenger) |
| Gets the private key file password for a messenger. | |
| int | pn_messenger_set_trusted_certificates (pn_messenger_t *messenger, const char *cert_db) |
| Sets the trusted certificates database for a messenger. | |
| const char * | pn_messenger_get_trusted_certificates (pn_messenger_t *messenger) |
| Gets the trusted certificates database for a messenger. | |
| int | pn_messenger_set_timeout (pn_messenger_t *messenger, int timeout) |
| Set the default timeout for a messenger. | |
| int | pn_messenger_get_timeout (pn_messenger_t *messenger) |
| Gets the timeout for a messenger object. | |
| bool | pn_messenger_is_blocking (pn_messenger_t *messenger) |
| Check if a messenger is in blocking mode. | |
| 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. | |
| bool | pn_messenger_is_passive (pn_messenger_t *messenger) |
| Check if a messenger is in passive mode. | |
| int | pn_messenger_set_passive (pn_messenger_t *messenger, bool passive) |
| Set the passive mode for a messenger. | |
| void | pn_messenger_free (pn_messenger_t *messenger) |
| Frees a Messenger. | |
| int | pn_messenger_errno (pn_messenger_t *messenger) |
| Get the code for a messenger's most recent error. | |
| pn_error_t * | pn_messenger_error (pn_messenger_t *messenger) |
| Get a messenger's error object. | |
| int | pn_messenger_get_outgoing_window (pn_messenger_t *messenger) |
| Get the size of a messenger's outgoing window. | |
| int | pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window) |
| Set the size of a messenger's outgoing window. | |
| int | pn_messenger_get_incoming_window (pn_messenger_t *messenger) |
| Get the size of a messenger's incoming window. | |
| int | pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window) |
| Set the size of a messenger's incoming window. | |
| int | pn_messenger_start (pn_messenger_t *messenger) |
| Currently a no-op placeholder. | |
| int | pn_messenger_stop (pn_messenger_t *messenger) |
| Stops a messenger. | |
| bool | pn_messenger_stopped (pn_messenger_t *messenger) |
| Returns true if a messenger is in the stopped state. | |
| pn_subscription_t * | pn_messenger_subscribe (pn_messenger_t *messenger, const char *source) |
| Subscribes a messenger to messages from the specified source. | |
| 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. | |
| 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. | |
| void * | pn_subscription_get_context (pn_subscription_t *sub) |
| Get a subscription's application context. | |
| void | pn_subscription_set_context (pn_subscription_t *sub, void *context) |
| Set an application context for a subscription. | |
| const char * | pn_subscription_address (pn_subscription_t *sub) |
| Get the source address of a subscription. | |
| int | pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg) |
| Puts a message onto the messenger's outgoing queue. | |
| pn_status_t | pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker) |
| Track the status of a delivery. | |
| pn_delivery_t * | pn_messenger_delivery (pn_messenger_t *messenger, pn_tracker_t tracker) |
| Get delivery information about a delivery. | |
| 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. | |
| 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. | |
| 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. | |
| int | pn_messenger_work (pn_messenger_t *messenger, int timeout) |
| Sends or receives any outstanding messages queued for a messenger. | |
| int | pn_messenger_interrupt (pn_messenger_t *messenger) |
| Interrupt a messenger object that may be blocking in another thread. | |
| int | pn_messenger_send (pn_messenger_t *messenger, int n) |
| Send messages from a messenger's outgoing queue. | |
| int | pn_messenger_recv (pn_messenger_t *messenger, int limit) |
| Retrieve messages into a messenger's incoming queue. | |
| int | pn_messenger_receiving (pn_messenger_t *messenger) |
| Get the capacity of the incoming message queue of a messenger. | |
| 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. | |
| pn_tracker_t | pn_messenger_incoming_tracker (pn_messenger_t *messenger) |
| Get a tracker for the message most recently retrieved by pn_messenger_get(). | |
| pn_subscription_t * | pn_messenger_incoming_subscription (pn_messenger_t *messenger) |
| Get the subscription of the message most recently retrieved by pn_messenger_get(). | |
| int | pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
| Signal successful processing of message(s). | |
| int | pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
| Signal unsuccessful processing of message(s). | |
| 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. | |
| int | pn_messenger_outgoing (pn_messenger_t *messenger) |
| Get the number of messages in the outgoing message queue of a messenger. | |
| int | pn_messenger_incoming (pn_messenger_t *messenger) |
| Get the number of messages in the incoming message queue of a messenger. | |
| 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. | |
| int | pn_messenger_rewrite (pn_messenger_t *messenger, const char *pattern, const char *address) |
| Rewrite message addresses prior to transmission. | |
| pn_selectable_t * | pn_messenger_selectable (pn_messenger_t *messenger) |
| Extract selectables from a passive messenger. | |
| pn_timestamp_t | pn_messenger_deadline (pn_messenger_t *messenger) |
| Get the nearest deadline for selectables associated with a messenger. | |
| int | pn_messenger_set_flags (pn_messenger_t *messenger, const int flags) |
| Sets control flags to enable additional function for the Messenger. | |
| int | pn_messenger_get_flags (pn_messenger_t *messenger) |
| Gets the flags for a Messenger. | |
| 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. | |
| 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. | |
| void | pn_messenger_set_tracer (pn_messenger_t *messenger, pn_tracer_t tracer) |
| Set the tracer associated with a messenger. | |
| 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. | |
| 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. | |
Deprecated - Use the Proactor API or Qpid Proton C++.
| 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 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.
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.
| 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_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 |
| const char * pn_messenger_name | ( | pn_messenger_t * | messenger | ) |
Get the name of a messenger.
| [in] | messenger | a messenger object |
| 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 |
| 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 |
| 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 |
| const char * pn_messenger_get_private_key | ( | pn_messenger_t * | messenger | ) |
Gets the private key file for a messenger.
| [in] | messenger | a messenger object |
| 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 |
| const char * pn_messenger_get_password | ( | pn_messenger_t * | messenger | ) |
Gets the private key file password for a messenger.
| [in] | messenger | a messenger object |
| 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 |
| const char * pn_messenger_get_trusted_certificates | ( | pn_messenger_t * | messenger | ) |
Gets the trusted certificates database for a messenger.
| [in] | messenger | a messenger object |
| 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 |
| 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 |
| bool pn_messenger_is_blocking | ( | pn_messenger_t * | messenger | ) |
Check if a messenger is in blocking mode.
| [in] | messenger | a messenger object |
| 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 |
| 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 |
| 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 |
| void pn_messenger_free | ( | pn_messenger_t * | messenger | ) |
Frees a Messenger.
| [in] | messenger | the messenger to free (or NULL), no longer valid on return |
| 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_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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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_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_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_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 |
| 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 |
| 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 |
| const char * pn_subscription_address | ( | pn_subscription_t * | sub | ) |
Get the source address of a subscription.
| [in] | sub | a subscription object |
| 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_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_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 |
| 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 |
| 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_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 |
| 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 |
| 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 |
| 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 |
| 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. |
| 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 |
| 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.
| [in] | messenger | a messenger object |
| [out] | message | upon return contains the message from the head of the queue |
| 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_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.
| [in] | messenger | a messenger object |
| 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 |
| 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_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 |
| 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 |
| 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 |
| 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 |
| 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_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.
| [in] | messenger | a messenger object |
| 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 |
| int pn_messenger_set_flags | ( | pn_messenger_t * | messenger, |
| const int | flags | ||
| ) |
Sets control flags to enable additional function for the Messenger.
| [in] | messenger | the messenger |
| [in] | flags | 0 or PN_FLAGS_CHECK_ROUTES |
| int pn_messenger_get_flags | ( | pn_messenger_t * | messenger | ) |
Gets the flags for a Messenger.
| [in] | messenger | the messenger |
| 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.
| [in] | messenger | the messenger |
| [in] | mode | the sender 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.
| [in] | messenger | the messenger |
| [in] | mode | the receiver settle mode |
| void pn_messenger_set_tracer | ( | pn_messenger_t * | messenger, |
| pn_tracer_t | tracer | ||
| ) |
Set the tracer associated with a messenger.
| [in] | messenger | a messenger object |
| [in] | tracer | the tracer callback |
| 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.
| [in] | messenger | a messenger object |
| [in] | address | of remote service whose idle timeout is required |
| 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.
| [in] | messenger | a messenger object |
| [in] | mode | the mode required (see pn_ssl_verify_mode_t enum for valid values) |
1.9.7