Collections.subproj/CFTree.h

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