C AMQP Protocol Engine API  0.4
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
messenger.h File Reference
Include dependency graph for messenger.h:

Go to the source code of this file.

Macros

#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_accept_mode_t { PN_ACCEPT_MODE_AUTO, PN_ACCEPT_MODE_MANUAL }
 
enum  pn_status_t { PN_STATUS_UNKNOWN = 0, PN_STATUS_PENDING = 1, PN_STATUS_ACCEPTED = 2, PN_STATUS_REJECTED = 3 }
 

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 void pn_messenger_free (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_errno (pn_messenger_t *messenger)
 
PN_EXTERN const char * pn_messenger_error (pn_messenger_t *messenger)
 
PN_EXTERN pn_accept_mode_t pn_messenger_get_accept_mode (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_set_accept_mode (pn_messenger_t *messenger, pn_accept_mode_t mode)
 
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 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_send (pn_messenger_t *messenger)
 
PN_EXTERN int pn_messenger_recv (pn_messenger_t *messenger, int n)
 
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)
 

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_ACCEPT_MODE_AUTO 
PN_ACCEPT_MODE_MANUAL 
Enumerator
PN_STATUS_UNKNOWN 
PN_STATUS_PENDING 
PN_STATUS_ACCEPTED 
PN_STATUS_REJECTED 

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 const char* pn_messenger_error ( pn_messenger_t messenger)

Returns the error info for a Messenger.

Parameters
[in]messengerthe messenger to check for errors
Returns
a descriptive error message or NULL if no error has occurred
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 pn_accept_mode_t pn_messenger_get_accept_mode ( pn_messenger_t messenger)

Gets the accept mode for a Messenger.

See Also
pn_messenger_set_accept_mode
Parameters
[in]messengerthe messenger
Returns
one of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
PN_EXTERN const char* pn_messenger_get_certificate ( pn_messenger_t messenger)

Gets the certificate file fora 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 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_recv ( pn_messenger_t messenger,
int  n 
)

Receives up to n messages into the incoming message queue of a messenger. If n is -1, Messenger will be able to receive as many messages as it can buffer internally. Blocks until at least one message is available in the incoming queue.

Parameters
[in]messengerthe messenger
[in]nthe 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_send ( pn_messenger_t messenger)

Sends any messages in the outgoing message queue for a messenger. This will block until the messages have been sent.

Parameters
[in]messengerthe messager
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_set_accept_mode ( pn_messenger_t messenger,
pn_accept_mode_t  mode 
)

Set the accept mode for a Messenger. If set to PN_ACCEPT_MODE_AUTO, the messenger will automatically accept every message as it is returned by pn_messenger_get(). If set to PN_ACCEPT_MODE_MANUAL, incoming messages must be manually accepted or rejected (either individually or cumulatively) via pn_messenger_accept() and/or pn_messenger_reject().

Parameters
[in]messengerthe messenger to set the accept mode for
[in]modeone of PN_ACCEPT_MODE_AUTO or PN_ACCEPT_MODE_MANUAL
Returns
an error code or zero on success
See Also
error.h
PN_EXTERN int pn_messenger_set_certificate ( pn_messenger_t messenger,
const char *  certificate 
)

Sets the certificate file for a Messenger.

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 
)

Sets the private key file for a Messenger.

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.

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 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 void* pn_subscription_get_context ( pn_subscription_t sub)
PN_EXTERN void pn_subscription_set_context ( pn_subscription_t sub,
void *  context 
)