1/* 2 * Copyright (c) 2014 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-2013, 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 38CF_IMPLICIT_BRIDGING_ENABLED 39CF_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*/ 51typedef 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*/ 59typedef 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*/ 68typedef 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*/ 87typedef 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*/ 103typedef void (*CFTreeApplierFunction)(const void *value, void *context); 104 105/*! 106 @typedef CFTreeRef 107 This is the type of a reference to CFTrees. 108*/ 109typedef struct __CFTree * CFTreeRef; 110 111/*! 112 @function CFTreeGetTypeID 113 Returns the type identifier of all CFTree instances. 114*/ 115CF_EXPORT 116CFTypeID 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*/ 135CF_EXPORT 136CFTreeRef 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*/ 145CF_EXPORT 146CFTreeRef 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*/ 155CF_EXPORT 156CFTreeRef 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*/ 165CF_EXPORT 166CFTreeRef 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*/ 179CF_EXPORT 180void 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*/ 189CF_EXPORT 190CFIndex 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*/ 202CF_EXPORT 203CFTreeRef 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*/ 215CF_EXPORT 216void 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*/ 236CF_EXPORT 237void 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*/ 246CF_EXPORT 247CFTreeRef 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*/ 263CF_EXPORT 264void 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*/ 276CF_EXPORT 277void 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*/ 289CF_EXPORT 290void 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*/ 304CF_EXPORT 305void 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*/ 313CF_EXPORT 314void 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*/ 322CF_EXPORT 323void 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*/ 342CF_EXPORT 343void CFTreeSortChildren(CFTreeRef tree, CFComparatorFunction comparator, void *context); 344 345CF_EXTERN_C_END 346CF_IMPLICIT_BRIDGING_DISABLED 347 348#endif /* ! __COREFOUNDATION_CFTREE__ */ 349 350