ThingWorx C SDK
Classes
twBaseTypes.h File Reference

ThingWorx BaseType definitions and functions. More...

#include "twOSPort.h"
#include "twDefinitions.h"
#include "twDefaultSettings.h"

Go to the source code of this file.

Classes

struct  twStream
 Dynamically allocated byte array. Automatically expands its length as needed. More...
 
struct  twLocation
 Location primitive structure. More...
 
struct  twPrimitive
 BaseType primitive structure. More...
 

Functions

::twPrimitive Convenience Functions
twPrimitivetwPrimitive_CreateFromLocation (const twLocation *value)
 Helper function to create a twPrimitive of type TW_LOCATION from a location structure. More...
 
twPrimitivetwPrimitive_CreateFromNumber (const double value)
 Helper function to create a twPrimitive of type TW_NUMBER from a double. More...
 
twPrimitivetwPrimitive_CreateFromInteger (const int32_t value)
 Helper function to create a twPrimitive of type TW_INTEGER from an integral type (int, short, char). More...
 
twPrimitivetwPrimitive_CreateFromDatetime (const DATETIME value)
 Helper function to create a twPrimitive of type TW_DATETIME from a DATETIME type. More...
 
twPrimitivetwPrimitive_CreateFromCurrentTime ()
 Helper function to create a twPrimitive of type TW_DATETIME from the current time. More...
 
twPrimitivetwPrimitive_CreateFromBoolean (const char value)
 Helper function to create a twPrimitive of type TW_BOOLEAN from a char type. More...
 
twPrimitivetwPrimitive_CreateFromInfoTable (struct twInfoTable *it)
 Helper function to create a twPrimitive of type TW_INFOTABLE from a twInfoTable structure. More...
 
twPrimitivetwPrimitive_CreateVariant (twPrimitive *input)
 Helper function to create a twPrimitive of type TW_VARIANT from a twPrimitive structure. More...
 
twPrimitivetwPrimitive_CreateFromString (const char *value, char duplicate)
 Helper function to create a twPrimitive of type TW_STRING from a null-terminated char array. More...
 
twPrimitivetwPrimitive_CreateFromBlob (const char *value, int32_t length, char isImage, char duplicate)
 Helper function to create a twPrimitive of type TW_BLOB or TW_IMAGE from a char array. More...
 
twPrimitivetwPrimitive_CreateFromVariable (const void *value, enum BaseType type, char duplicateCharArray, uint32_t blobLength)
 Helper function to create a twPrimitive of any type from a void *. More...
 
JSON Conversion Utils
Note
Using any of these functions will cause the cJSON library to be linked to your application, increasing the size of the application by ~22KB.
struct cJSONtwPrimitive_ToJson (char *name, twPrimitive *p, struct cJSON *parent)
 Helper function to convert a twPrimitive to a CJSON object. More...
 
twPrimitivetwPrimitive_CreateFromJson (struct cJSON *j, char *name, enum BaseType type)
 Helper function to convert a cJSON object to a twPrimitive. More...
 

ThingWorx Streams

typedef struct twStream twStream
 Dynamically allocated byte array. Automatically expands its length as needed. More...
 
twStreamtwStream_Create ()
 Creates a new twStream structure. More...
 
twStreamtwStream_CreateFromCharArray (const char *data, uint32_t length)
 Creates a new twStream structure and copies the data from a char array to the new structure's twStream::data. More...
 
twStreamtwStream_CreateFromCharArrayZeroCopy (const char *data, uint32_t length)
 Allocates a new twStream structure and points twStream::data to an existing char array. More...
 
void twStream_Delete (void *s)
 Frees all memory associated with a twStream and all of its owned substructures. More...
 
char * twStream_GetData (struct twStream *s)
 Gets a pointer to the twStream::data of a twStream. More...
 
int32_t twStream_GetIndex (struct twStream *s)
 Gets the ::twStream#index of a twStream. More...
 
int32_t twStream_GetLength (struct twStream *s)
 Gets the twStream::length of a twStream. More...
 
int twStream_AddBytes (struct twStream *s, void *b, uint32_t count)
 Adds data bytes to a twStream. More...
 
int twStream_GetBytes (struct twStream *s, void *b, uint32_t count)
 Copies count bytes of data from the twStream::data of a twStream into buf. More...
 
int twStream_Reset (struct twStream *s)
 Resets the position pointer of a twStream (twStream::ptr) to the beginning of that twStream's data (twStream::data). More...
 

ThingWorx Locations

typedef struct twLocation twLocation
 Location primitive structure.
 
void swap4bytes (char *bytes)
 
void swap8bytes (char *bytes)
 
