Initializing the API Singleton
Initializing the API singleton configures the connection to the ThingWorx Platform, but does not establish the connection. Typically, only the host and the application key must be modified, while all other default values can be used. For security purposes, the API defaults to rejecting self-signed certificates. If you choose to override this behavior (not recommended), you can tell the API to allow them.
To initialize the API, use the twAPI_Initialize() function. Here is an example from the Steam Sensor example application (main.c file):
/* Initialize the API */
err = twApi_Initialize(hostname, port, TW_URI, appKeyCallback, NULL, MESSAGE_CHUNK_SIZE,
MESSAGE_CHUNK_SIZE, TRUE);
if (TW_OK != err) {
TW_LOG(TW_ERROR, "Error initializing the API");
exit(err);
}
In this example, notice that this function does not take an application key variable. Instead, starting with v.2.2.0 of the C SDK, it uses the output of the appKeyCallback function. This callback function is called whenever the C SDK requires the current application key to authenticate with the ThingWorx Platform. Here is its signature:
void appKeyCallback(char* appKeyBuffer,unsigned int maxLength);
where appKeyBuffer is an allocated buffer in which to copy the application key, and maxLength is the size of the buffer. Do not copy an application key that is longer than this buffer size into appKeyBuffer. This callback usage applies to all C SDK functions that require an application key as input.
 |
In production, this callback should obtain an application key from a secure source.
|
The signature for the twApi_Initialize() function follows. The function and its parameters are defined in the file, twApi.h.
 |
The twApi_Initialize() function initializes the Subscribed Properties Manager. You do not need to initialize this manager separately.
|
The following table briefly describes the parameters of this function:
|
Parameter
|
Description
|
|---|---|
|
host
|
The host name of the ThingWorx Platform to connect to.
|
|
port
|
The TCP port number to used by the ThingWorx Platform for client connections.
|
|
resource
|
The ThingWorx Platform resource. This value should always be /ThingWorx/WS, unless it has been changed by the platform.
|
|
app_key_function
|
A pointer to a function that is called whenever the client must provide an application key for authentication. You must implement this function and pass a pointer to it to initialize the API. This function must be of type twPasswdCallbackFunction and should have a formate like the one shown here:
myPasswordCallback(char* passwdBuffer,unsigned int maxPasswordLength); The implementation of this function must fill passwdBuffer with the current application key. The application key is defined on the ThingWorx Platform. It represents a user and is used as an authentication token.
|
|
gatewayName
|
An optional name to register with if the application is acting as a gateway for multiple Things..
|
|
messageChunkSize
|
The maximum size of each chunk of a WebSocket message, in bytes. This value should match the value set on the ThingWorx Platform. The default value is 8192 bytes and should not be exceeded.
|
|
frameSize
|
The maximum size in bytes of a WebSocket frame. Typically matches the value of messageChunkSize.
|
|
autoreconnect
|
If set to TRUE, enables automatic reconnection to the ThingWorx Platform if a connection is lost.
|
Version 2.0.0 of the C SDK added an init callback that is fired when the SDK is initialized by twApi_Initialize. The registration function twApi_RegisterInitCallback for this callback allows you to provide a void* 'user data' pointer, which is cached in a data structure owned by twcfg. This type of user data pointer is useful for integrating C with C++ because it allows a C++ static member function to invoke a private member via the C++ this pointer.
Initializing with Proxy
Starting with v.2.2.8, use the twApi_InitializeWithProxy() function instead of the twApi_Initialize() if the SDK is connecting to the ThingWorx Platform through a proxy server. For more information, refer to Proxy Server Authentication.
Post-Initialization Functions (C SDK v.2.0.0 and later)
Version 2.0.0 of the ThingWorx Edge C SDK added initialization functions that you can call AFTER the API is initialized with twApi_Initialize(): twExt_Start() and twExt_Idle(). Located in the /src/threadUtils/twThreadUtils.c file in the C SDK installation, these functions provide bsic thread management for C SDK functionality. Both functions can be called to establish the minimum number of support threads and services to manage an AlwaysOn connection to ThingWorx Platform. The main difference between them is that twExt_Idle() will not return until your application is terminated. Any thread used to call this function will not exit. The twExt_Idle() function is useful in situations where your application only wants to start up services and then idle until it is exited. Call this function if you want this thread to take control of polling any registered polled functions.
The twExt_Start() function assumes that you are starting up AlwaysOn services as part of your application’s normal startup process and need the calling thread to return once. The return is done to continue with operations that you may need to perform as part of your startup process. This function starts a thread to monitor all Things with registered polled functions. Use this function if you need control of the calling thread in order to perform other work inside your application. This function relies on the tasker to call polled functions on a thread that it creates. Here is the function signture from src/threadUtils/twThreadUtils.h:
void twExt_Start(uint32_t dataCollectionRate, enum twThreadingModel threadingModel,
uint32_t messageHandlerThreadCount);
uint32_t messageHandlerThreadCount);
where:
• intervalMsec is the polling period in milliseconds.
• threadingModel is the threading model that you want to use.
• messageHandlerThreadCount is the number of message handling threads to spawn.
The signature of the twExt_Idle() function from twThreadUtils.h:
void twExt_Idle(uint32_t intervalMsec, enum twThreadingModel threadingModel, uint32_t messageHandlerThreadCount);
where:
• intervalMsec is the polling period in milliseconds.
• messageHandlerThreadCount is the number of message handling threads to spawn.
• twThreadingModel specifies which threading model you want to use:
◦ TW_THREADING_SINGLE— Use the thread on which this function is called to service registered polled functions.
◦ TW_THREADING_TASKER — Use the built-in tasker functionality of the C SDK to call all polled functions.
Both the twExt_Start() and twExt_Stop() functions set up periodic calls to any polled functions that you declare and that will be bound to specific Thing Shapes or Thing Templates. Often referred to as “Process Scan Request” functions, periodic polled functions can be declared against any Edge Thing Shape or Edge Thing Template, using the functions, twExt_RegisterPolledTemplateFunction() and twExt_RegisterPolledShapeFunction(). These periodic polled functions can be used to generate simulated data or to poll hardware for new data in your Thing or Shape. For details about these functions, refer to threadUtils.c and threadUtils.h in the src/threadUtils subdirectory of your C SDK installation.
The twExt_Stop() function shuts down all threads associated with your current threading model. Call twExt_Stop() before calling twApi_Disconnect(). Here is the signature of the twExt_Stop() function from twThreadUtils.h:
int twExt_Stop()
For details about each of these functions, refer to the twThreadUtils.h and twTrheadUtils.c files in the C SDK installation directory, ../src/threadUtils.