/builddir/build/BUILD/qpid-proton-0.10/proton-c/include/proton/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>
#include <proton/selectable.h>
#include <proton/condition.h>
#include <proton/terminus.h>
#include <proton/link.h>
#include <proton/transport.h>
#include <proton/ssl.h>

Go to the source code of this file.

Defines

#define PROTON_MESSENGER_H   1
#define PN_CUMULATIVE   (0x1)
 Indicates that an accept or reject should operate cumulatively.
#define PN_FLAGS_CHECK_ROUTES   (0x1)
#define PN_FLAGS_ALLOW_INSECURE_MECHS   (0x2)
 Messenger flag to indicate that a call \ to pn_messenger_start should check that \ any defined routes are valid.

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 = 0, PN_STATUS_PENDING = 1, PN_STATUS_ACCEPTED = 2, PN_STATUS_REJECTED = 3,
  PN_STATUS_RELEASED = 4, PN_STATUS_MODIFIED = 5, PN_STATUS_ABORTED = 6, PN_STATUS_SETTLED = 7
}
 

Describes all the possible states for a message associated with a given tracker.

More...

Functions

PN_EXTERN pn_messenger_tpn_messenger (const char *name)
 Construct a new pn_messenger_t with the given name.
PN_EXTERN const char * pn_messenger_name (pn_messenger_t *messenger)
 Get the name of a messenger.
PN_EXTERN 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.
PN_EXTERN const char * pn_messenger_get_certificate (pn_messenger_t *messenger)
 Get the certificate path.
PN_EXTERN 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.
PN_EXTERN const char * pn_messenger_get_private_key (pn_messenger_t *messenger)
 Gets the private key file for a messenger.
PN_EXTERN int pn_messenger_set_password (pn_messenger_t *messenger, const char *password)
 Sets the private key password for a messenger.
PN_EXTERN const char * pn_messenger_get_password (pn_messenger_t *messenger)
 Gets the private key file password for a messenger.
PN_EXTERN int pn_messenger_set_trusted_certificates (pn_messenger_t *messenger, const char *cert_db)
 Sets the trusted certificates database for a messenger.
PN_EXTERN const char * pn_messenger_get_trusted_certificates (pn_messenger_t *messenger)
 Gets the trusted certificates database for a messenger.
PN_EXTERN int pn_messenger_set_timeout (pn_messenger_t *messenger, int timeout)
 Set the default timeout for a messenger.
PN_EXTERN int pn_messenger_get_timeout (pn_messenger_t *messenger)
 Gets the timeout for a messenger object.
PN_EXTERN bool pn_messenger_is_blocking (pn_messenger_t *messenger)
 Check if a messenger is in blocking mode.
PN_EXTERN 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.
PN_EXTERN bool pn_messenger_is_passive (pn_messenger_t *messenger)
 Check if a messenger is in passive mode.
PN_EXTERN int pn_messenger_set_passive (pn_messenger_t *messenger, bool passive)
 Set the passive mode for a messenger.
PN_EXTERN void pn_messenger_free (pn_messenger_t *messenger)
 Frees a Messenger.
PN_EXTERN int pn_messenger_errno (pn_messenger_t *messenger)
 Get the code for a messenger's most recent error.
PN_EXTERN pn_error_tpn_messenger_error (pn_messenger_t *messenger)
 Get a messenger's error object.
PN_EXTERN int pn_messenger_get_outgoing_window (pn_messenger_t *messenger)
 Get the size of a messenger's outgoing window.
PN_EXTERN int pn_messenger_set_outgoing_window (pn_messenger_t *messenger, int window)
 Set the size of a messenger's outgoing window.
PN_EXTERN int pn_messenger_get_incoming_window (pn_messenger_t *messenger)
 Get the size of a messenger's incoming window.
PN_EXTERN int pn_messenger_set_incoming_window (pn_messenger_t *messenger, int window)
 Set the size of a messenger's incoming window.
PN_EXTERN int pn_messenger_start (pn_messenger_t *messenger)
 Currently a no-op placeholder.
PN_EXTERN int pn_messenger_stop (pn_messenger_t *messenger)
 Stops a messenger.
PN_EXTERN bool pn_messenger_stopped (pn_messenger_t *messenger)
 Returns true if a messenger is in the stopped state.
PN_EXTERN pn_subscription_tpn_messenger_subscribe (pn_messenger_t *messenger, const char *source)
 Subscribes a messenger to messages from the specified source.
PN_EXTERN pn_subscription_tpn_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_EXTERN pn_link_tpn_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.
PN_EXTERN void * pn_subscription_get_context (pn_subscription_t *sub)
 Get a subscription's application context.
PN_EXTERN void pn_subscription_set_context (pn_subscription_t *sub, void *context)
 Set an application context for a subscription.
PN_EXTERN const char * pn_subscription_address (pn_subscription_t *sub)
 Get the source address of a subscription.
PN_EXTERN int pn_messenger_put (pn_messenger_t *messenger, pn_message_t *msg)
 Puts a message onto the messenger's outgoing queue.
PN_EXTERN pn_status_t pn_messenger_status (pn_messenger_t *messenger, pn_tracker_t tracker)
 Track the status of a delivery.
