CFTree.h

   1 /*
   2  * Copyright (c) 2009 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*      CFTree.h
  25         Copyright (c) 1998-2009, Apple Inc. All rights reserved.
  26 */
  27 /*!
  28         @header CFTree
  29         CFTree implements a container which stores references to other CFTrees.
  30         Each tree may have a parent, and a variable number of children.
  31 */
  32
  33 #if !defined(__COREFOUNDATION_CFTREE__)
  34 #define __COREFOUNDATION_CFTREE__ 1
  35
  36 #include <CoreFoundation/CFBase.h>
  37
  38 CF_EXTERN_C_BEGIN
  39
  40 /*!
  41         @typedef CFTreeRetainCallBack
  42         Type of the callback function used to add a retain to the user-specified
  43         info parameter.  This callback may returns the value to use whenever the
  44         info parameter is retained, which is usually the value parameter passed
  45         to this callback, but may be a different value if a different value
  46         should be used.
  47         @param info A user-supplied info parameter provided in a CFTreeContext.
  48         @result The retained info parameter.
  49 */
  50 typedef const void *    (*CFTreeRetainCallBack)(const void *info);
  51
  52 /*!
  53         @typedef CFTreeReleaseCallBack
  54         Type of the callback function used to remove a retain previously
  55         added to the user-specified info parameter.
  56         @param info A user-supplied info parameter provided in a CFTreeContext.
  57 */
  58 typedef void            (*CFTreeReleaseCallBack)(const void *info);
  59
  60 /*!
  61         @typedef CFTreeCopyDescriptionCallBack
  62         Type of the callback function used to provide a description of the
  63         user-specified info parameter.
  64         @param info A user-supplied info parameter provided in a CFTreeContext.
  65         @result A description of the info parameter.
  66 */
  67 typedef CFStringRef     (*CFTreeCopyDescriptionCallBack)(const void *info);
  68
  69 /*!
  70         @typedef CFTreeContext
  71         Structure containing user-specified data and callbacks for a CFTree.
  72         @field version The version number of the structure type being passed
  73                 in as a parameter to the CFTree creation function.
  74                 This structure is version 0.
  75         @field info A C pointer to a user-specified block of data.
  76         @field retain The callback used to add a retain for the info field.
  77                 If this parameter is not a pointer to a function of the correct
  78                 prototype, the behavior is undefined.  The value may be NULL.
  79         @field release The calllback used to remove a retain previously added
  80                 for the info field.  If this parameter is not a pointer to a
  81                 function of the correct prototype, the behavior is undefined.
  82                 The value may be NULL.
  83         @field copyDescription The callback used to provide a description of
  84                 the info field.
  85 */
  86 typedef struct {
  87     CFIndex                             version;
  88     void *                              info;
  89     CFTreeRetainCallBack                retain;
  90     CFTreeReleaseCallBack               release;
  91     CFTreeCopyDescriptionCallBack       copyDescription;
  92 } CFTreeContext;
  93
  94 /*!
  95         @typedef CFTreeApplierFunction
  96         Type of the callback function used by the apply functions of
  97                 CFTree.
  98         @param value The current value from the CFTree
  99         @param context The user-defined context parameter give to the apply
 100                 function.
 101 */
 102 typedef void (*CFTreeApplierFunction)(const void *value, void *context);
 103
 104 /*!
 105         @typedef CFTreeRef
 106         This is the type of a reference to CFTrees.
 107 */
 108 typedef struct __CFTree * CFTreeRef;
 109
 110 /*!
 111         @function CFTreeGetTypeID
 112         Returns the type identifier of all CFTree instances.
 113 */
 114 CF_EXPORT
 115 CFTypeID CFTreeGetTypeID(void);
 116
 117 /*!
 118         @function CFTreeCreate
 119         Creates a new mutable tree.
 120         @param allocator The CFAllocator which should be used to allocate
 121                 memory for the tree and storage for its children.  This
 122                 parameter may be NULL in which case the current default
 123                 CFAllocator is used.  If this reference is not a valid
 124                 CFAllocator, the behavior is undefined.
 125         @param context A C pointer to a CFTreeContext structure to be copied
 126                 and used as the context of the new tree.  The info parameter
 127                 will be retained by the tree if a retain function is provided.
 128                 If this value is not a valid C pointer to a CFTreeContext
 129                 structure-sized block of storage, the result is undefined.
 130                 If the version number of the storage is not a valid CFTreeContext
 131                 version number, the result is undefined.
 132         @result A reference to the new CFTree.
 133 */
 134 CF_EXPORT
 135 CFTreeRef CFTreeCreate(CFAllocatorRef allocator, const CFTreeContext *context);
 136
 137 /*!
 138         @function CFTreeGetParent
 139         Returns the parent of the specified tree.
 140         @param tree The tree to be queried.  If this parameter is not a valid
 141                 CFTree, the behavior is undefined.
 142         @result The parent of the tree.
 143 */
 144 CF_EXPORT
 145 CFTreeRef CFTreeGetParent(CFTreeRef tree);
 146
 147 /*!
 148         @function CFTreeGetNextSibling
 149         Returns the sibling after the specified tree in the parent tree's list.
 150         @param tree The tree to be queried.  If this parameter is not a valid
 151                 CFTree, the behavior is undefined.
 152         @result The next sibling of the tree.
 153 */
 154 CF_EXPORT
 155 CFTreeRef CFTreeGetNextSibling(CFTreeRef tree);
 156
 157 /*!
 158         @function CFTreeGetFirstChild
 159         Returns the first child of the tree.
 160         @param tree The tree to be queried.  If this parameter is not a valid
 161                 CFTree, the behavior is undefined.
 162         @result The first child of the tree.
 163 */
 164 CF_EXPORT
 165 CFTreeRef CFTreeGetFirstChild(CFTreeRef tree);
 166
 167 /*!
 168         @function CFTreeGetContext
 169         Returns the context of the specified tree.
 170         @param tree The tree to be queried.  If this parameter is not a valid
 171                 CFTree, the behavior is undefined.
 172         @param context A C pointer to a CFTreeContext structure to be filled in with
 173                 the context of the specified tree.  If this value is not a valid C
 174                 pointer to a CFTreeContext structure-sized block of storage, the
 175                 result is undefined.  If the version number of the storage is not
 176                 a valid CFTreeContext version number, the result is undefined.
 177 */
 178 CF_EXPORT
 179 void CFTreeGetContext(CFTreeRef tree, CFTreeContext *context);
 180
 181 /*!
 182         @function CFTreeGetChildCount
 183         Returns the number of children of the specified tree.
 184         @param tree The tree to be queried.  If this parameter is not a valid
 185                 CFTree, the behavior is undefined.
 186         @result The number of children.
 187 */
 188 CF_EXPORT
 189 CFIndex CFTreeGetChildCount(CFTreeRef tree);
 190
 191 /*!
 192         @function CFTreeGetChildAtIndex
 193         Returns the nth child of the specified tree.
 194         @param tree The tree to be queried.  If this parameter is not a valid
 195                 CFTree, the behavior is undefined.
 196         @param idx The index of the child tree to be returned.  If this parameter
 197                 is less than zero or greater than the number of children of the
 198                 tree, the result is undefined.
 199         @result A reference to the specified child tree.
 200 */
 201 CF_EXPORT
 202 CFTreeRef CFTreeGetChildAtIndex(CFTreeRef tree, CFIndex idx);
 203
 204 /*!
 205         @function CFTreeGetChildren
 206         Fills the buffer with children from the tree.
 207         @param tree The tree to be queried.  If this parameter is not a valid
 208                 CFTree, the behavior is undefined.
 209         @param children A C array of pointer-sized values to be filled with
 210                 children from the tree.  If this parameter is not a valid pointer to a
 211                 C array of at least CFTreeGetChildCount() pointers, the behavior is undefined.
 212         @result A reference to the specified child tree.
 213 */
 214 CF_EXPORT
 215 void CFTreeGetChildren(CFTreeRef tree, CFTreeRef *children);
 216
 217 /*!
 218         @function CFTreeApplyFunctionToChildren
 219         Calls a function once for each child of the tree.  Note that the applier
 220         only operates one level deep, and does not operate on descendents further
 221         removed than the immediate children of the tree.
 222         @param heap The tree to be operated upon.  If this parameter is not a
 223                 valid CFTree, the behavior is undefined.
 224         @param applier The callback function to call once for each child of
 225                 the given tree.  If this parameter is not a pointer to a
 226                 function of the correct prototype, the behavior is undefined.
 227                 If there are values in the tree which the applier function does
 228                 not expect or cannot properly apply to, the behavior is undefined.
 229         @param context A pointer-sized user-defined value, which is passed
 230                 as the second parameter to the applier function, but is
 231                 otherwise unused by this function.  If the context is not
 232                 what is expected by the applier function, the behavior is
 233                 undefined.
 234 */
 235 CF_EXPORT
 236 void CFTreeApplyFunctionToChildren(CFTreeRef tree, CFTreeApplierFunction applier, void *context);
 237
 238 /*!
 239         @function CFTreeFindRoot
 240         Returns the root tree of which the specified tree is a descendent.
 241         @param tree The tree to be queried.  If this parameter is not a valid
 242                 CFTree, the behavior is undefined.
 243         @result A reference to the root of the tree.
 244 */
 245 CF_EXPORT
 246 CFTreeRef CFTreeFindRoot(CFTreeRef tree);
 247
 248 /*!
 249         @function CFTreeSetContext
 250         Replaces the context of a tree.  The tree releases its retain on the
 251         info of the previous context, and retains the info of the new context.
 252         @param tree The tree to be operated on.  If this parameter is not a valid
 253                 CFTree, the behavior is undefined.
 254         @param context A C pointer to a CFTreeContext structure to be copied
 255                 and used as the context of the new tree.  The info parameter
 256                 will be retained by the tree if a retain function is provided.
 257                 If this value is not a valid C pointer to a CFTreeContext
 258                 structure-sized block of storage, the result is undefined.
 259                 If the version number of the storage is not a valid CFTreeContext
 260                 version number, the result is undefined.
 261 */
 262 CF_EXPORT
 263 void CFTreeSetContext(CFTreeRef tree, const CFTreeContext *context);
 264
 265 /*!
 266         @function CFTreePrependChild
 267         Adds the newChild to the specified tree as the first in its list of children.
 268         @param tree The tree to be operated on.  If this parameter is not a valid
 269                 CFTree, the behavior is undefined.
 270         @param newChild The child to be added.
 271                 If this parameter is not a valid CFTree, the behavior is undefined.
 272                 If this parameter is a tree which is already a child of any tree,
 273                 the behavior is undefined.
 274 */
 275 CF_EXPORT
 276 void CFTreePrependChild(CFTreeRef tree, CFTreeRef newChild);
 277
 278 /*!
 279         @function CFTreeAppendChild
 280         Adds the newChild to the specified tree as the last in its list of children.
 281         @param tree The tree to be operated on.  If this parameter is not a valid
 282                 CFTree, the behavior is undefined.
 283         @param newChild The child to be added.
 284                 If this parameter is not a valid CFTree, the behavior is undefined.
 285                 If this parameter is a tree which is already a child of any tree,
 286                 the behavior is undefined.
 287 */
 288 CF_EXPORT
 289 void CFTreeAppendChild(CFTreeRef tree, CFTreeRef newChild);
 290
 291 /*!
 292         @function CFTreeInsertSibling
 293         Inserts newSibling into the the parent tree's linked list of children after
 294         tree.  The newSibling will have the same parent as tree.
 295         @param tree The tree to insert newSibling after.  If this parameter is not a valid
 296                 CFTree, the behavior is undefined.  If the tree does not have a
 297                 parent, the behavior is undefined.
 298         @param newSibling The sibling to be added.
 299                 If this parameter is not a valid CFTree, the behavior is undefined.
 300                 If this parameter is a tree which is already a child of any tree,
 301                 the behavior is undefined.
 302 */
 303 CF_EXPORT
 304 void CFTreeInsertSibling(CFTreeRef tree, CFTreeRef newSibling);
 305
 306 /*!
 307         @function CFTreeRemove
 308         Removes the tree from its parent.
 309         @param tree The tree to be removed.  If this parameter is not a valid
 310                 CFTree, the behavior is undefined.
 311 */
 312 CF_EXPORT
 313 void CFTreeRemove(CFTreeRef tree);
 314
 315 /*!
 316         @function CFTreeRemoveAllChildren
 317         Removes all the children of the tree.
 318         @param tree The tree to remove all children from.  If this parameter is not a valid
 319                 CFTree, the behavior is undefined.
 320 */
 321 CF_EXPORT
 322 void CFTreeRemoveAllChildren(CFTreeRef tree);
 323
 324 /*!
 325         @function CFTreeSortChildren
 326         Sorts the children of the specified tree using the specified comparator function.
 327         @param tree The tree to be operated on.  If this parameter is not a valid
 328                 CFTree, the behavior is undefined.
 329         @param comparator The function with the comparator function type
 330                 signature which is used in the sort operation to compare
 331                 children of the tree with the given value. If this parameter
 332                 is not a pointer to a function of the correct prototype, the
 333                 the behavior is undefined. The children of the tree are sorted
 334                 from least to greatest according to this function.
 335         @param context A pointer-sized user-defined value, which is passed
 336                 as the third parameter to the comparator function, but is
 337                 otherwise unused by this function. If the context is not
 338                 what is expected by the comparator function, the behavior is
 339                 undefined.
 340 */
 341 CF_EXPORT
 342 void CFTreeSortChildren(CFTreeRef tree, CFComparatorFunction comparator, void *context);
 343
 344 CF_EXTERN_C_END
 345
 346 #endif /* ! __COREFOUNDATION_CFTREE__ */
 347