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"

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

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

enum amps_result

Return values from amps_xxx functions.

Enumerator
AMPS_E_OK	Success.
AMPS_E_MEMORY	A memory error occured.
AMPS_E_COMMAND	An error with a command occured.
AMPS_E_CONNECTION	A connection error occured.
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 occured.
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 occured.

Function Documentation

amps_result amps_client_attempt_reconnect	(	amps_handle	client,
		unsigned	version
	)

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

Parameters

client	An AMPS client object on which to attempt reconnect.
version	The 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.

amps_result AMPSDLL amps_client_connect	(	amps_handle	handle,
		const amps_char *	uri
	)

Connects to the AMPS server specified in uri.

Parameters

handle	The handle to a client created with amps_client_create().
uri	An 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.

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.

Parameters

clientName A 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 occured.

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.

Parameters

handle the client object to destroy.

void AMPSDLL amps_client_disconnect ( amps_handle handle )

Disconnects from the AMPS server, if connected.

Parameters

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.

Parameters

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.

Returns: The length of the message written to 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.

Parameters

client An AMPS client object from which to get the transport handle.

Returns: An amps_handle that represents the transport used by the client.

amps_result amps_client_send	(	amps_handle	client,
		amps_handle	message
	)

Sends a message to the AMPS server.

Parameters

client	The client to sent the message on.
message	An 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.

amps_result amps_client_send_with_version	(	amps_handle	client,
		amps_handle	message,
		unsigned *	version_out
	)

Sends a message to the AMPS server.

Parameters

client	The client to sent the message on.
message	An AMPS message to send.
version_out	The 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.

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

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.

Parameters

client	The client on which to request idle time.
idleTime	The 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.

void amps_client_set_message_handler	(	amps_handle	client,
		amps_handler	messageHandler,
		void *	userData
	)

Sets the message handler function for this client.

Parameters

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.

Parameters

handle	The client object on which to set the name.
clientName	A 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.

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

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.

Parameters

client	The client on which to set the read timeout.
readTimeout	The 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.

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

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.

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.

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

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.

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.

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

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.

Parameters

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.

Parameters

message The message to copy.

Returns: An amps_handle that represents the new message, or NULL if an error occurs.

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

client The client for which a new message should be constructed.

Returns: An amps_handle that represents the new message, or NULL if an error occurs.

void amps_message_destroy ( amps_handle message )

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

Parameters

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.

Parameters

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.

Parameters

message	The message to examine.
field	The field containing the long data.

Returns: The long value found in the field, or 0 if not present.

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

message	The message to examine.
field	The field containing the long data.

Returns: The uint64_t value found in the field, or 0 if not present.

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

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.

Parameters

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.

Parameters

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.

Parameters

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")

Parameters

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.

Parameters

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.

Parameters

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().

Returns: The formatted error string with information regarding why amps_ssl_init() failed.

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.

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.

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.

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.

Parameters

transport The transport handle to retrieve the underling SSL object from.

Returns: The OpenSSL SSL* object which may be used with the OpenSSL api.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation