ThingWorx C SDK
Classes | Macros
twApi.h File Reference

Portable ThingWorx C SDK API layer. More...

#include "twMap.h"
#include "twDict.h"
#include "twOSPort.h"
#include "twDefinitions.h"
#include "twDefaultSettings.h"
#include "twLogger.h"
#include "twBaseTypes.h"
#include "twMessaging.h"
#include "twInfoTable.h"
#include "twTasker.h"
#include "twConnectionInfo.h"
#include "twOfflineMsgStore.h"

Go to the source code of this file.

Classes

struct  callbackInfo
 
struct  bindListEntry
 
struct  init_cb
 
struct  twApi
 ThingWorx API structure definition. More...
 

Macros

#define OFFLINE_MSG_STORE   0
 
#define propertyList   twList /* A propertyList is a twList */
 

Typedefs

Generic callback data structure
Note
Internal structure to handle callback information. There should be no need to manipulate this structure directly.
typedef struct callbackInfo callbackInfo
 
typedef struct bindListEntry bindListEntry
 
Callback Function Signatures
typedef 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 received from the ThingWorx server. More...
 
typedef 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 received from the ThingWorx server. More...
 
typedef twMessage *(* genericRequest_cb) (twMessage *msg)
 Signature of a callback function that is registered to be called for unhandled requests. More...
 
typedef 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. More...
 
typedef void(* synchronizeEvent_cb) (char *entityName, twInfoTable *subscriptionInfo, void *userdata)
 Signature of a callback function that is registered to be called when a platform subscription synchronization completes. More...
 
typedef 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 server completes. More...
 
typedef void(* init_cb_t) (void *userdata)
 
typedef struct init_cb init_cb
 
API Structure Definition
typedef struct twApi twApi
 ThingWorx API structure definition. More...
 

Functions

Lifecycle Functions
int twApi_Initialize (char *host, uint16_t port, char *resource, twPasswdCallbackFunction app_key_function, char *gatewayName, uint32_t messageChunkSize, uint16_t frameSize, char autoreconnect)
 Creates the twApi singleton and any dependent structures. More...
 
int twApi_Delete ()
 Shuts down the websocket and frees all memory associated with the twApi structure and all its owned substructures. More...
 
char * twApi_GetVersion ()
 Returns a constant pointer to the version string of the API. More...
 
Connection Functions
int twApi_Connect (uint32_t timeout, int16_t retries)
 Establishes the websocket connection, performs authentication and binds any registered Things. More...
 
int twApi_Disconnect (char *reason)
 Unbinds any bound entities and disconnects from the ThingWorx server. More...
 
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. More...
 
void twApi_SetSelfSignedOk ()
 Passthru to notify the TLS library to accept self-signed certificates. More...
 
int twApi_IsFIPSCompatible ()
 Ask the TLS implementation if it is capable of supporting FIPS. More...
 
int twApi_EnableFipsMode ()
 Passthru to enable FIPS mode for TLS providers that support it. More...
 
int twApi_DisableFipsMode ()
 Passthru to disable FIPS mode for TLS providers that support it. More...
 
int twApi_IsFipsModeEnabled ()
 Ask the TLS implementation if FIPS mode is currently enabled. More...
 
void twApi_DisableCertValidation ()
 Passthru to notify the TLS library to not validate the ThingWorx server certificate. More...
 
void twApi_DisableEncryption ()
 Passthru to notify the TLS library to disable encryption. More...
 
void twApi_DisableWebSocketCompression ()
 Force WebSocket communications to not use compression. More...
 
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. More...
 
int twApi_LoadCACert (const char *file, int type)
 Loads the local PEM or DER formatted certificate file used to validate the ThingWorx server. More...
 
int twApi_LoadClientCert (char *file)
 Loads the local PEM or DER formatted certificate file used to validate the client to the ThingWorx server. More...
 
int twApi_SetClientKey (const char *file, twPasswdCallbackFunction passphraseCallback, int type)
 Sets the passphrase key of the local PEM or DER formatted certificate file used to validate the client to the ThingWorx server. More...
 
int twApi_SetPingRate (uint32_t rate)
 Sets the websockets ping/pong interval (see twApi::ping_rate). More...
 
int twApi_SetConnectTimeout (uint32_t timeout)
 Sets the amount of time (in milliseconds) the websocket waits while attempting a connection (see twApi::connect_timeout). More...
 
int twApi_SetConnectRetries (signed char retries)
 Sets the number of times to attempt to reconnect if the connection fails (see twApi::connect_retries). More...
 
int twApi_SetGatewayName (const char *input_name)
 Sets the Gateway Name that will be bound with the platform. More...
 
int twApi_SetGatewayType (const char *input_type)
 Sets the Gateway Type that will be bound with the platform. More...
 
int twApi_ClearProxyInfo ()
 Clears the proxy information of the socket to be used when making a connection. More...
 
int twApi_SetProxyInfo (char *proxyHost, uint16_t proxyPort, char *proxyUser, twPasswdCallbackFunction proxyPassCallback)
 Sets the proxy information to be used when making a connection. More...
 
twConnectionInfotwApi_GetConnectionInfo ()
 Creates a copy of the current connection info of the ThingWorx server. More...
 
