Freeing allocated memory

Many of the AR System data structures use allocated memory. For input parameters, use the malloc function to allocate the necessary space. For output parameters, based on their content, the system dynamically allocates memory . Only you (the caller of the API function) will know whether you allocated space for input parameters. When you are finished with output parameters, it is your responsibility to free all allocated memory. To avoid a buildup of allocated space, free memory when 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.

Related topics

Developing-an-API-program

Data-structures

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 the difference:
    freealloc.gif


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.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*