AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.3.2
|
Core type and function declarations for the AMPS C client. More...
#include <netdb.h>
#include <netinet/ip.h>
#include <errno.h>
#include <pthread.h>
#include <unistd.h>
#include <string.h>
#include <time.h>
#include <stdio.h>
#include "amps_generated.h"
Go to the source code of this file.
Typedefs | |
typedef void * | amps_handle |
Opaque handle type used to refer to objects in the AMPS api. More... | |
typedef void(* | amps_transport_filter_function) (const unsigned char *, size_t, short, void *) |
Prototype for a user-supplied callback function for filtering data before it is sent and after it is received. More... | |
typedef amps_result(* | amps_thread_created_callback) (AMPS_THREAD_T, void *) |
Prototype for a user-supplied callback function to allow thread attributes to be set when a new thread is created for a connection. More... | |
Enumerations |
Functions | |
amps_handle AMPSDLL | amps_client_create (const amps_char *clientName) |
Functions for creation of an AMPS client. More... | |
amps_result AMPSDLL | amps_client_set_name (amps_handle handle, const amps_char *clientName) |
Sets the name on an amps client object. More... | |
amps_result AMPSDLL | amps_client_connect (amps_handle handle, const amps_char *uri) |
Connects to the AMPS server specified in uri. More... | |
void AMPSDLL | amps_client_disconnect (amps_handle handle) |
Disconnects from the AMPS server, if connected. More... | |
void AMPSDLL | amps_client_destroy (amps_handle handle) |
Disconnects and destroys an AMPS client object. More... | |
size_t | amps_client_get_error (amps_handle client, amps_char *errorMessageOut, size_t bufferSize) |
Returns the last error set on this client. More... | |
amps_result | amps_client_send (amps_handle client, amps_handle message) |
Sends a message to the AMPS server. More... | |
amps_result | amps_client_send_with_version (amps_handle client, amps_handle message, unsigned *version_out) |
Sends a message to the AMPS server. More... | |
void | amps_client_set_message_handler (amps_handle client, amps_handler messageHandler, void *userData) |
Sets the message handler function for this client. More... | |
void | amps_client_set_predisconnect_handler (amps_handle client, amps_predisconnect_handler predisconnectHandler, void *userData) |
Sets the predisconnect handler function to be called when a disconnect occurs. More... | |
void | amps_client_set_disconnect_handler (amps_handle client, amps_handler disconnectHandler, void *userData) |
Sets the disconnect handler function to be called when a disconnect occurs. More... | |
amps_handle | amps_client_get_transport (amps_handle client) |
Returns a handle to the transport set in client, or NULL if no transport is associated with this transport. More... | |
amps_result | amps_client_attempt_reconnect (amps_handle client, unsigned version) |
Manually invokes the user-supplied disconnect handler for this client. More... | |
amps_handle | amps_message_create (amps_handle client) |
Functions for creation and manipulation of AMPS messages. More... | |
amps_handle | amps_message_copy (amps_handle message) |
Creates and returns a handle to a new AMPS message object that is a deep copy of the message passed in. More... | |
void | amps_message_destroy (amps_handle message) |
Destroys and frees the memory associated with an AMPS message object. More... | |
void | amps_message_reset (amps_handle message) |
Clears all fields and data in a message. More... | |
void | amps_message_get_field_value (amps_handle message, FieldId field, const amps_char **value_ptr, size_t *length_ptr) |
Retrieves the value of a header field in an AMPS message. More... | |
void | amps_message_set_field_value (amps_handle message, FieldId field, const amps_char *value, size_t length) |
Sets the value of a header field in an AMPS message. More... | |
void | amps_message_assign_field_value (amps_handle message, FieldId field, const amps_char *value, size_t length) |
Assigns the value of a header field in an AMPS message, without copying the value. More... | |
void | amps_message_set_field_value_nts (amps_handle message, FieldId field, const amps_char *value) |
Sets the value of a header field in an AMPS message from a null-terminated string. More... | |
void | amps_message_set_field_guid (amps_handle message, FieldId field) |
Sets the value of a header field in an AMPS message to a new, globally unique identifier("GUID") More... | |
void | amps_message_set_data (amps_handle message, const amps_char *value, size_t length) |
Sets the data component of an AMPS message. More... | |
void | amps_message_assign_data (amps_handle message, const amps_char *value, size_t length) |
Assigns the data component of an AMPS message, without copying the value. More... | |
void | amps_message_set_data_nts (amps_handle message, const amps_char *value) |
Sets the data component of an AMPS message. More... | |
void | amps_message_get_data (amps_handle message, amps_char **value_ptr, size_t *length_ptr) |
Gets the data component of an AMPS message. More... | |
unsigned long | amps_message_get_field_long (amps_handle message, FieldId field) |
Gets the long integer value of a header field in an AMPS message. More... | |
amps_uint64_t | amps_message_get_field_uint64 (amps_handle message, FieldId field) |
Gets the unsigned 64-bit int value of a header field in an AMPS message. More... | |
amps_result | amps_client_set_read_timeout (amps_handle client, int readTimeout) |
Sets a read timeout (seconds), in which if no message is received, the connection is presumed dead. More... | |
amps_result | amps_client_set_idle_time (amps_handle client, int idleTime) |
Sets an idle-time (milliseconds). More... | |
amps_result | amps_client_set_transport_filter_function (amps_handle client, amps_transport_filter_function filter, void *userData) |
Sets a user-supplied callback function for filtering data before it is sent and after it is received. More... | |
amps_result | amps_client_set_thread_created_callback (amps_handle client, amps_thread_created_callback callback, void *userData) |
Sets a user-supplied callback function to allow thread attributes to set when a new thread is created for a connection. More... | |
AMPS_SOCKET | amps_tcp_get_socket (amps_handle transport) |
TRANSPORT-SPECIFIC APIS. More... | |
void * | amps_tcps_get_SSL (amps_handle transport) |
Retrieves the SSL object from the underlying TCPS transport. More... | |
int | amps_ssl_init (const char *dllPath_) |
Initializes SSL support in the AMPS Client. More... | |
int | amps_ssl_set_verify (int mode_) |
Configures OpenSSL to validate the server's certificate when connecting. More... | |
int | amps_ssl_load_verify_locations (const char *caFile_, const char *caPath_) |
Configures OpenSSL to use the specified locations for locating CA certificates. More... | |
void | amps_ssl_free (void) |
Frees OpenSSL context and shared library. More... | |
const char * | amps_ssl_get_error (void) |
Returns the description of the last error from calling amps_ssl_init(). More... | |
Core type and function declarations for the AMPS C client.
typedef void* amps_handle |
Opaque handle type used to refer to objects in the AMPS api.
Opaque handle type used to refer to objects in the AMPS api. The size of a pointer.
typedef amps_result(* amps_thread_created_callback) (AMPS_THREAD_T, void *) |
Prototype for a user-supplied callback function to allow thread attributes to be set when a new thread is created for a connection.
The callback takes two parameters: thread A native handle for the thread. userdata A user-defined void* supplied with the callback.
typedef void(* amps_transport_filter_function) (const unsigned char *, size_t, short, void *) |
Prototype for a user-supplied callback function for filtering data before it is sent and after it is received.
The callback takes four parameters: data An unsigned char* that points to the raw data bytes. len The length of the data. direction 0 if data is outgoing/sent, 1 if data is incoming/received. userdata A user-defined void* supplied with the callback.
enum amps_result |
Return values from amps_xxx functions.
amps_result amps_client_attempt_reconnect | ( | amps_handle | client, |
unsigned | version | ||
) |
Manually invokes the user-supplied disconnect handler for this client.
client | An AMPS client object on which to attempt reconnect. |
version | The connection version that failed and is attempting reconnect. |
amps_result AMPSDLL amps_client_connect | ( | amps_handle | handle, |
const amps_char * | uri | ||
) |
Connects to the AMPS server specified in uri.
handle | The handle to a client created with amps_client_create(). |
uri | An AMPS uri, e.g. tcp://localhost:9004/nvfix |
amps_handle AMPSDLL amps_client_create | ( | const amps_char * | clientName | ) |
Functions for creation of an AMPS client.
Creates and returns a handle to a new amps client object.
clientName | A null-terminated, unique name for this client, or NULL if one will be supplied later. |
void AMPSDLL amps_client_destroy | ( | amps_handle | handle | ) |
Disconnects and destroys an AMPS client object.
Destroys the AMPS client object, and frees all resources associated with the client and any underlying transport.
handle | the client object to destroy. |
void AMPSDLL amps_client_disconnect | ( | amps_handle | handle | ) |
Disconnects from the AMPS server, if connected.
handle | The handle to a client created with amps_client_create(). |
size_t amps_client_get_error | ( | amps_handle | client, |
amps_char * | errorMessageOut, | ||
size_t | bufferSize | ||
) |
Returns the last error set on this client.
The result is undefined if the last operation on the client was successful.
client | The client handle to retrieve the last error for. |
errorMessageOut | A buffer to place the error message into, as a null-terminated string. |
bufferSize | The size, in bytes, of the buffer passed in errorMessageOut. |
amps_handle amps_client_get_transport | ( | amps_handle | client | ) |
Returns a handle to the transport set in client, or NULL if no transport is associated with this transport.
client | An AMPS client object from which to get the transport handle. |
amps_result amps_client_send | ( | amps_handle | client, |
amps_handle | message | ||
) |
Sends a message to the AMPS server.
client | The client to sent the message on. |
message | An AMPS message to send. |
amps_result amps_client_send_with_version | ( | amps_handle | client, |
amps_handle | message, | ||
unsigned * | version_out | ||
) |
Sends a message to the AMPS server.
client | The client to sent the message on. |
message | An AMPS message to send. |
version_out | The connection version used to send the message. |
void amps_client_set_disconnect_handler | ( | amps_handle | client, |
amps_handler | disconnectHandler, | ||
void * | userData | ||
) |
Sets the disconnect handler function to be called when a disconnect occurs.
client | An AMPS client object on which to set this handler. |
disconnectHandler | A pointer to function of signature: amps_result myfunction(amps_handle client, void* userData) to be called when a disconnect occurs on client. |
userData | User-defined data to be passed to the handler function |
amps_result amps_client_set_idle_time | ( | amps_handle | client, |
int | idleTime | ||
) |
Sets an idle-time (milliseconds).
If no message arrives in this time, the message handler is invoked with a NULL message handle, which allows the application to perform background processing on the message handler thread if it chooses.
client | The client on which to request idle time. |
idleTime | The time in milliseconds. |
void amps_client_set_message_handler | ( | amps_handle | client, |
amps_handler | messageHandler, | ||
void * | userData | ||
) |
Sets the message handler function for this client.
client | An AMPS client object. |
messageHandler | A pointer to function of signature: amps_result myfunction(amps_handle message, void* userData) that is called when a message arrives. |
userData | User-defined data to be passed to the handler function. |
amps_result AMPSDLL amps_client_set_name | ( | amps_handle | handle, |
const amps_char * | clientName | ||
) |
Sets the name on an amps client object.
This may only be called for client that do not already have a name set via a previous call to this function, or amps_client_create.
handle | The client object on which to set the name. |
clientName | A null-terminated, unique name for this client. |
void amps_client_set_predisconnect_handler | ( | amps_handle | client, |
amps_predisconnect_handler | predisconnectHandler, | ||
void * | userData | ||
) |
Sets the predisconnect handler function to be called when a disconnect occurs.
client | An AMPS client object on which to set this handler. |
predisconnectHandler | A pointer to function of signature: amps_result myfunction(amps_handle client, void* userData) to be called when a disconnect occurs on client. |
userData | User-defined data to be passed to the handler function |
amps_result amps_client_set_read_timeout | ( | amps_handle | client, |
int | readTimeout | ||
) |
Sets a read timeout (seconds), in which if no message is received, the connection is presumed dead.
Useful when a specific publish rate is expected, OR when using server heartbeating via the `heartbeat' command.
client | The client on which to set the read timeout. |
readTimeout | The timeout in seconds. |
amps_result amps_client_set_thread_created_callback | ( | amps_handle | client, |
amps_thread_created_callback | callback, | ||
void * | userData | ||
) |
Sets a user-supplied callback function to allow thread attributes to set when a new thread is created for a connection.
The callback takes two parameters: thread A native handle for the thread. userdata A user-defined void* supplied with the callback.
client | The client on which to set the callback function. |
callback | The callback function to invoke. |
userData | The user data that should be included in each call to the callback. |
amps_result amps_client_set_transport_filter_function | ( | amps_handle | client, |
amps_transport_filter_function | filter, | ||
void * | userData | ||
) |
Sets a user-supplied callback function for filtering data before it is sent and after it is received.
The callback takes four parameters: data An unsigned char* that points to the raw data bytes. len The length of the data. direction 0 if data is outgoing/sent, 1 if data is incoming/received. userdata A user-defined void* supplied with the callback.
client | The client on which to set the callback function. |
filter | The filter function pointer. |
userData | The user data that should be included in each call to the filter. |
void amps_message_assign_data | ( | amps_handle | message, |
const amps_char * | value, | ||
size_t | length | ||
) |
Assigns the data component of an AMPS message, without copying the value.
message | The AMPS message to set the data of. |
value | The value to set the data with. |
length | The length of the value |
void amps_message_assign_field_value | ( | amps_handle | message, |
FieldId | field, | ||
const amps_char * | value, | ||
size_t | length | ||
) |
Assigns the value of a header field in an AMPS message, without copying the value.
message | The AMPS message to mutate |
field | The header field to set. |
value | The value to set. |
length | The length (excluding any null-terminator) of the value |
amps_handle amps_message_copy | ( | amps_handle | message | ) |
Creates and returns a handle to a new AMPS message object that is a deep copy of the message passed in.
message | The message to copy. |
amps_handle amps_message_create | ( | amps_handle | client | ) |
Functions for creation and manipulation of AMPS messages.
Creates and returns a handle to a new AMPS message object for client.
client | The client for which a new message should be constructed. |
void amps_message_destroy | ( | amps_handle | message | ) |
Destroys and frees the memory associated with an AMPS message object.
message | A handle to the message to destroy. |
void amps_message_get_data | ( | amps_handle | message, |
amps_char ** | value_ptr, | ||
size_t * | length_ptr | ||
) |
Gets the data component of an AMPS message.
message | The AMPS message to get the data of. |
value_ptr | A pointer to an amps_char* that is modifed to reflect the address of the data of this message. |
length_ptr | A pointer to a size_t that will be modified to reflect the length of the data of this message. |
Note: The returned data is not null-terminated, and is owned by the message. You may wish to copy the data into your own memory for safe-keeping.
unsigned long amps_message_get_field_long | ( | amps_handle | message, |
FieldId | field | ||
) |
Gets the long integer value of a header field in an AMPS message.
message | The message to examine. |
field | The field containing the long data. |
amps_uint64_t amps_message_get_field_uint64 | ( | amps_handle | message, |
FieldId | field | ||
) |
Gets the unsigned 64-bit int value of a header field in an AMPS message.
message | The message to examine. |
field | The field containing the long data. |
void amps_message_get_field_value | ( | amps_handle | message, |
FieldId | field, | ||
const amps_char ** | value_ptr, | ||
size_t * | length_ptr | ||
) |
Retrieves the value of a header field in an AMPS message.
message | The AMPS message from which the value is retrieved. |
field | The header field to retrieve the value of. |
value_ptr | The address of an amps_char* pointer. This pointer is modified by amps_message_get_field_value() to point at the data for this field. |
length_ptr | The address of a size_t in which the length of the data is written. |
Note: The returned data is not null-terminated, and is owned by the message. You may wish to copy the data into your own memory for safe-keeping.
void amps_message_reset | ( | amps_handle | message | ) |
Clears all fields and data in a message.
This restores the message to the same state it had at creation, but with much higher performance.
message | A handle to the message to clear. |
void amps_message_set_data | ( | amps_handle | message, |
const amps_char * | value, | ||
size_t | length | ||
) |
Sets the data component of an AMPS message.
message | The AMPS message to set the data of. |
value | The value to set the data with. |
length | The length of the value |
void amps_message_set_data_nts | ( | amps_handle | message, |
const amps_char * | value | ||
) |
Sets the data component of an AMPS message.
message | The AMPS message to set the data of. |
value | The null-terminated string value to set the data with. |
void amps_message_set_field_guid | ( | amps_handle | message, |
FieldId | field | ||
) |
Sets the value of a header field in an AMPS message to a new, globally unique identifier("GUID")
message | The AMPS message to mutate. |
field | The field to apply the new GUID to. |
void amps_message_set_field_value | ( | amps_handle | message, |
FieldId | field, | ||
const amps_char * | value, | ||
size_t | length | ||
) |
Sets the value of a header field in an AMPS message.
message | The AMPS message to mutate |
field | The header field to set. |
value | The value to set. |
length | The length (excluding any null-terminator) of the value |
void amps_message_set_field_value_nts | ( | amps_handle | message, |
FieldId | field, | ||
const amps_char * | value | ||
) |
Sets the value of a header field in an AMPS message from a null-terminated string.
message | The AMPS message to mutate. |
field | The field to set. |
value | The null-terminated string value to set. |
void amps_ssl_free | ( | void | ) |
Frees OpenSSL context and shared library.
This function should be called to free up OpenSSL resources and context allocated by amps_ssl_init().
const char* amps_ssl_get_error | ( | void | ) |
Returns the description of the last error from calling amps_ssl_init().
int amps_ssl_init | ( | const char * | dllPath_ | ) |
Initializes SSL support in the AMPS Client.
This function may be called exactly once, before the first TCPS connection is attempted, in order to provide the path to an OpenSSL DLL or shared library to use.
On Windows: this function must be called with either (a) a path to "ssleay32.dll", in which case the specified DLL will be loaded, or (b) the string "ssleay32.dll" alone, in which case the default system DLL search path will be used to locate ssleay32.dll. You may also choose to link ssleay32.dll into your application directly, in which case this function does not need to be invoked.
On Linux: this function may be called with the path to a copy of libssl.so (for example, "/lib/libssl.so.1.0.0"), or with the filename to load, in which case LD_LIBRARY_PATH is searched for the specified filename. You may also link or load libssl.sl into your application directly, in which case this function does not need to be invoked.
dllPath_ | The name or path to your OpenSSL dll. |
int amps_ssl_load_verify_locations | ( | const char * | caFile_, |
const char * | caPath_ | ||
) |
Configures OpenSSL to use the specified locations for locating CA certificates.
caFile_ | A null-terminated string to pass to OpenSSL as the default PEM file. |
caPath_ | A null-terminated string to pass to OpenSSL as the directory containing PEM files. |
See OpenSSL's SSL_CTX_load_verify_locations for more information on OpenSSL's certificate location options.
int amps_ssl_set_verify | ( | int | mode_ | ) |
Configures OpenSSL to validate the server's certificate when connecting.
This parameter must be set before attempting to connect to AMPS.
mode_ | 1 = enable, 0 = disable. (default: 0) |
AMPS_SOCKET amps_tcp_get_socket | ( | amps_handle | transport | ) |
TRANSPORT-SPECIFIC APIS.
void* amps_tcps_get_SSL | ( | amps_handle | transport | ) |
Retrieves the SSL object from the underlying TCPS transport.
transport | The transport handle to retrieve the underling SSL object from. |