ThingWorx Edge C SDK > Running the C SDK > Initializing the API Singleton
Initializing the API Singleton
Initializing the API singleton configures the connection to the server, but does NOT establish the connection. Typically, only the host and the application key need to be modified, all other defaults can be used. For security purposes, the API defaults to rejecting self-signed certificates. If you choose to override this behavior, 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,
if (TW_OK != err) {
TW_LOG(TW_ERROR, "Error initializing the API");
In this example, notice that this function no longer takes 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 and definitions of its parameters can be found in the file, twApi.h.
The twApi_Initialize() function initializes the Subscribed Properties Manager. You do not need to initialize this manager separately.
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.
Simpler Initialization (C SDK v.2.0.0 and later)
Version 2.0.0 of the ThingWorx Edge C SDK has introduced initialization functions that simplify startup, namely twExt_Start() and twExt_Idle(). Located in the /src/threadUtils/twThreadUtils.c file in the C SDK installation, these functions provide simple 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. twExt_Idle() 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.
twExt_Start() 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 want control of the calling thread to perfom 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);
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);
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, see 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, see the twThreadUtils.h and twTrheadUtils.c files in the C SDK installation directory, ../src/threadUtils.