Connection Status Functions
int twApi_RegisterConnectCallback (eventcb cb)
 Registers a function to be called when the web socket connects (see callback function signature eventcb()). More...
 
int twApi_RegisterCloseCallback (eventcb cb)
 Registers a function to be called when the websocket disconnects (see callback function signature eventcb()). More...
 
char twApi_isConnected ()
 Checks to see if the API websocket is connected. More...
 
char twApi_ConnectionInProgress ()
 Checks to see if the API is in the process of connecting to the websocket. More...
 
int twApi_StopConnectionAttempt ()
 Kills any long running connection attempt. More...
 
Binding Functions
int twApi_BindThingWithoutDefaultServices (char *entityName)
 Bind an entity to this connection with the ThingWorx server. This version of the function will not register the getMetadata service expecting the calling appliation ro register their own version which is useful in api integration with other languages which use annotaions or other methods to define their metadata. More...
 
int twApi_BindThing (char *entityName)
 Bind an entity to this connection with the ThingWorx server. More...
 
int twApi_BindThings (twList *entityNames)
 Bind entities to this connection with the ThingWorx server. More...
 
int twApi_BindThings_Metadata_Option (twList *entityNames, char omitMetadataCallback)
 Bind entities to this connection with the ThingWorx server. More...
 
int twApi_UnbindThing (char *entityName)
 Unbind an entity from this connection with the ThingWorx server. More...
 
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 bindEvent_cb()). More...
 
int twApi_UnregisterBindEventCallback (char *entityName, bindEvent_cb cb, void *userdata)
 Unregisters a callback registered via twApi_RegisterBindEventCallback() (see callback function signature bindEvent_cb()). More...
 
int twApi_UnregisterSynchronizeStateEventCallback (char *entityName, synchronizeEvent_cb cb, void *userdata)
 Unregisters a callback registered via twApi_RegisterSynchronizeStateEventCallback() (see callback function signature synchronizedEvent_cb()). More...
 
int twApi_RegisterSynchronizeStateEventCallback (char *entityName, synchronizeEvent_cb cb, void *userdata)
 Registers a function to be called when an entity synchronizes its subscribed property list with the platform. (see callback function signature synchronizeEvent_cb()). More...
 
int twApi_RegisterOnAuthenticatedCallback (authEvent_cb cb, void *userdata)
 Registers a function to be called when the connection to the ThingWorx server is fully authenticated (see callback function signature authEvent_cb()). More...
 
int twApi_UnregisterOnAuthenticatedCallback (authEvent_cb cb, void *userdata)
 Unregisters a callback registered via twApi_RegisterOnAuthenticatedCallback() (see callback function signature authEvent_cb()). More...
 
int twApi_RegisterInitCallback (init_cb_t cb, void *userdata)
 
char twApi_IsEntityBound (char *entityName)
 Checks to see if an entity is bound through the API. More...
 
Operational Functions
void twApi_TaskerFunction (DATETIME now, void *params)
 Executes all functions required for proper operation of the API. This includes the connection receive loop, duty cycle control, stale message cleanup, ping/pong, etc. More...
 
Property and Service Callback Registration Functions
int twApi_RegisterProperty (enum entityTypeEnum entityType, const char *entityName, const char *propertyName, enum BaseType propertyType, const char *propertyDescription, const 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 it is browsing (see callback function signature property_cb()). More...
 
int twApi_AddAspectToProperty (const char *entityName, const char *propertyName, const char *aspectName, twPrimitive *aspectValue)
 Adds an aspect to an already registered property. More...
 
int twApi_AddAspectToEvent (char *entityName, char *eventName, char *aspectName, twPrimitive *aspectValue)
 Adds an aspect to an already registered event. More...
 
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. More...
 
int twApi_RegisterService (enum entityTypeEnum entityType, const 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 is browsing (see callback function signature property_cb()). More...
 
int twApi_AddAspectToService (char *entityName, char *serviceName, char *aspectName, twPrimitive *aspectValue)
 Adds an aspect to an already registered service. More...
 
int twApi_RegisterEvent (enum entityTypeEnum entityType, char *entityName, char *eventName, char *eventDescription, twDataShape *parameters)
 
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 ThingWorx server while browsing. More...
 
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 ThingWorx server while browsing. More...
 
int twApi_UnregisterThing (char *entityName)
 Removes all property & service callbacks for an entity. More...
 
int twApi_RegisterDefaultRequestHandler (genericRequest_cb cb)
 Registers a service callback function that will get called for all unhandled requests (see callback function signature genericRequest_cb()). More...
 
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()). More...
 
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()). More...
 
Server Property/Service/Event Accessor Functions
propertyList * twApi_CreatePropertyList (char *name, twPrimitive *value, DATETIME timestamp)
 Creates a list of properties. More...
 
int twApi_DeletePropertyList (propertyList *list)
 Frees all memory associated with a ::propertyList and all its owned substructures. More...
 
int twApi_AddPropertyToList (propertyList *proplist, char *name, twPrimitive *value, DATETIME timestamp)
 Adds a property to a property list. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int twApi_InvokeServiceAsync (enum entityTypeEnum entityType, char *entityName, char *serviceName, twInfoTable *params, char forceConnect, response_cb cb, uint32_t *messageId)
 Invokes a service on the ThingWorx server and then immediately returns, calling back a callback function when the service call completes. More...
 