int stringToStream (char *string, twStream *s)
 
char * streamToString (twStream *s)
 
enum BaseType baseTypeFromString (const char *s)
 
const char * baseTypeToString (enum BaseType b)
 

ThingWorx Primitives

typedef struct twPrimitive twPrimitive
 BaseType primitive structure. More...
 
twPrimitivetwPrimitive_Create ()
 Creates a new twPrimitive structure. More...
 
twPrimitivetwPrimitive_CreateFromStream (twStream *s)
 Creates a new twPrimitive structure and populates it with data from a twStream. More...
 
twPrimitivetwPrimitive_CreateFromStreamTyped (twStream *s, enum BaseType type)
 Allocates a new twPrimitive structure of a specified type and populates it with data from a twStream. More...
 
twPrimitivetwPrimitive_ZeroCopy (twPrimitive *p)
 Creates a new twPrimitive structure which inherits all pointers of an existing twPrimitive structure p. The pointers of p will be zeroed so that it may be safely deleted. More...
 
twPrimitivetwPrimitive_FullCopy (twPrimitive *p)
 Creates a new twPrimitive structure and copies all data from an existing twPrimitive structure to the newly created twPrimitive structure. More...
 
void twPrimitive_Delete (void *p)
 Frees all memory associated with a twPrimitive and all of its owned substructures. More...
 
int twPrimitive_ToStream (twPrimitive *p, twStream *s)
 Copies the data from a twPrimitive structure to a twStream structure. More...
 
char * twPrimitive_DecoupleStringAndDelete (twPrimitive *p)
 Helper function to return the value of a TW_STRING family type, remove it from the twPrimitive p, and then delete , leaving the caller with ownership of the returned TW_STRING TW_STRING. More...
 
int twPrimitive_Compare (twPrimitive *p1, twPrimitive *p2)
 Compares two twPrimitive structures for equivalence. More...
 
char twPrimitive_IsTrue (twPrimitive *p1)
 Compares a twPrimitive to "true". For booleans true is if the value is "true", for numeric and dattime values true means non-zero, for string, blob & image types true means non-zero length, for locations true means one of longitude, latitude or altitude is non-zero, for infotables true means the table has at least one row. More...
 

Detailed Description

ThingWorx BaseType definitions and functions.

Typedef Documentation

typedef struct twPrimitive twPrimitive

BaseType primitive structure.

Note
Used as a "variant" type throughout the entire API.
typedef struct twStream twStream

Dynamically allocated byte array. Automatically expands its length as needed.

Note
Usually not used by applications directly.

Function Documentation

int twPrimitive_Compare ( twPrimitive p1,
twPrimitive p2 
)

Compares two twPrimitive structures for equivalence.

Parameters
[in]p1A pointer to the twPrimitive to be compared against.
[in]p2A pointer to the twPrimitive to compare with.
Returns
0 if the twPrimitive structures are identical, 1 if they are not identical, -1 if an error was encountered.
twPrimitive* twPrimitive_Create ( )

Creates a new twPrimitive structure.

Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The newly allocated twPrimitive structure defaults to a type of TW_NOTHING.
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromBlob ( const char *  value,
int32_t  length,
char  isImage,
char  duplicate 
)

Helper function to create a twPrimitive of type TW_BLOB or TW_IMAGE from a char array.

Parameters
[in]valueA pointer to the char array to assign to the twPrimitive.
[in]lengthThe length of the char array.
[in]isImageIf #TRUE, the returned twPrimitive::type is set to TW_IMAGE. If FALSE, it is set to TW_BLOB.
[in]duplicateIf #TRUE, a copy of the array is made. If #FALSE, the primitive takes ownership of the array.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
If duplicate is #TRUE, the calling function retains ownership of value and is responsible for freeing it.
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete();
twPrimitive* twPrimitive_CreateFromBoolean ( const char  value)

Helper function to create a twPrimitive of type TW_BOOLEAN from a char type.

Parameters
[in]valueA char value to assign to the twPrimitive.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromCurrentTime ( )

Helper function to create a twPrimitive of type TW_DATETIME from the current time.

Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromDatetime ( const DATETIME  value)

Helper function to create a twPrimitive of type TW_DATETIME from a DATETIME type.

Parameters
[in]valueA DATETIME to assign to the twPrimitive.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromInfoTable ( struct twInfoTable it)

Helper function to create a twPrimitive of type TW_INFOTABLE from a twInfoTable structure.

Parameters
[in]valueA pointer to the twInfoTable structure.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function retains ownership of value and is responsible for freeing it via twInfoTable_Delete().
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromInteger ( const int32_t  value)

