CFTree.h

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