Lists and structures

Lists manipulate sets of objects of a particular type, for example:

  • ARNameList manipulates any set of names.
  • ARDiaryList manages the group of entries in a diary field.
  • AREntryListList represents any group of entries in a schema.
  • ARFilterActionList defines the set of actions that the server performs when it executes a filter or escalation.

While each type of list has its own data structure, all list structures have the same form:


typedef struct {
unsigned int     numItems;
AR xxxStruct      *xxxList;
} ARxxxList;

Each list structure has an integer that identifies the number of items in the list and a pointer to the allocated memory containing those items. If the number of items is zero, the server or client ignores the pointer and the pointer is usually set to NULL. The following figure shows an example that uses the ARFilterActionList structure.

Generic list structure

Generic_list.gif

For simplicity, subsequent structure diagrams do not illustrate the numItems element (unsigned int) for any list structures. The number of items in the list is the first component of all list structures in the API.

In general, the AR System server handles lists as arrays instead of as linked lists. It then stores all items in the structure in a single area of memory with a pointer that identifies the memory address of the first item in the array. If the item structure itself (ARFilterActionStruct) contains a pointer, the server allocates the nested memory separately.