proton
0
|
The messenger API provides a high level interface for sending and receiving AMQP messages. More...
Go to the source code of this file.
Macros | |
#define | PN_CUMULATIVE (0x1) |
Typedefs | |
typedef struct pn_messenger_t | pn_messenger_t |
Messenger. More... | |
typedef struct pn_subscription_t | pn_subscription_t |
Subscription. More... | |
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_MODIFIED = 4 } |
Functions | |
PN_EXTERN pn_messenger_t * | pn_messenger (const char *name) |
Construct a new Messenger with the given name. More... | |
PN_EXTERN const char * | pn_messenger_name (pn_messenger_t *messenger) |
Retrieves the name of a Messenger. More... | |
PN_EXTERN int | pn_messenger_set_certificate (pn_messenger_t *messenger, const char *certificate) |
Provides a certificate that will be used to identify the local Messenger to the peer. More... | |
PN_EXTERN const char * | pn_messenger_get_certificate (pn_messenger_t *messenger) |
Gets the certificate file for a Messenger. More... | |
PN_EXTERN int | pn_messenger_set_private_key (pn_messenger_t *messenger, const char *private_key) |
Provides 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) |
Sets the timeout for a Messenger. More... | |
PN_EXTERN int | pn_messenger_get_timeout (pn_messenger_t *messenger) |
Retrieves the timeout for a Messenger. More... | |
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 void | pn_messenger_free (pn_messenger_t *messenger) |
Frees a Messenger. More... | |
PN_EXTERN int | pn_messenger_errno (pn_messenger_t *messenger) |
Returns the error code for the Messenger. More... | |
PN_EXTERN pn_error_t * | pn_messenger_error (pn_messenger_t *messenger) |
Returns the error info for a Messenger. More... | |
PN_EXTERN int | pn_messenger_get_outgoing_window (pn_messenger_t *messenger) |
Gets the outgoing window for a Messenger. More... | |
PN_EXTERN int | pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window) |
Sets the outgoing window for a Messenger. More... | |
PN_EXTERN int | pn_messenger_get_incoming_window (pn_messenger_t *messenger) |
Gets the incoming window for a Messenger. More... | |
PN_EXTERN int | pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window) |
Sets the incoming window for a Messenger. More... | |
PN_EXTERN int | pn_messenger_start (pn_messenger_t *messenger) |
Starts a messenger. 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) |
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 void * | pn_subscription_get_context (pn_subscription_t *sub) |
PN_EXTERN void | pn_subscription_set_context (pn_subscription_t *sub, void *context) |
PN_EXTERN int | pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg) |
Puts a message on the outgoing message queue for a messenger. More... | |
PN_EXTERN pn_status_t | pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker) |
Gets the last known remote state of the delivery associated with the given tracker. 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) |
Gets the tracker for the message most recently provided 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) |
Interrupts a messenger that is blocking. More... | |
PN_EXTERN int | pn_messenger_send (pn_messenger_t *messenger, int n) |
Sends messages in the outgoing message queue for a messenger. More... | |
PN_EXTERN int | pn_messenger_recv (pn_messenger_t *messenger, int limit) |
Instructs the messenger to receives up to limit messages into the incoming message queue of a messenger. More... | |
PN_EXTERN int | pn_messenger_receiving (pn_messenger_t *messenger) |
Returns the number of messages currently being received by a messenger. More... | |
PN_EXTERN int | pn_messenger_get (pn_messenger_t *messenger, pn_message_t *msg) |
Gets a message from the head of the incoming message queue of a messenger. More... | |
PN_EXTERN pn_tracker_t | pn_messenger_incoming_tracker (pn_messenger_t *messenger) |
Gets the tracker for the message most recently fetched by pn_messenger_get. More... | |
PN_EXTERN pn_subscription_t * | pn_messenger_incoming_subscription (pn_messenger_t *messenger) |
PN_EXTERN int | pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
Accepts the incoming messages identified by the tracker. More... | |
PN_EXTERN int | pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags) |
Rejects the incoming messages identified by the tracker. More... | |
PN_EXTERN int | pn_messenger_outgoing (pn_messenger_t *messenger) |
Returns the number of messages in the outgoing message queue of a messenger. More... | |
PN_EXTERN int | pn_messenger_incoming (pn_messenger_t *messenger) |
Returns 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) |
The messenger API provides a high level interface for sending and receiving AMQP messages.
#define PN_CUMULATIVE (0x1) |
typedef struct pn_messenger_t pn_messenger_t |
Messenger.
typedef struct pn_subscription_t pn_subscription_t |
Subscription.
typedef int64_t pn_tracker_t |
enum pn_status_t |
PN_EXTERN pn_messenger_t* pn_messenger | ( | const char * | name | ) |
Construct a new Messenger 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 | ||
) |
Accepts the incoming messages identified by the tracker.
Use the PN_CUMULATIVE flag to accept everything prior to the supplied tracker.
[in] | messenger | the messenger |
[in] | tracker | an incoming tracker |
[in] | flags | 0 or PN_CUMULATIVE |
PN_EXTERN int pn_messenger_errno | ( | pn_messenger_t * | messenger | ) |
Returns the error code for the Messenger.
[in] | messenger | the messenger to check for errors |
PN_EXTERN pn_error_t* pn_messenger_error | ( | pn_messenger_t * | messenger | ) |
Returns the error info for a Messenger.
[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, no longer valid on return |
PN_EXTERN int pn_messenger_get | ( | pn_messenger_t * | messenger, |
pn_message_t * | msg | ||
) |
Gets a message from the head of the incoming message queue of a messenger.
[in] | messenger | the messenger |
[out] | msg | upon return contains the message from the head of the queue |
PN_EXTERN const char* pn_messenger_get_certificate | ( | pn_messenger_t * | messenger | ) |
Gets the certificate file for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_get_incoming_window | ( | pn_messenger_t * | messenger | ) |
Gets the incoming window for a Messenger.
[in] | messenger | the Messenger |
PN_EXTERN int pn_messenger_get_outgoing_window | ( | pn_messenger_t * | messenger | ) |
Gets the outgoing window for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN const char* pn_messenger_get_password | ( | pn_messenger_t * | messenger | ) |
Gets the private key file password for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN const char* pn_messenger_get_private_key | ( | pn_messenger_t * | messenger | ) |
Gets the private key file for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_get_timeout | ( | pn_messenger_t * | messenger | ) |
Retrieves the timeout for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN const char* pn_messenger_get_trusted_certificates | ( | pn_messenger_t * | messenger | ) |
Gets the trusted certificates database for a Messenger.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_incoming | ( | pn_messenger_t * | messenger | ) |
Returns the number of messages in the incoming message queue of a messenger.
[in] | messenger | the Messenger |
PN_EXTERN pn_subscription_t* pn_messenger_incoming_subscription | ( | pn_messenger_t * | messenger | ) |
PN_EXTERN pn_tracker_t pn_messenger_incoming_tracker | ( | pn_messenger_t * | messenger | ) |
Gets the tracker for the message most recently fetched by pn_messenger_get.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_interrupt | ( | pn_messenger_t * | messenger | ) |
Interrupts a messenger that is blocking.
This method may be safely called from a different thread than the one that is blocking.
[in] | messenger | the Messenger |
PN_EXTERN bool pn_messenger_is_blocking | ( | pn_messenger_t * | messenger | ) |
PN_EXTERN const char* pn_messenger_name | ( | pn_messenger_t * | messenger | ) |
Retrieves the name of a Messenger.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_outgoing | ( | pn_messenger_t * | messenger | ) |
Returns the number of messages in the outgoing message queue of a messenger.
[in] | messenger | the Messenger |
PN_EXTERN pn_tracker_t pn_messenger_outgoing_tracker | ( | pn_messenger_t * | messenger | ) |
Gets the tracker for the message most recently provided to pn_messenger_put.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_put | ( | pn_messenger_t * | messenger, |
pn_message_t * | msg | ||
) |
Puts a message on the outgoing message queue for a messenger.
[in] | messenger | the messenger |
[in] | msg | the message to put on the outgoing queue |
PN_EXTERN int pn_messenger_receiving | ( | pn_messenger_t * | messenger | ) |
Returns the number of messages currently being received by a messenger.
[in] | messenger | the messenger |
PN_EXTERN int pn_messenger_recv | ( | pn_messenger_t * | messenger, |
int | limit | ||
) |
Instructs the messenger to receives up to limit messages into the incoming message queue of a messenger.
If limit is -1, 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 previos receive operation, so pn_messenger_recv(messenger, 0) will cancel any outstanding receive.
[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 | ||
) |
Rejects the incoming messages identified by the tracker.
Use the PN_CUMULATIVE flag to reject everything prior to the supplied tracker.
[in] | messenger | the Messenger |
[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 | ||
) |
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 int pn_messenger_send | ( | pn_messenger_t * | messenger, |
int | n | ||
) |
Sends messages in the outgoing message queue for a messenger.
This call will block until the indicated number of messages have been sent. If n is -1 this call will block until all outgoing messages have been sent. If n is 0 then this call won't block.
[in] | messenger | the messager |
[in] | n | the number of messages to send |
PN_EXTERN int pn_messenger_set_blocking | ( | pn_messenger_t * | messenger, |
bool | blocking | ||
) |
PN_EXTERN int pn_messenger_set_certificate | ( | pn_messenger_t * | messenger, |
const char * | certificate | ||
) |
Provides a certificate that will be used to identify the local Messenger to the peer.
[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 | ||
) |
Sets the incoming window for a Messenger.
If the incoming window is set to a positive value, then after each call to pn_messenger_accept or pn_messenger_reject, the Messenger will track the status of that many deliveries.
[in] | messenger | the Messenger |
[in] | window | the number of deliveries to track |
PN_EXTERN int pn_messenger_set_outgoing_window | ( | pn_messenger_t * | messenger, |
int | window | ||
) |
Sets the outgoing window for a Messenger.
If the outgoing window is set to a positive value, then after each call to pn_messenger_send, the Messenger will track the status of that many deliveries.
[in] | messenger | the Messenger |
[in] | window | the number of deliveries to track |
PN_EXTERN int pn_messenger_set_password | ( | pn_messenger_t * | messenger, |
const char * | password | ||
) |
Sets the private key password for a Messenger.
[in] | messenger | the messenger |
[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 | ||
) |
Provides the private key that was used to sign the certificate.
See pn_messenger_set_certificate
[in] | messenger | the Messenger |
[in] | private_key | a path to a private key file |
PN_EXTERN int pn_messenger_set_timeout | ( | pn_messenger_t * | messenger, |
int | timeout | ||
) |
Sets the timeout for a Messenger.
A negative timeout means infinite.
[in] | messenger | the messenger |
[in] | timeout | the 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.
Messenger will use this database to validate the certificate provided by the peer.
[in] | messenger | the messenger |
[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 | ) |
Starts a messenger.
A messenger cannot send or recv messages until it is started.
[in] | messenger | the messenger to start |
PN_EXTERN pn_status_t pn_messenger_status | ( | pn_messenger_t * | messenger, |
pn_tracker_t | tracker | ||
) |
Gets the last known remote state of the delivery associated with the given tracker.
[in] | messenger | the messenger |
[in] | tracker | the tracker identify the delivery |
PN_EXTERN int pn_messenger_stop | ( | pn_messenger_t * | messenger | ) |
Stops a messenger.
A messenger cannot send or recv messages when it is stopped.
[in] | messenger | the messenger to stop |
PN_EXTERN bool pn_messenger_stopped | ( | pn_messenger_t * | messenger | ) |
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 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 |
PN_EXTERN void* pn_subscription_get_context | ( | pn_subscription_t * | sub | ) |
PN_EXTERN void pn_subscription_set_context | ( | pn_subscription_t * | sub, |
void * | context | ||
) |