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

amps.h
Go to the documentation of this file.
1 /* ////////////////////////////////////////////////////////////////////////
2 *
3 * Copyright (c) 2010-2025 60East Technologies Inc., All Rights Reserved.
4 *
5 * This computer software is owned by 60East Technologies Inc. and is
6 * protected by U.S. copyright laws and other laws and by international
7 * treaties. This computer software is furnished by 60East Technologies
8 * Inc. pursuant to a written license agreement and may be used, copied,
9 * transmitted, and stored only in accordance with the terms of such
10 * license agreement and with the inclusion of the above copyright notice.
11 * This computer software or any other copies thereof may not be provided
12 * or otherwise made available to any other person.
13 *
14 * U.S. Government Restricted Rights. This computer software: (a) was
15 * developed at private expense and is in all respects the proprietary
16 * information of 60East Technologies Inc.; (b) was not developed with
17 * government funds; (c) is a trade secret of 60East Technologies Inc.
18 * for all purposes of the Freedom of Information Act; and (d) is a
19 * commercial item and thus, pursuant to Section 12.212 of the Federal
20 * Acquisition Regulations (FAR) and DFAR Supplement Section 227.7202,
21 * Government's use, duplication or disclosure of the computer software
22 * is subject to the restrictions set forth by 60East Technologies Inc..
23 *
24 * ////////////////////////////////////////////////////////////////////// */
25
26 #ifndef _AMPS_H_
27 #define _AMPS_H_
28
29 #ifdef _WIN32
30 #include <WinSock2.h>
31 #else
32 #include <netdb.h>
33 #include <netinet/ip.h>
34 #include <errno.h>
35 #include <pthread.h>
36 #include <unistd.h>
37 #include <time.h>
38 #endif
39 #include <string.h>
40 #include <time.h>
41 #include <stdio.h>
42 #include "amps/amps_generated.h"
43
44 #ifdef AMPS_CPP_COUNT_THREADS
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 size_t amps_get_thread_create_count(void);
49 size_t amps_get_thread_join_count(void);
50 size_t amps_get_thread_detach_count(void);
51 #ifdef __cplusplus
52 }
53 #endif
54 #endif
55
56 //Avoid compiler warnings on win
57 #ifdef INVALID_SOCKET
58 #define AMPS_INVALID_SOCKET INVALID_SOCKET
59 #else
60 #define AMPS_INVALID_SOCKET -1
61 #endif
62
63 #ifdef _WIN32
64 #ifdef AMPS_SHARED
65 #ifdef AMPS_BUILD
66 #define AMPSDLL __declspec(dllexport)
67 #else
68 #define AMPSDLL __declspec(dllimport)
69 #endif
70 #else
71 #define AMPSDLL
72 #endif
73 #define AMPS_USLEEP(x) Sleep((DWORD)(x)/(DWORD)1000);
74 #define AMPS_YIELD() SwitchToThread()
75 #define AMPS_CURRENT_THREAD() GetCurrentThreadId()
76 typedef HANDLE AMPS_THREAD_T;
77 typedef DWORD AMPS_THREAD_ID;
78 typedef SOCKET AMPS_SOCKET;
79 typedef __int32 amps_int32_t;
80 typedef unsigned __int32 amps_uint32_t;
81 typedef __int64 amps_int64_t;
82 typedef unsigned __int64 amps_uint64_t;
83 #else
84 #define AMPSDLL
85 #define AMPS_USLEEP(x) usleep((useconds_t)x)
86 #define AMPS_YIELD() sched_yield()
87 #define AMPS_CURRENT_THREAD() pthread_self()
88 typedef pthread_t AMPS_THREAD_T;
89 typedef pthread_t AMPS_THREAD_ID;
90 typedef int AMPS_SOCKET;
91 typedef int32_t amps_int32_t;
92 typedef uint32_t amps_uint32_t;
93 typedef int64_t amps_int64_t;
94 typedef uint64_t amps_uint64_t;
95 #endif
96
97 #if defined(_WIN32) || defined(__SSE_4_2__)
98 #define AMPS_SSE_42 1
99 #endif
100
199 #ifdef __cplusplus
200 extern "C" {
201 #endif
202
203 typedef char amps_char;
204
211 typedef void* amps_handle;
212
216 typedef enum
217 {
221 AMPS_E_OK,
225 AMPS_E_MEMORY,
229 AMPS_E_COMMAND,
233 AMPS_E_CONNECTION,
237 AMPS_E_TOPIC,
241 AMPS_E_FILTER,
245 AMPS_E_RETRY,
249 AMPS_E_DISCONNECTED,
253 AMPS_E_CONNECTION_REFUSED,
257 AMPS_E_STREAM,
261 AMPS_E_URI,
265 AMPS_E_TRANSPORT_TYPE,
269 AMPS_E_USAGE,
273 AMPS_E_SSL
274 } amps_result;
275
276 typedef amps_result(*amps_handler)(amps_handle, void*);
277 typedef void(*amps_predisconnect_handler)(amps_handle, unsigned, void*);
278
279
289 AMPSDLL amps_handle amps_client_create(
290 const amps_char* clientName);
291
302 AMPSDLL amps_result amps_client_set_name(
303 amps_handle handle,
304 const amps_char* clientName);
305
313 AMPSDLL amps_result amps_client_connect(
314 amps_handle handle,
315 const amps_char* uri);
316
321 AMPSDLL void amps_client_disconnect(
322 amps_handle handle);
323
330 AMPSDLL void amps_client_destroy(
331 amps_handle handle);
332
341 AMPSDLL size_t amps_client_get_error(
342 amps_handle client,
343 amps_char* errorMessageOut,
344 size_t bufferSize);
345
353 AMPSDLL amps_result amps_client_send(
354 amps_handle client,
355 amps_handle message);
356
365 AMPSDLL amps_result amps_client_send_with_version(
366 amps_handle client,
367 amps_handle message,
368 unsigned* version_out);
369
379 AMPSDLL amps_result amps_client_send_batch(
380 amps_handle client,
381 amps_handle message,
382 unsigned* version_out,
383 int addToBatch);
384
393 AMPSDLL void amps_client_set_message_handler(
394 amps_handle client,
395 amps_handler messageHandler,
396 void* userData);
397
406 AMPSDLL void amps_client_set_predisconnect_handler(
407 amps_handle client,
408 amps_predisconnect_handler predisconnectHandler,
409 void* userData);
410
419 AMPSDLL void amps_client_set_disconnect_handler(
420 amps_handle client,
421 amps_handler disconnectHandler,
422 void* userData);
423
430 AMPSDLL amps_handle amps_client_get_transport(
431 amps_handle client);
432
440 AMPSDLL amps_result
441 amps_client_attempt_reconnect(amps_handle client, unsigned version);
442
449 AMPSDLL AMPS_SOCKET
450 amps_client_get_socket(amps_handle client);
451
461 AMPSDLL amps_handle amps_message_create(amps_handle client);
462
468 AMPSDLL amps_handle amps_message_copy(amps_handle message);
469
474 AMPSDLL void amps_message_destroy(amps_handle message);
475
482 AMPSDLL void amps_message_reset(amps_handle message);
483
498 AMPSDLL void amps_message_get_field_value(
499 amps_handle message,
500 FieldId field,
501 const amps_char** value_ptr,
502 size_t* length_ptr);
503
511 AMPSDLL void amps_message_set_field_value(
512 amps_handle message,
513 FieldId field,
514 const amps_char* value,
515 size_t length);
516
524 AMPSDLL void amps_message_assign_field_value(
525 amps_handle message,
526 FieldId field,
527 const amps_char* value,
528 size_t length);
529
538 AMPSDLL void amps_message_assign_field_value_ownership(
539 amps_handle message,
540 FieldId field,
541 const amps_char* value,
542 size_t length);
543
551 AMPSDLL void amps_message_set_field_value_nts(
552 amps_handle message,
553 FieldId field,
554 const amps_char* value);
555
556
563 AMPSDLL void amps_message_set_field_guid(
564 amps_handle message,
565 FieldId field);
566
573 AMPSDLL void amps_message_set_data(
574 amps_handle message,
575 const amps_char* value,
576 size_t length);
577
584 AMPSDLL void amps_message_assign_data(
585 amps_handle message,
586 const amps_char* value,
587 size_t length);
588
594 AMPSDLL void amps_message_set_data_nts(
595 amps_handle message,
596 const amps_char* value);
597
610 AMPSDLL void amps_message_get_data(
611 amps_handle message,
612 amps_char** value_ptr,
613 size_t* length_ptr);
614
621 AMPSDLL unsigned long amps_message_get_field_long(
622 amps_handle message,
623 FieldId field);
624
631 AMPSDLL amps_uint64_t amps_message_get_field_uint64(
632 amps_handle message,
633 FieldId field);
634
644 AMPSDLL amps_result amps_client_set_read_timeout(
645 amps_handle client,
646 int readTimeout);
647
648
658 AMPSDLL amps_result amps_client_set_idle_time(
659 amps_handle client,
660 int idleTime);
661
670 typedef void(*amps_transport_filter_function)(const unsigned char*, size_t, short, void*);
671
685 AMPSDLL amps_result amps_client_set_transport_filter_function(
686 amps_handle client,
687 amps_transport_filter_function filter,
688 void* userData);
689
696 typedef amps_result(*amps_thread_created_callback)(AMPS_THREAD_T, void*);
697
709 AMPSDLL amps_result amps_client_set_thread_created_callback(
710 amps_handle client,
711 amps_thread_created_callback callback,
712 void* userData);
713
720 typedef amps_result(*amps_thread_exit_callback)(AMPS_THREAD_ID, void*);
721
733 AMPSDLL amps_result amps_client_set_thread_exit_callback(
734 amps_handle client,
735 amps_thread_exit_callback callback,
736 void* userData);
737
747 typedef const char* (*amps_http_preflight_callback)(void*);
748
759 AMPSDLL amps_result amps_client_set_http_preflight_callback(
760 amps_handle client,
761 amps_http_preflight_callback callback,
762 void* userData);
763
771 AMPSDLL void amps_client_set_batch_send(amps_handle client_, amps_uint64_t batchSizeBytes_,
772 amps_uint64_t batchTimeout_);
773
779 AMPSDLL AMPS_SOCKET
780 amps_tcp_get_socket(amps_handle transport);
781
782 AMPSDLL AMPS_SOCKET
783 amps_tcps_get_socket(amps_handle transport);
784
790 AMPSDLL void*
791 amps_tcps_get_SSL(amps_handle transport);
792
793 /*
794 * Returns the current wall-clock time in milliseconds
795 */
796 AMPSDLL amps_uint64_t
797 amps_now(void);
798
799
823 AMPSDLL int amps_ssl_init(const char* dllPath_);
824
825 AMPSDLL int amps_ssl_init_from_context(void* sslContext_, const char* fileName_);
826
827 /* From OpenSSL header
828 * use either SSL_VERIFY_NONE or SSL_VERIFY_PEER, the last 3 options are
829 * 'ored' with SSL_VERIFY_PEER if they are desired
830 # define SSL_VERIFY_NONE 0x00
831 # define SSL_VERIFY_PEER 0x01
832 # define SSL_VERIFY_FAIL_IF_NO_PEER_CERT 0x02
833 # define SSL_VERIFY_CLIENT_ONCE 0x04
834 # define SSL_VERIFY_POST_HANDSHAKE 0x08
835 */
836
844 AMPSDLL int amps_ssl_set_verify(int mode_);
845
856 AMPSDLL int amps_ssl_load_verify_locations(const char* caFile_, const char* caPath_);
857
858 /* From OpenSSL header
859 # define SSL_FILETYPE_PEM 1
860 # define SSL_FILETYPE_ASN1 2
861 # define SSL_FILETYPE_DEFAULT 3
862 */
863
874 AMPSDLL int amps_ssl_use_certificate_file(const char* fileName_, int type_);
875
886 AMPSDLL int amps_ssl_use_PrivateKey_file(const char* fileName_, int type_);
887
893 AMPSDLL void amps_ssl_free(void);
894
900 AMPSDLL const char* amps_ssl_get_error(void);
901
902 AMPSDLL void amps_noOpFn(void*);
903
904 /*
905 * Internal API for use by the python client.
906 */
907 AMPSDLL void amps_set_waiting_function(void*);
908 AMPSDLL void amps_invoke_waiting_function(void);
909 AMPSDLL void amps_set_remove_route_function(void*);
910 AMPSDLL void amps_invoke_remove_route_function(void*);
911 AMPSDLL void amps_set_copy_route_function(void*);
912 AMPSDLL void* amps_invoke_copy_route_function(void*);
913
914 #ifdef __cplusplus
915 }
916 #if !defined(_AMPS_BUILD_C_CLIENT) && !defined(_AMPS_SKIP_AMPSPLUSPLUS)
917 #include <amps/ampsplusplus.hpp>
918 #endif
919 #endif
920
921 #endif
amps_ssl_set_verify
AMPSDLL int amps_ssl_set_verify(int mode_)
Configures OpenSSL to validate the server's certificate when connecting.
amps_client_disconnect
AMPSDLL void amps_client_disconnect(amps_handle handle)
Disconnects from the AMPS server, if connected.
amps_message_create
AMPSDLL amps_handle amps_message_create(amps_handle client)
Functions for creation and manipulation of AMPS messages.
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.
amps_ssl_init
AMPSDLL int amps_ssl_init(const char *dllPath_)
Initializes SSL support in the AMPS Client.
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.
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.
amps_client_destroy
AMPSDLL void amps_client_destroy(amps_handle handle)
Disconnects and destroys an AMPS client object.
amps_ssl_free
AMPSDLL void amps_ssl_free(void)
Frees OpenSSL context and shared library.
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.
amps_client_connect
AMPSDLL amps_result amps_client_connect(amps_handle handle, const amps_char *uri)
Connects to the AMPS server specified in uri.
amps_client_send
AMPSDLL amps_result amps_client_send(amps_handle client, amps_handle message)
Sends a message to the AMPS server.
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.
amps_ssl_get_error
AMPSDLL const char * amps_ssl_get_error(void)
Returns the description of the last error from calling amps_ssl_init().
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.
amps_message_reset
AMPSDLL void amps_message_reset(amps_handle message)
Clears all fields and data in a message.
amps_tcp_get_socket
AMPSDLL AMPS_SOCKET amps_tcp_get_socket(amps_handle transport)
TRANSPORT-SPECIFIC APIS.
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.
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.
amps_http_preflight_callback
const char *(* amps_http_preflight_callback)(void *)
Prototype for a user-supplied callback function that creates an HTTP GET message to send immediately ...
Definition: amps.h:747
amps_result
amps_result
Return values from amps_xxx functions.
Definition: amps.h:217
AMPS_E_RETRY
@ AMPS_E_RETRY
The operation has not succeeded, but ought to be retried.
Definition: amps.h:245
AMPS_E_USAGE
@ AMPS_E_USAGE
The usage of this function is invalid.
Definition: amps.h:269
AMPS_E_URI
@ AMPS_E_URI
The specified URI is invalid.
Definition: amps.h:261
AMPS_E_OK
@ AMPS_E_OK
Success.
Definition: amps.h:221
AMPS_E_MEMORY
@ AMPS_E_MEMORY
A memory error occurred.
Definition: amps.h:225
AMPS_E_DISCONNECTED
@ AMPS_E_DISCONNECTED
The client and server are disconnected.
Definition: amps.h:249
AMPS_E_STREAM
@ AMPS_E_STREAM
A stream error has occurred.
Definition: amps.h:257
AMPS_E_COMMAND
@ AMPS_E_COMMAND
An error with a command occurred.
Definition: amps.h:229
AMPS_E_SSL
@ AMPS_E_SSL
A Secure Sockets Layer (SSL) error occurred.
Definition: amps.h:273
AMPS_E_TRANSPORT_TYPE
@ AMPS_E_TRANSPORT_TYPE
The specified transport type is invalid.
Definition: amps.h:265
AMPS_E_TOPIC
@ AMPS_E_TOPIC
The specified topic was invalid.
Definition: amps.h:237
AMPS_E_CONNECTION_REFUSED
@ AMPS_E_CONNECTION_REFUSED
The server could not be found, or it actively refused our connection.
Definition: amps.h:253
AMPS_E_CONNECTION
@ AMPS_E_CONNECTION
A connection error occurred.
Definition: amps.h:233
AMPS_E_FILTER
@ AMPS_E_FILTER
The specified filter was invalid.
Definition: amps.h:241
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.
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 tran...
amps_message_destroy
AMPSDLL void amps_message_destroy(amps_handle message)
Destroys and frees the memory associated with an AMPS message object.
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.
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.
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.
amps_thread_created_callback
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 threa...
Definition: amps.h:696
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.
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")
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 i...
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...
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.
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.
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,...
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.
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.
amps_thread_exit_callback
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.
Definition: amps.h:720
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.
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.
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.
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.
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 wit...
amps_handle
void * amps_handle
Opaque handle type used to refer to objects in the AMPS api.
Definition: amps.h:211
amps_transport_filter_function
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 ...
Definition: amps.h:670
amps_client_set_idle_time
AMPSDLL amps_result amps_client_set_idle_time(amps_handle client, int idleTime)
Sets an idle-time (milliseconds).
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.
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.
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 messag...
amps_tcps_get_SSL
AMPSDLL void * amps_tcps_get_SSL(amps_handle transport)
Retrieves the SSL object from the underlying TCPS transport.
amps_client_create
AMPSDLL amps_handle amps_client_create(const amps_char *clientName)
Functions for creation of an AMPS client.
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.
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 incl...
ampsplusplus.hpp
Core type, function, and class declarations for the AMPS C++ client.