int twApi_FireEvent (enum entityTypeEnum entityType, char *entityName, char *eventName, twInfoTable *params, int32_t timeout, char forceConnect)
 Invokes an event on the ThingWorx server. More...
 
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 etermines if the new value will be pushed to the server based on the property's push setting and the new value. More...
 
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 value will be pushed to the server based on the property's push setting and the new value. More...
 
int twApi_PushSubscribedProperties (char *entityName, char forceConnect)
 Pushes all queued subscribed properties to the server. More...
 
int twApi_PushSubscribedPropertiesAsync (char *entityName, char forceConnect, response_cb cb, twList **messageListRef)
 Pushes all queued subscribed properties to the server and then returns immediately. A callback function cb will be called, potentially, more than once, if the requested property push requires more than once service call to deliver. The number of service calls made will be a function of the maximum configured message size. If the max message size is large, fewer service calls will be required to push all property changes. The number of messages sent will equal the number of times the callback function cb will be called. The length of the list *messageListRef will be equal to the number of times the callback cb will be called. Each item in the *messageListRef contains a single uint32_t message id which can be used to verify that all the messages generated by this call have been processed. More...
 
Keep Alive Functions
int twApi_SendPing (char *content)
 Pings the ThingWorx server. More...
 
int twApi_RegisterPingCallback (eventcb cb)
 Registers a callback function to be called when a Ping is received (see callback function signature eventcb()). More...
 
int twApi_RegisterPongCallback (eventcb cb)
 Registers a callback function to be called when a Pong is received (see callback function signature eventcb()). More...
 
Tasker Functions
int twApi_CreateTask (uint32_t runTimeIntervalMsec, twTaskFunction func)
 Adds a new task to the round robin scheduler (see callback function signature twTaskFunction). More...
 
int twApi_SetOfflineMsgStoreDir (const char *dir)
 sets the offline message store directory. If the offline message store has already been initialized, then the change will not take effect until the entire API is restarted More...
 
twApitwApi_GetApi (void)
 
int twApi_SetIsAuthenticated (char value)
 Sets the isAuthenticated flag in the API singleton. More...
 
char twApi_GetIsAuthenticated ()
 Returns the value of the API singleton's isAuthenticated flag. More...
 
int twApi_ClearSubscribedPropertyCurrentValues ()
 Clears the spm's current values list. More...
 
int base64_encode (const unsigned char *in, unsigned long inlen, unsigned char *out, unsigned long *outlen)
 

Detailed Description

Portable ThingWorx C SDK API layer.

Contains structure type definitions and function prototypes for the ThingWorx API.

Typedef Documentation

typedef 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 server completes.

Parameters
[in]credentialTypeThe type of credential that was used to authenticate.
[in]credentialValueThe value for the credential that was passed to the ThingWorx server.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
Nothing.
Note
This callback is an indication that the connection to the ThingWorx server is fully up and accessible.
credentialType is guaranteed to not be NULL.
typedef 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.

Parameters
[in]entityNameName of the entity (Thing, Resource, etc.) this request is for.
[in]isBound#TRUE if the entity was bound, #FALSE if the entity was unbound.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
Nothing.
Note
This callback is an indication that the entity that was bound can (bind) or can no longer (unbind) be used by the application.
typedef struct bindListEntry bindListEntry

Bindlist Entry

typedef twMessage*(* genericRequest_cb) (twMessage *msg)

Signature of a callback function that is registered to be called for unhandled requests.

Parameters
[in]msgA twMessage structure.
Returns
A pointer to the response message.
Note
Registered via twApi_RegisterDefaultRequestHandler().
Warning
The user must keep the message ID the same as the request.
typedef 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 received from the ThingWorx server.

Parameters
[in]entityNameName of the entity (Thing, Resource, etc.) this request is for.
[in]propertyNameName of the property being requested. If NULL, return all properties.
[in,out]valueA pointer to a pointer to a twInfoTable containing the value of the property.
[in]isWrite#TRUE if this request is a write, #FALSE if this request is a read.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
TWX_SUCCESS if the request completes successfully, an appropriate error code if not (see msgCodeEnum).
Note
entityName is guaranteed to not be NULL.
value is guaranteed to not be NULL.
typedef 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 received from the ThingWorx server.

Parameters
[in]entityNameName of the entity (Thing, Resource, etc.) this request is for.
[in]serviceNameName of the service being requested.
[in]paramsA pointer to a twInfoTable containing all input parameters for the service.
[out]contentA pointer to a pointer to a twInfoTable.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
TWX_SUCCESS if the request completes successfully, an appropriate error code if not (see msgCodeEnum).
Note
entityName is guaranteed to not be NULL.
content is guaranteed to not be NULL, *content is not.
The function should create a new instance of a twInfoTable on the heap and return it via content.
Calling function will retain ownership of the content pointer and is responsible for freeing it.
typedef void(* synchronizeEvent_cb) (char *entityName, twInfoTable *subscriptionInfo, void *userdata)

Signature of a callback function that is registered to be called when a platform subscription synchronization completes.

Parameters
[in]entityNameName of the entity (Thing, Resource, etc.) this request is for.
[in]subscriptionInfoThe infotable returned from the lastg getPropertySubscriptions() call to the platform for this entity.
[in]userdataAn opaque pointer that is passed in when the callback is registered.
Returns
Nothing.
Note
This callback is an indication that the entity that was bound can (bind) or can no longer (unbind) be used by the application.
entityName is guaranteed to not be NULL.
typedef struct twApi twApi

