AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.3.2
amps.h
Go to the documentation of this file.
1 /* ////////////////////////////////////////////////////////////////////////
2  *
3  * Copyright (c) 2010-2021 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 #endif
38 #include <string.h>
39 #include <time.h>
40 #include <stdio.h>
41 #include "amps_generated.h"
42 
43 #define AMPSDLL
44 
45 #ifdef _WIN32
46 #define AMPS_USLEEP(x) Sleep((DWORD)(x)/(DWORD)1000);
47 #define AMPS_YIELD() SwitchToThread()
48 typedef HANDLE AMPS_THREAD_T;
49 typedef SOCKET AMPS_SOCKET;
50 typedef __int32 amps_int32_t;
51 typedef unsigned __int32 amps_uint32_t;
52 typedef __int64 amps_int64_t;
53 typedef unsigned __int64 amps_uint64_t;
54 #else
55 #define AMPS_USLEEP(x) usleep((unsigned int)(x));
56 #define AMPS_YIELD() pthread_yield()
57 typedef pthread_t AMPS_THREAD_T;
58 typedef int AMPS_SOCKET;
59 typedef int32_t amps_int32_t;
60 typedef uint32_t amps_uint32_t;
61 typedef int64_t amps_int64_t;
62 typedef uint64_t amps_uint64_t;
63 #endif
64 
65 #if defined(_WIN32) || defined(__SSE_4_2__)
66 #define AMPS_SSE_42 1
67 #endif
68 
167 #ifdef __cplusplus
168 extern "C" {
169 #endif
170 
171  typedef char amps_char;
172 
179  typedef void* amps_handle;
180 
184  typedef enum
185  {
242  } amps_result;
243 
244  typedef amps_result(*amps_handler)(amps_handle, void*);
245  typedef void(*amps_predisconnect_handler)(amps_handle, unsigned, void*);
246 
247 
257  amps_handle AMPSDLL amps_client_create(
258  const amps_char* clientName);
259 
270  amps_result AMPSDLL amps_client_set_name(
271  amps_handle handle,
272  const amps_char* clientName);
273 
281  amps_result AMPSDLL amps_client_connect(
282  amps_handle handle,
283  const amps_char* uri);
284 
289  void AMPSDLL amps_client_disconnect(
290  amps_handle handle);
291 
298  void AMPSDLL amps_client_destroy(
299  amps_handle handle);
300 
309  size_t amps_client_get_error(
310  amps_handle client,
311  amps_char* errorMessageOut,
312  size_t bufferSize);
313 
321  amps_result amps_client_send(
322  amps_handle client,
323  amps_handle message);
324 
333  amps_result amps_client_send_with_version(
334  amps_handle client,
335  amps_handle message,
336  unsigned* version_out);
337 
338 
348  amps_handle client,
349  amps_handler messageHandler,
350  void* userData);
351 
361  amps_handle client,
362  amps_predisconnect_handler predisconnectHandler,
363  void* userData);
364 
374  amps_handle client,
375  amps_handler disconnectHandler,
376  void* userData);
377 
384  amps_handle amps_client_get_transport(
385  amps_handle client);
386 
394  amps_result
395  amps_client_attempt_reconnect(amps_handle client, unsigned version);
396 
406  amps_handle amps_message_create(amps_handle client);
407 
413  amps_handle amps_message_copy(amps_handle message);
414 
419  void amps_message_destroy(amps_handle message);
420 
427  void amps_message_reset(amps_handle message);
428 
444  amps_handle message,
445  FieldId field,
446  const amps_char** value_ptr,
447  size_t* length_ptr);
448 
457  amps_handle message,
458  FieldId field,
459  const amps_char* value,
460  size_t length);
461 
470  amps_handle message,
471  FieldId field,
472  const amps_char* value,
473  size_t length);
474 
483  amps_handle message,
484  FieldId field,
485  const amps_char* value);
486 
487 
495  amps_handle message,
496  FieldId field);
497 
505  amps_handle message,
506  const amps_char* value,
507  size_t length);
508 
516  amps_handle message,
517  const amps_char* value,
518  size_t length);
519 
526  amps_handle message,
527  const amps_char* value);
528 
542  amps_handle message,
543  amps_char** value_ptr,
544  size_t* length_ptr);
545 
552  unsigned long amps_message_get_field_long(
553  amps_handle message,
554  FieldId field);
555 
562  amps_uint64_t amps_message_get_field_uint64(
563  amps_handle message,
564  FieldId field);
565 
575  amps_result amps_client_set_read_timeout(
576  amps_handle client,
577  int readTimeout);
578 
579 
589  amps_result amps_client_set_idle_time(
590  amps_handle client,
591  int idleTime);
592 
601 typedef void(*amps_transport_filter_function)(const unsigned char*,size_t,short,void*);
602 
617  amps_handle client,
619  void* userData);
620 
627 typedef amps_result(*amps_thread_created_callback)(AMPS_THREAD_T,void*);
628 
641  amps_handle client,
643  void* userData);
644 
650  AMPS_SOCKET
651  amps_tcp_get_socket(amps_handle transport);
652 
653  AMPS_SOCKET
654  amps_tcps_get_socket(amps_handle transport);
655 
661  void*
662  amps_tcps_get_SSL(amps_handle transport);
663 
664 /*
665  * Returns the current wall-clock time in milliseconds
666  */
667  amps_uint64_t
668  amps_now(void);
669 
670 
694 int amps_ssl_init(const char* dllPath_);
695 
703 int amps_ssl_set_verify(int mode_);
704 
715 int amps_ssl_load_verify_locations(const char* caFile_, const char* caPath_);
716 
722 void amps_ssl_free(void);
723 
729 const char* amps_ssl_get_error(void);
730 
731 void amps_noOpFn(void*);
732 
733 /*
734  * Internal API for use by the python client.
735  */
736 void amps_set_waiting_function(void*);
737 void amps_invoke_waiting_function(void);
738 void amps_set_remove_route_function(void*);
739 void amps_invoke_remove_route_function(void*);
740 void amps_set_copy_route_function(void*);
741 void* amps_invoke_copy_route_function(void*);
742 
743 #ifdef __cplusplus
744 }
745 #if !defined(_AMPS_BUILD_C_CLIENT) && !defined(_AMPS_SKIP_AMPSPLUSPLUS)
746 #include <ampsplusplus.hpp>
747 #endif
748 #endif
749 
750 #endif
A connection error occured.
Definition: amps.h:201
int amps_ssl_load_verify_locations(const char *caFile_, const char *caPath_)
Configures OpenSSL to use the specified locations for locating CA certificates.
The specified URI is invalid.
Definition: amps.h:229
void amps_message_reset(amps_handle message)
Clears all fields and data in a 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.
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...
A Secure Sockets Layer (SSL) error occured.
Definition: amps.h:241
void AMPSDLL amps_client_disconnect(amps_handle handle)
Disconnects from the AMPS server, if connected.
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...
size_t amps_client_get_error(amps_handle client, amps_char *errorMessageOut, size_t bufferSize)
Returns the last error set on this client.
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.
Success.
Definition: amps.h:189
amps_handle AMPSDLL amps_client_create(const amps_char *clientName)
Functions for creation of an AMPS client.
The specified topic was invalid.
Definition: amps.h:205
void * amps_handle
Opaque handle type used to refer to objects in the AMPS api.
Definition: amps.h:179
amps_result
Return values from amps_xxx functions.
Definition: amps.h:184
void amps_ssl_free(void)
Frees OpenSSL context and shared library.
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:601
amps_result AMPSDLL amps_client_connect(amps_handle handle, const amps_char *uri)
Connects to the AMPS server specified in uri.
int amps_ssl_init(const char *dllPath_)
Initializes SSL support in the AMPS Client.
A memory error occured.
Definition: amps.h:193
amps_result amps_client_attempt_reconnect(amps_handle client, unsigned version)
Manually invokes the user-supplied disconnect handler for this client.
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...
Core type, function, and class declarations for the AMPS C++ client.
The specified filter was invalid.
Definition: amps.h:209
void AMPSDLL amps_client_destroy(amps_handle handle)
Disconnects and destroys an AMPS client object.
void * amps_tcps_get_SSL(amps_handle transport)
Retrieves the SSL object from the underlying TCPS transport.
An error with a command occured.
Definition: amps.h:197
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_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_result amps_client_send_with_version(amps_handle client, amps_handle message, unsigned *version_out)
Sends a message to the AMPS server.
The server could not be found, or it actively refused our connection.
Definition: amps.h:221
void amps_client_set_message_handler(amps_handle client, amps_handler messageHandler, void *userData)
Sets the message handler function for this client.
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_handle amps_message_create(amps_handle client)
Functions for creation and manipulation of AMPS messages.
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.
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_SOCKET amps_tcp_get_socket(amps_handle transport)
TRANSPORT-SPECIFIC APIS.
void amps_message_set_data_nts(amps_handle message, const amps_char *value)
Sets the data component of an AMPS message.
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.
int amps_ssl_set_verify(int mode_)
Configures OpenSSL to validate the server&#39;s certificate when connecting.
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_result amps_client_set_idle_time(amps_handle client, int idleTime)
Sets an idle-time (milliseconds).
The usage of this function is invalid.
Definition: amps.h:237
amps_result AMPSDLL amps_client_set_name(amps_handle handle, const amps_char *clientName)
Sets the name on an amps client object.
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...
void amps_message_set_data(amps_handle message, const amps_char *value, size_t length)
Sets the data component of an AMPS message.
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:627
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.
A stream error has occured.
Definition: amps.h:225
The operation has not succeeded, but ought to be retried.
Definition: amps.h:213
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.
The client and server are disconnected.
Definition: amps.h:217
const char * amps_ssl_get_error(void)
Returns the description of the last error from calling amps_ssl_init().
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_result amps_client_send(amps_handle client, amps_handle message)
Sends a message to the AMPS server.
The specified transport type is invalid.
Definition: amps.h:233
void amps_message_destroy(amps_handle message)
Destroys and frees the memory associated with an AMPS message object.