PN_EXTERN pn_delivery_tpn_messenger_delivery (pn_messenger_t *messenger, pn_tracker_t tracker)
 Get delivery information about a delivery.
PN_EXTERN 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.
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.
PN_EXTERN 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.
PN_EXTERN int pn_messenger_work (pn_messenger_t *messenger, int timeout)
 Sends or receives any outstanding messages queued for a messenger.
PN_EXTERN int pn_messenger_interrupt (pn_messenger_t *messenger)
 Interrupt a messenger object that may be blocking in another thread.
PN_EXTERN int pn_messenger_send (pn_messenger_t *messenger, int n)
 Send messages from a messenger's outgoing queue.
PN_EXTERN int pn_messenger_recv (pn_messenger_t *messenger, int limit)
 Retrieve messages into a messenger's incoming queue.
PN_EXTERN int pn_messenger_receiving (pn_messenger_t *messenger)
 Get the capacity of the incoming message queue of a messenger.
PN_EXTERN 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_EXTERN 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_EXTERN pn_subscription_tpn_messenger_incoming_subscription (pn_messenger_t *messenger)
 Get the subscription of the message most recently retrieved by pn_messenger_get().
PN_EXTERN int pn_messenger_accept (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 Signal successful processing of message(s).
PN_EXTERN int pn_messenger_reject (pn_messenger_t *messenger, pn_tracker_t tracker, int flags)
 Signal unsuccessful processing of message(s).
PN_EXTERN pn_link_tpn_messenger_tracker_link (pn_messenger_t *messenger, pn_tracker_t tracker)
 Get link for the message referenced by the given tracker.
PN_EXTERN int pn_messenger_outgoing (pn_messenger_t *messenger)
 Get the number of messages in the outgoing message queue of a messenger.
PN_EXTERN int pn_messenger_incoming (pn_messenger_t *messenger)
 Get the number of messages in the incoming message queue of a messenger.
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.
PN_EXTERN int pn_messenger_rewrite (pn_messenger_t *messenger, const char *pattern, const char *address)
 Rewrite message addresses prior to transmission.
PN_EXTERN pn_selectable_tpn_messenger_selectable (pn_messenger_t *messenger)
 Extract selectables from a passive messenger.
PN_EXTERN pn_timestamp_t pn_messenger_deadline (pn_messenger_t *messenger)
 Get the nearest deadline for selectables associated with a messenger.
PN_EXTERN int pn_messenger_set_flags (pn_messenger_t *messenger, const int flags)
 Messenger flag to indicate that the PLAIN \ mechanism is allowed on an unencrypted \ connection.
PN_EXTERN int pn_messenger_get_flags (pn_messenger_t *messenger)
 Gets the flags for a Messenger.
PN_EXTERN 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.
PN_EXTERN 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.
PN_EXTERN void pn_messenger_set_tracer (pn_messenger_t *messenger, pn_tracer_t tracer)
 Set the tracer associated with a messenger.
PN_EXTERN 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.
PN_EXTERN int pn_messenger_set_ssl_peer_authentication_mode (pn_messenger_t *messenger, const pn_ssl_verify_mode_t mode)
 Sets the SSL peer authentiacation mode required when a trust certificate is used.

Detailed Description

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


Define Documentation

#define PN_FLAGS_ALLOW_INSECURE_MECHS   (0x2)

Messenger flag to indicate that a call \ to pn_messenger_start should check that \ any defined routes are valid.

#define PN_FLAGS_CHECK_ROUTES   (0x1)
#define PROTON_MESSENGER_H   1

Function Documentation

PN_EXTERN int pn_messenger_get_flags ( pn_messenger_t messenger  ) 

Gets the flags for a Messenger.

Parameters:
[in] messenger the messenger
Returns:
The flags set for the messenger
PN_EXTERN 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.

Parameters:
[in] messenger a messenger object
[in] address of remote service whose idle timeout is required
Returns:
the timeout in milliseconds or -1 if an error occurs
PN_EXTERN int pn_messenger_set_flags ( pn_messenger_t messenger,
const int  flags 
)

Messenger flag to indicate that the PLAIN \ mechanism is allowed on an unencrypted \ connection.

Sets control flags to enable additional function for the Messenger.

Parameters:
[in] messenger the messenger
[in] flags 0 or PN_FLAGS_CHECK_ROUTES
Returns:
an error code of zero if there is no error
PN_EXTERN 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.

Parameters:
[in] messenger the messenger
[in] mode the receiver settle mode
PN_EXTERN 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.

Parameters:
[in] messenger the messenger
[in] mode the sender settle mode
PN_EXTERN int pn_messenger_set_ssl_peer_authentication_mode ( pn_messenger_t messenger,
const pn_ssl_verify_mode_t  mode 
)

Sets the SSL peer authentiacation mode required when a trust certificate is used.

Parameters:
[in] messenger a messenger object
[in] mode the mode required (see pn_ssl_verify_mode_t enum for valid values)
Returns:
0 if successful or -1 if an error occurs
PN_EXTERN void pn_messenger_set_tracer ( pn_messenger_t messenger,
pn_tracer_t  tracer 
)

Set the tracer associated with a messenger.

Parameters:
[in] messenger a messenger object
[in] tracer the tracer callback
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 1 Oct 2015 for proton by  doxygen 1.6.1