ThingWorx API structure definition.

Note
A singleton instance of this structure is automatically created when twApi_initialize() is called. There should be no need to manipulate this structure directly.

Function Documentation

int base64_encode ( const unsigned char *  in,
unsigned long  inlen,
unsigned char *  out,
unsigned long *  outlen 
)

base64 Encode a buffer (NUL terminated)

Parameters
inThe input buffer to encode
inlenThe length of the input buffer
out[out] The destination of the base64 encoded data
outlen[in/out] The max size and resulting size
Returns
CRYPT_OK if successful
int twApi_AddAspectToEvent ( char *  entityName,
char *  eventName,
char *  aspectName,
twPrimitive aspectValue 
)

Adds an aspect to an already registered event.

Parameters
[in]entityNameThe name of the entity that the event belongs to.
[in]eventNameThe name of the property to add the aspect to.
[in]aspectNameThe name of the aspect.
[in]aspectValueThe value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_AddAspectToProperty ( const char *  entityName,
const char *  propertyName,
const char *  aspectName,
twPrimitive aspectValue 
)

Adds an aspect to an already registered property.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to add the aspect to.
[in]aspectNameThe name of the aspect.
[in]aspectValueThe value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_AddAspectToService ( char *  entityName,
char *  serviceName,
char *  aspectName,
twPrimitive aspectValue 
)

Adds an aspect to an already registered service.

Adds an aspect to an already registered event.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]serviceNameThe name of the service to add the aspect to.
[in]aspectNameThe name of the aspect.
[in]aspectValueThe value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]eventNameThe name of the event to add the aspect to.
[in]aspectNameThe name of the aspect.
[in]aspectValueThe value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.

Adds an aspect to an already registered service.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]eventNameThe name of the event to add the aspect to.
[in]aspectNameThe name of the aspect.
[in]aspectValueThe value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_AddPropertyToList ( propertyList *  proplist,
char *  name,
twPrimitive value,
DATETIME  timestamp 
)

Adds a property to a property list.

Parameters
[in]proplistA pointer to the list to add the property to.
[in]nameThe name of the property to add to the list.
[in]valueA pointer to the primitive containing the property type and value.
[in]timestampTimestamp of the first property (defaults to current time).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The newly allocated list will gain ownership the value pointer.
int twApi_BindThing ( char *  entityName)

Bind an entity to this connection with the ThingWorx server.

Parameters
[in]entityNameThe name of the entity to bind with the ThingWorx server.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
If there is currently an active connection a bind message is sent. If not, the bind message will be sent on the next connection.
int twApi_BindThings ( twList entityNames)

Bind entities to this connection with the ThingWorx server.

Parameters
[in]entityNamesThe names of the entities to bind with the ThingWorx server.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
If there is currently an active connection a bind message is sent. If not, the bind message will be sent on the next connection.
int twApi_BindThings_Metadata_Option ( twList entityNames,
char  omitMetadataCallback 
)

Bind entities to this connection with the ThingWorx server.

Parameters
[in]entityNamesThe names of the entities to bind with the ThingWorx server.
[in]omitMetadataCallbackFlag to omit registering metadata callback service on bind.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
this function can be used in advanced binding situations where the metadata callback should be ommitted, otherwise please use the twApi_BindThings method
int twApi_BindThingWithoutDefaultServices ( char *  entityName)

Bind an entity to this connection with the ThingWorx server. This version of the function will not register the getMetadata service expecting the calling appliation ro register their own version which is useful in api integration with other languages which use annotaions or other methods to define their metadata.

Parameters
[in]entityNameThe name of the entity to bind with the ThingWorx server.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
If there is currently an active connection a bind message is sent. If not, the bind message will be sent on the next connection.
int twApi_ClearProxyInfo ( )

Clears the proxy information of the socket to be used when making a connection.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_ClearSubscribedPropertyCurrentValues ( )

Clears the spm's current values list.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_Connect ( uint32_t  timeout,
int16_t  retries 
)

Establishes the websocket connection, performs authentication and binds any registered Things.

Parameters
[in]timeoutHow long to wait for the websocket to be established (in milliseconds).
[in]retriesThe number of times to attempt to reconnect if the connection fails.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
char twApi_ConnectionInProgress ( )

Checks to see if the API is in the process of connecting to the websocket.

Returns
#TRUE if connecting, #FALSE if not connecting.
propertyList* twApi_CreatePropertyList ( char *  name,
twPrimitive value,
DATETIME  timestamp 
)

Creates a list of properties.

Parameters
[in]nameThe name of the first property to add to the list.
[in]valueA pointer to the primitive containing the first property value.
[in]timestampTimestamp of the first property (defaults to current time).
Returns
Pointer to the created property list. Returns NULL on error.
Note
The newly allocated list will gain ownership the value pointer.
int twApi_CreateTask ( uint32_t  runTimeIntervalMsec,
twTaskFunction  func 
)

Adds a new task to the round robin scheduler (see callback function signature twTaskFunction).

