| /* CFTree.h |
| Copyright (c) 1998-2016, Apple Inc. and the Swift project authors |
| |
| Portions Copyright (c) 2014-2016 Apple Inc. and the Swift project authors |
| Licensed under Apache License v2.0 with Runtime Library Exception |
| See http://swift.org/LICENSE.txt for license information |
| See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| */ |
| /*! |
| @header CFTree |
| CFTree implements a container which stores references to other CFTrees. |
| Each tree may have a parent, and a variable number of children. |
| */ |
| |
| #if !defined(__COREFOUNDATION_CFTREE__) |
| #define __COREFOUNDATION_CFTREE__ 1 |
| |
| #include <CoreFoundation/CFBase.h> |
| |
| CF_IMPLICIT_BRIDGING_ENABLED |
| CF_EXTERN_C_BEGIN |
| |
| /*! |
| @typedef CFTreeRetainCallBack |
| Type of the callback function used to add a retain to the user-specified |
| info parameter. This callback may returns the value to use whenever the |
| info parameter is retained, which is usually the value parameter passed |
| to this callback, but may be a different value if a different value |
| should be used. |
| @param info A user-supplied info parameter provided in a CFTreeContext. |
| @result The retained info parameter. |
| */ |
| typedef const void * (*CFTreeRetainCallBack)(const void *info); |
| |
| /*! |
| @typedef CFTreeReleaseCallBack |
| Type of the callback function used to remove a retain previously |
| added to the user-specified info parameter. |
| @param info A user-supplied info parameter provided in a CFTreeContext. |
| */ |
| typedef void (*CFTreeReleaseCallBack)(const void *info); |
| |
| /*! |
| @typedef CFTreeCopyDescriptionCallBack |
| Type of the callback function used to provide a description of the |
| user-specified info parameter. |
| @param info A user-supplied info parameter provided in a CFTreeContext. |
| @result A description of the info parameter. |
| */ |
| typedef CFStringRef (*CFTreeCopyDescriptionCallBack)(const void *info); |
| |
| /*! |
| @typedef CFTreeContext |
| Structure containing user-specified data and callbacks for a CFTree. |
| @field version The version number of the structure type being passed |
| in as a parameter to the CFTree creation function. |
| This structure is version 0. |
| @field info A C pointer to a user-specified block of data. |
| @field retain The callback used to add a retain for the info field. |
| If this parameter is not a pointer to a function of the correct |
| prototype, the behavior is undefined. The value may be NULL. |
| @field release The calllback used to remove a retain previously added |
| for the info field. If this parameter is not a pointer to a |
| function of the correct prototype, the behavior is undefined. |
| The value may be NULL. |
| @field copyDescription The callback used to provide a description of |
| the info field. |
| */ |
| typedef struct { |
| CFIndex version; |
| void * info; |
| CFTreeRetainCallBack retain; |
| CFTreeReleaseCallBack release; |
| CFTreeCopyDescriptionCallBack copyDescription; |
| } CFTreeContext; |
| |
| /*! |
| @typedef CFTreeApplierFunction |
| Type of the callback function used by the apply functions of |
| CFTree. |
| @param value The current value from the CFTree |
| @param context The user-defined context parameter give to the apply |
| function. |
| */ |
| typedef void (*CFTreeApplierFunction)(const void *value, void *context); |
| |
| /*! |
| @typedef CFTreeRef |
| This is the type of a reference to CFTrees. |
| */ |
| typedef struct CF_BRIDGED_MUTABLE_TYPE(id) __CFTree * CFTreeRef; |
| |
| /*! |
| @function CFTreeGetTypeID |
| Returns the type identifier of all CFTree instances. |
| */ |
| CF_EXPORT |
| CFTypeID CFTreeGetTypeID(void); |
| |
| /*! |
| @function CFTreeCreate |
| Creates a new mutable tree. |
| @param allocator The CFAllocator which should be used to allocate |
| memory for the tree and storage for its children. This |
| parameter may be NULL in which case the current default |
| CFAllocator is used. If this reference is not a valid |
| CFAllocator, the behavior is undefined. |
| @param context A C pointer to a CFTreeContext structure to be copied |
| and used as the context of the new tree. The info parameter |
| will be retained by the tree if a retain function is provided. |
| If this value is not a valid C pointer to a CFTreeContext |
| structure-sized block of storage, the result is undefined. |
| If the version number of the storage is not a valid CFTreeContext |
| version number, the result is undefined. |
| @result A reference to the new CFTree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeCreate(CFAllocatorRef allocator, const CFTreeContext *context); |
| |
| /*! |
| @function CFTreeGetParent |
| Returns the parent of the specified tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @result The parent of the tree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeGetParent(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeGetNextSibling |
| Returns the sibling after the specified tree in the parent tree's list. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @result The next sibling of the tree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeGetNextSibling(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeGetFirstChild |
| Returns the first child of the tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @result The first child of the tree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeGetFirstChild(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeGetContext |
| Returns the context of the specified tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param context A C pointer to a CFTreeContext structure to be filled in with |
| the context of the specified tree. If this value is not a valid C |
| pointer to a CFTreeContext structure-sized block of storage, the |
| result is undefined. If the version number of the storage is not |
| a valid CFTreeContext version number, the result is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeGetContext(CFTreeRef tree, CFTreeContext *context); |
| |
| /*! |
| @function CFTreeGetChildCount |
| Returns the number of children of the specified tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @result The number of children. |
| */ |
| CF_EXPORT |
| CFIndex CFTreeGetChildCount(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeGetChildAtIndex |
| Returns the nth child of the specified tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param idx The index of the child tree to be returned. If this parameter |
| is less than zero or greater than the number of children of the |
| tree, the result is undefined. |
| @result A reference to the specified child tree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeGetChildAtIndex(CFTreeRef tree, CFIndex idx); |
| |
| /*! |
| @function CFTreeGetChildren |
| Fills the buffer with children from the tree. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param children A C array of pointer-sized values to be filled with |
| children from the tree. If this parameter is not a valid pointer to a |
| C array of at least CFTreeGetChildCount() pointers, the behavior is undefined. |
| @result A reference to the specified child tree. |
| */ |
| CF_EXPORT |
| void CFTreeGetChildren(CFTreeRef tree, CFTreeRef *children); |
| |
| /*! |
| @function CFTreeApplyFunctionToChildren |
| Calls a function once for each child of the tree. Note that the applier |
| only operates one level deep, and does not operate on descendents further |
| removed than the immediate children of the tree. |
| @param heap The tree to be operated upon. If this parameter is not a |
| valid CFTree, the behavior is undefined. |
| @param applier The callback function to call once for each child of |
| the given tree. If this parameter is not a pointer to a |
| function of the correct prototype, the behavior is undefined. |
| If there are values in the tree which the applier function does |
| not expect or cannot properly apply to, the behavior is undefined. |
| @param context A pointer-sized user-defined value, which is passed |
| as the second parameter to the applier function, but is |
| otherwise unused by this function. If the context is not |
| what is expected by the applier function, the behavior is |
| undefined. |
| */ |
| CF_EXPORT |
| void CFTreeApplyFunctionToChildren(CFTreeRef tree, CFTreeApplierFunction CF_NOESCAPE applier, void *context); |
| |
| /*! |
| @function CFTreeFindRoot |
| Returns the root tree of which the specified tree is a descendent. |
| @param tree The tree to be queried. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @result A reference to the root of the tree. |
| */ |
| CF_EXPORT |
| CFTreeRef CFTreeFindRoot(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeSetContext |
| Replaces the context of a tree. The tree releases its retain on the |
| info of the previous context, and retains the info of the new context. |
| @param tree The tree to be operated on. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param context A C pointer to a CFTreeContext structure to be copied |
| and used as the context of the new tree. The info parameter |
| will be retained by the tree if a retain function is provided. |
| If this value is not a valid C pointer to a CFTreeContext |
| structure-sized block of storage, the result is undefined. |
| If the version number of the storage is not a valid CFTreeContext |
| version number, the result is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeSetContext(CFTreeRef tree, const CFTreeContext *context); |
| |
| /*! |
| @function CFTreePrependChild |
| Adds the newChild to the specified tree as the first in its list of children. |
| @param tree The tree to be operated on. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param newChild The child to be added. |
| If this parameter is not a valid CFTree, the behavior is undefined. |
| If this parameter is a tree which is already a child of any tree, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFTreePrependChild(CFTreeRef tree, CFTreeRef newChild); |
| |
| /*! |
| @function CFTreeAppendChild |
| Adds the newChild to the specified tree as the last in its list of children. |
| @param tree The tree to be operated on. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param newChild The child to be added. |
| If this parameter is not a valid CFTree, the behavior is undefined. |
| If this parameter is a tree which is already a child of any tree, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeAppendChild(CFTreeRef tree, CFTreeRef newChild); |
| |
| /*! |
| @function CFTreeInsertSibling |
| Inserts newSibling into the the parent tree's linked list of children after |
| tree. The newSibling will have the same parent as tree. |
| @param tree The tree to insert newSibling after. If this parameter is not a valid |
| CFTree, the behavior is undefined. If the tree does not have a |
| parent, the behavior is undefined. |
| @param newSibling The sibling to be added. |
| If this parameter is not a valid CFTree, the behavior is undefined. |
| If this parameter is a tree which is already a child of any tree, |
| the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeInsertSibling(CFTreeRef tree, CFTreeRef newSibling); |
| |
| /*! |
| @function CFTreeRemove |
| Removes the tree from its parent. |
| @param tree The tree to be removed. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeRemove(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeRemoveAllChildren |
| Removes all the children of the tree. |
| @param tree The tree to remove all children from. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| */ |
| CF_EXPORT |
| void CFTreeRemoveAllChildren(CFTreeRef tree); |
| |
| /*! |
| @function CFTreeSortChildren |
| Sorts the children of the specified tree using the specified comparator function. |
| @param tree The tree to be operated on. If this parameter is not a valid |
| CFTree, the behavior is undefined. |
| @param comparator The function with the comparator function type |
| signature which is used in the sort operation to compare |
| children of the tree with the given value. If this parameter |
| is not a pointer to a function of the correct prototype, the |
| the behavior is undefined. The children of the tree are sorted |
| from least to greatest according to this function. |
| @param context A pointer-sized user-defined value, which is passed |
| as the third parameter to the comparator function, but is |
| otherwise unused by this function. If the context is not |
| what is expected by the comparator function, the behavior is |
| undefined. |
| */ |
| CF_EXPORT |
| void CFTreeSortChildren(CFTreeRef tree, CFComparatorFunction comparator, void *context); |
| |
| CF_EXTERN_C_END |
| CF_IMPLICIT_BRIDGING_DISABLED |
| |
| #endif /* ! __COREFOUNDATION_CFTREE__ */ |
| |