Freeing allocated memory

Many of the  data structures use allocated memory. For input parameters, use the malloc function to allocate the necessary space. The system dynamically allocates memory for output parameters based on their content. Only you (the caller of the API function) know whether you allocated space for input parameters, and when you are finished with output parameters, you are responsible for freeing all allocated memory. To avoid a buildup of allocated space, free memory as soon as you no longer need it.

To ease the process of freeing memory, the API includes FreeAR functions, each specialized to free all allocated memory associated with a particular data structure. These functions assume that all structure components are in allocated memory and must not be used if any components of a structure are on the stack. In that case, you must use the free function to free the memory manually.

All FreeAR functions accept these input arguments:

• value—Pointer to the structure to free. The function recursively frees all allocated memory in the structure. If you set this to NULL (or the structure is a list with zero items), the function performs no operations.
• freeStruct—Boolean value that specifies whether to free the top-level structure. If you allocated memory for the top-level structure, specify TRUE to free both the structure and its contents. If you used a stack variable for the top-level structure, specify FALSE to free only the contents of the structure. The following example illustrates this difference.

When an API function fails (that is, status is greater than one), the system initializes all output parameters except ARStatusList. As a result, the only FreeAR function the program must call is FreeARStatusList. Calling FreeAR data Structure for the other parameters is unnecessary but harmless.