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