proton  0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Macros | Typedefs | Enumerations | Functions
messenger.h File Reference

The messenger API provides a high level interface for sending and receiving AMQP messages. More...

#include <proton/import_export.h>
#include <proton/message.h>

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_tpn_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_tpn_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_tpn_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_tpn_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)
 

Detailed Description

The messenger API provides a high level interface for sending and receiving AMQP messages.

Macro Definition Documentation

#define PN_CUMULATIVE   (0x1)

Typedef Documentation

Messenger.

Subscription.

typedef int64_t pn_tracker_t

Enumeration Type Documentation

Enumerator
PN_STATUS_UNKNOWN 
PN_STATUS_PENDING 
PN_STATUS_ACCEPTED 
PN_STATUS_REJECTED 
PN_STATUS_MODIFIED 

Function Documentation

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.

Parameters
[in]namethe name of the messenger or NULL
Returns
pointer to a new 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.

Use the PN_CUMULATIVE flag to accept everything prior to the supplied tracker.

Parameters
[in]messengerthe messenger
[in]trackeran incoming tracker
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_errno ( pn_messenger_t messenger)

Returns the error code for the Messenger.

Parameters
[in]messengerthe messenger to check for errors
Returns
an error code or zero if there is no error
See Also
error.h
PN_EXTERN pn_error_t* pn_messenger_error ( pn_messenger_t messenger)

Returns the error info for a Messenger.

Parameters
[in]messengerthe messenger to check for errors
Returns
a pointer to the messenger's error descriptor
See Also
error.h
PN_EXTERN void pn_messenger_free ( pn_messenger_t messenger)

Frees a Messenger.

Parameters
[in]messengerthe messenger to free, 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.

Parameters
[in]messengerthe messenger
[out]msgupon return contains the message from the head of the queue
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN const char* pn_messenger_get_certificate ( pn_messenger_t messenger)

Gets the certificate file for a Messenger.

Parameters
[in]messengerthe messenger
Returns
the certificate file path
PN_EXTERN int pn_messenger_get_incoming_window ( pn_messenger_t messenger)

Gets the incoming window for a Messenger.

See Also
pn_messenger_set_incoming_window
Parameters
[in]messengerthe Messenger
Returns
the incoming window
PN_EXTERN int pn_messenger_get_outgoing_window ( pn_messenger_t messenger)

Gets the outgoing window for a Messenger.

See Also
pn_messenger_set_outgoing_window
Parameters
[in]messengerthe messenger
Returns
the outgoing window
PN_EXTERN const char* pn_messenger_get_password ( pn_messenger_t messenger)

Gets the private key file password for a Messenger.

Parameters
[in]messengerthe messenger
Returns
password for the private key file
PN_EXTERN const char* pn_messenger_get_private_key ( pn_messenger_t messenger)

Gets the private key file for a Messenger.

Parameters
[in]messengerthe messenger
Returns
the private key file path
PN_EXTERN int pn_messenger_get_timeout ( pn_messenger_t messenger)

Retrieves the timeout for a Messenger.

Parameters
[in]messengerthe messenger
Returns
the timeout for the messenger, in milliseconds
PN_EXTERN const char* pn_messenger_get_trusted_certificates ( pn_messenger_t messenger)

Gets the trusted certificates database for a Messenger.

Parameters
[in]messengerthe messenger
Returns
path to the trusted certificates database
PN_EXTERN int pn_messenger_incoming ( pn_messenger_t messenger)

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

Parameters
[in]messengerthe Messenger
Returns
the incoming queue depth
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.

Parameters
[in]messengerthe messenger
Returns
a pn_tracker_t or an undefined value if pn_messenger_get has never been called for the given messenger
PN_EXTERN int pn_messenger_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.

Parameters
[in]messengerthe 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.

Parameters
[in]messengerthe messenger
Returns
the name of 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.

Parameters
[in]messengerthe Messenger
Returns
the outgoing queue depth
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.

Parameters
[in]messengerthe messenger
Returns
a pn_tracker_t or an undefined value if pn_messenger_get has never been called for the given messenger
PN_EXTERN int pn_messenger_put ( pn_messenger_t messenger,
pn_message_t msg 
)

Puts a message on the outgoing message queue for a messenger.

Parameters
[in]messengerthe messenger
[in]msgthe message to put on the outgoing queue
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_receiving ( pn_messenger_t messenger)

Returns the number of messages currently being received by a messenger.

Parameters
[in]messengerthe 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.

