CFURL.h

   1 /*
   2  * Copyright (c) 2010 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 /*      CFURL.h
  25         Copyright (c) 1998-2009, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFURL__)
  29 #define __COREFOUNDATION_CFURL__ 1
  30
  31 #include <CoreFoundation/CFBase.h>
  32 #include <CoreFoundation/CFData.h>
  33 #include <CoreFoundation/CFError.h>
  34 #include <CoreFoundation/CFString.h>
  35
  36 CF_EXTERN_C_BEGIN
  37
  38 enum {
  39     kCFURLPOSIXPathStyle = 0,
  40     kCFURLHFSPathStyle,
  41     kCFURLWindowsPathStyle
  42 };
  43 typedef CFIndex CFURLPathStyle;
  44
  45 typedef const struct __CFURL * CFURLRef;
  46
  47 /* CFURLs are composed of two fundamental pieces - their string, and a */
  48 /* (possibly NULL) base URL.  A relative URL is one in which the string */
  49 /* by itself does not fully specify the URL (for instance "myDir/image.tiff"); */
  50 /* an absolute URL is one in which the string does fully specify the URL */
  51 /* ("file://localhost/myDir/image.tiff").  Absolute URLs always have NULL */
  52 /* base URLs; however, it is possible for a URL to have a NULL base, and still */
  53 /* not be absolute.  Such a URL has only a relative string, and cannot be */
  54 /* resolved.  Two CFURLs are considered equal if and only if their strings */
  55 /* are equal and their bases are equal.  In other words, */
  56 /* "file://localhost/myDir/image.tiff" is NOT equal to the URL with relative */
  57 /* string "myDir/image.tiff" and base URL "file://localhost/".  Clients that */
  58 /* need these less strict form of equality should convert all URLs to their */
  59 /* absolute form via CFURLCopyAbsoluteURL(), then compare the absolute forms. */
  60
  61 CF_EXPORT
  62 CFTypeID CFURLGetTypeID(void);
  63
  64 /* encoding will be used both to interpret the bytes of URLBytes, and to */
  65 /* interpret any percent-escapes within the bytes. */
  66 CF_EXPORT
  67 CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator, const UInt8 *URLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL);
  68
  69 /* Escapes any character that is not 7-bit ASCII with the byte-code */
  70 /* for the given encoding.  If escapeWhitespace is true, whitespace */
  71 /* characters (' ', '\t', '\r', '\n') will be escaped also (desirable */
  72 /* if embedding the URL into a larger text stream like HTML) */
  73 CF_EXPORT
  74 CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace);
  75
  76 /* Any escape sequences in URLString will be interpreted via UTF-8. */
  77 CF_EXPORT
  78 CFURLRef CFURLCreateWithString(CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL);
  79
  80 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
  81
  82 /* Create an absolute URL directly, without requiring the extra step */
  83 /* of calling CFURLCopyAbsoluteURL().  If useCompatibilityMode is  */
  84 /* true, the rules historically used on the web are used to resolve */
  85 /* relativeString against baseURL - these rules are generally listed */
  86 /* in the RFC as optional or alternate interpretations.  Otherwise, */
  87 /* the strict rules from the RFC are used.  The major differences are */
  88 /* that in compatibility mode, we are lenient of the scheme appearing */
  89 /* in relative portion, leading "../" components are removed from the */
  90 /* final URL's path, and if the relative portion contains only */
  91 /* resource specifier pieces (query, parameters, and fragment), then */
  92 /* the last path component of the base URL will not be deleted  */
  93 CF_EXPORT
  94 CFURLRef CFURLCreateAbsoluteURLWithBytes(CFAllocatorRef alloc, const UInt8 *relativeURLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL, Boolean useCompatibilityMode) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
  95 #endif
  96
  97 /* filePath should be the URL's path expressed as a path of the type */
  98 /* fsType.  If filePath is not absolute, the resulting URL will be */
  99 /* considered relative to the current working directory (evaluated */
 100 /* at creation time).  isDirectory determines whether filePath is */
 101 /* treated as a directory path when resolving against relative path */
 102 /* components */
 103 CF_EXPORT
 104 CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
 105
 106 CF_EXPORT
 107 CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory);
 108
 109 /* The path style of the baseURL must match the path style of the relative */
 110 /* url or the results are undefined.  If the provided filePath looks like an */
 111 /* absolute path ( starting with '/' if pathStyle is kCFURLPosixPathStyle, */
 112 /* not starting with ':' for kCFURLHFSPathStyle, or starting with what looks */
 113 /* like a drive letter and colon for kCFURLWindowsPathStyle ) then the baseURL */
 114 /* is ignored. */
 115 CF_EXPORT
 116 CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL);
 117
 118 CF_EXPORT
 119 CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory, CFURLRef baseURL);
 120
 121 /* Fills buffer with the file system's native representation of */
 122 /* url's path. No more than maxBufLen bytes are written to buffer. */
 123 /* The buffer should be at least the maximum path length for */
 124 /* the file system in question to avoid failures for insufficiently */
 125 /* large buffers.  If resolveAgainstBase is true, the url's relative */
 126 /* portion is resolved against its base before the path is computed. */
 127 /* Returns success or failure. */
 128 CF_EXPORT
 129 Boolean CFURLGetFileSystemRepresentation(CFURLRef url, Boolean resolveAgainstBase, UInt8 *buffer, CFIndex maxBufLen);
 130
 131 /* Creates a new URL by resolving the relative portion of relativeURL against its base. */
 132 CF_EXPORT
 133 CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
 134
 135 /* Returns the URL's string. */
 136 CF_EXPORT
 137 CFStringRef CFURLGetString(CFURLRef anURL);
 138
 139 /* Returns the base URL if it exists */
 140 CF_EXPORT
 141 CFURLRef CFURLGetBaseURL(CFURLRef anURL);
 142
 143 /*
 144 All URLs can be broken into two pieces - the scheme (preceding the
 145 first colon) and the resource specifier (following the first colon).
 146 Most URLs are also "standard" URLs conforming to RFC 1808 (available
 147 from www.w3c.org).  This category includes URLs of the file, http,
 148 https, and ftp schemes, to name a few.  Standard URLs start the
 149 resource specifier with two slashes ("//"), and can be broken into
 150 four distinct pieces - the scheme, the net location, the path, and
 151 further resource specifiers (typically an optional parameter, query,
 152 and/or fragment).  The net location appears immediately following
 153 the two slashes and goes up to the next slash; it's format is
 154 scheme-specific, but is usually composed of some or all of a username,
 155 password, host name, and port.  The path is a series of path components
 156 separated by slashes; if the net location is present, the path always
 157 begins with a slash.  Standard URLs can be relative to another URL,
 158 in which case at least the scheme and possibly other pieces as well
 159 come from the base URL (see RFC 1808 for precise details when resolving
 160 a relative URL against its base).  The full URL is therefore
 161
 162 <scheme> "://" <net location> <path, always starting with slash> <add'l resource specifiers>
 163
 164 If a given CFURL can be decomposed (that is, conforms to RFC 1808), you
 165 can ask for each of the four basic pieces (scheme, net location, path,
 166 and resource specifer) separately, as well as for its base URL.  The
 167 basic pieces are returned with any percent escape sequences still in
 168 place (although note that the scheme may not legally include any
 169 percent escapes); this is to allow the caller to distinguish between
 170 percent sequences that may have syntactic meaning if replaced by the
 171 character being escaped (for instance, a '/' in a path component).
 172 Since only the individual schemes know which characters are
 173 syntactically significant, CFURL cannot safely replace any percent
 174 escape sequences.  However, you can use
 175 CFURLCreateStringByReplacingPercentEscapes() to create a new string with
 176 the percent escapes removed; see below.
 177
 178 If a given CFURL can not be decomposed, you can ask for its scheme and its
 179 resource specifier; asking it for its net location or path will return NULL.
 180
 181 To get more refined information about the components of a decomposable
 182 CFURL, you may ask for more specific pieces of the URL, expressed with
 183 the percent escapes removed.  The available functions are CFURLCopyHostName(),
 184 CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(),
 185 CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and
 186 CFURLCopyFragment().  Because the parameters, query, and fragment of an
 187 URL may contain scheme-specific syntaxes, these methods take a second
 188 argument, giving a list of characters which should NOT be replaced if
 189 percent escaped.  For instance, the ftp parameter syntax gives simple
 190 key-value pairs as "<key>=<value>;"  Clearly if a key or value includes
 191 either '=' or ';', it must be escaped to avoid corrupting the meaning of
 192 the parameters, so the caller may request the parameter string as
 193
 194 CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%"));
 195
 196 requesting that all percent escape sequences be replaced by the represented
 197 characters, except for escaped '=', '%' or ';' characters.  Pass the empty
 198 string (CFSTR("")) to request that all percent escapes be replaced, or NULL
 199 to request that none be.
 200 */
 201
 202 /* Returns true if anURL conforms to RFC 1808 */
 203 CF_EXPORT
 204 Boolean CFURLCanBeDecomposed(CFURLRef anURL);
 205
 206 /* The next several methods leave any percent escape sequences intact */
 207
 208 CF_EXPORT
 209 CFStringRef CFURLCopyScheme(CFURLRef anURL);
 210
 211 /* NULL if CFURLCanBeDecomposed(anURL) is false */
 212 CF_EXPORT
 213 CFStringRef CFURLCopyNetLocation(CFURLRef anURL);
 214
 215 /* NULL if CFURLCanBeDecomposed(anURL) is false; also does not resolve the URL */
 216 /* against its base.  See also CFURLCopyAbsoluteURL().  Note that, strictly */
 217 /* speaking, any leading '/' is not considered part of the URL's path, although */
 218 /* its presence or absence determines whether the path is absolute. */
 219 /* CFURLCopyPath()'s return value includes any leading slash (giving the path */
 220 /* the normal POSIX appearance); CFURLCopyStrictPath()'s return value omits any */
 221 /* leading slash, and uses isAbsolute to report whether the URL's path is absolute. */
 222
 223 /* CFURLCopyFileSystemPath() returns the URL's path as a file system path for the */
 224 /* given path style.  All percent escape sequences are replaced.  The URL is not */
 225 /* resolved against its base before computing the path. */
 226 CF_EXPORT
 227 CFStringRef CFURLCopyPath(CFURLRef anURL);
 228
 229 CF_EXPORT
 230 CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
 231
 232 CF_EXPORT
 233 CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
 234
 235 /* Returns whether anURL's path represents a directory */
 236 /* (true returned) or a simple file (false returned) */
 237 CF_EXPORT
 238 Boolean CFURLHasDirectoryPath(CFURLRef anURL);
 239
 240 /* Any additional resource specifiers after the path.  For URLs */
 241 /* that cannot be decomposed, this is everything except the scheme itself. */
 242 CF_EXPORT
 243 CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL);
 244
 245 CF_EXPORT
 246 CFStringRef CFURLCopyHostName(CFURLRef anURL);
 247
 248 CF_EXPORT
 249 SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */
 250
 251 CF_EXPORT
 252 CFStringRef CFURLCopyUserName(CFURLRef anURL);
 253
 254 CF_EXPORT
 255 CFStringRef CFURLCopyPassword(CFURLRef anURL);
 256
 257 /* These remove all percent escape sequences except those for */
 258 /* characters in charactersToLeaveEscaped.  If charactersToLeaveEscaped */
 259 /* is empty (""), all percent escape sequences are replaced by their */
 260 /* corresponding characters.  If charactersToLeaveEscaped is NULL, */
 261 /* then no escape sequences are removed at all */
 262 CF_EXPORT
 263 CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 264
 265 CF_EXPORT
 266 CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 267
 268 CF_EXPORT
 269 CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 270
 271 CF_EXPORT
 272 CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
 273
 274 CF_EXPORT
 275 CFStringRef CFURLCopyPathExtension(CFURLRef url);
 276
 277 /* These functions all treat the base URL of the supplied url as */
 278 /* invariant.  In other words, the URL returned will always have */
 279 /* the same base as the URL supplied as an argument. */
 280
 281 CF_EXPORT
 282 CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
 283
 284 CF_EXPORT
 285 CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
 286
 287 CF_EXPORT
 288 CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
 289
 290 CF_EXPORT
 291 CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
 292
 293 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 294 /* Fills buffer with the bytes for url, returning the number of bytes */
 295 /* filled.  If buffer is of insufficient size, returns -1 and no bytes */
 296 /* are placed in buffer.  If buffer is NULL, the needed length is */
 297 /* computed and returned.  The returned bytes are the original bytes */
 298 /* from which the URL was created; if the URL was created from a */
 299 /* string, the bytes will be the bytes of the string encoded via UTF-8  */
 300 CF_EXPORT
 301 CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 302
 303 enum {
 304         kCFURLComponentScheme = 1,
 305         kCFURLComponentNetLocation = 2,
 306         kCFURLComponentPath = 3,
 307         kCFURLComponentResourceSpecifier = 4,
 308
 309         kCFURLComponentUser = 5,
 310         kCFURLComponentPassword = 6,
 311         kCFURLComponentUserInfo = 7,
 312         kCFURLComponentHost = 8,
 313         kCFURLComponentPort = 9,
 314         kCFURLComponentParameterString = 10,
 315         kCFURLComponentQuery = 11,
 316         kCFURLComponentFragment = 12
 317 };
 318 typedef CFIndex CFURLComponentType;
 319
 320 /*
 321 Gets the  range of the requested component in the bytes of url, as
 322 returned by CFURLGetBytes().  This range is only good for use in the
 323 bytes returned by CFURLGetBytes!
 324
 325 If non-NULL, rangeIncludingSeparators gives the range of component
 326 including the sequences that separate component from the previous and
 327 next components.  If there is no previous or next component, that end of
 328 rangeIncludingSeparators will match the range of the component itself.
 329 If url does not contain the given component type, (kCFNotFound, 0) is
 330 returned, and rangeIncludingSeparators is set to the location where the
 331 component would be inserted.  Some examples -
 332
 333 For the URL http://www.apple.com/hotnews/
 334
 335 Component           returned range      rangeIncludingSeparators
 336 scheme              (0, 4)              (0, 7)
 337 net location        (7, 13)             (4, 16)
 338 path                (20, 9)             (20, 9)
 339 resource specifier  (kCFNotFound, 0)    (29, 0)
 340 user                (kCFNotFound, 0)    (7, 0)
 341 password            (kCFNotFound, 0)    (7, 0)
 342 user info           (kCFNotFound, 0)    (7, 0)
 343 host                (7, 13)             (4, 16)
 344 port                (kCFNotFound, 0)    (20, 0)
 345 parameter           (kCFNotFound, 0)    (29, 0)
 346 query               (kCFNotFound, 0)    (29, 0)
 347 fragment            (kCFNotFound, 0)    (29, 0)
 348
 349
 350 For the URL ./relPath/file.html#fragment
 351
 352 Component           returned range      rangeIncludingSeparators
 353 scheme              (kCFNotFound, 0)    (0, 0)
 354 net location        (kCFNotFound, 0)    (0, 0)
 355 path                (0, 19)             (0, 20)
 356 resource specifier  (20, 8)             (19, 9)
 357 user                (kCFNotFound, 0)    (0, 0)
 358 password            (kCFNotFound, 0)    (0, 0)
 359 user info           (kCFNotFound, 0)    (0, 0)
 360 host                (kCFNotFound, 0)    (0, 0)
 361 port                (kCFNotFound, 0)    (0, 0)
 362 parameter           (kCFNotFound, 0)    (19, 0)
 363 query               (kCFNotFound, 0)    (19, 0)
 364 fragment            (20, 8)             (19, 9)
 365
 366
 367 For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment
 368
 369 Component           returned range      rangeIncludingSeparators
 370 scheme              (0, 6)              (0, 9)
 371 net location        (9, 16)             (6, 19)
 372 path                (25, 21)            (25, 22)
 373 resource specifier  (47, 21)            (46, 22)
 374 user                (9, 4)              (6, 8)
 375 password            (14, 4)             (13, 6)
 376 user info           (9, 9)              (6, 13)
 377 host                (19, 4)             (18, 6)
 378 port                (24, 1)             (23, 2)
 379 parameter           (47, 6)             (46, 8)
 380 query               (54, 5)             (53, 7)
 381 fragment            (60, 8)             (59, 9)
 382 */
 383 CF_EXPORT
 384 CFRange CFURLGetByteRangeForComponent(CFURLRef url, CFURLComponentType component, CFRange *rangeIncludingSeparators) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 385 #endif
 386
 387 /* Returns a string with any percent escape sequences that do NOT */
 388 /* correspond to characters in charactersToLeaveEscaped with their */
 389 /* equivalent.  Returns NULL on failure (if an invalid percent sequence */
 390 /* is encountered), or the original string (retained) if no characters */
 391 /* need to be replaced. Pass NULL to request that no percent escapes be */
 392 /* replaced, or the empty string (CFSTR("")) to request that all percent */
 393 /* escapes be replaced.  Uses UTF8 to interpret percent escapes. */
 394 CF_EXPORT
 395 CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
 396
 397 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 398 /* As above, but allows you to specify the encoding to use when interpreting percent escapes */
 399 CF_EXPORT
 400 CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding(CFAllocatorRef allocator, CFStringRef origString, CFStringRef charsToLeaveEscaped, CFStringEncoding encoding) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
 401 #endif
 402
 403 /* Creates a copy or originalString, replacing certain characters with */
 404 /* the equivalent percent escape sequence based on the encoding specified. */
 405 /* If the originalString does not need to be modified (no percent escape */
 406 /* sequences are missing), may retain and return originalString. */
 407 /* If you are uncertain of the correct encoding, you should use UTF-8, */
 408 /* which is the encoding designated by RFC 2396 as the correct encoding */
 409 /* for use in URLs.  The characters so escaped are all characters that */
 410 /* are not legal URL characters (based on RFC 2396), plus any characters */
 411 /* in legalURLCharactersToBeEscaped, less any characters in */
 412 /* charactersToLeaveUnescaped.  To simply correct any non-URL characters */
 413 /* in an otherwise correct URL string, do: */
 414
 415 /* newString = CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, origString, NULL, NULL, kCFStringEncodingUTF8); */
 416 CF_EXPORT
 417 CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding);
 418
 419
 420 /* Returns a file reference URL, a path-idependent form of file URL. */
 421 /* Converts a file path URL if necessary. For non-file URLs, returns NULL. */
 422 /* Also returns NULL when the conversion fails because the target resource doesn't exist. */
 423 /* Optional output error: The error is set to a valid CFErrorRef when the function */
 424 /* result is NULL. A valid output error must be released by the caller. */
 425 CF_EXPORT
 426 CFURLRef CFURLCreateFileReferenceURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 427
 428
 429 /* Returns a file path URL, converting a file reference URL if necessary. */
 430 /* For non-file URLs, returns NULL. Also returns NULL when the conversion fails */
 431 /* because the target resource doesn't exist. */
 432 /* Optional output error: The error is set to a valid CFErrorRef when the function */
 433 /* result is NULL. A valid output error must be released by the caller. */
 434 CF_EXPORT
 435 CFURLRef CFURLCreateFilePathURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 436
 437
 438
 439
 440 #if TARGET_OS_MAC
 441
 442 /* The following APIs provide efficient access to resource properties. Properties
 443 are identified by keys, and values are represented as Core Foundation objects. The
 444 type of each value is fixed for each property, e.g. the modification date is a CFDateRef,
 445 the file size is a CFNumberRef.
 446
 447 Values are fetched on-demand, synchronously, from the resource's backing store. They
 448 are cached and reused when fetched again through the same URL instance, until the
 449 client clears the value. The client has complete control over the cache lifetime.
 450
 451 Some resource property values can be changed, given sufficient access permission to the resource.
 452 When a resource property value is set, the change is written to backing store synchronously.
 453 */
 454
 455 /* Assigns the requested resource property value to the typeRefValuePtr output */
 456 /* argument. Returns true if the output value was set. Note that NULL is a valid output value. */
 457 /* The value is fetched synchronously from the resource backing store only if a value is not */
 458 /* already cached. The type of the output value type varies by property (see property key */
 459 /* definitions). Returns false if an error occurs. Optional output error: the error is set to */
 460 /* a valid CFErrorRef when the function returns false. A valid output error must be */
 461 /* released by the caller. */
 462 CF_EXPORT
 463 Boolean CFURLCopyResourcePropertyForKey(CFURLRef url, CFStringRef key, void *propertyValueTypeRefPtr, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 464
 465
 466 /* Returns any number of resource property values as a dictionary of keyed values. */
 467 /* The requested values are specified as an array of keys to appear in */
 468 /* the result dictionary. Values are fetched synchronously from the resource backing store unless */
 469 /* already cached. The type of each value type varies (see key definitions, below). */
 470 /* Returns an empty dictionary if no values are found. Returns NULL when an error occurs. */
 471 /* Optional output error: the error is set to a valid CFErrorRef when the */
 472 /* function returns NULL. A valid output error must be released by the caller. */
 473 CF_EXPORT
 474 CFDictionaryRef CFURLCopyResourcePropertiesForKeys(CFURLRef url, CFArrayRef keys, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 475
 476
 477 /* Changes a resource property value. Synchronously writes the value to the resource backing */
 478 /* store. The input value type must be a valid CFTypeRef, of the type required for the specified */
 479 /* key (see key definitions). Returns true upon success, false when an error occurs. */
 480 /* Optional output error: the error is set to a valid CFErrorRef when the function */
 481 /* returns false. A valid output error must be released by the caller. */
 482 /* Note that some values are read-only. Attempting to set a read-only property */
 483 /* results in an error. */
 484 CF_EXPORT
 485 Boolean CFURLSetResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertValue, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 486
 487
 488 /* Changes any number of resource property values, specified as a dictionary of keyed values. */
 489 /* Synchronously writes values to the resource backing store. The input dictionary's value types must conform */
 490 /* to the type required for its key (see key definitions). Returns true when all values are set successfully, */
 491 /* and false if an error occurs. Optional output error: the error is set to a valid CFErrorRef when the function returns */
 492 /* false. A valid output error must be released by the caller. When an error occurs after some properties have been */
 493 /* successfully changed, the user dictionary in the error contains an array of keys that */
 494 /* were not set. Note that some values are read-only. Attempting to set a read-only value */
 495 /* results in an error. */
 496 CF_EXPORT
 497 Boolean CFURLSetResourcePropertiesForKeys(CFURLRef url, CFDictionaryRef keyedPropertyValues, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 498
 499
 500 /* Discards a cached property value for a specific key */
 501 CF_EXPORT
 502 void CFURLClearResourcePropertyCacheForKey(CFURLRef url, CFStringRef key) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 503
 504
 505 /* Discards all cached property values */
 506 CF_EXPORT
 507 void CFURLClearResourcePropertyCache(CFURLRef url) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 508
 509
 510 /* Sets a temporary property value. Temporary properties exist only in memory and are never */
 511 /* written to resource backing store. Once set, a temporary property value can be fetched */
 512 /* with CFURLCopyResourcePropertyForKey and CFURLCopyResourcePropertiesForKeys. Temporary property */
 513 /* values are for client use. Values must be valid Core Foundation types, and will be retained. */
 514 /* To remove a temporary property value, use CFURLClearResourcePropertyCacheForKey. */
 515 CF_EXPORT
 516 void CFURLSetTemporaryResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertyValue) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 517
 518
 519 /* Synchronously checks if the resource's backing store is reachable and the resource exists, */
 520 /* returning true if so. The optional output error can be used to determine the type of reachability */
 521 /* failure (e.g., file not found, network error, etc.). The error is set to a valid CFErrorRef if */
 522 /* and only if the function returns false. A valid output error must be released by */
 523 /* the caller. Checking for resource existence and reachability is appropriate when making decisions */
 524 /* that do not require other immediate operations on the resource. An example would be */
 525 /* periodic maintenance of UI state that depends on the existence of a particular document. */
 526 /* When performing an operation such as opening a file, it is more efficient to */
 527 /* simply try the operation and handle failures than to check first for reachability. */
 528 CF_EXPORT
 529 Boolean CFURLResourceIsReachable(CFURLRef url, CFErrorRef *error) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 530
 531
 532 /* Properties of File System Resources */
 533
 534 CF_EXPORT
 535 const CFStringRef kCFURLNameKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 536     /* The resource name provided by the file system (value type CFString) */
 537
 538 CF_EXPORT
 539 const CFStringRef kCFURLLocalizedNameKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 540     /* Localized or extension-hidden name as displayed to users (Read-only, value type CFString) */
 541
 542 CF_EXPORT
 543 const CFStringRef kCFURLIsRegularFileKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 544     /* True for regular files (Read-only, value type CFBoolean) */
 545
 546 CF_EXPORT
 547 const CFStringRef kCFURLIsDirectoryKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 548     /* True for directories (Read-only, CFBoolean) */
 549
 550 CF_EXPORT
 551 const CFStringRef kCFURLIsSymbolicLinkKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 552     /* True for symlinks (Read-only, value type CFBoolean) */
 553
 554 CF_EXPORT
 555 const CFStringRef kCFURLIsVolumeKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 556     /* True for the root directory of a volume (Read-only, value type CFBoolean) */
 557
 558 CF_EXPORT
 559 const CFStringRef kCFURLIsPackageKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 560     /* True for packaged directories (value type CFBoolean) */
 561
 562 CF_EXPORT
 563 const CFStringRef kCFURLIsSystemImmutableKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 564     /* True for system-immutable resources (value type CFBoolean) */
 565
 566 CF_EXPORT
 567 const CFStringRef kCFURLIsUserImmutableKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 568     /* True for user-immutable resources (value type CFBoolean) */
 569
 570 CF_EXPORT
 571 const CFStringRef kCFURLIsHiddenKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 572     /* True for resources normally hidden from users (value type CFBoolean) */
 573
 574 CF_EXPORT
 575 const CFStringRef kCFURLHasHiddenExtensionKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 576     /* True for resources whose filename extension is hiden (value type CFBoolean) */
 577
 578 CF_EXPORT
 579 const CFStringRef kCFURLCreationDateKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 580     /* Value type CFDate */
 581
 582 CF_EXPORT
 583 const CFStringRef kCFURLContentAccessDateKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 584     /* Value type CFDate */
 585
 586 CF_EXPORT
 587 const CFStringRef kCFURLContentModificationDateKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 588     /* Value type CFDate */
 589
 590 CF_EXPORT
 591 const CFStringRef kCFURLAttributeModificationDateKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 592     /* Value type CFDate */
 593
 594 CF_EXPORT
 595 const CFStringRef kCFURLLinkCountKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 596     /* Number of hard links to the resource (Read-only, CFNumber) */
 597
 598 CF_EXPORT
 599 const CFStringRef kCFURLParentDirectoryURLKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 600     /* URL of the parent directory, if any (Read-only, value type CFURL) */
 601
 602 CF_EXPORT
 603 const CFStringRef kCFURLVolumeURLKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 604     /* URL of the volume on which the resource is stored (Read-only, value type CFURL) */
 605
 606 CF_EXPORT
 607 const CFStringRef kCFURLTypeIdentifierKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 608     /* Uniform type identifier for the resource (Read-only, value type CFString) */
 609
 610 CF_EXPORT
 611 const CFStringRef kCFURLLocalizedTypeDescriptionKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 612     /* User-visible type or "kind" descriptiopn (Read-only, value type CFString) */
 613
 614 CF_EXPORT
 615 const CFStringRef kCFURLLabelNumberKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 616     /* The label number assigned to the resource (value type CFNumber) */
 617
 618 CF_EXPORT
 619 const CFStringRef kCFURLLabelColorKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 620     /* The color of the assigned label (Read-only, value type CGColorRef, must link with Application Services) */
 621
 622 CF_EXPORT
 623 const CFStringRef kCFURLLocalizedLabelKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 624     /* The user-visible label text (Read-only, value type CFString) */
 625
 626 CF_EXPORT
 627 const CFStringRef kCFURLEffectiveIconKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 628     /* The icon normally displayed for the resource (Read-only, value type CGImageRef, must link with Application Services) */
 629
 630 CF_EXPORT
 631 const CFStringRef kCFURLCustomIconKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 632     /* The custom icon assigned to the resource, if any (value type CGImageRef, must link with Application Services) */
 633
 634
 635 /* File Properties */
 636
 637 CF_EXPORT
 638 const CFStringRef kCFURLFileSizeKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 639     /* Total file size, in bytes (Read-only, value type CFNumber) */
 640
 641 CF_EXPORT
 642 const CFStringRef kCFURLFileAllocatedSizeKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 643     /* Total size of blocks allocated (Read-only, value type CFNumber) */
 644
 645 CF_EXPORT
 646 const CFStringRef kCFURLIsAliasFileKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 647 /*  true if the url is a Finder alias file, false otherwise ( Read-only, value type CFBooleanRef) */
 648
 649
 650 /* Volume Properties */
 651
 652 /* For convenience, volume properties may be requested from any resource on a volume. */
 653
 654 CF_EXPORT
 655 const CFStringRef kCFURLVolumeLocalizedFormatDescriptionKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 656     /* The user-visible volume format (Read-only, value type CFString) */
 657
 658 CF_EXPORT
 659 const CFStringRef kCFURLVolumeTotalCapacityKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 660     /* Total volume capacity in bytes (Read-only, value type CFNumber) */
 661
 662 CF_EXPORT
 663 const CFStringRef kCFURLVolumeAvailableCapacityKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 664     /* Total free space, in bytes (Read-only, value type CFNumber) */
 665
 666 CF_EXPORT
 667 const CFStringRef kCFURLVolumeResourceCountKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 668     /* Total number of resources on the volume (Read-only, value type CFNumber) */
 669
 670 CF_EXPORT
 671 const CFStringRef kCFURLVolumeSupportsPersistentIDsKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 672     /* Read-only, value type CFBoolean */
 673
 674 CF_EXPORT
 675 const CFStringRef kCFURLVolumeSupportsSymbolicLinksKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 676     /* Read-only, value type CFBoolean */
 677
 678 CF_EXPORT
 679 const CFStringRef kCFURLVolumeSupportsHardLinksKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 680     /* Read-only, value type CFBoolean */
 681
 682 CF_EXPORT
 683 const CFStringRef kCFURLVolumeSupportsJournalingKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 684     /* Read-only, value type CFBoolean */
 685
 686 CF_EXPORT
 687 const CFStringRef kCFURLVolumeIsJournalingKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 688     /* Read-only, value type CFBoolean */
 689
 690 CF_EXPORT
 691 const CFStringRef kCFURLVolumeSupportsSparseFilesKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 692     /* Read-only, value type CFBoolean */
 693
 694 CF_EXPORT
 695 const CFStringRef kCFURLVolumeSupportsZeroRunsKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 696     /* Read-only, value type CFBoolean */
 697
 698 CF_EXPORT
 699 const CFStringRef kCFURLVolumeSupportsCaseSensitiveNamesKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 700     /* Read-only, value type CFBoolean */
 701
 702 CF_EXPORT
 703 const CFStringRef kCFURLVolumeSupportsCasePreservedNamesKey AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 704     /* Read-only, value type CFBoolean */
 705
 706 enum {
 707     kCFURLBookmarkCreationPreferFileIDResolutionMask = ( 1UL << 8 ),  // At resolution time, this alias will prefer resolving by the embedded fileID to the path
 708     kCFURLBookmarkCreationMinimalBookmarkMask = ( 1UL << 9 ), // Creates a bookmark with "less" information, which may be smaller but still be able to resolve in certain ways
 709     kCFURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), // includes in the created bookmark those properties which are needed for a bookmark/alias file
 710 };
 711 typedef CFOptionFlags CFURLBookmarkCreationOptions;
 712
 713 enum  {
 714     kCFBookmarkResolutionWithoutUIMask = ( 1UL << 8 ),          // don't perform any UI during bookmark resolution
 715     kCFBookmarkResolutionWithoutMountingMask = ( 1UL << 9 ),    // don't mount a volume during bookmark resolution
 716 };
 717 typedef CFOptionFlags CFURLBookmarkResolutionOptions;
 718
 719 typedef CFOptionFlags CFURLBookmarkFileCreationOptions;
 720
 721 /*      @function CFURLCreateBookmarkData
 722         @discussion     Create a CFDataRef containing an externalizable representation from a CFURLRef, modified with the given options, including ( at the minimum ) any
 723                 properties in the propertiesToInclude array which are retrievable from the given url.
 724         @param  allocator               the CFAllocator to use to create this object
 725         @param  url     the CFURLRef to create a bookmark data from.
 726         @param  options a set of options which control creation of the bookmark data
 727         @param resourcePropertiesToInclude      If non-NULL, an CFArrayRef of additional properties copied from the url to include in the created bookmark data.
 728         @param relativeToURL If non-NULL, the created bookmark will be relative to the given url
 729         @param error    If non-NULL, on exit will be filled in with a CFErrorRef representing any error which occured during creation of the bookmark data
 730         @result A CFDataRef containing an data, which can be later be passed to CFURLCreateByResolvingBookmarkData() or to CFURLCopyPropertiesForKeysFromBookmarkData() / CFURLCopyPropertyForKeyFromBookmarkData() */
 731 CFDataRef CFURLCreateBookmarkData ( CFAllocatorRef allocator, CFURLRef url, CFURLBookmarkCreationOptions options, CFArrayRef resourcePropertiesToInclude, CFURLRef relativeToURL, CFErrorRef* error ) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 732
 733 /*      @function CFURLCreateByResolvingBookmarkData
 734         @discussion Given a CFDataRef created with CFURLCreateBookmarkRepresentation(), return a CFURLRef of the item it was a bookmark to, and
 735                 attempt to pre-cache those properties in propertiesToInclude in the resulting url.  If in the process of resolving the bookmark into the CFURLRef
 736                 it points to this determines that  some properties in the bookmark are out of date or not correct for the item it resolves to, set *isStale to YES,
 737                 which the client may want to use to decide to make a new bookmark from the returned item and replace the saved bookmark it has.  If the bookmarked
 738                 item cannot be found, return NULL.  If an error ( other than "original item can not be found" ) occurs during the process, return NULL and fill in error )
 739         @param  allocator        the CFAllocator to use to create this object
 740         @param   bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData
 741         @param  options options which affect the resolution
 742         @param relativeToURL If non-NULL, and if the bookmark was created relative to another url, then resolve it relative to this url
 743         @param resourcePropertiesToInclude If non-NULL, a CFArray containing those properties which the caller would like to already be cached on the given url
 744         @param isStale If non-NULL, on exit will be set to true if during resolution any of the properties in the bookmark no longer seemed to match the
 745                 corresponding properties on the returned file.  Clients, upon seeing a stale representation, may want to replace whatever stored bookmark data they
 746                 have saved and create a new one.
 747         @param error    If non-NULL, on exit will be filled in with a CFErrorRef representing any error which occured during resolution of the bookmark data
 748         @result A CFURLRef of a file which is the closest match to the file the bookmark data */
 749 CFURLRef CFURLCreateByResolvingBookmarkData ( CFAllocatorRef allocator, CFDataRef bookmark, CFURLBookmarkResolutionOptions options, CFURLRef relativeToURL, CFArrayRef resourcePropertiesToInclude, Boolean* isStale, CFErrorRef* error ) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 750
 751 /*      @function       CFURLCreatePropertiesForKeysFromBookmarkData
 752         @discussion     Given a bookmark, return a dictionary of properties ( all properties if propertiesToReturn == NULL ).
 753                                 This returns only the properties stored within the bookmark and will not attempt to resolve the bookmark or do i/o.
 754         @param  allocator        the CFAllocator to use to create this object
 755         @param   bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData
 756         @param  propertiesToReturn a CFArrayRef of the properties of the bookmark data which the client would like returned.
 757         @result a CFDictionaryRef containing the values for the properties passed in obtained from the bookmark data ( not by attempting to resolve it or do i/o in any way ) */
 758 CFDictionaryRef CFURLCreateResourcePropertiesForKeysFromBookmarkData ( CFAllocatorRef allocator, CFArrayRef resourcePropertiesToReturn, CFDataRef bookmark ) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 759
 760 /*      @function       CFURLCreatePropertyForKeyFromBookmarkData
 761         @discussion     Given a bookmark, return the value for a given property from the bookmark data
 762                                 This returns only the properties stored within the bookmark and will not attempt to resolve the bookmark or do i/o.
 763         @param  allocator        the CFAllocator to use to create this object
 764         @param   bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData
 765         @param  propertyKey the property key to return.
 766         @result a CFTypeRef value for the property passed in obtained from the bookmark data ( not by attempting to resolve it or do i/o in any way ) */
 767 CFTypeRef  CFURLCreateResourcePropertyForKeyFromBookmarkData( CFAllocatorRef allocator, CFStringRef resourcePropertyKey, CFDataRef bookmark ) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;
 768
 769 /*!     @function       CFURLCreateBookmarkDataFromFile
 770         @description    Given a fileURL of a file which is a Finder "alias" file, return a CFDataRef with the bookmark data from the file.  If urlRef points to an alias file
 771                         created before SnowLeopard which contains Alias Manager information and no bookmark data, then a CFDataRef will be synthesized which contains
 772                         a approximation of the alias information in a format which can be used to resolve the bookmark.  If an error prevents reading the data or
 773                         if it is corrupt, NULL will be returned and error will be filled in if errorRef is non-NULL.
 774         @param  allocator the CFAllocator to use to create this object
 775         @param  fileURL a CFURLRef to to the alias file to create the bookmark data from
 776         @param  errorRef    if non-NULL, on exit will be filled in with a CFErrorRef representing any error which occurred during the creation of the bookmark data from the file
 777         @result A CFDataRef containing bookmark data, or NULL if there was an error creating bookmark data from the file, such as if the file is not an alias file.
 778  */
 779 CFDataRef CFURLCreateBookmarkDataFromFile(CFAllocatorRef allocator, CFURLRef fileURL, CFErrorRef *errorRef );
 780
 781 /*!     @function       CFURLWriteBookmarkDataToFile
 782         @description    Given a created bookmarkData object, create a new Finder "alias" file at fileURL which contains the bookmark data.  If fileURL is a url to a directory, an alias file
 783                         will be created with the same name as the bookmarked item and a ".alias" extension.  If fileURL is a url for a file and it exists it will be overwritten.  If a
 784                         .alias extension is not present it will be added.  In addition to the bookmark data, sufficient pre-SnowLeopard alias data will added to the file to allow
 785                         systems running something before SnowLeopard to resolve this file using Alias Manager routines and get back the same file as the bookmark routines.
 786                         The bookmark data must have been created with the kCFURLBookmarkCreationSuitableForBookmarkFile option and an error will be returned if not.
 787         @param  allocator        the CFAllocator to use to create this object
 788         @param   bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData
 789         @param  options options flags
 790         @param  errorRef    if non-NULL, on exit will be filled in with a CFErrorRef representing any error which occurred during the creation of the alias file
 791  */
 792 Boolean CFURLWriteBookmarkDataToFile( CFDataRef bookmarkRef, CFURLRef fileURL, CFURLBookmarkFileCreationOptions options, CFErrorRef *errorRef );
 793
 794 /*!     @function       CFURLCreateBookmarkDataFromAliasRecord
 795         @discussion     Create a CFDataRef containing bookmarkdata by converting the alias data in aliasRecordDataRef, which should be the contents of an AliasRecord copied into a CFDataRef object.
 796                 The created bookmarkdata can be passed into CFURLCreateByResolvingBookmarkData() to resolve the item into a CFURLRef, or a small set of information can be returned from
 797                 CFURLCreateResourcePropertiesForKeysFromBookmarkData() / CFURLCreateResourcePropertyForKeyFromBookmarkData().
 798                 @param  allocator               the CFAllocator to use to create this object
 799                 @param  aliasRecordDataRef      the contents of an AliasRecord to create bookmark data for
 800                 @result A CFDataRef containing an data, which can be later be passed to CFURLCreateByResolvingBookmarkData() or to CFURLCopyPropertiesForKeysFromBookmarkData() / CFURLCopyPropertyForKeyFromBookmarkData()
 801  */
 802 CFDataRef CFURLCreateBookmarkDataFromAliasRecord ( CFAllocatorRef allocatorRef, CFDataRef aliasRecordDataRef );
 803
 804 #endif /* TARGET_OS_MAC */
 805
 806 CF_EXTERN_C_END
 807
 808 #endif /* ! __COREFOUNDATION_CFURL__ */
 809