Macros That Take Actions
The macro commands are based on a core set of actions that can be performed within the C SDK. Macros start with TW_ and then list their action, followed by the target or result of that action. For example, the action of the TW_MAKE_DATASHAPE() macro is MAKE, and it will produce a DATASHAPE. The file, twMacros.h in the api subdirectory of the installation contains the macro definitions.
The basic actions include:
• MAKE — Make style macros allocate memory from the heap to store information. When you use MAKE, you must take one of these actions:
◦ Store the made objects in a list,
◦ Use the made objects in a C API call that will dispose of it later, or
◦ Delete them at the end of a function using TW_FREE().
An example would be TW_MAKE_DATASHAPE(). Since its action is MAKE, the returned value must be assigned to a list or given to another API function that will claim responsibility for disposing of it later. If the returned value is not assigned to a list or given to another function, you must call TW_FREE() to dispose of the made object at the end of the function in which it was made. Here is an example:
twExt_DataShape* ds = TW_MAKE_DATASHAPE(NO_SHAPE_NAME,
TW_DS_ENTRY("price", "How much it costs." ,TW_NUMBER),
TW_DS_ENTRY("description", "What its for.", TW_STRING),
TW_DS_ENTRY("truth","Is it the?", TW_BOOLEAN)
);
TW_FREE(ds);
If this Data Shape is not used in another C API call, you must call TW_FREE() on it at the end of the function.
In most cases, you will not be directly freeing anything you create using a MAKE style macro as this memory is deleted if used in an API call.
• SET — Set style macros assign a value to an existing variable or memory location. Here is an example:
TW_SET_PROPERTY("testThing", "Pressure", TW_MAKE_NUMBER(50));
Here we are setting the property Pressure on the Thing testThing to the numeric value 50. Note that you are calling TW_MAKE_NUMBER(), which allocates memory to contain the number 50. You are not responsible for calling TW_FREE() on this number because responsibility has been turned over to the TW_SET_PROPERY() command.
• GET—A get-style macro returns memory that the API manages. Do not use TW_FREE() after it.
• DECLARE (Implicit)—Any macro that does not contain the words SET or MAKE in its name is a declaration macro. The actual action DECLARE can be omitted. Declaration macros declare contextual variables within the function in which they are used, or configure the C SDK directly. They return no values and do not declare any memory on the heap that would need to later be freed. They are often used in conjunction with other macros to control how they behave. Here is an example:
// Configures a MyThing Thing within the C SDK. declares a variable
// called _tw_thing_name used by TW_PROPERTY()
TW_THING("MyThing",TW_THING_TEMPLATE_GENERIC);
//Configures MyThing to have multiple properties: FaultStatus, InletValve,
// Pressure, and Temperature.
TW_PROPERTY("FaultStatus", TW_NO_DESCRIPTION, TW_BOOLEAN); //
TW_PROPERTY("InletValve", TW_NO_DESCRIPTION, TW_BOOLEAN);
TW_PROPERTY("Pressure", TW_NO_DESCRIPTION, TW_NUMBER);
TW_PROPERTY("Temperature", TW_NO_DESCRIPTION, TW_NUMBER);
With all declarations, you are not responsible for deleting heap objects. All objects declared are managed by the C SDK. DECLARE macros can be confused with the many constants in the ThingWorx C SDK. To reduce confusion, all DECLARE macros are available in both the implicit and explicit forms. For example, TW_PROPERTY() can also be called as TW_DECLARE_PROPERTY(), which is more verbose. There are other actions such as PUSH and BIND, but they will be defined later in this document.