Parameters
[in]messengerthe messenger
[in]limitthe maximum number of messages to receive or -1 to to receive as many messages as it can buffer internally.
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_reject ( pn_messenger_t messenger,
pn_tracker_t  tracker,
int  flags 
)

Rejects the incoming messages identified by the tracker.

Use the PN_CUMULATIVE flag to reject everything prior to the supplied tracker.

Parameters
[in]messengerthe Messenger
[in]trackeran incoming tracker
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_rewrite ( pn_messenger_t messenger,
const char *  pattern,
const char *  address 
)
PN_EXTERN int pn_messenger_route ( pn_messenger_t messenger,
const char *  pattern,
const char *  address 
)

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

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

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

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

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

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

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

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

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

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

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

Route all messages over TLS:

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

Supply credentials for foo.com:

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

Supply credentials for all domains:

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

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

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

Route any address through a single broker:

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

Parameters
[in]messengerthe Messenger
[in]patterna glob pattern
[in]addressan address indicating alternative routing
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN 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.

Parameters
[in]messengerthe messager
[in]nthe number of messages to send
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_set_blocking ( pn_messenger_t messenger,
bool  blocking 
)
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.

Parameters
[in]messengerthe messenger
[in]certificatea path to a certificate file
Returns
an error code of zero if there is no error
PN_EXTERN int pn_messenger_set_incoming_window ( pn_messenger_t messenger,
int  window 
)

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.

See Also
pn_messenger_status
Parameters
[in]messengerthe Messenger
[in]windowthe number of deliveries to track
Returns
an error or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_set_outgoing_window ( pn_messenger_t messenger,
int  window 
)

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.

See Also
pn_messenger_status
Parameters
[in]messengerthe Messenger
[in]windowthe number of deliveries to track
Returns
an error or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_set_password ( pn_messenger_t messenger,
const char *  password 
)

Sets the private key password for a Messenger.

Parameters
[in]messengerthe messenger
[in]passwordthe password for the private key file
Returns
an error code of zero if there is no error
PN_EXTERN int pn_messenger_set_private_key ( pn_messenger_t messenger,
const char *  private_key 
)

Provides the private key that was used to sign the certificate.

See pn_messenger_set_certificate

Parameters
[in]messengerthe Messenger
[in]private_keya path to a private key file
Returns
an error code of zero if there is no error
PN_EXTERN int pn_messenger_set_timeout ( pn_messenger_t messenger,
int  timeout 
)

Sets the timeout for a Messenger.

A negative timeout means infinite.

Parameters
[in]messengerthe messenger
[in]timeoutthe new timeout for the messenger, in milliseconds
Returns
an error code or zero if there is no error
PN_EXTERN int pn_messenger_set_trusted_certificates ( pn_messenger_t messenger,
const char *  cert_db 
)

Sets the trusted certificates database for a Messenger.

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

Parameters
[in]messengerthe messenger
[in]cert_dba path to the certificates database
Returns
an error code of zero if there is no error
PN_EXTERN int pn_messenger_settle ( pn_messenger_t messenger,
pn_tracker_t  tracker,
int  flags 
)

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

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

Parameters
[in]messengerthe Messenger
[in]trackeridentifies a delivery
[in]flags0 or PN_CUMULATIVE
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_start ( pn_messenger_t messenger)

Starts a messenger.

A messenger cannot send or recv messages until it is started.

Parameters
[in]messengerthe messenger to start
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN pn_status_t pn_messenger_status ( pn_messenger_t messenger,
pn_tracker_t  tracker 
)

Gets the last known remote state of the delivery associated with the given tracker.

Parameters
[in]messengerthe messenger
[in]trackerthe tracker identify the delivery
Returns
a status code for 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.

Parameters
[in]messengerthe messenger to stop
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN bool pn_messenger_stopped ( pn_messenger_t messenger)
PN_EXTERN pn_subscription_t* pn_messenger_subscribe ( pn_messenger_t messenger,
const char *  source 
)

Subscribes a messenger to messages from the specified source.

Parameters
[in]messengerthe messenger to subscribe
[in]source
Returns
a subscription
PN_EXTERN int pn_messenger_work ( pn_messenger_t messenger,
int  timeout 
)

Sends or receives any outstanding messages queued for a messenger.

This will block for the indicated timeout.

Parameters
[in]messengerthe Messenger
[in]timeoutthe maximum time to block
PN_EXTERN void* pn_subscription_get_context ( pn_subscription_t sub)
PN_EXTERN void pn_subscription_set_context ( pn_subscription_t sub,
void *  context 
)