Helper function to create a twPrimitive of type TW_INTEGER from an integral type (int, short, char).

Parameters
[in]valueAn integral value to assign to the twPrimitive.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromJson ( struct cJSON j,
char *  name,
enum BaseType  type 
)

Helper function to convert a cJSON object to a twPrimitive.

Parameters
[in]jA pointer to the cJSON object to convert.
[in]nameThe name of the element that is to be converted.
[in]typeThe BaseType of the twPrimitive to be created.
Returns
A pointer to the newly allocated twPrimitive object. Returns NULL if an error was encountered.
Note
The calling function will gain ownership of the newly allocated cJSON object and is responsible for freeing it.
Warning
Using this function will cause the cJSON library to be linked to your application, increasing the size of the application by ~22KB.
twPrimitive* twPrimitive_CreateFromLocation ( const twLocation value)

Helper function to create a twPrimitive of type TW_LOCATION from a location structure.

Parameters
[in]valueA pointer to the location structure.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function retains ownership of value and is responsible for freeing it.
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromNumber ( const double  value)

Helper function to create a twPrimitive of type TW_NUMBER from a double.

Parameters
[in]valueA numeric value to assign to the twPrimitive.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromStream ( twStream s)

Creates a new twPrimitive structure and populates it with data from a twStream.

Parameters
[in]sA pointer to the twStream containing the data to populate the twPrimitive with.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The newly allocated twPrimitive structure defaults to a type of TW_NOTHING.
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromStreamTyped ( twStream s,
enum BaseType  type 
)

Allocates a new twPrimitive structure of a specified type and populates it with data from a twStream.

Parameters
[in]sA pointer to the twStream containing the data to populate the twPrimitive with.
[in]typeThe BaseType to associate with the twPrimitive.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twPrimitive_Delete().
twPrimitive* twPrimitive_CreateFromString ( const char *  value,
char  duplicate 
)

Helper function to create a twPrimitive of type TW_STRING from a null-terminated char array.

Parameters
[in]valueA pointer to the null-terminated char array to assign to the twPrimitive.
[in]duplicateIf #TRUE, a copy of the string is made. If #FALSE, the primitive takes ownership of the string.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
If duplicate is #TRUE, the calling function retains ownership of value and is responsible for freeing it.
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete();
twPrimitive* twPrimitive_CreateFromVariable ( const void *  value,
enum BaseType  type,
char  duplicateCharArray,
uint32_t  blobLength 
)

Helper function to create a twPrimitive of any type from a void *.

Parameters
[in]valueA pointer to the char array to assign to the twPrimitive.
[in]typeThe base type to assign to the new twPrimitive.
[in]duplicateCharArrayIf #TRUE, a copy of the array is made. If #FALSE, the primitive takes ownership of the array.
[in]blobLengthThe length of the char array if the type is TW_BLOB or TW_IMAGE.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
If duplicate is #TRUE, the calling function retains ownership of value and is responsible for freeing it.
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete();
twPrimitive* twPrimitive_CreateVariant ( twPrimitive input)

Helper function to create a twPrimitive of type TW_VARIANT from a twPrimitive structure.

Parameters
[in]valueA pointer to the twPrimitive structure.
Returns
A pointer to the newly allocated twPrimitive. Returns NULL if an error was encountered.
Note
The calling function retains ownership of value and is responsible for freeing it via twPrimitive_Delete().
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
char* twPrimitive_DecoupleStringAndDelete ( twPrimitive p)

Helper function to return the value of a TW_STRING family type, remove it from the twPrimitive p, and then delete , leaving the caller with ownership of the returned TW_STRING TW_STRING.

Parameters
[in]pA pointer to the twPrimitive (must have twPrimitive::typeFamily of type TW_STRING).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will gain ownership of the returned string and is responsible for freeing it.
The returned string is guaranteed to not be NULL.
void twPrimitive_Delete ( void *  p)

Frees all memory associated with a twPrimitive and all of its owned substructures.

Parameters
[in]pA pointer to the twPrimitive to be deleted.
Returns
Nothing.
twPrimitive* twPrimitive_FullCopy ( twPrimitive p)

Creates a new twPrimitive structure and copies all data from an existing twPrimitive structure to the newly created twPrimitive structure.

Parameters
[in]pA pointer to the twPrimitive to be copied from.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The original twPrimitive structure p will not be modified. The calling function will therefore retain ownership of p and is responsible for freeing it via twPrimitive_Delete().
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twPrimitive_Delete().
char twPrimitive_IsTrue ( twPrimitive p1)

