Property List Functions

List   *proplist_add(List * proplist, void *ptr, int type,
                     void (*freefunc) ( /* ??? */ ))

List   *proplist_addifnp(List * proplist, void *ptr, int type,
                         void (*freefunc) ( /* ??? */ ), Bool dofree)

int     prop_set(List * proplist, void *ptr, int type, Bool dofree)

For adding new properties and/or replacing existing ones. The type field is used as a key to the data referenced by ptr. Property lists are able to destroy the data they refer to using freefunc. The function freefunc is of the form

void freefunc(void *ptr, int type)

Copied data can be protected with a NULL freefunc. When setting a property the boolean dofree determines whether freefunc should be run on the existing property. This is important when augmenting or updating an existing property.

proplist_addifnp (property list add if not present) performs proplist_add or prop_set depending on whether a property keyed by type exist or not. New properties are always added to the front of the list. Multiple calls to proplist_add with the same type argument result in shadowing of previous property settings.

void   *prop_get(List * proplist, int type)

int     prop_present(List * proplist, int type)

int     prop_ref_present(List * proplist, void *ptr)

Property location and retrieval functions. Each prop_get function finds the first property in to match the type or ptr argument.

List   *proplist_rm(List * proplist, int type)

List   *proplist_rm_by_ref(List * proplist, void *ptr)

List   *proplist_free(List * proplist, int type)

List   *proplist_free_by_ref(List * proplist, void *ptr)

Functions to remove properties ( _rm initial postfix) or both remove properties and free references ( _free initial postfix) of individual items in a property list and return the amended property list. Versions with the additional _by_ref postfix, use the value referenced by the property (if available) rather than the property itself as a key to the property list.

void    proplist_rmlist(List * proplist)

void    proplist_freelist(List * proplist)

Functions to remove properties ( _rmlist postfix) or both remove properties and free references ( _freelist postfix) of an entire property list.

List   *proplist_copy(List * proplist)

Make a copy of a property list. It actually references the same items through the same property structure (hence a change to a shared property will change all occurrences of it). Subsequent rm and free requests made on the property will only remove the property structure and/or free the referenced data when made by the last remaining share holder. Other requests will only update the list through which properties are accessed.