AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.3
amps.h File Reference

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 <time.h>
#include <string.h>
#include <stdio.h>
#include "amps/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...
 
typedef amps_result(* amps_thread_exit_callback) (AMPS_THREAD_ID, void *)
 Prototype for a user-supplied callback function when a thread created for a connection is exiting. More...
 

Enumerations

Functions

AMPSDLL amps_handle amps_client_create (const amps_char *clientName)
 Functions for creation of an AMPS client. More...
 
AMPSDLL amps_result amps_client_set_name (amps_handle handle, const amps_char *clientName)
 Sets the name on an amps client object. More...
 
AMPSDLL amps_result amps_client_connect (amps_handle handle, const amps_char *uri)
 Connects to the AMPS server specified in uri. More...
 
AMPSDLL void amps_client_disconnect (amps_handle handle)
 Disconnects from the AMPS server, if connected. More...
 
AMPSDLL void amps_client_destroy (amps_handle handle)
 Disconnects and destroys an AMPS client object. More...
 
AMPSDLL size_t amps_client_get_error (amps_handle client, amps_char *errorMessageOut, size_t bufferSize)
 Returns the last error set on this client. More...
 
AMPSDLL amps_result amps_client_send (amps_handle client, amps_handle message)
 Sends a message to the AMPS server. More...
 
AMPSDLL amps_result amps_client_send_with_version (amps_handle client, amps_handle message, unsigned *version_out)
 Sends a message to the AMPS server. More...
 
AMPSDLL void amps_client_set_message_handler (amps_handle client, amps_handler messageHandler, void *userData)
 Sets the message handler function for this client. More...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL amps_result amps_client_attempt_reconnect (amps_handle client, unsigned version)
 Manually invokes the user-supplied disconnect handler for this client. More...
 
AMPSDLL AMPS_SOCKET amps_client_get_socket (amps_handle client)
 Returns the socket from the underlying transport in client, or NULL if no transport is associated with this client. More...
 
AMPSDLL amps_handle amps_message_create (amps_handle client)
 Functions for creation and manipulation of AMPS messages. More...
 
AMPSDLL 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...
 
AMPSDLL void amps_message_destroy (amps_handle message)
 Destroys and frees the memory associated with an AMPS message object. More...
 
AMPSDLL void amps_message_reset (amps_handle message)
 Clears all fields and data in a message. More...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL void amps_message_set_data (amps_handle message, const amps_char *value, size_t length)
 Sets the data component of an AMPS message. More...
 
AMPSDLL 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...
 
AMPSDLL void amps_message_set_data_nts (amps_handle message, const amps_char *value)
 Sets the data component of an AMPS message. More...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL amps_result amps_client_set_idle_time (amps_handle client, int idleTime)
 Sets an idle-time (milliseconds). More...
 
AMPSDLL 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...
 
AMPSDLL 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...
 
AMPSDLL amps_result amps_client_set_thread_exit_callback (amps_handle client, amps_thread_exit_callback callback, void *userData)
 Sets a user-supplied callback function for when a thread created for a connection is exiting. More...
 
AMPSDLL AMPS_SOCKET amps_tcp_get_socket (amps_handle transport)
 TRANSPORT-SPECIFIC APIS. More...
 
AMPSDLL void * amps_tcps_get_SSL (amps_handle transport)
 Retrieves the SSL object from the underlying TCPS transport. More...
 
AMPSDLL int amps_ssl_init (const char *dllPath_)
 Initializes SSL support in the AMPS Client. More...
 
AMPSDLL int amps_ssl_set_verify (int mode_)
 Configures OpenSSL to validate the server's certificate when connecting. More...
 
AMPSDLL int amps_ssl_load_verify_locations (const char *caFile_, const char *caPath_)
 Configures OpenSSL to use the specified locations for locating CA certificates. More...
 
AMPSDLL void amps_ssl_free (void)
 Frees OpenSSL context and shared library. More...
 
AMPSDLL const char * amps_ssl_get_error (void)
 Returns the description of the last error from calling amps_ssl_init(). More...
 

Detailed Description

Core type and function declarations for the AMPS C client.

Typedef Documentation

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 amps_result(* amps_thread_exit_callback) (AMPS_THREAD_ID, void *)

Prototype for a user-supplied callback function when a thread created for a connection is exiting.

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.

Enumeration Type Documentation

Return values from amps_xxx functions.

Enumerator
AMPS_E_OK 

Success.

AMPS_E_MEMORY 

A memory error occurred.

AMPS_E_COMMAND 

An error with a command occurred.

AMPS_E_CONNECTION 

A connection error occurred.

AMPS_E_TOPIC 

The specified topic was invalid.

AMPS_E_FILTER 

The specified filter was invalid.

AMPS_E_RETRY 

