source: trunk/Cocoa/Pester/Source/MoreSecurity/MoreCFQ.h@ 118

Last change on this file since 118 was 118, checked in by Nicholas Riley, 21 years ago

Broken, to-be-removed authorization implementation
File size: 13.2 KB
Line 
1/*
2 File: MoreCFQ.h
3
4 Contains: Core Foundation utility Routines.
5
6 Written by: Quinn
7
8 Copyright: Copyright (c) 2001 by Apple Computer, Inc., All Rights Reserved.
9
10 Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Computer, Inc.
11 ("Apple") in consideration of your agreement to the following terms, and your
12 use, installation, modification or redistribution of this Apple software
13 constitutes acceptance of these terms. If you do not agree with these terms,
14 please do not use, install, modify or redistribute this Apple software.
15
16 In consideration of your agreement to abide by the following terms, and subject
17 to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs
18 copyrights in this original Apple software (the "Apple Software"), to use,
19 reproduce, modify and redistribute the Apple Software, with or without
20 modifications, in source and/or binary forms; provided that if you redistribute
21 the Apple Software in its entirety and without modifications, you must retain
22 this notice and the following text and disclaimers in all such redistributions of
23 the Apple Software. Neither the name, trademarks, service marks or logos of
24 Apple Computer, Inc. may be used to endorse or promote products derived from the
25 Apple Software without specific prior written permission from Apple. Except as
26 expressly stated in this notice, no other rights or licenses, express or implied,
27 are granted by Apple herein, including but not limited to any patent rights that
28 may be infringed by your derivative works or by other works in which the Apple
29 Software may be incorporated.
30
31 The Apple Software is provided by Apple on an "AS IS" basis. APPLE MAKES NO
32 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
33 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
34 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
35 COMBINATION WITH YOUR PRODUCTS.
36
37 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
38 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
39 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
40 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
41 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
42 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
43 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44
45 Change History (most recent first):
46
47$Log: MoreCFQ.h,v $
48Revision 1.6 2002/12/12 15:22:29 eskimo1
49Added CFQDictionaryMerge.
50
51Revision 1.5 2002/11/25 18:08:31 eskimo1
52Allow non-Carbon builds.
53
54Revision 1.4 2002/11/08 23:07:22 eskimo1
55When using framework includes, explicitly include the frameworks we need. Convert nil to NULL. Added CFQStringCopyCString.
56
57Revision 1.3 2002/10/24 11:46:27 eskimo1
58Added CFQError routines. Fixed non-framework includes build.
59
60Revision 1.2 2002/01/22 06:14:21 eskimo1
61Change CFQDictionaryAddNumber to CFQDictionarySetNumber.
62
63Revision 1.1 2002/01/16 22:51:32 eskimo1
64First checked in.
65
66
67*/
68
69#pragma once
70
71/////////////////////////////////////////////////////////////////
72
73// MoreIsBetter Setup
74
75#include "MoreSetup.h"
76
77// System Interfaces
78
79#if MORE_FRAMEWORK_INCLUDES
80 #include <CoreServices/CoreServices.h>
81#else
82 #include <CFBase.h>
83 #include <CFURL.h>
84 #include <CFPropertyList.h>
85 #include <Files.h>
86#endif
87
88/////////////////////////////////////////////////////////////////
89
90#ifdef __cplusplus
91extern "C" {
92#endif
93
94/////////////////////////////////////////////////////////////////
95// Trivial Utilities
96
97enum {
98 kCFQKeyNotFoundErr = 5400,
99 kCFQDataErr = 5401
100};
101
102extern pascal OSStatus CFQErrorBoolean(Boolean shouldBeTrue);
103extern pascal OSStatus CFQError(const void *shouldBeNotNULL);
104
105// Two wrappers around CFRelease/Retain that allow you to pass in NULL.
106
107extern pascal CFTypeRef CFQRetain(CFTypeRef cf);
108 // CFRetain if cf is not NULL. Returns cf.
109
110extern pascal void CFQRelease(CFTypeRef cf);
111 // CFRelease if cf is not NULL.
112
113extern pascal OSStatus CFQArrayCreateMutable(CFMutableArrayRef *result);
114 // Creates an empty CFMutableArray that holds other CFTypes.
115 //
116 // result must not be NULL.
117 // On input, *result must be NULL.
118 // On error, *result will be NULL.
119 // On success, *result will be an empty mutable array.
120
121extern pascal OSStatus CFQArrayCreateWithDictionaryKeys(CFDictionaryRef dict, CFArrayRef *result);
122extern pascal OSStatus CFQArrayCreateWithDictionaryValues(CFDictionaryRef dict, CFArrayRef *result);
123 // Creates an array that holds all of the keys (or values) of dict.
124 //
125 // dict must not be NULL.
126 // result must not be NULL.
127 // On input, *result must be NULL.
128 // On error, *result will be NULL.
129 // On success, *result will be an array.
130
131extern pascal OSStatus CFQDictionaryCreateMutable(CFMutableDictionaryRef *result);
132 // Creates an empty CFMutableDictionary that holds other CFTypes.
133 //
134 // result must not be NULL.
135 // On input, *result must be NULL.
136 // On error, *result will be NULL.
137 // On success, *result will be an empty mutable dictionary.
138
139extern pascal OSStatus CFQDictionaryCreateWithArrayOfKeysAndValues(CFArrayRef keys,
140 CFArrayRef values,
141 CFDictionaryRef *result);
142 // Creates a dictionary with the specified keys and values.
143 //
144 // keys must not be NULL.
145 // values must not be NULL.
146 // The length of keys and values must be the same.
147 // result must not be NULL.
148 // On input, *result must be NULL.
149 // On error, *result will be NULL.
150 // On success, *result will be an empty mutable dictionary.
151
152extern pascal OSStatus CFQDictionarySetNumber(CFMutableDictionaryRef dict, const void *key, long value);
153 // Set a CFNumber (created using kCFNumberLongType) in the
154 // dictionary with the specified key. If an error is returned
155 // the dictionary will be unmodified.
156
157extern pascal OSStatus CFQStringCopyCString(CFStringRef str, CFStringEncoding encoding, char **cStrPtr);
158 // Extracts a C string from an arbitrary length CFString.
159 // The caller must free the resulting string using "free".
160 // Returns kCFQDataErr if the CFString contains characters
161 // that can't be encoded in encoding.
162 //
163 // str must not be NULL
164 // On input, cStrPtr must not be NULL
165 // On input, *cStrPtr must be NULL
166 // On error, *cStrPtr will be NULL
167 // On success, *cStrPtr will be a C string that you must free
168
169/////////////////////////////////////////////////////////////////
170// Dictionary Path Routines
171
172extern pascal OSStatus CFQDictionaryGetValueAtPath(CFDictionaryRef dict,
173 const void *path[], CFIndex pathElementCount,
174 const void **result);
175 // Given a dictionary possibly containing nested dictionaries,
176 // this routine returns the value specified by path. path is
177 // unbounded array of dictionary keys. The first element of
178 // path must be the key of a property in dict. If path has
179 // more than one element then the value of the property must
180 // be a dictionary and the next element of path must be a
181 // key in that dictionary. And so on. The routine returns
182 // the value of the dictionary property found at the end
183 // of the path.
184 //
185 // For example, if path is "A"/"B"/"C", then dict must contain
186 // a property whose key is "A" and whose value is a dictionary.
187 // That dictionary must contain a property whose key is "B" and
188 // whose value is a dictionary. That dictionary must contain
189 // a property whose key is "C" and whose value this routine
190 // returns.
191 //
192 // dict must not be NULL.
193 // path must not be NULL.
194 // pathElementCount must be greater than 0.
195 // result must not be NULL.
196 // On input, *result must be NULL.
197 // On error, *result will be NULL.
198 // On success, *result is the value from the dictionary.
199
200extern pascal OSStatus CFQDictionaryGetValueAtPathArray(CFDictionaryRef dict,
201 CFArrayRef path,
202 const void **result);
203 // This routine is identical to CFQDictionaryGetValueAtPath except
204 // that you supply path as a CFArray instead of a C array.
205 //
206 // dict must not be NULL.
207 // path must not be NULL.
208 // path must have at least one element.
209 // result must not be NULL.
210 // On input, *result must be NULL.
211 // On error, *result will be NULL.
212 // On success, *result is the value from the dictionary.
213
214extern pascal OSStatus CFQDictionarySetValueAtPath(CFMutableDictionaryRef dict,
215 const void *path[], CFIndex pathElementCount,
216 const void *value);
217 // This routines works much like CFQDictionaryGetValueAtPath
218 // except that it sets the value at the end of the path
219 // instead of returning it. For the set to work,
220 // dict must be mutable. However, the dictionaries
221 // nested inside dict may not be mutable. To make this
222 // work this routine makes a mutable copy of any nested
223 // dictionaries it traverses and replaces the (possibly)
224 // immutable nested dictionaries with these mutable versions.
225 //
226 // The path need not necessarily denote an existing node
227 // in the nested dictionary tree. However, this routine
228 // will only create a leaf node. It won't create any
229 // parent nodes required to holf that leaf.
230 //
231 // dict must not be NULL.
232 // path must not be NULL.
233 // pathElementCount must be greater than 0.
234
235extern pascal OSStatus CFQDictionarySetValueAtPathArray(CFMutableDictionaryRef dict,
236 CFArrayRef path,
237 const void *value);
238 // This routine is identical to CFQDictionarySetValueAtPath except
239 // that you supply path as a CFArray instead of a C array.
240 //
241 // dict must not be NULL.
242 // path must not be NULL.
243 // path must have at least one element.
244
245extern pascal OSStatus CFQDictionaryRemoveValueAtPath(CFMutableDictionaryRef dict,
246 const void *path[], CFIndex pathElementCount);
247 // This routines works much like CFQDictionarySetValueAtPath
248 // except that it removes the value at the end of the path.
249 //
250 // Unlike CFQDictionarySetValueAtPath, this routine requires
251 // that path denote an existing node in the nested dictionary
252 // tree. Removing a non-existant node, even a leaf node,
253 // results in an error.
254 //
255 // dict must not be NULL.
256 // path must not be NULL.
257 // pathElementCount must be greater than 0.
258
259extern pascal OSStatus CFQDictionaryRemoveValueAtPathArray(CFMutableDictionaryRef dict,
260 CFArrayRef path);
261 // This routine is identical to CFQDictionaryRemoveValueAtPathArray
262 // except that you supply path as a CFArray instead of a C array.
263 //
264 // dict must not be NULL.
265 // path must not be NULL.
266 // path must have at least one element.
267
268/////////////////////////////////////////////////////////////////
269// Property List Traversal Routines
270
271typedef pascal void (*CFQPropertyListDeepApplierFunction)(CFTypeRef node, void *context);
272 // A callback function for CFQPropertyListDeepApplyFunction.
273
274extern pascal void CFQPropertyListDeepApplyFunction(CFPropertyListRef propList,
275 CFQPropertyListDeepApplierFunction func,
276 void *context);
277 // Calls "func" for every node in the property list.
278 //
279 // propList must not be NULL.
280 // func must not be NULL.
281
282extern pascal Boolean CFQPropertyListIsLeaf(CFTypeRef node);
283 // Given a node in a property list, this routine returns
284 // true if the node is a leaf (ie not a dictionary or an
285 // array).
286
287typedef pascal void (*CFQPropertyListShallowApplierFunction)(CFTypeRef key, CFTypeRef node, void *context);
288 // A callback function for CFQPropertyListShallowApplyFunction.
289 //
290 // node must be an element of either a dictionary or an array.
291 // If node is an element of a dictionary, key is its key within
292 // the dictionary. If node is an element of an array, key
293 // is a CFNumber of its index in the array.
294
295extern pascal void CFQPropertyListShallowApplyFunction(CFPropertyListRef propList,
296 CFQPropertyListShallowApplierFunction func,
297 void *context);
298 // Calls "func" for every node in the first level of the
299 // property list. propList must be either a dictionary
300 // or an array. To continue to lower levels, "func" should
301 // call CFQPropertyListApplyFunctionShallow again (only if
302 // CFQPropertyListIsLeaf is false).
303 //
304 // propList must not be NULL.
305 // func must not be NULL.
306
307extern pascal OSStatus CFQPropertyListCreateFromXMLFSRef(const FSRef *xmlFile, CFPropertyListMutabilityOptions options, CFPropertyListRef *result);
308 // Creates a property list based on the XML in the file.
309 //
310 // xmlFile must not be NULL
311 // result must not be NULL
312 // *result must be NULL
313 // on success, *result will be a valid property list
314 // on error, *result will be NULL
315
316extern pascal OSStatus CFQPropertyListCreateFromXMLCFURL(CFURLRef xmlFile, CFPropertyListMutabilityOptions options, CFPropertyListRef *result);
317 // Creates a property list based on the XML in the file.
318 //
319 // xmlFile must not be NULL
320 // result must not be NULL
321 // *result must be NULL
322 // on success, *result will be a valid property list
323 // on error, *result will be NULL
324
325extern pascal OSStatus CFQDictionaryMerge(CFMutableDictionaryRef dst, CFDictionaryRef src);
326 // Adds every key/value pair from src into dst, overwriting any
327 // current value for the key.
328 //
329 // dst must not be NULL
330 // src must not be NULL
331
332#ifdef __cplusplus
333}
334#endif
Note: See TracBrowser for help on using the repository browser.