ThingWorx C SDK
|
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 | |
| |
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... | |
twConnectionInfo * | twApi_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... | |
Portable ThingWorx C SDK API layer.
Contains structure type definitions and function prototypes for the ThingWorx API.
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.
[in] | credentialType | The type of credential that was used to authenticate. |
[in] | credentialValue | The value for the credential that was passed to the ThingWorx server. |
[in] | userdata | An opaque pointer that is passed in when the callback is registered. |
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.
[in] | entityName | Name 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] | userdata | An opaque pointer that is passed in when the callback is registered. |
entityName
is guaranteed to not be NULL. Signature of a callback function that is registered to be called for unhandled requests.
[in] | msg | A twMessage structure. |
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.
[in] | entityName | Name of the entity (Thing, Resource, etc.) this request is for. |
[in] | propertyName | Name of the property being requested. If NULL, return all properties. |
[in,out] | value | A 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] | userdata | An opaque pointer that is passed in when the callback is registered. |
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.
[in] | entityName | Name of the entity (Thing, Resource, etc.) this request is for. |
[in] | serviceName | Name of the service being requested. |
[in] | params | A pointer to a twInfoTable containing all input parameters for the service. |
[out] | content | A pointer to a pointer to a twInfoTable. |
[in] | userdata | An opaque pointer that is passed in when the callback is registered. |
entityName
is guaranteed to not be NULL. content
is guaranteed to not be NULL, *content
is not. content
. content
pointer and is responsible for freeing it. ThingWorx API structure definition.
int twApi_AddAspectToProperty | ( | char * | entityName, |
char * | propertyName, | ||
char * | aspectName, | ||
twPrimitive * | aspectValue | ||
) |
Adds an aspect to an already registered property.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to add the aspect to. |
[in] | aspectName | The name of the aspect. |
[in] | aspectValue | The value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it. |
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.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | serviceName | The name of the service to add the aspect to. |
[in] | aspectName | The name of the aspect. |
[in] | aspectValue | The value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it. |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | eventName | The name of the event to add the aspect to. |
[in] | aspectName | The name of the aspect. |
[in] | aspectValue | The value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it. |
Adds an aspect to an already registered service.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | eventName | The name of the event to add the aspect to. |
[in] | aspectName | The name of the aspect. |
[in] | aspectValue | The value of the aspect expressed as a twPrimitive. The called function takes ownership of the primitive and will delete it. |
int twApi_AddPropertyToList | ( | propertyList * | proplist, |
char * | name, | ||
twPrimitive * | value, | ||
DATETIME | timestamp | ||
) |
Adds a property to a property list.
[in] | proplist | A pointer to the list to add the property to. |
[in] | name | The name of the property to add to the list. |
[in] | value | A pointer to the primitive containing the property type and value. |
[in] | timestamp | Timestamp of the first property (defaults to current time). |
value
pointer. int twApi_BindThing | ( | char * | entityName | ) |
Bind an entity to this connection with the ThingWorx server.
[in] | entityName | The name of the entity to bind with the ThingWorx server. |
int twApi_ClearProxyInfo | ( | ) |
Clears the proxy information of the socket to be used when making a connection.
int twApi_Connect | ( | uint32_t | timeout, |
int32_t | retries | ||
) |
Establishes the websocket connection, performs authentication and binds any registered Things.
[in] | timeout | How long to wait for the websocket to be established (in milliseconds). |
[in] | retries | The number of times to attempt to reconnect if the connection fails. |
char twApi_ConnectionInProgress | ( | ) |
Checks to see if the API is in the process of connecting to the websocket.
propertyList* twApi_CreatePropertyList | ( | char * | name, |
twPrimitive * | value, | ||
DATETIME | timestamp | ||
) |
Creates a list of properties.
[in] | name | The name of the first property to add to the list. |
[in] | value | A pointer to the primitive containing the first property value. |
[in] | timestamp | Timestamp of the first property (defaults to current time). |
value
pointer. int twApi_CreateTask | ( | uint32_t | runTimeIntervalMsec, |
twTaskFunction | func | ||
) |
Adds a new task to the round robin scheduler (see callback function signature twTaskFunction).
[in] | runTimeIntervalMsec | Time (in milliseconds) to wait between calls to the task function specified. |
[in] | func | The function to be called. |
int twApi_Delete | ( | ) |
Shuts down the websocket and frees all memory associated with the twApi structure and all its owned substructures.
int twApi_DeletePropertyList | ( | propertyList * | list | ) |
Frees all memory associated with a ::propertyList and all its owned substructures.
[in] | list | A pointer to the list to delete. |
void twApi_DisableCertValidation | ( | ) |
Passthru to notify the TLS library to not validate the ThingWorx server certificate.
void twApi_DisableEncryption | ( | ) |
Passthru to notify the TLS library to disable encryption.
int twApi_Disconnect | ( | char * | reason | ) |
Unbinds any bound entities and disconnects from the ThingWorx server.
[in] | reason | The reason for disconnecting. |
int twApi_EnableFipsMode | ( | ) |
Passthru to enable FIPS mode for TLS providers that support it.
int twApi_FireEvent | ( | enum entityTypeEnum | entityType, |
char * | entityName, | ||
char * | eventName, | ||
twInfoTable * | params, | ||
int32_t | timeout, | ||
char | forceConnect | ||
) |
Invokes an event on the ThingWorx server.
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the event belongs to. |
[in] | eventName | The name of the event to be triggered. |
[in] | params | A pointer to a twInfoTable containing the event parameters. |
[in] | timeout | Time (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. |
params
pointer and is responsible for freeing it. twConnectionInfo* twApi_GetConnectionInfo | ( | ) |
Creates a copy of the current connection info of the ThingWorx server.
char* twApi_GetVersion | ( | ) |
Returns a constant pointer to the version string of the API.
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.
[in] | host | The hostname of the ThingWorx server to connect to. |
[in] | port | The TCP port number to be used by the ThingWorx server. |
[in] | resource | ThingWorx server resource (should always be /ThingWorx/WS unless changed by the server. |
[in] | app_key | The application key defined on the ThingWorx server that this entity should use as an authentication token. |
[in] | gatewayName | An optional name to register with if the application is acting as a gateway for multiple Things. |
[in] | messageChunkSize | The maximum chunk of a websock message (should match the ThingWorx server). Default is 8192 and should not be exceeded. |
[in] | frameSize | The maximum size of a websocket frame. Ordinarily matches messageChunkSize . |
[in] | autoreconnect | #TRUE enables automatic reconnection to ThingWorx server if a connection is lost. |
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.
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the service belongs to. |
[in] | serviceName | The name of the service to be invoked. |
[in] | params | A pointer to a twInfoTable containing the service parameters. |
[out] | result | A pointer to a twInfoTable containing the service response. |
[in] | timeout | Time (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. |
result
pointer and is responsible for freeing it. params
pointer and is responsible for freeing it. char twApi_isConnected | ( | ) |
Checks to see if the API websocket is connected.
char twApi_IsEntityBound | ( | char * | entityName | ) |
Checks to see if an entity is bound through the API.
[in] | entityName | The name of the entity to check. |
int twApi_LoadCACert | ( | const char * | file, |
int | type | ||
) |
Loads the local PEM or DER formatted certificate file used to validate the ThingWorx server.
[in] | issuer_ou | The organizational unit of the issuer in the certificate. |
[in] | file | The full path to the file containing the certificate. |
[in] | type | Definition is dependent on the underlying TLS library (can be set to 0 for AxTLS). |
int twApi_LoadClientCert | ( | char * | file | ) |
Loads the local PEM or DER formatted certificate file used to validate the client to the ThingWorx server.
[in] | file | The full path to the file containing the certificate. |
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.
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the properties belong to. |
[in] | properties | A twList of twProperty pointers containing the values of the properties to write. |
[in] | timeout | Time (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. |
properties
pointer and is responsible for freeing it. int twApi_PushSubscribedProperties | ( | char * | entityName, |
char | forceConnect | ||
) |
Pushes all queued subscribed properties to the server.
[in] | entityName | The name of the entity that the properties belongs to. |
[in] | forceConnect | Force a connection if the Thing is currently offline. |
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.
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be read. |
[out] | result | Pointer to a twPrimitive pointer. |
[in] | timeout | Time (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. |
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()).
[in] | entityName | Callbacks are filtered to the specified entity. A NULL value receives all callbacks. |
[in] | cb | The function to be called. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
int twApi_RegisterCloseCallback | ( | eventcb | cb | ) |
Registers a function to be called when the websocket disconnects (see callback function signature eventcb()).
[in] | cb | The function to be called. |
int twApi_RegisterConnectCallback | ( | eventcb | cb | ) |
Registers a function to be called when the web socket connects (see callback function signature eventcb()).
[in] | cb | The function to be called. |
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()).
[in] | cb | Pointer to the generic callback function. |
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()).
[in] | cb | The function to be called. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
int twApi_RegisterPingCallback | ( | eventcb | cb | ) |
Registers a callback function to be called when a Ping is received (see callback function signature eventcb()).
[in] | cb | The function to be called. |
int twApi_RegisterPongCallback | ( | eventcb | cb | ) |
Registers a callback function to be called when a Pong is received (see callback function signature eventcb()).
[in] | cb | The function to be called. |
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()).
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be registered. |
[in] | propertyType | The BaseType of the property. |
[in] | propertyPushType | The push type of the property. Can be set to #NEVER, #ALWAYS, or #VALUE (on change). |
[in] | propertyPushThreshold | The amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value. |
[in] | cb | Pointer to the property callback function. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
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()).
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be registered. Value of "*" registers the callback for all property requests for the specified entity. |
[in] | cb | Pointer to the generic callback function. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
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()).
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the service belongs to. |
[in] | serviceName | The name of the service to be registered. |
[in] | serviceDescription | A description of the service to be registered. |
[in] | inputs | A twDataShape that describes the service input. |
[in] | outputType | The BaseType of the service result. |
[in] | outputDataShape | A twDataShape that described the service output if the output is a twInfoTable. |
[in] | cb | Pointer to the service callback function. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
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()).
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the service belongs to. |
[in] | serviceName | The name of the service to be registered. Value of "*" registers the callback for all service requests for the specified entity. |
[in] | cb | Pointer to the generic callback function. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
int twApi_SendPing | ( | char * | content | ) |
Pings the ThingWorx server.
[in] | content | A string to send with the ping. |
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.
[in] | file | The full path to the file containing the certificate. |
[in] | passphrase | The passphrase used to open the file. |
[in] | type | Definition is dependent on the underlying TLS library. Can be set to 0 for AxTLS. |
int twApi_SetConnectRetries | ( | signed char | retries | ) |
Sets the number of times to attempt to reconnect if the connection fails (see twApi::connect_retries).
[in] | retries | The number of times to attempt to reconnect if the connection fails. |
int twApi_SetConnectTimeout | ( | uint32_t | timeout | ) |
Sets the amount of time (in milliseconds) the websocket waits while attempting a connection (see twApi::connect_timeout).
[in] | timeout | The new timeout (in milliseconds). |
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.
[in] | duty_cycle | The duty cycle of the connection in percent (1-100). Values over 100 will be set to 100. |
[in] | period | The connection period (in milliseconds). Value of 0 indicates AlwaysOn and overrides duty_cycle. |
int twApi_SetGatewayName | ( | const char * | input_name | ) |
Sets the Gateway Name that will be bound with the platform.
[in] | input_name | The Gateway name as configured on the edge |
int twApi_SetGatewayType | ( | const char * | input_type | ) |
Sets the Gateway Type that will be bound with the platform.
[in] | input_type | The Gateway name as configured on the edge |
int twApi_SetOfflineMsgStoreDir | ( | const char * | dir | ) |
Sets the offline message store directory.
[in] | dir | The full path to the directory where the offline message store file should be created. |
int twApi_SetPingRate | ( | uint32_t | rate | ) |
Sets the websockets ping/pong interval (see twApi::ping_rate).
[in] | rate | The new ping rate (in milliseconds). |
int twApi_SetProxyInfo | ( | char * | proxyHost, |
uint16_t | proxyPort, | ||
char * | proxyUser, | ||
char * | proxyPass | ||
) |
Sets the proxy information to be used when making a connection.
[in] | retries | The number of times to attempt to reconnect if the connection fails. |
[in] | proxyHost | The host name of the proxy. |
[in] | proxyPort | The port used by the proxy. |
[in] | proxyUser | The username to supply to the proxy (can be NULL if the proxy fails to authenticate). |
[in] | proxyPass | The password to supply to the proxy (can be NULL if the proxy fails to authenticate). |
void twApi_SetSelfSignedOk | ( | ) |
Passthru to notify the TLS library to accept self-signed certificates.
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.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be written to. |
[in] | quality | The 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. |
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.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be written to. |
[in] | value | Pointer to a twPrimitive pointer containing the new property value. |
[in] | timestamp | The timestamp of the reading to send to the server Defaults to the current time. |
[in] | quality | The 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. |
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.
[in] | subject_cn | The common name of the subject in the certificate. |
[in] | subject_o | The organization of the subject in the certificate. |
[in] | subject_ou | The organizational unit of the subject in the certificate. |
[in] | issuer_cn | The common name of the issuer in the certificate. |
[in] | issuer_o | The organization of the issuer in the certificate. |
[in] | issuer_ou | The organizational unit of the issuer in the certificate. |
int twApi_StopConnectionAttempt | ( | ) |
Kills any long running connection attempt.
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.
[in] | now | The current timestamp. |
[in] | params | Required by the tasker function signature but currently unused. |
int twApi_UnbindThing | ( | char * | entityName | ) |
Unbind an entity from this connection with the ThingWorx server.
[in] | entityName | The name of the entity to unbind from the ThingWorx server. |
int twApi_UnregisterBindEventCallback | ( | char * | entityName, |
bindEvent_cb | cb, | ||
void * | userdata | ||
) |
Unregisters a callback registered via twApi_RegisterBindEventCallback() (see callback function signature bindEvent_cb()).
[in] | entityName | Callbacks are filtered to the specified entity. A NULL value receives all callbacks. |
[in] | cb | The function to be unregistered. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
int twApi_UnregisterOnAuthenticatedCallback | ( | authEvent_cb | cb, |
void * | userdata | ||
) |
Unregisters a callback registered via twApi_RegisterOnAuthenticatedCallback() (see callback function signature authEvent_cb()).
[in] | cb | The function to be unregistered. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
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.
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be unregistered. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
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.
[in] | entityName | The name of the entity that the service belongs to. |
[in] | serviceName | The name of the service to be unregistered. |
[in] | userdata | An opaque pointer that is passed into the callback function. |
int twApi_UnregisterThing | ( | char * | entityName | ) |
Removes all property & service callbacks for an entity.
[in] | entityName | The name of the entity. |
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.
[in] | entityType | The type of the entity the property is associated with. |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to update. |
[in] | propertyType | The BaseType of the property. See BaseTypes definition in twDefinitions.h. TW_UNKNOWN_TYPE keeps the current type. |
[in] | propertyDescription | The description of the property. NULL means keep the current description. |
[in] | propertyPushType | The push type of the property. Can be NEVER, ALWAYS, VALUE (on change). |
[in] | propertyPushThreshold | The amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value. |
[in] | entityType | The type of the entity that the properties belongs to. |
[in] | entityName | The name of the entity that the properties belongs to. |
[in] | propertyName | The name of the property. |
[in] | propertyType | The BaseType of the property. TW_UNKNOWN_TYPE keeps the current type. |
[in] | propertyDescription | A description of the property. NULL means keep the current description. |
[in] | propertyPushType | The push type of the property. Can be NEVER, ALWAYS, VALUE (on change). |
[in] | propertyPushThreshold | The amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value. |
Updates the metadata aspects of a property.
[in] | entityType | The type of the entity that the properties belongs to. |
[in] | entityName | The name of the entity that the properties belongs to. |
[in] | propertyName | The name of the property. |
[in] | propertyType | The BaseType of the property. TW_UNKNOWN_TYPE keeps the current type. |
[in] | propertyDescription | A description of the property. NULL means keep the current description. |
[in] | propertyPushType | The push type of the property. Can be NEVER, ALWAYS, VALUE (on change). |
[in] | propertyPushThreshold | The amount the property has to change (if the type is TW_NUMBER or TW_INTEGER) before pushing the new value. |
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.
[in] | entityType | The type of entity that the property belongs to (see entityTypeEnum). |
[in] | entityName | The name of the entity that the property belongs to. |
[in] | propertyName | The name of the property to be written to. |
[out] | value | Pointer to a twPrimitive pointer containing the new property value. |
[in] | timeout | Time (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. |
value
pointer and is responsible for freeing it.