Compares a twPrimitive to "true". For booleans true is if the value is "true", for numeric and dattime values true means non-zero, for string, blob & image types true means non-zero length, for locations true means one of longitude, latitude or altitude is non-zero, for infotables true means the table has at least one row.

Parameters
[in]p1A pointer to the twPrimitive to be compared.
Returns
0 if the twPrimitive structures is "true", 1 if they are not identical, -1 if an error was encountered.
struct cJSON* twPrimitive_ToJson ( char *  name,
twPrimitive p,
struct cJSON parent 
)

Helper function to convert a twPrimitive to a CJSON object.

Parameters
[in]nameThe name of the newly created JSON object.
[in]pA pointer to the twPrimitive to convert.
[in]parent(Optional) parent to add the JSON object to (may be NULL).
Returns
A pointer to the newly allocated cJSON object. Returns NULL if an error was encountered.
Note
The calling function will retain ownership of the parent object and is responsible for freeing it if necessary.
The calling function will gain ownership of the newly allocated cJSON object and is responsible for freeing it.
Warning
Using this function will cause the cJSON library to be linked to your application, increasing the size of the application by ~22KB.
int twPrimitive_ToStream ( twPrimitive p,
twStream s 
)

Copies the data from a twPrimitive structure to a twStream structure.

Parameters
[in]pA pointer to the twPrimitive to write to s.
[in,out]sA pointer to the twStream to write p to.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
This function is typically not used directly by applications.
twPrimitive* twPrimitive_ZeroCopy ( twPrimitive p)

Creates a new twPrimitive structure which inherits all pointers of an existing twPrimitive structure p. The pointers of p will be zeroed so that it may be safely deleted.

Parameters
[in]pA pointer to the twPrimitive to be copied from and zeroed.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The calling function gains ownership of the returned twPrimitive and is responsible for freeing it via twPrimitive_Delete().
twPrimitive_ZeroCopy() does not free /p p.It only zeros the pointers of p so that the base structure p may be deleted without modifying the newly created twPrimitive. The calling function must still free p via twPrimitive_Delete().
int twStream_AddBytes ( struct twStream s,
void *  b,
uint32_t  count 
)

Adds data bytes to a twStream.

Parameters
[in]sA pointer to the twStream to add bytes to.
[in]bA pointer to the bytes to add.
[in]countThe number of bytes to be added.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
twStream* twStream_Create ( )

Creates a new twStream structure.

Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twStream_Delete().
twStream* twStream_CreateFromCharArray ( const char *  data,
uint32_t  length 
)

Creates a new twStream structure and copies the data from a char array to the new structure's twStream::data.

Parameters
[in]dataA pointer to the char array to copy into twStream::data.
[in]lengthThe length of the char array.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twStream_Delete().
The calling function will retain ownership of data and will is responsible for freeing it.
twStream* twStream_CreateFromCharArrayZeroCopy ( const char *  data,
uint32_t  length 
)

Allocates a new twStream structure and points twStream::data to an existing char array.

Parameters
[in]dataA pointer to the char array to point twStream::data to.
[in]lengthThe length of the char array.
Returns
A pointer to the newly allocated structure. Returns NULL on error.
Note
The newly allocated twStream will gain ownership of data. The calling function should not free it directly.
The calling function will gain ownership of the returned structure and will be responsible for freeing it via twStream_Delete().
void twStream_Delete ( void *  s)

Frees all memory associated with a twStream and all of its owned substructures.

Parameters
[in]sA pointer to the twStream to be deleted.
Returns
Nothing.
int twStream_GetBytes ( struct twStream s,
void *  b,
uint32_t  count 
)

Copies count bytes of data from the twStream::data of a twStream into buf.

Parameters
[in]sA pointer to the twStream to get the bytes from.
[out]bufA pointer to a buffer to hold the copied data.
[in]countThe number of bytes to copy.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
char* twStream_GetData ( struct twStream s)

Gets a pointer to the twStream::data of a twStream.

Parameters
[in]sA pointer to the twStream to get the data of.
Returns
The twStream::data pointer of s.
int32_t twStream_GetIndex ( struct twStream s)

Gets the ::twStream#index of a twStream.

Parameters
[in]sA pointer to the twStream to get the index of.
Returns
The ::twStream#index of s.
int32_t twStream_GetLength ( struct twStream s)

Gets the twStream::length of a twStream.

Parameters
[in]sA pointer to the twStream to get the length of.
Returns
The twStream::length of s.
int twStream_Reset ( struct twStream s)

Resets the position pointer of a twStream (twStream::ptr) to the beginning of that twStream's data (twStream::data).

Parameters
[in]sA pointer to the twStream to reset.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.