C AMQP Protocol Engine API  0.5
proton/messenger.h File Reference
Include dependency graph for messenger.h:

Go to the source code of this file.

Defines

#define PN_CUMULATIVE   (0x1)

Typedefs

typedef struct pn_messenger_t pn_messenger_t
typedef struct pn_subscription_t pn_subscription_t
typedef int64_t pn_tracker_t

Enumerations

enum  pn_status_t {
  PN_STATUS_UNKNOWN = 0, PN_STATUS_PENDING = 1, PN_STATUS_ACCEPTED = 2, PN_STATUS_REJECTED = 3,
  PN_STATUS_MODIFIED = 4
}

Functions

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

Detailed Description

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


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