Parameters
[in]runTimeIntervalMsecTime (in milliseconds) to wait between calls to the task function specified.
[in]funcThe function to be called.
Returns
positive task id if successful, #TW_MAX_TASKS_EXCEEDED if there are no available task slots
int twApi_Delete ( )

Shuts down the websocket and frees all memory associated with the twApi structure and all its owned substructures.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_DeletePropertyList ( propertyList *  list)

Frees all memory associated with a ::propertyList and all its owned substructures.

Parameters
[in]listA pointer to the list to delete.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twApi_DisableCertValidation ( )

Passthru to notify the TLS library to not validate the ThingWorx server certificate.

Returns
Nothing.
Warning
Disabling certificate validation may induce a security risk.
void twApi_DisableEncryption ( )

Passthru to notify the TLS library to disable encryption.

Returns
Nothing.
Warning
Disabling encryption may induce a security risk<.
int twApi_DisableFipsMode ( )

Passthru to disable FIPS mode for TLS providers that support it.

Returns
returns #TW_OK on success if using the default AxTls or OpenSSL libs, otherwise return an integer error code
void twApi_DisableWebSocketCompression ( )

Force WebSocket communications to not use compression.

Returns
Nothing.
int twApi_Disconnect ( char *  reason)

Unbinds any bound entities and disconnects from the ThingWorx server.

Parameters
[in]reasonThe reason for disconnecting.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_EnableFipsMode ( )

Passthru to enable FIPS mode for TLS providers that support it.

Returns
returns #TW_OK on success if using the default AxTls or OpenSSL libs, otherwise return an integer error code
int twApi_FireEvent ( enum entityTypeEnum  entityType,
char *  entityName,
char *  eventName,
twInfoTable params,
int32_t  timeout,
char  forceConnect 
)

Invokes an event on the ThingWorx server.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the event belongs to.
[in]eventNameThe name of the event to be triggered.
[in]paramsA pointer to a twInfoTable containing the event parameters.
[in]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. -1 uses DEFAULT_MESSAGE_TIMEOUT.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of the params pointer and is responsible for freeing it.
twConnectionInfo* twApi_GetConnectionInfo ( )

Creates a copy of the current connection info of the ThingWorx server.

Returns
Pointer to a copy of the API connection info.
Note
The API retains ownership of returned pointer and the calling function must not delete it.
char twApi_GetIsAuthenticated ( )

Returns the value of the API singleton's isAuthenticated flag.

Returns
The value of tw_api->isAuthenticated
char* twApi_GetVersion ( )

Returns a constant pointer to the version string of the API.

Returns
The current version of the API as a constant string.
int twApi_Initialize ( char *  host,
uint16_t  port,
char *  resource,
twPasswdCallbackFunction  app_key_function,
char *  gatewayName,
uint32_t  messageChunkSize,
uint16_t  frameSize,
char  autoreconnect 
)

Creates the twApi singleton and any dependent structures.

