ThingWorx C SDK
twApi.h
Go to the documentation of this file.
1 /***************************************
2  * Copyright (C) 2015 ThingWorx Inc. *
3  ***************************************/
4 
13 #ifndef TW_API_H
14 #define TW_API_H
15 
16 #include "twOSPort.h"
17 #include "twDefinitions.h"
18 #include "twDefaultSettings.h"
19 #include "twLogger.h"
20 #include "twBaseTypes.h"
21 #include "twMessaging.h"
22 #include "twInfoTable.h"
23 #include "twTasker.h"
24 #include "twConnectionInfo.h"
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 #define propertyList twList /* A propertyList is a twList */
31 
38 typedef struct callbackInfo {
39  enum entityTypeEnum entityType;
40  char * entityName;
41  enum characteristicEnum characteristicType;
42  char * charateristicName;
43  void * charateristicDefinition;
44  void * cb;
45  void * userdata;
46 } callbackInfo;
47 
73 typedef enum msgCodeEnum (*property_cb) (const char * entityName, const char * propertyName, twInfoTable ** value, char isWrite, void * userdata);
74 
98 typedef enum msgCodeEnum (*service_cb) (const char * entityName, const char * serviceName, twInfoTable * params, twInfoTable ** content, void * userdata);
99 
111 typedef twMessage * (*genericRequest_cb)(twMessage * msg);
112 
130 typedef void (*bindEvent_cb)(char * entityName, char isBound, void * userdata);
131 
149 typedef void (*authEvent_cb)(char * credentialType, char * credentialValue, void * userdata);
150 
162 typedef struct twApi {
171  uint8_t duty_cycle;
172  uint32_t duty_cycle_period;
176  uint32_t offlineMsgSize;
177  char * offlineMsgFile;
180  uint32_t ping_rate;
182  uint32_t connect_timeout;
183  int16_t connect_retries;
187 } twApi;
188 
189 
220 int twApi_Initialize(char * host, uint16_t port, char * resource, char * app_key, char * gatewayName,
221  uint32_t messageChunkSize, uint16_t frameSize, char autoreconnect);
222 
230 int twApi_Delete();
231 
237 char * twApi_GetVersion();
238 
255 int twApi_Connect(uint32_t timeout, int32_t retries);
256 
265 int twApi_Disconnect(char * reason);
266 
279 int twApi_SetDutyCycle(uint8_t duty_cycle, uint32_t period);
280 
287 void twApi_SetSelfSignedOk();
288 
296 
306 
315 
338 int twApi_SetX509Fields(char * subject_cn, char * subject_o, char * subject_ou,
339  char * issuer_cn, char * issuer_o, char * issuer_ou);
340 
355 int twApi_LoadCACert(const char *file, int type);
356 
367 int twApi_LoadClientCert(char *file);
368 
381 int twApi_SetClientKey(const char *file, char * passphrase, int type);
382 
393 int twApi_SetPingRate(uint32_t rate);
394 
406 int twApi_SetConnectTimeout(uint32_t timeout);
407 
418 int twApi_SetConnectRetries(signed char retries);
419 
420 
429 int twApi_SetGatewayName(const char* input_name);
430 
439 int twApi_SetGatewayType(const char* input_type);
447 
463 int twApi_SetProxyInfo(char * proxyHost, uint16_t proxyPort, char * proxyUser, char * proxyPass);
464 
475 
489 int twApi_SetOfflineMsgStoreDir(const char *dir);
490 
504 int twApi_RegisterConnectCallback(eventcb cb);
505 
515 int twApi_RegisterCloseCallback(eventcb cb);
516 
522 char twApi_isConnected();
523 
531 
539 
556 int twApi_BindThing(char * entityName);
557 
570 int twApi_UnbindThing(char * entityName);
571 
585 int twApi_RegisterBindEventCallback(char * entityName, bindEvent_cb cb, void * userdata);
586 
601 int twApi_UnregisterBindEventCallback(char * entityName, bindEvent_cb cb, void * userdata);
602 
615 int twApi_RegisterOnAuthenticatedCallback(authEvent_cb cb, void * userdata);
616 
630 
638 char twApi_IsEntityBound(char * entityName);
639 
659 void twApi_TaskerFunction(DATETIME now, void * params);
660 
692 int twApi_RegisterProperty(enum entityTypeEnum entityType, char * entityName, char * propertyName, enum BaseType propertyType,
693  char * propertyDescription, char * propertyPushType, double propertyPushThreshold, property_cb cb, void * userdata);
694 
709 int twApi_AddAspectToProperty(char * entityName, char * propertyName,
710  char * aspectName, twPrimitive * aspectValue);
711 
729 int twApi_UpdatePropertyMetaData(enum entityTypeEnum entityType, char * entityName, char * propertyName, enum BaseType propertyType,
730  char * propertyDescription, char * propertyPushType, double propertyPushThreshold);
731 
759 int twApi_RegisterService(enum entityTypeEnum entityType, char * entityName, char * serviceName, char * serviceDescription,
760  twDataShape * inputs, enum BaseType outputType, twDataShape * outputDataShape, service_cb cb, void * userdata);
761 
776 int twApi_AddAspectToService(char * entityName, char * serviceName,
777  char * aspectName, twPrimitive * aspectValue);
778 
779 /*
780 twApi_RegisterEvent - register an event. This event will be reported back to the server when it is browsing. Note that Events do not have callbacks since
781  they not invokeable from the server to the edge.
782 Parameters:
783  entityType - the type of entity that the property belongs to. Enum can be found in twDefinitions.h
784  entityName - the name of the entity that the property belongs to.
785  eventName - the name of the service.
786  eventDescription - description of the service
787  inputs - a datashape that describes the event parameters. See twInfoTable for the twDataShape definition.
788 Return:
789  int - 0 if successful, positive integral error code (see twErrors.h) if an was encountered
790 */
791 int twApi_RegisterEvent(enum entityTypeEnum entityType, char * entityName, char * eventName, char * eventDescription, twDataShape * parameters);
792 
807 int twApi_AddAspectToService(char * entityName, char * eventName,
808  char * aspectName, twPrimitive * aspectValue);
809 
824 int twApi_UnregisterPropertyCallback(char * entityName, char * propertyName, void * userdata);
825 
840 int twApi_UnregisterServiceCallback(char * entityName, char * serviceName, void * userdata);
841 
850 int twApi_UnregisterThing(char * entityName);
851 
862 
884 int twApi_RegisterPropertyCallback(enum entityTypeEnum entityType, char * entityName, char * propertyName, property_cb cb, void * userdata);
885 
907 int twApi_RegisterServiceCallback(enum entityTypeEnum entityType, char * entityName, char * serviceName, service_cb cb, void * userdata);
908 
927 propertyList * twApi_CreatePropertyList(char * name, twPrimitive * value, DATETIME timestamp);
928 
938 int twApi_DeletePropertyList(propertyList * list);
939 
957 int twApi_AddPropertyToList(propertyList * proplist, char * name, twPrimitive * value, DATETIME timestamp);
958 
981 int twApi_ReadProperty(enum entityTypeEnum entityType, char * entityName, char * propertyName, twPrimitive ** result, int32_t timeout, char forceConnect);
982 
1006 int twApi_WriteProperty(enum entityTypeEnum entityType, char * entityName, char * propertyName, twPrimitive * value, int32_t timeout, char forceConnect);
1007 
1032 int twApi_PushProperties(enum entityTypeEnum entityType, char * entityName, propertyList * properties, int32_t timeout, char forceConnect);
1033 
1061 int twApi_InvokeService(enum entityTypeEnum entityType, char * entityName, char * serviceName, twInfoTable * params, twInfoTable ** result, int32_t timeout, char forceConnect);
1062 
1086 int twApi_FireEvent(enum entityTypeEnum entityType, char * entityName, char * eventName, twInfoTable * params, int32_t timeout, char forceConnect);
1087 
1110 int twApi_SetSubscribedPropertyVTQ(char * entityName, char * propertyName, twPrimitive * value, DATETIME timestamp, char * quality, char fold, char pushUpdate);
1111 
1130 int twApi_SetSubscribedProperty(char * entityName, char * propertyName, twPrimitive * value, char fold, char pushUpdate);
1131 
1143 int twApi_PushSubscribedProperties(char * entityName, char forceConnect);
1144 
1162 int twApi_UpdatePropertyMetaData(enum entityTypeEnum entityType, char * entityName, char * propertyName, enum BaseType propertyType,
1163  char * propertyDescription, char * propertyPushType, double propertyPushThreshold);
1164 
1169 /* Only use these functions if you want to override default keep alive handling */
1170 
1181 int twApi_SendPing(char * content);
1182 
1192 int twApi_RegisterPingCallback(eventcb cb);
1193 
1203 int twApi_RegisterPongCallback(eventcb cb);
1204 
1220 int twApi_CreateTask(uint32_t runTimeIntervalMsec, twTaskFunction func);
1221 
1222 #ifdef __cplusplus
1223 }
1224 #endif
1225 
1226 #endif /* TW_API_H */
char offlineMsgEnabled
Definition: twApi.h:174
uint8_t duty_cycle
Definition: twApi.h:171
void(* authEvent_cb)(char *credentialType, char *credentialValue, void *userdata)
Signature of a callback function that is registered to be called when authentication to the ThingWorx...
Definition: twApi.h:149
int twApi_EnableFipsMode()
Passthru to enable FIPS mode for TLS providers that support it.
Definition: twApi.c:1711
int twApi_UnregisterThing(char *entityName)
Removes all property & service callbacks for an entity.
Definition: twApi.c:1388
int twApi_AddPropertyToList(propertyList *proplist, char *name, twPrimitive *value, DATETIME timestamp)
Adds a property to a property list.
Definition: twApi.c:1468
twMessageHandler * mh
Definition: twApi.h:163
int twApi_SetSubscribedPropertyVTQ(char *entityName, char *propertyName, twPrimitive *value, DATETIME timestamp, char *quality, char fold, char pushUpdate)
Sets a new value, time and quality of the subscribed property. The subscribed property manager etermi...
Definition: twApi.c:1485
int twApi_SetDutyCycle(uint8_t duty_cycle, uint32_t period)
Changes the duty cycle (twApi::duty_cycle) and period (twApi::duty_cycle_period) of the connection...
Definition: twApi.c:1076
twList * callbackList
Definition: twApi.h:164
void twApi_TaskerFunction(DATETIME now, void *params)
Executes all functions required for proper operation of the API. This includes the connection receive...
Definition: twApi.c:1206
enum msgCodeEnum(* service_cb)(const char *entityName, const char *serviceName, twInfoTable *params, twInfoTable **content, void *userdata)
Signature of a callback function that is registered to be called when a specific service request is r...
Definition: twApi.h:98
twList * offlineMsgList
Definition: twApi.h:175
int twApi_SetGatewayName(const char *input_name)
Sets the Gateway Name that will be bound with the platform.
Definition: twApi.c:1104
ThingWorx API structure definition.
Definition: twApi.h:162
ThingWorx twInfoTable and twDataShape definitions and functions.
propertyList * twApi_CreatePropertyList(char *name, twPrimitive *value, DATETIME timestamp)
Creates a list of properties.
Definition: twApi.c:1450
int twApi_PushSubscribedProperties(char *entityName, char forceConnect)
Pushes all queued subscribed properties to the server.
Definition: twApi.c:1493
char * subscribedPropsFile
Definition: twApi.h:178
char isAuthenticated
Definition: twApi.h:170
char autoreconnect
Definition: twApi.h:168
Definition: twApi.h:38
int twApi_FireEvent(enum entityTypeEnum entityType, char *entityName, char *eventName, twInfoTable *params, int32_t timeout, char forceConnect)
Invokes an event on the ThingWorx server.
Definition: twApi.c:1556
int8_t manuallyDisconnected
Definition: twApi.h:169
int twApi_SetGatewayType(const char *input_type)
Sets the Gateway Type that will be bound with the platform.
Definition: twApi.c:1111
int twApi_InvokeService(enum entityTypeEnum entityType, char *entityName, char *serviceName, twInfoTable *params, twInfoTable **result, int32_t timeout, char forceConnect)
Invokes a service on the ThingWorx server.
Definition: twApi.c:1551
int twApi_SetPingRate(uint32_t rate)
Sets the websockets ping/pong interval (see twApi::ping_rate).
Definition: twApi.c:1086
#define TW_MUTEX
For Linux builds a TW_MUTEX is a pthread_mutex_t.
Definition: twLinux-openssl.h:81
int twApi_Disconnect(char *reason)
Unbinds any bound entities and disconnects from the ThingWorx server.
Definition: twApi.c:1046
char firstConnectionComplete
Definition: twApi.h:185
int twApi_SetProxyInfo(char *proxyHost, uint16_t proxyPort, char *proxyUser, char *proxyPass)
Sets the proxy information to be used when making a connection.
Wrappers for OS-specific functionality.
Linked list structure definition.
Definition: twList.h:46
void twApi_SetSelfSignedOk()
Passthru to notify the TLS library to accept self-signed certificates.
Definition: twApi.c:1653
char twApi_isConnected()
Checks to see if the API websocket is connected.
Definition: twApi.c:1061
int twApi_Initialize(char *host, uint16_t port, char *resource, char *app_key, char *gatewayName, uint32_t messageChunkSize, uint16_t frameSize, char autoreconnect)
Creates the twApi singleton and any dependent structures.
Definition: twApi.c:812
int twApi_LoadClientCert(char *file)
Loads the local PEM or DER formatted certificate file used to validate the client to the ThingWorx se...
Definition: twApi.c:1677
int twApi_SetSubscribedProperty(char *entityName, char *propertyName, twPrimitive *value, char fold, char pushUpdate)
Sets a new value for the subscribed property. The subscribed property manager determines if the new v...
Definition: twApi.c:1489
int twApi_UnregisterOnAuthenticatedCallback(authEvent_cb cb, void *userdata)
Unregisters a callback registered via twApi_RegisterOnAuthenticatedCallback() (see callback function ...
Definition: twApi.c:1624
int twApi_UpdatePropertyMetaData(enum entityTypeEnum entityType, char *entityName, char *propertyName, enum BaseType propertyType, char *propertyDescription, char *propertyPushType, double propertyPushThreshold)
Updates the metadata aspects of a property.
Definition: twApi.c:1295
int twApi_SendPing(char *content)
Pings the ThingWorx server.
Definition: twApi.c:1644
int twApi_Connect(uint32_t timeout, int32_t retries)
Establishes the websocket connection, performs authentication and binds any registered Things...
Definition: twApi.c:1009
Definition: twMessaging.h:51
int twApi_Delete()
Shuts down the websocket and frees all memory associated with the twApi structure and all its owned s...
Definition: twApi.c:915
int twApi_SetOfflineMsgStoreDir(const char *dir)
Sets the offline message store directory.
Definition: twApi.c:1771
char handle_pongs
Definition: twApi.h:181
int twApi_RegisterPropertyCallback(enum entityTypeEnum entityType, char *entityName, char *propertyName, property_cb cb, void *userdata)
Register a property callback only (see callback function signature property_cb()).
Definition: twApi.c:1346
twConnectionInfo * connectionInfo
Definition: twApi.h:186
int twApi_ReadProperty(enum entityTypeEnum entityType, char *entityName, char *propertyName, twPrimitive **result, int32_t timeout, char forceConnect)
Gets the current value of a property from the ThingWorx server.
Definition: twApi.c:1472
entityTypeEnum
Definition: twDefinitions.h:113
char twApi_ConnectionInProgress()
Checks to see if the API is in the process of connecting to the websocket.
Definition: twApi.c:1066
ThingWorx tunneling connection information structure definition and functions.
msgCodeEnum
Enumeration of HTTP message codes.
Definition: twDefinitions.h:74
characteristicEnum
Definition: twDefinitions.h:146
int twApi_RegisterBindEventCallback(char *entityName, bindEvent_cb cb, void *userdata)
Registers a function to be called when an entity is bound or unbound (see callback function signature...
Definition: twApi.c:1588
int twApi_RegisterDefaultRequestHandler(genericRequest_cb cb)
Registers a service callback function that will get called for all unhandled requests (see callback f...
Definition: twApi.c:1442
void(* bindEvent_cb)(char *entityName, char isBound, void *userdata)
Signature of a callback function that is registered to be called when a bind or unbind completes...
Definition: twApi.h:130
int twApi_UnregisterPropertyCallback(char *entityName, char *propertyName, void *userdata)
Removes a property from the callback list. This service will no longer be reported back to the ThingW...
Definition: twApi.c:1434
uint32_t duty_cycle_period
Definition: twApi.h:172
Default settings for ThingWorx C SDK.
int twApi_RegisterService(enum entityTypeEnum entityType, char *entityName, char *serviceName, char *serviceDescription, twDataShape *inputs, enum BaseType outputType, twDataShape *outputDataShape, service_cb cb, void *userdata)
Registers a service and callback. This service will be reported back to the ThingWorx server when it ...
Definition: twApi.c:1325
int twApi_SetConnectTimeout(uint32_t timeout)
Sets the amount of time (in milliseconds) the websocket waits while attempting a connection (see twAp...
Definition: twApi.c:1092
int twApi_AddAspectToService(char *entityName, char *serviceName, char *aspectName, twPrimitive *aspectValue)
Adds an aspect to an already registered service.
Definition: twApi.c:1331
uint32_t offlineMsgSize
Definition: twApi.h:176
char * offlineMsgFile
Definition: twApi.h:177
int twApi_UnregisterBindEventCallback(char *entityName, bindEvent_cb cb, void *userdata)
Unregisters a callback registered via twApi_RegisterBindEventCallback() (see callback function signat...
Definition: twApi.c:1598
Common definitions for C SDK.
int twApi_UnregisterServiceCallback(char *entityName, char *serviceName, void *userdata)
Removes a service from the callback list. This service will no longer be reported back to the ThingWo...
Definition: twApi.c:1438
twList * boundList
Definition: twApi.h:165
twConnectionInfo * twApi_GetConnectionInfo()
Creates a copy of the current connection info of the ThingWorx server.
Definition: twApi.c:1767
Data shape base structure definition.
Definition: twInfoTable.h:184
char connectionInProgress
Definition: twApi.h:184
int twApi_RegisterProperty(enum entityTypeEnum entityType, char *entityName, char *propertyName, enum BaseType propertyType, char *propertyDescription, char *propertyPushType, double propertyPushThreshold, property_cb cb, void *userdata)
Registers a property and callback. This property will be reported back to the ThingWorx server when i...
Definition: twApi.c:1270
ThingWorx BaseType definitions and functions.
int twApi_BindThing(char *entityName)
Bind an entity to this connection with the ThingWorx server.
Definition: twApi.c:1119
int twApi_AddAspectToProperty(char *entityName, char *propertyName, char *aspectName, twPrimitive *aspectValue)
Adds an aspect to an already registered property.
Definition: twApi.c:1320
int twApi_ClearProxyInfo()
Clears the proxy information of the socket to be used when making a connection.
void(* twTaskFunction)(uint64_t sys_msecs, void *params)
Function signature of a task called in round robin fashion.
Definition: twTasker.h:32
int twApi_DeletePropertyList(propertyList *list)
Frees all memory associated with a ::propertyList and all its owned substructures.
Definition: twApi.c:1464
void twApi_DisableCertValidation()
Passthru to notify the TLS library to not validate the ThingWorx server certificate.
Definition: twApi.c:1658
int twApi_UnbindThing(char *entityName)
Unbind an entity from this connection with the ThingWorx server.
Definition: twApi.c:1151
uint32_t subscribedPropsSize
Definition: twApi.h:179
int twApi_RegisterCloseCallback(eventcb cb)
Registers a function to be called when the websocket disconnects (see callback function signature eve...
Definition: twApi.c:1569
Definition: twMessages.h:32
Tunnel Connection Details Structure Definition.
Definition: twConnectionInfo.h:22
char * twApi_GetVersion()
Returns a constant pointer to the version string of the API.
Definition: twApi.c:966
int twApi_WriteProperty(enum entityTypeEnum entityType, char *entityName, char *propertyName, twPrimitive *value, int32_t timeout, char forceConnect)
Writes a new value of the property to the ThingWorx server.
Definition: twApi.c:1477
Info table base structure.
Definition: twInfoTable.h:418
int twApi_CreateTask(uint32_t runTimeIntervalMsec, twTaskFunction func)
Adds a new task to the round robin scheduler (see callback function signature twTaskFunction).
Definition: twApi.c:1649
int twApi_LoadCACert(const char *file, int type)
Loads the local PEM or DER formatted certificate file used to validate the ThingWorx server...
Definition: twApi.c:1663
int twApi_PushProperties(enum entityTypeEnum entityType, char *entityName, propertyList *properties, int32_t timeout, char forceConnect)
Writes a set of values of various properties (stored in a propertyList) to the ThingWorx server...
Definition: twApi.c:1497
int twApi_SetClientKey(const char *file, char *passphrase, int type)
Sets the passphrase key of the local PEM or DER formatted certificate file used to validate the clien...
Definition: twApi.c:1691
enum msgCodeEnum(* property_cb)(const char *entityName, const char *propertyName, twInfoTable **value, char isWrite, void *userdata)
Signature of a callback function that is registered to be called when a specific property request is ...
Definition: twApi.h:73
int twApi_RegisterOnAuthenticatedCallback(authEvent_cb cb, void *userdata)
Registers a function to be called when the connection to the ThingWorx server is fully authenticated ...
Definition: twApi.c:1613
uint32_t connect_timeout
Definition: twApi.h:182
Simple ThingWorx Tasker.
twList * bindEventCallbackList
Definition: twApi.h:166
int twApi_SetX509Fields(char *subject_cn, char *subject_o, char *subject_ou, char *issuer_cn, char *issuer_o, char *issuer_ou)
Defines which fields of an X509 certificate will be validated.
Definition: twApi.c:1727
Structure definitions and function prototypes for the ThingWorx logging facility. ...
char twApi_IsEntityBound(char *entityName)
Checks to see if an entity is bound through the API.
Definition: twApi.c:1189
int twApi_RegisterServiceCallback(enum entityTypeEnum entityType, char *entityName, char *serviceName, service_cb cb, void *userdata)
Register a service callback only (see callback function signature service_cb()).
Definition: twApi.c:1367
int twApi_RegisterPongCallback(eventcb cb)
Registers a callback function to be called when a Pong is received (see callback function signature e...
Definition: twApi.c:1579
TW_MUTEX mtx
Definition: twApi.h:173
void twApi_DisableEncryption()
Passthru to notify the TLS library to disable encryption.
Definition: twApi.c:1719
BaseType
Definition: twDefinitions.h:155
BaseType primitive structure.
Definition: twBaseTypes.h:207
struct twApi twApi
ThingWorx API structure definition.
int twApi_SetConnectRetries(signed char retries)
Sets the number of times to attempt to reconnect if the connection fails (see twApi::connect_retries)...
Definition: twApi.c:1098
int16_t connect_retries
Definition: twApi.h:183
genericRequest_cb defaultRequestHandler
Definition: twApi.h:167
twMessage *(* genericRequest_cb)(twMessage *msg)
Signature of a callback function that is registered to be called for unhandled requests.
Definition: twApi.h:111
int twApi_StopConnectionAttempt()
Kills any long running connection attempt.
Definition: twApi.c:1071
int twApi_RegisterPingCallback(eventcb cb)
Registers a callback function to be called when a Ping is received (see callback function signature e...
Definition: twApi.c:1574
int twApi_RegisterConnectCallback(eventcb cb)
Registers a function to be called when the web socket connects (see callback function signature event...
Definition: twApi.c:1564
uint32_t ping_rate
Definition: twApi.h:180