CFTree.h

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