ThingWorx C SDK
Classes | Macros
twApi.h File Reference

Portable ThingWorx C SDK API layer. More...

#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"

Go to the source code of this file.

Classes

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

Macros

#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
 
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(* 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...
 
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, char *app_key, 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, int32_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_EnableFipsMode ()
 Passthru to enable FIPS mode for TLS providers that support it. 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...
 
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, char *passphrase, 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, char *proxyPass)
 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...
 
int twApi_SetOfflineMsgStoreDir (const char *dir)
 Sets the offline message store directory. 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_BindThing (char *entityName)
 Bind an entity 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_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...
 
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, 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 it is browsing (see callback function signature property_cb()). More...
 
int twApi_AddAspectToProperty (char *entityName, char *propertyName, char *aspectName, twPrimitive *aspectValue)
 Adds an aspect to an already registered property. 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, 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_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...
 
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...
 

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.
entityName is guaranteed to not be NULL.
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 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 twApi_AddAspectToProperty ( char *  entityName,
char *  propertyName,
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_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_Connect ( uint32_t  timeout,
int32_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
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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_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
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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_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,
char *  app_key,
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_keyThe application key defined on the ThingWorx server that this entity should use as an authentication token.
[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.
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_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
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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.
[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_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,
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 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,
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_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,
char *  passphrase,
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]passphraseThe passphrase used to open the file.
[in]typeDefinition is dependent on the underlying TLS library. Can be set to 0 for AxTLS.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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_SetOfflineMsgStoreDir ( const char *  dir)

Sets the offline message store directory.

Parameters
[in]dirThe full path to the directory where the offline message store file should be created.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Warning
If the current offline msg store file is not empty an error will be returned and the directory will not< > be changed.
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,
char *  proxyPass 
)

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]proxyPassThe password to supply to the proxy (can be NULL if the proxy fails to authenticate).
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 retain 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 retain 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
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
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_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.