AMPS C/C++ Client Class Reference AMPS C/C++ Client Version 5.3.5.4

Typedefs | Enumerations | Functions
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...
typedef const char *(* | amps_http_preflight_callback) (void *)
| Prototype for a user-supplied callback function that creates an HTTP GET message to send immediately after connecting. More...

## Enumerations
enum | amps_result { AMPS_E_OK , AMPS_E_MEMORY , AMPS_E_COMMAND , AMPS_E_CONNECTION , AMPS_E_TOPIC , AMPS_E_FILTER , AMPS_E_RETRY , AMPS_E_DISCONNECTED , AMPS_E_CONNECTION_REFUSED , AMPS_E_STREAM , AMPS_E_URI , AMPS_E_TRANSPORT_TYPE , AMPS_E_USAGE , AMPS_E_SSL }
| Return values from amps_xxx functions. More...

## 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 amps_result | amps_client_send_batch (amps_handle client, amps_handle message, unsigned *version_out, int addToBatch)
| Adds a message to the send cache, possibly sending the cache. 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_assign_field_value_ownership (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, and gives ownership of value to the field for deletion. 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_result | amps_client_set_http_preflight_callback (amps_handle client, amps_http_preflight_callback callback, void *userData)
| Sets a user-supplied callback function for when a connection is established and the provided uri included http_preflight=true in the options. More...
AMPSDLL void | amps_client_set_batch_send (amps_handle client_, amps_uint64_t batchSizeBytes_, amps_uint64_t batchTimeout_)
| Sets a byte size batchSizeBytes and timeout for using batch sends of publish and delta_publish messages only. More...
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. 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 int | amps_ssl_use_certificate_file (const char *fileName_, int type_)
| Configures OpenSSL to use the specified file for its certificate. More...
AMPSDLL int | amps_ssl_use_PrivateKey_file (const char *fileName_, int type_)
| Configures OpenSSL to use the specified file for its private key. 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

## ◆ amps_handle

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.

## ◆ amps_http_preflight_callback

typedef const char*(* amps_http_preflight_callback) (void *)

Prototype for a user-supplied callback function that creates an HTTP GET message to send immediately after connecting.

This preflight message is most useful when connecting through a proxy server. It requests a connection upgrade to either tcp or tcps and will get back a 101 response from the AMPS server if successful. The callback takes two parameter: userdata A user-defined void* supplied with the callback.

## ◆ amps_thread_created_callback

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.

## ◆ amps_thread_exit_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.

## ◆ amps_transport_filter_function

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

## ◆ amps_result

enum amps_result

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

## ◆ amps_client_attempt_reconnect()

AMPSDLL 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_client_connect()

AMPSDLL amps_result 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_client_create()

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

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

## ◆ amps_client_destroy()

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

  handle | the client object to destroy.

## ◆ amps_client_disconnect()

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

## ◆ amps_client_get_error()

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

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

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

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

Returns
  The socket currently used for communication with the server.

## ◆ amps_client_get_transport()

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

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

AMPSDLL 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_client_send_batch()

AMPSDLL amps_result amps_client_send_batch | ( | amps_handle | client,
|  | amps_handle | message,
|  | unsigned * | version_out,
|  | int | addToBatch
| ) |  |

Adds a message to the send cache, possibly sending the cache.

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.
  addToBatch | Is 1 to add or 0 to send what's cached and this 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.

## ◆ amps_client_send_with_version()

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

  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.

## ◆ amps_client_set_batch_send()

AMPSDLL void amps_client_set_batch_send | ( | amps_handle | client_,
|  | amps_uint64_t | batchSizeBytes_,
|  | amps_uint64_t | batchTimeout_
| ) |  |

Sets a byte size batchSizeBytes and timeout for using batch sends of publish and delta_publish messages only.

Parameters

  client_ | The client on which to set the batchSizeBytess.
  batchSizeBytes_ | The max number of bytes to cache before a send.
  batchTimeout_ | The max time for cached messages to be held before send.

## ◆ amps_client_set_disconnect_handler()

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

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

AMPSDLL amps_result amps_client_set_http_preflight_callback | ( | amps_handle | client,
|  | amps_http_preflight_callback | callback,
|  | void * | userData
| ) |  |

Sets a user-supplied callback function for when a connection is established and the provided uri included http_preflight=true in the options.

The callback returns the full message that will be sent to the server.

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

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

  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.

## ◆ amps_client_set_message_handler()

AMPSDLL 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_client_set_name()

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

  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.

## ◆ amps_client_set_predisconnect_handler()

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

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

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

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

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

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

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

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

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

  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.

## ◆ amps_message_assign_data()

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

  message | The AMPS message to set the data of.
  value | The value to set the data with.
  length | The length of the value

## ◆ amps_message_assign_field_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

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

AMPSDLL void amps_message_assign_field_value_ownership | ( | 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, and gives ownership of value to the field for deletion.

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

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

  message | The message to copy.

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

## ◆ amps_message_create()

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

  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.

## ◆ amps_message_destroy()

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

## ◆ amps_message_get_data()

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

  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.

## ◆ amps_message_get_field_long()

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

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

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

  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.

## ◆ amps_message_get_field_value()

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

  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.

## ◆ amps_message_reset()

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

  message | A handle to the message to clear.

## ◆ amps_message_set_data()

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

  message | The AMPS message to set the data of.
  value | The value to set the data with.
  length | The length of the value

## ◆ amps_message_set_data_nts()

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

## ◆ amps_message_set_field_guid()

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

  message | The AMPS message to mutate.
  field | The field to apply the new GUID to.

## ◆ amps_message_set_field_value()

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

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

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

  message | The AMPS message to mutate.
  field | The field to set.
  value | The null-terminated string value to set.

## ◆ amps_ssl_free()

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

## ◆ amps_ssl_get_error()

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.

## ◆ amps_ssl_init()

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.

## ◆ amps_ssl_load_verify_locations()

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.

## ◆ amps_ssl_set_verify()

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.

## ◆ amps_ssl_use_certificate_file()

AMPSDLL int amps_ssl_use_certificate_file | ( | const char * | fileName_,
|  | int | type_
| ) |  |

Configures OpenSSL to use the specified file for its certificate.

Parameters

  fileName_ | A null-terminated string to pass to OpenSSL as the default PEM file.
  type_ | An int representing the file type: SSL_FILETYPE_PEM, SSL_FILETYPE_ASN1, SSL_FILETYPE_DEFAULT

Returns
  0 if successful, -1 if an error occurred.

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

## ◆ amps_ssl_use_PrivateKey_file()

AMPSDLL int amps_ssl_use_PrivateKey_file | ( | const char * | fileName_,
|  | int | type_
| ) |  |

Configures OpenSSL to use the specified file for its private key.

Parameters

  fileName_ | A null-terminated string to pass to OpenSSL as the file.
  type_ | An int representing the file type: AMPS_SSL_FILETYPE_PEM, AMPS_SSL_FILETYPE_ASN1, AMPS_SSL_FILETYPE_DEFAULT

Returns
  0 if successful, -1 if an error occurred.

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

## ◆ amps_tcps_get_SSL()

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