Parameters
[in]hostThe hostname of the ThingWorx server to connect to.
[in]portThe TCP port number to be used by the ThingWorx server.
[in]resourceThingWorx server resource (should always be /ThingWorx/WS unless changed by the server.
[in]app_key_functionThis is a pointer to a function which will be called whenever the client must provide an application key for authentication. You must implement this function and pass a pointer to it to initialize the API. This function must be of type twPasswdCallbackFunction and should have a format like the one shown below.

myPasswordCallback(char* passwdBuffer,unsigned int maxPasswordLength);

The implementation of this function must fill passwdBuffer with the current application key. The application key that must be returned is defined on the ThingWorx server. This key represents a user and is used as an authentication token.

Parameters
[in]gatewayNameAn optional name to register with if the application is acting as a gateway for multiple Things.
[in]messageChunkSizeThe maximum chunk of a websock message (should match the ThingWorx server). Default is 8192 and should not be exceeded.
[in]frameSizeThe maximum size of a websocket frame. Ordinarily matches messageChunkSize.
[in]autoreconnect#TRUE enables automatic reconnection to ThingWorx server if a connection is lost.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the service belongs to.
[in]serviceNameThe name of the service to be invoked.
[in]paramsA pointer to a twInfoTable containing the service parameters.
[out]resultA pointer to a twInfoTable containing the service response.
[in]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. -1 uses DEFAULT_MESSAGE_TIMEOUT.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of the result pointer and is responsible for freeing it.
The calling function will retain ownership of the params pointer and is responsible for freeing it.
int twApi_InvokeServiceAsync ( enum entityTypeEnum  entityType,
char *  entityName,
char *  serviceName,
twInfoTable params,
char  forceConnect,
response_cb  cb,
uint32_t *  messageId 
)

Invokes a service on the ThingWorx server and then immediately returns, calling back a callback function when the service call completes.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the service belongs to.
[in]serviceNameThe name of the service to be invoked.
[in]paramsA pointer to a twInfoTable containing the service parameters.
[out]resultA pointer to a twInfoTable containing the service response.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
[in]response_cba callback function which will be called on completetion of this service.
[out]messageIdA pointer to a uint32_t which will have the message ID of this service call copied into it for later use to identify this service in the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The callback function will retain ownership of the result pointer and is responsible for freeing it.
The calling function will retain ownership of the params pointer and is responsible for freeing it.
char twApi_isConnected ( )

Checks to see if the API websocket is connected.

Returns
#TRUE if connected, #FALSE if not connected.
char twApi_IsEntityBound ( char *  entityName)

Checks to see if an entity is bound through the API.

Parameters
[in]entityNameThe name of the entity to check.
Returns
#TRUE if bound, #FALSE if not bound.
int twApi_IsFIPSCompatible ( )

Ask the TLS implementation if it is capable of supporting FIPS.

Returns
returns #TW_OK if using a FIPS-compatible OpenSSL lib, otherwise return an integer error code
int twApi_IsFipsModeEnabled ( )

Ask the TLS implementation if FIPS mode is currently enabled.

Returns
returns #TRUE if FIPS mode is enabled, #FALSE otherwise.
int twApi_LoadCACert ( const char *  file,
int  type 
)

Loads the local PEM or DER formatted certificate file used to validate the ThingWorx server.

Parameters
[in]issuer_ouThe organizational unit of the issuer in the certificate.
[in]fileThe full path to the file containing the certificate.
[in]typeDefinition is dependent on the underlying TLS library (can be set to 0 for AxTLS).
Returns
return values vary based on SSL library implemented the default AxTls and OpenSSL implementation will return #TW_OK on success or an integer error code on failure
int twApi_LoadClientCert ( char *  file)

Loads the local PEM or DER formatted certificate file used to validate the client to the ThingWorx server.

Parameters
[in]fileThe full path to the file containing the certificate.
Returns
return values vary based on SSL library implemented the default AxTls and OpenSSL implementation will return #TW_OK on success or an integer error code on failure
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.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the properties belong to.
[in]propertiesA twList of twProperty pointers containing the values of the properties to write.
[in]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. -1 uses DEFAULT_MESSAGE_TIMEOUT.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of the properties pointer and is responsible for freeing it.
int twApi_PushSubscribedProperties ( char *  entityName,
char  forceConnect 
)

Pushes all queued subscribed properties to the server.

Parameters
[in]entityNameThe name of the entity that the properties belongs to. If EntityName is NULL, all entities will be pushed.
[in]forceConnectForce a connection if the Thing is currently offline.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_PushSubscribedPropertiesAsync ( char *  entityName,
char  forceConnect,
response_cb  cb,
twList **  messageListRef 
)

Pushes all queued subscribed properties to the server and then returns immediately. A callback function cb will be called, potentially, more than once, if the requested property push requires more than once service call to deliver. The number of service calls made will be a function of the maximum configured message size. If the max message size is large, fewer service calls will be required to push all property changes. The number of messages sent will equal the number of times the callback function cb will be called. The length of the list *messageListRef will be equal to the number of times the callback cb will be called. Each item in the *messageListRef contains a single uint32_t message id which can be used to verify that all the messages generated by this call have been processed.

Parameters
[in]entityNameThe name of the entity that the properties belongs to. If EntityName is NULL, all entities will be pushed.
[in]forceConnectForce a connection if the Thing is currently offline.
[in]forceConnectForce a connection if the Thing is currently offline.
[in]cbA callback function that will be called once for each message generated by the property push.
[out]messageListRefa twList that is created by this function and used to return a list of message ids for the messages generated by this push. It is the responsibility of the caller to delete this list once this function has returned.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be read.
[out]resultPointer to a twPrimitive pointer.
[in]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. -1 uses DEFAULT_MESSAGE_TIMEOUT.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of the result pointer and is responsible for freeing it.
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 bindEvent_cb()).

Parameters
[in]entityNameCallbacks are filtered to the specified entity. A NULL value receives all callbacks.
[in]cbThe function to be called.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterCloseCallback ( eventcb  cb)

Registers a function to be called when the websocket disconnects (see callback function signature eventcb()).

Parameters
[in]cbThe function to be called.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterConnectCallback ( eventcb  cb)

Registers a function to be called when the web socket connects (see callback function signature eventcb()).

Parameters
[in]cbThe function to be called.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterDefaultRequestHandler ( genericRequest_cb  cb)

Registers a service callback function that will get called for all unhandled requests (see callback function signature genericRequest_cb()).

Parameters
[in]cbPointer to the generic callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterOnAuthenticatedCallback ( authEvent_cb  cb,
void *  userdata 
)

Registers a function to be called when the connection to the ThingWorx server is fully authenticated (see callback function signature authEvent_cb()).

Parameters
[in]cbThe function to be called.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterPingCallback ( eventcb  cb)

Registers a callback function to be called when a Ping is received (see callback function signature eventcb()).

Parameters
[in]cbThe function to be called.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterPongCallback ( eventcb  cb)

Registers a callback function to be called when a Pong is received (see callback function signature eventcb()).