The operation has not succeeded, but ought to be retried.

AMPS_E_DISCONNECTED 

The client and server are disconnected.

AMPS_E_CONNECTION_REFUSED 

The server could not be found, or it actively refused our connection.

AMPS_E_STREAM 

A stream error has occurred.

AMPS_E_URI 

The specified URI is invalid.

AMPS_E_TRANSPORT_TYPE 

The specified transport type is invalid.

AMPS_E_USAGE 

The usage of this function is invalid.

AMPS_E_SSL 

A Secure Sockets Layer (SSL) error occurred.

Function Documentation

AMPSDLL amps_result amps_client_attempt_reconnect ( amps_handle  client,
unsigned  version 
)

Manually invokes the user-supplied disconnect handler for this client.

Parameters
clientAn AMPS client object on which to attempt reconnect.
versionThe connection version that failed and is attempting reconnect.
Returns
An amps_result indicating the success or failure of reconnect. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL amps_result amps_client_connect ( amps_handle  handle,
const amps_char *  uri 
)

Connects to the AMPS server specified in uri.

Parameters
handleThe handle to a client created with amps_client_create().
uriAn AMPS uri, e.g. tcp://localhost:9004/nvfix
Returns
An amps_result indicating the success or failure of this connection attempt. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL amps_handle 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.

Parameters
clientNameA null-terminated, unique name for this client, or NULL if one will be supplied later.
Returns
A handle to the newly-created client, or NULL if an error occurred.
AMPSDLL void 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.

Parameters
handlethe client object to destroy.
AMPSDLL void amps_client_disconnect ( amps_handle  handle)

Disconnects from the AMPS server, if connected.

Parameters
handleThe handle to a client created with amps_client_create().
AMPSDLL 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.

Parameters
clientThe client handle to retrieve the last error for.
errorMessageOutA buffer to place the error message into, as a null-terminated string.
bufferSizeThe size, in bytes, of the buffer passed in errorMessageOut.
Returns
The length of the message written to errorMessageOut.
AMPSDLL AMPS_SOCKET amps_client_get_socket ( amps_handle  client)

Returns the socket from the underlying transport in client, or NULL if no transport is associated with this client.

Parameters
clientAn AMPS client object from which to get the transport handle.
Returns
The socket currently used for communication with the server.
AMPSDLL 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.

Parameters
clientAn AMPS client object from which to get the transport handle.
Returns
An amps_handle that represents the transport used by the client.
AMPSDLL amps_result amps_client_send ( amps_handle  client,
amps_handle  message 
)

Sends a message to the AMPS server.

Parameters
clientThe client to sent the message on.
messageAn AMPS message to send.
Returns
An amps_result indicating the success or failure of this send. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL amps_result amps_client_send_with_version ( amps_handle  client,
amps_handle  message,
unsigned *  version_out 
)

Sends a message to the AMPS server.

Parameters
clientThe client to sent the message on.
messageAn AMPS message to send.
version_outThe connection version used to send the message.
Returns
An amps_result indicating the success or failure of this send. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL 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.

Parameters
clientAn AMPS client object on which to set this handler.
disconnectHandlerA pointer to function of signature: amps_result myfunction(amps_handle client, void* userData) to be called when a disconnect occurs on client.
userDataUser-defined data to be passed to the handler function
AMPSDLL 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.

Parameters
clientThe client on which to request idle time.
idleTimeThe time in milliseconds.
Returns
An amps_result indicating the success or failure of setting the idle time. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL void amps_client_set_message_handler ( amps_handle  client,
amps_handler  messageHandler,
void *  userData 
)

Sets the message handler function for this client.

Parameters
clientAn AMPS client object.
messageHandlerA pointer to function of signature: amps_result myfunction(amps_handle message, void* userData) that is called when a message arrives.
userDataUser-defined data to be passed to the handler function.
AMPSDLL amps_result 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.

Parameters
handleThe client object on which to set the name.
clientNameA null-terminated, unique name for this client.
Returns
AMPS_E_OK if the name is successfully passed to the client, AMPS_E_USAGE if the name could not be set because this client already has a name.
AMPSDLL 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.

Parameters
clientAn AMPS client object on which to set this handler.
predisconnectHandlerA pointer to function of signature: amps_result myfunction(amps_handle client, void* userData) to be called when a disconnect occurs on client.
userDataUser-defined data to be passed to the handler function
AMPSDLL 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.

Parameters
clientThe client on which to set the read timeout.
readTimeoutThe timeout in seconds.
Returns
An amps_result indicating the success or failure of setting the read timeout. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL 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.

Parameters
clientThe client on which to set the callback function.
callbackThe callback function to invoke.
userDataThe user data that should be included in each call to the callback.
Returns
An amps_result indicating the success or failure of setting the callback. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL amps_result amps_client_set_thread_exit_callback ( amps_handle  client,
amps_thread_exit_callback  callback,
void *  userData 
)

Sets a user-supplied callback function for when a thread created for a connection is exiting.

The callback takes two parameters: thread A native handle for the thread. userdata A user-defined void* supplied with the callback.

Parameters
clientThe client on which to set the callback function.
callbackThe callback function to invoke.
userDataThe user data that should be included in each call to the callback.
Returns
An amps_result indicating the success or failure of setting the callback. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL 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.

Parameters
clientThe client on which to set the callback function.
filterThe filter function pointer.
userDataThe user data that should be included in each call to the filter.
Returns
An amps_result indicating the success or failure of setting the filter. If not AMPS_E_OK, use amps_client_get_error() to find the text of the error message.
AMPSDLL 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.

Parameters
messageThe AMPS message to set the data of.
valueThe value to set the data with.
lengthThe length of the value
AMPSDLL 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.

Parameters
messageThe AMPS message to mutate
fieldThe header field to set.
valueThe value to set.
lengthThe length (excluding any null-terminator) of the value
AMPSDLL 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.

Parameters
messageThe message to copy.
Returns
An amps_handle that represents the new message, or NULL if an error occurs.
AMPSDLL 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.

Parameters
clientThe client for which a new message should be constructed.
Returns
An amps_handle that represents the new message, or NULL if an error occurs.
AMPSDLL void amps_message_destroy ( amps_handle  message)

Destroys and frees the memory associated with an AMPS message object.

Parameters
messageA handle to the message to destroy.
AMPSDLL void amps_message_get_data ( amps_handle  message,
amps_char **  value_ptr,
size_t *  length_ptr 
)

Gets the data component of an AMPS message.

Parameters
messageThe AMPS message to get the data of.
value_ptrA pointer to an amps_char* that is modifed to reflect the address of the data of this message.
length_ptrA 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.

AMPSDLL 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.

Parameters
messageThe message to examine.
fieldThe field containing the long data.
Returns
The long value found in the field, or 0 if not present.
AMPSDLL 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.

Parameters
messageThe message to examine.
fieldThe field containing the long data.
Returns
The uint64_t value found in the field, or 0 if not present.
AMPSDLL 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.

Parameters
messageThe AMPS message from which the value is retrieved.
fieldThe header field to retrieve the value of.
value_ptrThe 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_ptrThe 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.

AMPSDLL 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.

Parameters
messageA handle to the message to clear.
AMPSDLL void amps_message_set_data ( amps_handle  message,
const amps_char *  value,
size_t  length 
)

Sets the data component of an AMPS message.

Parameters
messageThe AMPS message to set the data of.
valueThe value to set the data with.
lengthThe length of the value
AMPSDLL void amps_message_set_data_nts ( amps_handle  message,
const amps_char *  value 
)

Sets the data component of an AMPS message.

Parameters
messageThe AMPS message to set the data of.
valueThe null-terminated string value to set the data with.
AMPSDLL 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")

Parameters
messageThe AMPS message to mutate.
fieldThe field to apply the new GUID to.
AMPSDLL 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.

Parameters
messageThe AMPS message to mutate
fieldThe header field to set.
valueThe value to set.
lengthThe length (excluding any null-terminator) of the value
AMPSDLL 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.

Parameters
messageThe AMPS message to mutate.
fieldThe field to set.
valueThe null-terminated string value to set.
AMPSDLL 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().

AMPSDLL const char* amps_ssl_get_error ( void  )

Returns the description of the last error from calling amps_ssl_init().

Returns
The formatted error string with information regarding why amps_ssl_init() failed.
AMPSDLL 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.

Parameters
dllPath_The name or path to your OpenSSL dll.
Returns
0 if successful, -1 if an error occurred. Use amps_ssl_get_error to retrieve the error description.
AMPSDLL int amps_ssl_load_verify_locations ( const char *  caFile_,
const char *  caPath_ 
)

Configures OpenSSL to use the specified locations for locating CA certificates.

Parameters
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.
Returns
0 if successful, -1 if an error occurred.

See OpenSSL's SSL_CTX_load_verify_locations for more information on OpenSSL's certificate location options.

AMPSDLL 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.

Parameters
mode_1 = enable, 0 = disable. (default: 0)
Returns
0 if successful, -1 if an error occurred.
AMPSDLL AMPS_SOCKET amps_tcp_get_socket ( amps_handle  transport)

TRANSPORT-SPECIFIC APIS.

AMPSDLL void* amps_tcps_get_SSL ( amps_handle  transport)

Retrieves the SSL object from the underlying TCPS transport.

Parameters
transportThe transport handle to retrieve the underling SSL object from.
Returns
The OpenSSL SSL* object which may be used with the OpenSSL api.