[118] | 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 $
|
---|
| 48 | Revision 1.6 2002/12/12 15:22:29 eskimo1
|
---|
| 49 | Added CFQDictionaryMerge.
|
---|
| 50 |
|
---|
| 51 | Revision 1.5 2002/11/25 18:08:31 eskimo1
|
---|
| 52 | Allow non-Carbon builds.
|
---|
| 53 |
|
---|
| 54 | Revision 1.4 2002/11/08 23:07:22 eskimo1
|
---|
| 55 | When using framework includes, explicitly include the frameworks we need. Convert nil to NULL. Added CFQStringCopyCString.
|
---|
| 56 |
|
---|
| 57 | Revision 1.3 2002/10/24 11:46:27 eskimo1
|
---|
| 58 | Added CFQError routines. Fixed non-framework includes build.
|
---|
| 59 |
|
---|
| 60 | Revision 1.2 2002/01/22 06:14:21 eskimo1
|
---|
| 61 | Change CFQDictionaryAddNumber to CFQDictionarySetNumber.
|
---|
| 62 |
|
---|
| 63 | Revision 1.1 2002/01/16 22:51:32 eskimo1
|
---|
| 64 | First 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
|
---|
| 91 | extern "C" {
|
---|
| 92 | #endif
|
---|
| 93 |
|
---|
| 94 | /////////////////////////////////////////////////////////////////
|
---|
| 95 | // Trivial Utilities
|
---|
| 96 |
|
---|
| 97 | enum {
|
---|
| 98 | kCFQKeyNotFoundErr = 5400,
|
---|
| 99 | kCFQDataErr = 5401
|
---|
| 100 | };
|
---|
| 101 |
|
---|
| 102 | extern pascal OSStatus CFQErrorBoolean(Boolean shouldBeTrue);
|
---|
| 103 | extern pascal OSStatus CFQError(const void *shouldBeNotNULL);
|
---|
| 104 |
|
---|
| 105 | // Two wrappers around CFRelease/Retain that allow you to pass in NULL.
|
---|
| 106 |
|
---|
| 107 | extern pascal CFTypeRef CFQRetain(CFTypeRef cf);
|
---|
| 108 | // CFRetain if cf is not NULL. Returns cf.
|
---|
| 109 |
|
---|
| 110 | extern pascal void CFQRelease(CFTypeRef cf);
|
---|
| 111 | // CFRelease if cf is not NULL.
|
---|
| 112 |
|
---|
| 113 | extern 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 |
|
---|
| 121 | extern pascal OSStatus CFQArrayCreateWithDictionaryKeys(CFDictionaryRef dict, CFArrayRef *result);
|
---|
| 122 | extern 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 |
|
---|
| 131 | extern 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 |
|
---|
| 139 | extern 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 |
|
---|
| 152 | extern 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 |
|
---|
| 157 | extern 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 |
|
---|
| 172 | extern 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 |
|
---|
| 200 | extern 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 |
|
---|
| 214 | extern 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 |
|
---|
| 235 | extern 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 |
|
---|
| 245 | extern 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 |
|
---|
| 259 | extern 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 |
|
---|
| 271 | typedef pascal void (*CFQPropertyListDeepApplierFunction)(CFTypeRef node, void *context);
|
---|
| 272 | // A callback function for CFQPropertyListDeepApplyFunction.
|
---|
| 273 |
|
---|
| 274 | extern 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 |
|
---|
| 282 | extern 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 |
|
---|
| 287 | typedef 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 |
|
---|
| 295 | extern 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 |
|
---|
| 307 | extern 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 |
|
---|
| 316 | extern 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 |
|
---|
| 325 | extern 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
|
---|