Parameters
[in]cbThe function to be called.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_RegisterProperty ( enum entityTypeEnum  entityType,
const char *  entityName,
const char *  propertyName,
enum BaseType  propertyType,
const char *  propertyDescription,
const 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 it is browsing (see callback function signature property_cb()).

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be registered.
[in]propertyTypeThe BaseType of the property.
[in]propertyPushTypeThe push type of the property. Can be set to #NEVER, #ALWAYS, or #VALUE (on change).
[in]propertyPushThresholdThe amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value.
[in]cbPointer to the property callback function.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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()).

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be registered. Value of "*" registers the callback for all property requests for the specified entity.
[in]cbPointer to the generic callback function.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This property will not be reported back to the ThingWorx server when it is browsing.
int twApi_RegisterService ( enum entityTypeEnum  entityType,
const 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 is browsing (see callback function signature property_cb()).

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the service belongs to.
[in]serviceNameThe name of the service to be registered.
[in]serviceDescriptionA description of the service to be registered.
[in]inputsA twDataShape that describes the service input.
[in]outputTypeThe BaseType of the service result.
[in]outputDataShapeA twDataShape that described the service output if the output is a twInfoTable.
[in]cbPointer to the service callback function.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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()).

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the service belongs to.
[in]serviceNameThe name of the service to be registered. Value of "*" registers the callback for all service requests for the specified entity.
[in]cbPointer to the generic callback function.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This service will not be reported back to the ThingWorx server when it is browsing.
int twApi_RegisterSynchronizeStateEventCallback ( char *  entityName,
synchronizeEvent_cb  cb,
void *  userdata 
)

Registers a function to be called when an entity synchronizes its subscribed property list with the platform. (see callback function signature synchronizeEvent_cb()).

Parameters
[in]entityNameCallbacks are filtered to the specified entity. A NULL value receives all callbacks.
[in]cbThe function to be called.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SendPing ( char *  content)

Pings the ThingWorx server.

Parameters
[in]contentA string to send with the ping.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
#content must be less than 128 characters.
int twApi_SetClientKey ( const char *  file,
twPasswdCallbackFunction  passphraseCallback,
int  type 
)

Sets the passphrase key of the local PEM or DER formatted certificate file used to validate the client to the ThingWorx server.

Parameters
[in]fileThe full path to the file containing the certificate.
[in]passphraseCallbackThe passphraseCallback returns the password used to open the file.
[in]typeDefinition is dependent on the underlying TLS library. Can be set to 0 for AxTLS.
Returns
return values vary based on SSL library implemented the default AxTls and OpenSSL implementation will return #TW_OK on success or an integer error code on failure
int twApi_SetConnectRetries ( signed char  retries)

Sets the number of times to attempt to reconnect if the connection fails (see twApi::connect_retries).

Parameters
[in]retriesThe number of times to attempt to reconnect if the connection fails.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SetConnectTimeout ( uint32_t  timeout)

Sets the amount of time (in milliseconds) the websocket waits while attempting a connection (see twApi::connect_timeout).

Parameters
[in]timeoutThe new timeout (in milliseconds).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The twApi::ping_rate must align with twApi::connect_timeout.
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.

Parameters
[in]duty_cycleThe duty cycle of the connection in percent (1-100). Values over 100 will be set to 100.
[in]periodThe connection period (in milliseconds). Value of 0 indicates AlwaysOn and overrides duty_cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SetGatewayName ( const char *  input_name)

Sets the Gateway Name that will be bound with the platform.

Parameters
[in]input_nameThe Gateway name as configured on the edge
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SetGatewayType ( const char *  input_type)

Sets the Gateway Type that will be bound with the platform.

Parameters
[in]input_typeThe Gateway name as configured on the edge
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SetIsAuthenticated ( char  value)

Sets the isAuthenticated flag in the API singleton.

  • Parameters
    [in]valueThe value to set
    Returns
    #TW_OK if successful, TW_ERROR otherwise
int twApi_SetOfflineMsgStoreDir ( const char *  dir)

sets the offline message store directory. If the offline message store has already been initialized, then the change will not take effect until the entire API is restarted

Parameters
[in]dirconst char string that contains the new directory path for the offline messane store
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_SetPingRate ( uint32_t  rate)

Sets the websockets ping/pong interval (see twApi::ping_rate).

Parameters
[in]rateThe new ping rate (in milliseconds).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The twApi::ping_rate must align with twApi::connect_timeout.
int twApi_SetProxyInfo ( char *  proxyHost,
uint16_t  proxyPort,
char *  proxyUser,
twPasswdCallbackFunction  proxyPassCallback 
)

Sets the proxy information to be used when making a connection.

Parameters
[in]retriesThe number of times to attempt to reconnect if the connection fails.
[in]proxyHostThe host name of the proxy.
[in]proxyPortThe port used by the proxy.
[in]proxyUserThe username to supply to the proxy (can be NULL if the proxy fails to authenticate).
[in]proxyPassCallbackThe callback function used to obtain the password to supply to the proxy.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twApi_SetSelfSignedOk ( )

Passthru to notify the TLS library to accept self-signed certificates.

Returns
Nothing.
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 value will be pushed to the server based on the property's push setting and the new value.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be written to.
[in]qualityThe quality of the reading. NULL will default to "GOOD".
[in]fold(Boolean) enable property folding where only the most recent value will be sent to the server on a push. Default is all values are sent.
[in]pushUpdate(Boolean) All queue properties will be pushed to the server. Push will only happen if websocket is connected and authenticated.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The called function will gain ownership of the value pointer. Calling function must NOT delete it.
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 etermines if the new value will be pushed to the server based on the property's push setting and the new value.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be written to.
[in]valuePointer to a twPrimitive pointer containing the new property value.
[in]timestampThe timestamp of the reading to send to the server Defaults to the current time.
[in]qualityThe quality of the reading. NULL will default to "GOOD".
[in]fold(Boolean) enable property folding where only the most recent value will be sent to the server on a push. Default is all values are sent.
[in]pushUpdate(Boolean) All queue properties will be pushed to the server. Push will only happen if websocket is connected and authenticated.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The called function will gain ownership of the value pointer. Calling function must NOT delete it.
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.

