AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.0.0
|
The main class for interacting with AMPS. More...
#include <ampsplusplus.hpp>
Public Member Functions | |
Client (const std::string &clientName="") | |
Constructs a new client with a given client name. More... | |
void | setName (const std::string &name) |
Sets the name of this client, assuming no name was provided previously. More... | |
const std::string & | getName () const |
Returns the name of this client passed in the constructor. More... | |
void | setLogonCorrelationData (const std::string &logonCorrelationData_) |
Sets the logon correlation data for the client. More... | |
const std::string & | getLogonCorrelationData () const |
Returns the currently set logoon correlation data for the client. More... | |
size_t | getServerVersion () const |
Returns the server version retrieved during logon. More... | |
VersionInfo | getServerVersionInfo () const |
Returns the server version retrieved during logon. More... | |
const std::string & | getURI () const |
Returns the last URI this client is connected to. More... | |
void | connect (const std::string &uri) |
Connect to an AMPS server. More... | |
void | disconnect () |
Disconnect from an AMPS server. More... | |
void | send (const Message &message) |
Sends a Message to the connected AMPS server. More... | |
void | addMessageHandler (const Field &commandId_, const AMPS::MessageHandler &messageHandler_, unsigned requestedAcks_, bool isSubscribe_) |
Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id. More... | |
bool | removeMessageHandler (const Field &commandId_) |
Removes a MessageHandler for a given ComandId from self. More... | |
std::string | send (MessageHandler messageHandler, Message &message, int timeout=0) |
Sends a Message to the connected AMPS server. More... | |
void | setDisconnectHandler (DisconnectHandler disconnectHandler) |
Sets the function to be called when the client is unintentionally disconnected. More... | |
DisconnectHandler | getDisconnectHandler (void) |
Returns the callback function that is invoked when a disconnect occurs. More... | |
virtual ConnectionInfo | getConnectionInfo () const |
Get the connection information for the current connection. More... | |
void | setBookmarkStore (const BookmarkStore &bookmarkStore_) |
Set the bookmark store to be used by the client. More... | |
BookmarkStore | getBookmarkStore () |
Get the bookmark store being used by the client. More... | |
SubscriptionManager * | getSubscriptionManager () |
Get the subscription manager being used by the client. More... | |
void | setSubscriptionManager (SubscriptionManager *subscriptionManager_) |
Set the subscription manager to be used by the client. More... | |
void | setPublishStore (const Store &publishStore_) |
Set the publish store to be used by the client. More... | |
Store | getPublishStore () |
Get the publish store used by the client. More... | |
void | setDuplicateMessageHandler (const MessageHandler &duplicateMessageHandler_) |
Sets a callback function that is invoked when a duplicate message is detected. More... | |
MessageHandler | getDuplicateMessageHandler (void) |
Returns the callback function that is invoked when a duplicate message is detected. More... | |
void | setFailedWriteHandler (FailedWriteHandler *handler_) |
Set the handler that is invoked to report on duplicate or not entitled messages that have been published. More... | |
FailedWriteHandler * | getFailedWriteHandler () |
Get the handler that is invoked to report on failed writes. More... | |
amps_uint64_t | publish (const std::string &topic_, const std::string &data_) |
Publish a message to an AMPS topic. More... | |
amps_uint64_t | publish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_) |
Publish a message to an AMPS topic. More... | |
amps_uint64_t | publish (const std::string &topic_, const std::string &data_, unsigned long expiration_) |
Publish a message to an AMPS topic. More... | |
amps_uint64_t | publish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_, unsigned long expiration_) |
Publish a message to an AMPS topic. More... | |
void | publishFlush (long timeout_=0) |
Ensures that AMPS messages are sent and have been processed by the AMPS server. More... | |
amps_uint64_t | deltaPublish (const std::string &topic_, const std::string &data_) |
Publish the changed fields of a message to an AMPS topic. More... | |
amps_uint64_t | deltaPublish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_) |
Publish the changed fields of a message to an AMPS topic. More... | |
amps_uint64_t | deltaPublish (const std::string &topic_, const std::string &data_, unsigned long expiration_) |
Publish the changed fields of a message to an AMPS topic. More... | |
amps_uint64_t | deltaPublish (const char *topic_, size_t topicLength_, const char *data_, size_t dataLength_, unsigned long expiration_) |
Publish the changed fields of a message to an AMPS topic. More... | |
std::string | logon (int timeout_=0, Authenticator &authenticator_=DefaultAuthenticator::instance(), const char *options_=NULL) |
Logon to the server. More... | |
std::string | logon (const char *options_, int timeout_=0) |
Logon to the server. More... | |
std::string | logon (const std::string &options_, int timeout_=0) |
Logon to the server. More... | |
std::string | subscribe (MessageHandler messageHandler_, const std::string &topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic. More... | |
MessageStream | subscribe (const std::string &topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic. More... | |
MessageStream | subscribe (const char *topic_, long timeout_=0, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic. More... | |
std::string | deltaSubscribe (MessageHandler messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Delta Subscribe to a topic. More... | |
MessageStream | deltaSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Delta Subscribe to a topic. More... | |
MessageStream | deltaSubscribe (const char *topic_, long timeout_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Delta Subscribe to a topic. More... | |
std::string | bookmarkSubscribe (MessageHandler messageHandler_, const std::string &topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic using a bookmark. More... | |
MessageStream | bookmarkSubscribe (const std::string &topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic using a bookmark. More... | |
MessageStream | bookmarkSubscribe (const char *topic_, long timeout_, const std::string &bookmark_, const std::string &filter_="", const std::string &options_="", const std::string &subId_="") |
Subscribe to a topic using a bookmark. More... | |
void | unsubscribe (const std::string &commandId) |
Unsubscribe from a topic. More... | |
void | unsubscribe () |
Unsubscribe from all topics. More... | |
std::string | sow (MessageHandler messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query a State-of-the-World topic. More... | |
MessageStream | sow (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic. More... | |
MessageStream | sow (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic. More... | |
std::string | sow (MessageHandler messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic. More... | |
std::string | sowAndSubscribe (MessageHandler messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
MessageStream | sowAndSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
MessageStream | sowAndSubscribe (const char *topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
std::string | sowAndSubscribe (MessageHandler messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
MessageStream | sowAndSubscribe (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
MessageStream | sowAndSubscribe (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", const std::string &bookmark_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new subscription on it. More... | |
std::string | sowAndDeltaSubscribe (MessageHandler messageHandler_, const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
MessageStream | sowAndDeltaSubscribe (const std::string &topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
MessageStream | sowAndDeltaSubscribe (const char *topic_, const std::string &filter_="", const std::string &orderBy_="", int batchSize_=DEFAULT_BATCH_SIZE, int topN_=DEFAULT_TOP_N, const std::string &options_="", long timeout_=DEFAULT_COMMAND_TIMEOUT) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
std::string | sowAndDeltaSubscribe (MessageHandler messageHandler_, const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
MessageStream | sowAndDeltaSubscribe (const std::string &topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
MessageStream | sowAndDeltaSubscribe (const char *topic_, long timeout_, const std::string &filter_="", int batchSize_=DEFAULT_BATCH_SIZE, bool oofEnabled_=false, bool sendEmpties_=false, int topN_=DEFAULT_TOP_N) |
Query the SOW cache of a topic and initiates a new delta subscription on it. More... | |
std::string | sowDelete (MessageHandler messageHandler, const std::string &topic, const std::string &filter, long timeout) |
Deletes one or more messages from a topic's SOW cache. More... | |
Message | sowDelete (const std::string &topic, const std::string &filter, long timeout=0) |
Deletes one or more messages from a topic's SOW cache. More... | |
void | startTimer () |
Sends a message to AMPS requesting that AMPS start a server-side timer. More... | |
std::string | stopTimer (MessageHandler messageHandler) |
Sends a message to AMPS requesting that AMPS stop the previously started timer. More... | |
std::string | sowDeleteByKeys (MessageHandler messageHandler_, const std::string &topic_, const std::string &keys_, long timeout_=0) |
Deletes messages that match SOW keys from a topic's SOW cache. More... | |
Message | sowDeleteByKeys (const std::string &topic_, const std::string &keys_, long timeout_=0) |
Deletes messages that match SOW keys from a topic's SOW cache. More... | |
std::string | sowDeleteByData (MessageHandler messageHandler_, const std::string &topic_, const std::string &data_, long timeout_=0) |
Deletes the message whose keys match the message data provided. More... | |
Message | sowDeleteByData (const std::string &topic_, const std::string &data_, long timeout_=0) |
Deletes the message whose keys match the message data provided. More... | |
amps_handle | getHandle () |
Returns the underlying amps_handle for this client, to be used with amps_client_* functions from the C api. More... | |
void | setExceptionListener (const ExceptionListener &listener_) |
Sets the exception listener for exceptions that are not thrown back to the user. More... | |
const ExceptionListener & | getExceptionListener (void) const |
Returns the exception listener for exceptions that are not thrown back to the user. More... | |
void | setHeartbeat (unsigned heartbeatTime_, unsigned readTimeout_) |
Sets the heartbeat time on this Client, Server and Transport. More... | |
void | setHeartbeat (unsigned heartbeatTime_) |
Sets the heartbeat time on this Client, Server and Transport. More... | |
void | setUnhandledMessageHandler (const AMPS::MessageHandler &messageHandler) |
Deprecated. Use setLastChanceMessageHandler instead. | |
void | setLastChanceMessageHandler (const AMPS::MessageHandler &messageHandler) |
Sets the message handler called when no other handler matches. More... | |
void | addConnectionStateListener (ConnectionStateListener *listener) |
Adds a ConnectionStateListener to self's set of listeners. More... | |
void | removeConnectionStateListener (ConnectionStateListener *listener) |
Attempts to remove listener from self's set of ConnectionStateListeners. More... | |
std::string | executeAsync (Command &command_, MessageHandler handler_) |
Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler. More... | |
std::string | executeAsyncNoResubscribe (Command &command_, MessageHandler handler_) |
Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler. More... | |
MessageStream | execute (Command &command_) |
Execute the provided command and return messages received in response in a MessageStream. More... | |
void | ack (Field &topic_, Field &bookmark_, const char *options_=NULL) |
ACK a message queue message by supplying a topic and bookmark. More... | |
void | ack (Message &message_, const char *options_=NULL) |
ACK a message queue message by supplying the message directly. More... | |
void | ack (const std::string &topic_, const std::string &bookmark_, const char *options_=NULL) |
ACK a message queue message by supplying a topic and bookmark string. More... | |
void | flushAcks (void) |
Sends any queued message queue ACK messages to the server immediately. | |
bool | getAutoAck (void) const |
Returns the value of the auto-ack setting. More... | |
void | setAutoAck (bool isAutoAckEnabled_) |
Sets the auto-ack setting on this client. More... | |
unsigned | getAckBatchSize (void) const |
Returns the value of the ack batch size setting. More... | |
void | setAckBatchSize (const unsigned ackBatchSize_) |
Sets the ack batch size setting. More... | |
int | getAckTimeout (void) const |
Returns the current value of the ack timeout setting. More... | |
void | setAckTimeout (const int ackTimeout_) |
Sets the message queue ACK timeout value. More... | |
void | setRetryOnDisconnect (bool isRetryOnDisconnect_) |
Enables or disables automatic retry of a command to AMPS after a reconnect. More... | |
bool | getRetryOnDisconnect (void) const |
Returns true if automatic retry of a command to AMPS after a reconnect is enabled. | |
void | setDefaultMaxDepth (unsigned maxDepth_) |
Sets a defualt max depth on all subsequently created MessageStream objects. More... | |
unsigned | getDefaultMaxDepth (void) const |
Returns the default max depth for returned MessageStream objects. More... | |
void | setTransportFilterFunction (amps_transport_filter_function filter_, void *userData_) |
Sets a filter function on the transport that is called with all raw data sent or received. More... | |
Static Public Member Functions | |
static size_t | convertVersionToNumber (const std::string &version_) |
Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More... | |
static size_t | convertVersionToNumber (const char *data_, size_t len_) |
Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion. More... | |
The main class for interacting with AMPS.
Client represents a single connection to an AMPS server, and provides methods for subscribing, publishing, and disconnecting.
|
inline |
Constructs a new client with a given client name.
clientName | Name for the client. This name is used for duplicate message detection and should be unique. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets. |
ACK a message queue message by supplying a topic and bookmark.
topic_ | The topic to acknowledge |
bookmark_ | The bookmark of the message to acknowledge |
options_ | The options string for the ack, such as cancel |
|
inline |
ACK a message queue message by supplying the message directly.
message_ | The message to acknowledge |
options_ | The options string for the ack, such as cancel |
|
inline |
ACK a message queue message by supplying a topic and bookmark string.
topic_ | The message queue topic to acknowledge |
bookmark_ | The bookmark to acknowledge |
options_ | The options string for the ack, such as cancel |
|
inline |
Adds a ConnectionStateListener to self's set of listeners.
These listeners are invoked whenever the connection state of this client changes (either becomes connected or disconnected.)
listener | The ConnectionStateListener to invoke. |
|
inline |
Adds a MessageHandler to be invoked for Messages with the given CommandId as their command id, sub id, or query id.
commandId_ | The command, query, or subid used to invoke the handler. |
messageHandler_ | The message handler to route to |
requestedAcks_ | The actual acks requested from amps for this command |
isSubscribe_ | True is the handler is for an ongoing subscription. |
|
inline |
Subscribe to a topic using a bookmark.
Initiates a subscription to a topic on the server.
messageHandler_ | The function to be invoked when messages for this topic arrive. |
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
bookmark_ | Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription Id to use for this subscription. When used with the 'replace' option, this is the subscription to be replaced. With a bookmark store, this is the subscription Id used for recovery. so, when using a persistent bookmark store, provide an explicit subscription Id that is consistent across application restarts. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Subscribe to a topic using a bookmark.
Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
bookmark_ | Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription Id to use for this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Subscribe to a topic using a bookmark.
Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
bookmark_ | Bookmark to supply with this subscription. This can be a bookmark within the journal file, or one of the Special Bookmark Values. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription Id to use for this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Connect to an AMPS server.
Connects to the AMPS server specified by the uri parameter.
uri | The URI of the desired AMPS server, with the format transport://user:password@host:port/protocol , for example, tcp://localhost:9007/amps . |
The elements in the URI string are as follows:
InvalidURIException | The URI passed in is invalid. |
ConnectionRefusedException | The connection could not be established. |
|
inlinestatic |
Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion.
This can be used to do comparisons such as client.getServerVersion() >= "3.8" Conversion works with any string that starts with a number, and will assume 0 for any portions of the version not present. So "4" will return 4000000, equivalent to "4.0.0.0"
version_ | The version string to convert. |
|
inlinestatic |
Converts a string version, such as "3.8.1.5" into the same numeric form used internally and returned by getServerVersion.
This can be used to do comparisons such as client.getServerVersion() >= "3.8" Conversion works with any string that starts with a number, and will assume 0 for any portions of the version not present. So "4" will return 4000000, equivalent to "4.0.0.0"
data_ | The pointer the start of the character data to convert. |
len_ | The length of the character data to convert. |
|
inline |
Publish the changed fields of a message to an AMPS topic.
Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
data_ | The data corresponding to the fields you'd like to change. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish the changed fields of a message to an AMPS topic.
Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
topicLength_ | The length, in bytes, of the topic string. |
data_ | The data corresponding to the fields you'd like to change. |
dataLength_ | The length, in bytes, of the data. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish the changed fields of a message to an AMPS topic.
Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
data_ | The data corresponding to the fields you'd like to change. |
expiration_ | The number of seconds until the message expires. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish the changed fields of a message to an AMPS topic.
Send a delta_publish to the server, indicating that only changed fields are included in the data portion of this message. If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
topicLength_ | The length, in bytes, of the topic string. |
data_ | The data corresponding to the fields you'd like to change. |
dataLength_ | The length, in bytes, of the data. |
expiration_ | The number of seconds until the message expires. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
|
inline |
Delta Subscribe to a topic.
Initiates a delta subscription to a topic on the server.
messageHandler_ | The function to be invoked when messages for this topic arrive. |
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
|
inline |
Delta Subscribe to a topic.
Initiates a delta subscription to a topic on the server, returning a MessageStream.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
|
inline |
Delta Subscribe to a topic.
Initiates a delta subscription to a topic on the server, returning a MessageStream.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
|
inline |
Disconnect from an AMPS server.
Disconnects from the currently-connected AMPS server.
|
inline |
Execute the provided command and return messages received in response in a MessageStream.
This method creates a message based on the provided Command, sends the message to AMPS, and receives the results. AMPS sends the message and receives the results on a background thread. That thread populates the MessageStream returned by this method.
command_ | The Command object containing the command to send to AMPS |
|
inline |
Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler.
This method creates a message based on the provided Command, sends the message to AMPS, and invokes the provided MessageHandler to process messages returned in response to the command. Rather than providing messages on the calling thread, the Client runs the MessageHandler directly on the client receive thread.
When the provided MessageHandler is valid (that is, the object contains a function to be called), this method blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgement are provided to the MessageHandler.
command_ | The Command object containing the command to send to AMPS |
handler_ | The MessageHandler to invoke to process messages received |
|
inline |
Execute the provided command and, once AMPS acknowledges the command, process messages in response to the command on the client receive thread by invoking the provided handler.
This method creates a message based on the provided Command, sends the message to AMPS, and invokes the provided MessageHandler to process messages returned in response to the command. Rather than providing messages on the calling thread, the Client runs the MessageHandler directly on the client receive thread.
When the provided MessageHandler is valid (that is, the object contains a function to be called), this method blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgement are provided to the MessageHandler.
When the provided Command is a form of subscribe, the subscription will not be placed into any SubscriptionMananger which may be in place. If a disconnect occurs, the subscription will need to be placed again.
While the provided Command doesn't have to be a form of subscribe, the main purpose of this function is to place a subscription that doesn't restart after a disconnect.
command_ | The Command object containing the command to send to AMPS |
handler_ | The MessageHandler to invoke to process messages received |
|
inline |
Returns the value of the ack batch size setting.
|
inline |
Returns the current value of the ack timeout setting.
|
inline |
Returns the value of the auto-ack setting.
|
inline |
Get the bookmark store being used by the client.
|
inlinevirtual |
Get the connection information for the current connection.
Reimplemented in AMPS::HAClient.
|
inline |
Returns the default max depth for returned MessageStream
objects.
|
inline |
Returns the callback function that is invoked when a disconnect occurs.
|
inline |
Returns the callback function that is invoked when a duplicate message is detected.
|
inline |
Returns the exception listener for exceptions that are not thrown back to the user.
|
inline |
Get the handler that is invoked to report on failed writes.
|
inline |
Returns the underlying amps_handle for this client, to be used with amps_client_* functions from the C api.
|
inline |
Returns the currently set logoon correlation data for the client.
|
inline |
Returns the name of this client passed in the constructor.
|
inline |
Get the publish store used by the client.
|
inline |
Returns the server version retrieved during logon.
If the client has not logged on or is connected to a server whose version is less than 3.8.0.0 this function will return 0. The version uses 2 digits each for major, minor, maintenance & hotfix i.e., 3.8.1.4 will return 3080104 Versions of AMPS prior to 3.8.0.0 do not return the server version to the client.
|
inline |
Returns the server version retrieved during logon.
If the client has not logged on or is connected to a server whose version is less than 3.8.0.0 this function will return a default version. Versions of AMPS prior to 3.8.0.0 do not return the server version to the client.
|
inline |
Get the subscription manager being used by the client.
|
inline |
Returns the last URI this client is connected to.
|
inline |
Logon to the server.
Sends a logon request to the server, using a custom authenticator
timeout_ | The time to wait, in milliseconds, for a response. (Default: 0 – wait forever.) |
authenticator_ | The custom authenticator to use in the logon process. |
options_ | The options to pass in with the logon command such as "conflation_interval=10ms". |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
NameInUseException | The specified client name is already in use on the server. |
|
inline |
Logon to the server.
Sends a logon request to the server using the DefaultAuthenticator and given options
options_ | The options to pass in with the logon command such as "conflation_interval=10ms". |
timeout_ | The time to wait, in milliseconds, for a response. (Default: 0 – wait forever.) |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
NameInUseException | The specified client name is already in use on the server. |
|
inline |
Logon to the server.
Sends a logon request to the server using the DefaultAuthenticator and given options
options_ | The options to pass in with the logon command such as "conflation_interval=10ms". |
timeout_ | The time to wait, in milliseconds, for a response. (Default: 0 – wait forever.) |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
NameInUseException | The specified client name is already in use on the server. |
|
inline |
Publish a message to an AMPS topic.
If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
data_ | The data to include in the message. |
DisconnectedException | The Client is not connected to a server; the program needs to call connect(). |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish a message to an AMPS topic.
If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
topicLength_ | The length, in bytes, of the topic string. |
data_ | The data to include in the message. |
dataLength_ | The length, in bytes, of the data. |
DisconnectedException | The Client is not connected to a server; the program needs to call connect(). |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish a message to an AMPS topic.
If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
data_ | The data to include in the message. |
expiration_ | The number of seconds after which the message should expire |
DisconnectedException | The Client is not connected to a server; the program needs to call connect(). |
ConnectionException | An error occured while sending the message. |
|
inline |
Publish a message to an AMPS topic.
If the client has a publish store set, then the client will store the message before forwarding the message to AMPS. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If a DisconnectException occurs, the message is still stored in the publish store.
topic_ | The topic to publish on. |
topicLength_ | The length, in bytes, of the topic string. |
data_ | The data to include in the message. |
dataLength_ | The length, in bytes, of the data. |
expiration_ | The number of seconds after which the message should expire |
DisconnectedException | The Client is not connected to a server; the program needs to call connect(). |
ConnectionException | An error occured while sending the message. |
|
inline |
Ensures that AMPS messages are sent and have been processed by the AMPS server.
When the client is connected to a server that implements the flush command, the client issues that command and waits for an acknowledgement. For older versions of AMPS, the client sends a publish to a dummy topic. This method blocks until messages have been processed or until the timeout expires, and is most useful when the application reaches a point at which it is acceptable to block to ensure that messages are delivered to the AMPS server. For example, an application might call publishFlush before exiting. One thing to note is that if AMPS is unavailable (HA Client), publishFlush needs to wait for a connection to come back up which may look like it's hanging.
timeout_ | The maximum amount of time to wait for flush to complete. Default is 0, which is no maximum. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | The publish command was not acked in the allowed time. |
|
inline |
Attempts to remove listener from self's set of ConnectionStateListeners.
listener | The ConnectionStateListener to remove. |
|
inline |
Removes a MessageHandler for a given ComandId from self.
commandId_ | The CommandId for which to remove the hanlder. |
|
inline |
Sends a Message to the connected AMPS server.
Sends the given Message to the connected AMPS server. The Message must be formatted properly with the appropriate fields set for the command you wish to issue. No adjustments are made to the message before sending.
message | The Message to send to the AMPS server. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
|
inline |
Sends a Message to the connected AMPS server.
Sends the given Message to the connected AMPS server. The Message must be formatted properly with the appropriate fields set for the command you wish to issue. No adjustments are made to the message before sending.
messageHandler | The MessageHandler to associate with this message. |
message | The message to send to the AMPS server. |
timeout | For synchronous messages, the time to wait for a response, in milliseconds. 0 indicates no timeout. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
NameInUseException | The specified client name is already in use on the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
InvalidTopicException | The specified topic may not be used with this command. |
SubscriptionAlreadyExistsException | This ID already exists as a subscription. |
|
inline |
Sets the ack batch size setting.
When set to a value greater than 1, message queue success ACK messages are not sent immediately, but are batched together for increased performance.
ackBatchSize_ | The batch size to use. |
|
inline |
Sets the message queue ACK timeout value.
When set, queued message queue ACK messages are sent when the oldest pending ACK for a message queue has exceeded the timeout.
ackTimeout_ | The ACK timeout value, in milliseconds. |
|
inline |
Sets the auto-ack setting on this client.
If true, message queue messages are automatically acknowledged upon successful return from your message handler. If your message handler throws an exception, the message is returned to the queue.
isAutoAckEnabled_ | The new value of the auto-ack setting. |
|
inline |
Set the bookmark store to be used by the client.
bookmarkStore_ | The bookmark store to use. |
AlreadyConnectedException | If called while the client is already connected |
|
inline |
Sets a defualt max depth on all subsequently created MessageStream
objects.
maxDepth_ | The new max depth to use. |
|
inline |
Sets the function to be called when the client is unintentionally disconnected.
Sets a callback function that is invoked when a disconnect is detected.
disconnectHandler | The callback to be invoked on disconnect. |
|
inline |
Sets a callback function that is invoked when a duplicate message is detected.
duplicateMessageHandler_ | The callback to be invoked. |
|
inline |
Sets the exception listener for exceptions that are not thrown back to the user.
listener_ | The exception listener to be used |
|
inline |
Set the handler that is invoked to report on duplicate or not entitled messages that have been published.
The Client takes ownership of the pointer.
handler_ | The handler to invoke for failed writes. |
|
inline |
Sets the heartbeat time on this Client, Server and Transport.
heartbeatTime_ | The time (seconds) to request the server heartbeat. |
readTimeout_ | The time (seconds) to allow a read before timing out. |
|
inline |
Sets the heartbeat time on this Client, Server and Transport.
heartbeatTime_ | The time (seconds) to request the server heartbeat. |
|
inline |
Sets the message handler called when no other handler matches.
messageHandler | The message handler to invoke when no other handler matches. |
|
inline |
Sets the logon correlation data for the client.
The data should be in base64 characters. It is not escaped when sent to the server and the server does not interpret the data. The data can provide some extra information about the client that is logging into the server that may not be available from just the client name and user id.
logonCorrelationData_ | The data to be sent with the logon. |
|
inline |
Sets the name of this client, assuming no name was provided previously.
This may only be called on client objects with no name.
name | Name for the client. This name is used for duplicate message detection and should be unique. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets. |
UsageException | An attempt was made to set a name on a client, but the client already has a name. |
|
inline |
Set the publish store to be used by the client.
publishStore_ | The publish store to use. |
AlreadyConnectedException | If called while the client is already connected |
|
inline |
Enables or disables automatic retry of a command to AMPS after a reconnect.
This behavior is enabled by default. NOTE: Clients using a publish store will have all publish messages sent, regardless of this setting. Also, Clients with a subscription manager, including all HAClients, will have all subscribe calls placed.
isRetryOnDisconnect_ | false will disable this behavior. |
|
inline |
Set the subscription manager to be used by the client.
subscriptionManager_ | The subscription manager to use. |
|
inline |
Sets a filter function on the transport that is called with all raw data sent or received.
filter_ | The amps_transport_filter_function to call. |
userData_ | Any data that should be passed to the function. |
|
inline |
Query the SOW cache of a topic.
Queries the SOW cache of a topic on the AMPS server, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
filter_ | Optional filter expression for this subscription. |
orderBy_ | Optional orderBy to have records ordered by server. |
bookmark_ | Optional bookmark for historical query. Bookmarks can be one of the Special Bookmark Values, the bookmark assigned to a specific message, or a timestamp of the format YYYYmmddTHHMMSS, as described in the AMPS User's Guide. |
batchSize_ | The number of records the server should pack into each message. |
topN_ | The maximum number of records the server will return (default is all that match). |
options_ | An 'or'ing of options for the command. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
InvalidTopicException | The specified topic may not be used with this command. |
SubscriptionAlreadyExistsException | This ID already exists as a subscription. |
|
inline |
Query the SOW cache of a topic and initiates a new delta subscription on it.
Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new delta subscription on it. Returns a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
filter_ | Optional filter expression for this subscription. |
orderBy_ | Optional orderBy to have records ordered by server. |
batchSize_ | The number of records the server should pack into each message. |
topN_ | The maximum number of records the server will return (default is all that match). |
options_ | An 'or'ing of options for the command. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
InvalidTopicException | The specified topic may not be used with this command. |
SubscriptionAlreadyExistsException | This ID already exists as a subscription. |
|
inline |
Query the SOW cache of a topic and initiates a new subscription on it.
Queries the SOW cache of a topic on the AMPS server, and simultaneously begins a new subscription, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
filter_ | Optional filter expression for this subscription. |
orderBy_ | Optional orderBy to have records ordered by server. |
bookmark_ | Optional bookmark for historical query. Bookmarks can be one of the Special Bookmark Values, the bookmark assigned to a specific message, or a timestamp of the format YYYYmmddTHHMMSS, as described in the AMPS User's Guide. |
batchSize_ | The number of records the server should pack into each message. |
topN_ | The maximum number of records the server will return (default is all that match). |
options_ | An 'or'ing of options for the command. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
InvalidTopicException | The specified topic may not be used with this command. |
SubscriptionAlreadyExistsException | This ID already exists as a subscription. |
|
inline |
Sends a message to AMPS requesting that AMPS start a server-side timer.
The application can later call stopTimer() to stop the timer and request a message with the results.
|
inline |
Sends a message to AMPS requesting that AMPS stop the previously started timer.
The provided MessageHandler will receive an acknowledgement with information about the timer.
messageHandler | The function to be invoked when the acknowledgement message arrives |
|
inline |
Subscribe to a topic.
Initiates a subscription to a topic on the server.
messageHandler_ | The function to be invoked when messages for this topic arrive. |
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Subscribe to a topic.
Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Subscribe to a topic.
Initiates a subscription to a topic on the server, returning a MessageStream to iterate over.
topic_ | The topic, or regular expression topic, to subscribe to. |
timeout_ | The time to wait, in milliseconds, for a response from the server. 0 indicates no timeout. |
filter_ | Optional filter expression for this subscription. |
options_ | Optional options to supply with this subscription. |
subId_ | Optional subscription id to use with this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
BadFilterException | The specified filter is not valid or has a syntax error. |
BadRegexTopicException | The specified topic contains an invalid regex. |
|
inline |
Unsubscribe from a topic.
Stops a subscription already placed on this Client.
commandId | The unique identifier for this subscription. |
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |
|
inline |
Unsubscribe from all topics.
Stops all active subscriptions on this client.
DisconnectedException | The Client is no longer connected to a server. |
ConnectionException | An error occured while sending the message. |
TimedOutException | A timeout occured while waiting for a response from the server. |
AuthenticationException | An authentication failure was received from the server. |
UnknownException | An unknown failure was received from the server. |