Parameters
[in]subject_cnThe common name of the subject in the certificate.
[in]subject_oThe organization of the subject in the certificate.
[in]subject_ouThe organizational unit of the subject in the certificate.
[in]issuer_cnThe common name of the issuer in the certificate.
[in]issuer_oThe organization of the issuer in the certificate.
[in]issuer_ouThe organizational unit of the issuer in the certificate.
Returns
return values vary based on SSL library implemented the default AxTls and OpenSSL implementation will return #TW_OK on success or an integer error code on failure
Note
NULL values will not be checked against the deceived certificate, non-NULL values will be.
int twApi_StopConnectionAttempt ( )

Kills any long running connection attempt.

Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twApi_TaskerFunction ( DATETIME  now,
void *  params 
)

Executes all functions required for proper operation of the API. This includes the connection receive loop, duty cycle control, stale message cleanup, ping/pong, etc.

Parameters
[in]nowThe current timestamp.
[in]paramsRequired by the tasker function signature but currently unused.
Returns
Nothing.
Note
This function should be called at a regular rate every 5 milliseconds or so depending on your tolerance for system latency. This function is automatically called by the tasker.
int twApi_UnbindThing ( char *  entityName)

Unbind an entity from this connection with the ThingWorx server.

Parameters
[in]entityNameThe name of the entity to unbind from the ThingWorx server.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
If there is currently an active connection an unbind message is sent. If not, the unbind message will be sent on the next connection.
int twApi_UnregisterBindEventCallback ( char *  entityName,
bindEvent_cb  cb,
void *  userdata 
)

Unregisters a callback registered via twApi_RegisterBindEventCallback() (see callback function signature bindEvent_cb()).

Parameters
[in]entityNameCallbacks are filtered to the specified entity. A NULL value receives all callbacks.
[in]cbThe function to be unregistered.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_UnregisterOnAuthenticatedCallback ( authEvent_cb  cb,
void *  userdata 
)

Unregisters a callback registered via twApi_RegisterOnAuthenticatedCallback() (see callback function signature authEvent_cb()).

Parameters
[in]cbThe function to be unregistered.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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 ThingWorx server while browsing.

Parameters
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be unregistered.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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 ThingWorx server while browsing.

Parameters
[in]entityNameThe name of the entity that the service belongs to.
[in]serviceNameThe name of the service to be unregistered.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_UnregisterSynchronizeStateEventCallback ( char *  entityName,
synchronizeEvent_cb  cb,
void *  userdata 
)

Unregisters a callback registered via twApi_RegisterSynchronizeStateEventCallback() (see callback function signature synchronizedEvent_cb()).

Parameters
[in]entityNameCallbacks are filtered to the specified entity. A NULL value receives all callbacks.
[in]cbThe function to be unregistered.
[in]userdataAn opaque pointer that is passed into the callback function.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twApi_UnregisterThing ( char *  entityName)

Removes all property & service callbacks for an entity.

Parameters
[in]entityNameThe name of the entity.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.

Updates the metadata for pre-registered properties.

Parameters
[in]entityTypeThe type of the entity the property is associated with.
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to update.
[in]propertyTypeThe BaseType of the property. See BaseTypes definition in twDefinitions.h. TW_UNKNOWN_TYPE keeps the current type.
[in]propertyDescriptionThe description of the property. NULL means keep the current description.
[in]propertyPushTypeThe push type of the property. Can be NEVER, ALWAYS, VALUE (on change).
[in]propertyPushThresholdThe amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Parameters
[in]entityTypeThe type of the entity that the properties belongs to.
[in]entityNameThe name of the entity that the properties belongs to.
[in]propertyNameThe name of the property.
[in]propertyTypeThe BaseType of the property. TW_UNKNOWN_TYPE keeps the current type.
[in]propertyDescriptionA description of the property. NULL means keep the current description.
[in]propertyPushTypeThe push type of the property. Can be NEVER, ALWAYS, VALUE (on change).
[in]propertyPushThresholdThe amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.

Updates the metadata aspects of a property.

Parameters
[in]entityTypeThe type of the entity that the properties belongs to.
[in]entityNameThe name of the entity that the properties belongs to.
[in]propertyNameThe name of the property.
[in]propertyTypeThe BaseType of the property. TW_UNKNOWN_TYPE keeps the current type.
[in]propertyDescriptionA description of the property. NULL means keep the current description.
[in]propertyPushTypeThe push type of the property. Can be NEVER, ALWAYS, VALUE (on change).
[in]propertyPushThresholdThe amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.

Parameters
[in]entityTypeThe type of entity that the property belongs to (see entityTypeEnum).
[in]entityNameThe name of the entity that the property belongs to.
[in]propertyNameThe name of the property to be written to.
[out]valuePointer to a twPrimitive pointer containing the new property value.
[in]timeoutTime (in milliseconds) to wait for a response from the ThingWorx server. -1 uses DEFAULT_MESSAGE_TIMEOUT.
[in]forceConnect#TRUE forces a reconnect and send if currently in the disconnected state of the duty cycle.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of the value pointer and is responsible for freeing it.