CFURL.h

   1 /*
   2  * Copyright (c) 2015 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-2014, 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_IMPLICIT_BRIDGING_ENABLED
  37 CF_EXTERN_C_BEGIN
  38
  39 typedef CF_ENUM(CFIndex, CFURLPathStyle) {
  40     kCFURLPOSIXPathStyle = 0,
  41     kCFURLHFSPathStyle CF_ENUM_DEPRECATED(10_0, 10_9, 2_0, 7_0), /* The use of kCFURLHFSPathStyle is deprecated. The Carbon File Manager, which uses HFS style paths, is deprecated. HFS style paths are unreliable because they can arbitrarily refer to multiple volumes if those volumes have identical volume names. You should instead use kCFURLPOSIXPathStyle wherever possible. */
  42     kCFURLWindowsPathStyle
  43 };
  44
  45 typedef const struct CF_BRIDGED_TYPE(NSURL) __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 /* Using a string encoding which isn't a superset of ASCII encoding is not */
  67 /* supported because CFURLGetBytes and CFURLGetByteRangeForComponent require */
  68 /* 7-bit ASCII characters to be stored in a single 8-bit byte. */
  69 /* CFStringEncodings which are a superset of ASCII encoding include MacRoman, */
  70 /* WindowsLatin1, ISOLatin1, NextStepLatin, ASCII, and UTF8. */
  71 CF_EXPORT
  72 CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator, const UInt8 *URLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL);
  73
  74 /* Escapes any character that is not 7-bit ASCII with the byte-code */
  75 /* for the given encoding.  If escapeWhitespace is true, whitespace */
  76 /* characters (' ', '\t', '\r', '\n') will be escaped also (desirable */
  77 /* if embedding the URL into a larger text stream like HTML) */
  78 CF_EXPORT
  79 CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace);
  80
  81 /* Any escape sequences in URLString will be interpreted via UTF-8. */
  82 CF_EXPORT
  83 CFURLRef CFURLCreateWithString(CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL);
  84
  85 /* Create an absolute URL directly, without requiring the extra step */
  86 /* of calling CFURLCopyAbsoluteURL().  If useCompatibilityMode is  */
  87 /* true, the rules historically used on the web are used to resolve */
  88 /* relativeString against baseURL - these rules are generally listed */
  89 /* in the RFC as optional or alternate interpretations.  Otherwise, */
  90 /* the strict rules from the RFC are used.  The major differences are */
  91 /* that in compatibility mode, we are lenient of the scheme appearing */
  92 /* in relative portion, leading "../" components are removed from the */
  93 /* final URL's path, and if the relative portion contains only */
  94 /* resource specifier pieces (query, parameters, and fragment), then */
  95 /* the last path component of the base URL will not be deleted.  */
  96 /* Using a string encoding which isn't a superset of ASCII encoding is not */
  97 /* supported because CFURLGetBytes and CFURLGetByteRangeForComponent require */
  98 /* 7-bit ASCII characters to be stored in a single 8-bit byte. */
  99 /* CFStringEncodings which are a superset of ASCII encoding include MacRoman, */
 100 /* WindowsLatin1, ISOLatin1, NextStepLatin, ASCII, and UTF8. */
 101 CF_EXPORT
 102 CFURLRef CFURLCreateAbsoluteURLWithBytes(CFAllocatorRef alloc, const UInt8 *relativeURLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL, Boolean useCompatibilityMode);
 103
 104 /* filePath should be the URL's path expressed as a path of the type */
 105 /* fsType.  If filePath is not absolute, the resulting URL will be */
 106 /* considered relative to the current working directory (evaluated */
 107 /* at creation time).  isDirectory determines whether filePath is */
 108 /* treated as a directory path when resolving against relative path */
 109 /* components */
 110 CF_EXPORT
 111 CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
 112
 113 CF_EXPORT
 114 CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory);
 115
 116 /* The path style of the baseURL must match the path style of the relative */
 117 /* url or the results are undefined.  If the provided filePath looks like an */
 118 /* absolute path ( starting with '/' if pathStyle is kCFURLPosixPathStyle, */
 119 /* not starting with ':' for kCFURLHFSPathStyle, or starting with what looks */
 120 /* like a drive letter and colon for kCFURLWindowsPathStyle ) then the baseURL */
 121 /* is ignored. */
 122 CF_EXPORT
 123 CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL);
 124
 125 CF_EXPORT
 126 CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory, CFURLRef baseURL);
 127
 128 /* Fills buffer with the file system's native representation of */
 129 /* url's path. No more than maxBufLen bytes are written to buffer. */
 130 /* The buffer should be at least the maximum path length for */
 131 /* the file system in question to avoid failures for insufficiently */
 132 /* large buffers.  If resolveAgainstBase is true, the url's relative */
 133 /* portion is resolved against its base before the path is computed. */
 134 /* Returns success or failure. */
 135 CF_EXPORT
 136 Boolean CFURLGetFileSystemRepresentation(CFURLRef url, Boolean resolveAgainstBase, UInt8 *buffer, CFIndex maxBufLen);
 137
 138 /* Creates a new URL by resolving the relative portion of relativeURL against its base. */
 139 CF_EXPORT
 140 CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
 141
 142 /* Returns the URL's string. */
 143 CF_EXPORT
 144 CFStringRef CFURLGetString(CFURLRef anURL);
 145
 146 /* Returns the base URL if it exists */
 147 CF_EXPORT
 148 CFURLRef CFURLGetBaseURL(CFURLRef anURL);
 149
 150 /*
 151 All URLs can be broken into two pieces - the scheme (preceding the
 152 first colon) and the resource specifier (following the first colon).
 153 Most URLs are also "standard" URLs conforming to RFC 1808 (available
 154 from www.w3c.org).  This category includes URLs of the file, http,
 155 https, and ftp schemes, to name a few.  Standard URLs start the
 156 resource specifier with two slashes ("//"), and can be broken into
 157 four distinct pieces - the scheme, the net location, the path, and
 158 further resource specifiers (typically an optional parameter, query,
 159 and/or fragment).  The net location appears immediately following
 160 the two slashes and goes up to the next slash; it's format is
 161 scheme-specific, but is usually composed of some or all of a username,
 162 password, host name, and port.  The path is a series of path components
 163 separated by slashes; if the net location is present, the path always
 164 begins with a slash.  Standard URLs can be relative to another URL,
 165 in which case at least the scheme and possibly other pieces as well
 166 come from the base URL (see RFC 1808 for precise details when resolving
 167 a relative URL against its base).  The full URL is therefore
 168
 169 <scheme> "://" <net location> <path, always starting with slash> <add'l resource specifiers>
 170
 171 If a given CFURL can be decomposed (that is, conforms to RFC 1808), you
 172 can ask for each of the four basic pieces (scheme, net location, path,
 173 and resource specifer) separately, as well as for its base URL.  The
 174 basic pieces are returned with any percent escape sequences still in
 175 place (although note that the scheme may not legally include any
 176 percent escapes); this is to allow the caller to distinguish between
 177 percent sequences that may have syntactic meaning if replaced by the
 178 character being escaped (for instance, a '/' in a path component).
 179 Since only the individual schemes know which characters are
 180 syntactically significant, CFURL cannot safely replace any percent
 181 escape sequences.  However, you can use
 182 CFURLCreateStringByReplacingPercentEscapes() to create a new string with
 183 the percent escapes removed; see below.
 184
 185 If a given CFURL can not be decomposed, you can ask for its scheme and its
 186 resource specifier; asking it for its net location or path will return NULL.
 187
 188 To get more refined information about the components of a decomposable
 189 CFURL, you may ask for more specific pieces of the URL, expressed with
 190 the percent escapes removed.  The available functions are CFURLCopyHostName(),
 191 CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(),
 192 CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and
 193 CFURLCopyFragment().  Because the parameters, query, and fragment of an
 194 URL may contain scheme-specific syntaxes, these methods take a second
 195 argument, giving a list of characters which should NOT be replaced if
 196 percent escaped.  For instance, the ftp parameter syntax gives simple
 197 key-value pairs as "<key>=<value>;"  Clearly if a key or value includes
 198 either '=' or ';', it must be escaped to avoid corrupting the meaning of
 199 the parameters, so the caller may request the parameter string as
 200
 201 CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%"));
 202
 203 requesting that all percent escape sequences be replaced by the represented
 204 characters, except for escaped '=', '%' or ';' characters.  Pass the empty
 205 string (CFSTR("")) to request that all percent escapes be replaced, or NULL
 206 to request that none be.
 207 */
 208
 209 /* Returns true if anURL conforms to RFC 1808 */
 210 CF_EXPORT
 211 Boolean CFURLCanBeDecomposed(CFURLRef anURL);
 212
 213 /* The next several methods leave any percent escape sequences intact */
 214
 215 CF_EXPORT
 216 CFStringRef CFURLCopyScheme(CFURLRef anURL);
 217
 218 /* NULL if CFURLCanBeDecomposed(anURL) is false */
 219 CF_EXPORT
 220 CFStringRef CFURLCopyNetLocation(CFURLRef anURL);
 221
 222 /* NULL if CFURLCanBeDecomposed(anURL) is false; also does not resolve the URL */
 223 /* against its base.  See also CFURLCopyAbsoluteURL().  Note that, strictly */
 224 /* speaking, any leading '/' is not considered part of the URL's path, although */
 225 /* its presence or absence determines whether the path is absolute. */
 226 /* CFURLCopyPath()'s return value includes any leading slash (giving the path */
 227 /* the normal POSIX appearance); CFURLCopyStrictPath()'s return value omits any */
 228 /* leading slash, and uses isAbsolute to report whether the URL's path is absolute. */
 229
 230 /* CFURLCopyFileSystemPath() returns the URL's path as a file system path for the */
 231 /* given path style.  All percent escape sequences are replaced.  The URL is not */
 232 /* resolved against its base before computing the path. */
 233 CF_EXPORT
 234 CFStringRef CFURLCopyPath(CFURLRef anURL);
 235
 236 CF_EXPORT
 237 CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
 238
 239 CF_EXPORT
 240 CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
 241
 242 /* Returns whether anURL's path represents a directory */
 243 /* (true returned) or a simple file (false returned) */
 244 CF_EXPORT
 245 Boolean CFURLHasDirectoryPath(CFURLRef anURL);
 246
 247 /* Any additional resource specifiers after the path.  For URLs */
 248 /* that cannot be decomposed, this is everything except the scheme itself. */
 249 CF_EXPORT
 250 CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL);
 251
 252 CF_EXPORT
 253 CFStringRef CFURLCopyHostName(CFURLRef anURL);
 254
 255 CF_EXPORT
 256 SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */
 257
 258 CF_EXPORT
 259 CFStringRef CFURLCopyUserName(CFURLRef anURL);
 260
 261 CF_EXPORT
 262 CFStringRef CFURLCopyPassword(CFURLRef anURL);
 263
 264 /* These remove all percent escape sequences except those for */
 265 /* characters in charactersToLeaveEscaped.  If charactersToLeaveEscaped */
 266 /* is empty (""), all percent escape sequences are replaced by their */
 267 /* corresponding characters.  If charactersToLeaveEscaped is NULL, */
 268 /* then no escape sequences are removed at all */
 269 CF_EXPORT
 270 CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 271
 272 CF_EXPORT
 273 CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 274
 275 CF_EXPORT
 276 CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 277
 278 CF_EXPORT
 279 CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
 280
 281 CF_EXPORT
 282 CFStringRef CFURLCopyPathExtension(CFURLRef url);
 283
 284 /* These functions all treat the base URL of the supplied url as */
 285 /* invariant.  In other words, the URL returned will always have */
 286 /* the same base as the URL supplied as an argument. */
 287
 288 CF_EXPORT
 289 CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
 290
 291 CF_EXPORT
 292 CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
 293
 294 CF_EXPORT
 295 CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
 296
 297 CF_EXPORT
 298 CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
 299
 300 /* Fills buffer with the bytes for url, returning the number of bytes */
 301 /* filled.  If buffer is of insufficient size, returns -1 and no bytes */
 302 /* are placed in buffer.  If buffer is NULL, the needed length is */
 303 /* computed and returned.  The returned bytes are the original bytes */
 304 /* from which the URL was created; if the URL was created from a */
 305 /* string, the bytes will be the bytes of the string encoded via UTF-8  */
 306 CF_EXPORT
 307 CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength);
 308
 309 typedef CF_ENUM(CFIndex, CFURLComponentType) {
 310         kCFURLComponentScheme = 1,
 311         kCFURLComponentNetLocation = 2,
 312         kCFURLComponentPath = 3,
 313         kCFURLComponentResourceSpecifier = 4,
 314
 315         kCFURLComponentUser = 5,
 316         kCFURLComponentPassword = 6,
 317         kCFURLComponentUserInfo = 7,
 318         kCFURLComponentHost = 8,
 319         kCFURLComponentPort = 9,
 320         kCFURLComponentParameterString = 10,
 321         kCFURLComponentQuery = 11,
 322         kCFURLComponentFragment = 12
 323 };
 324
 325 /*
 326 Gets the  range of the requested component in the bytes of url, as
 327 returned by CFURLGetBytes().  This range is only good for use in the
 328 bytes returned by CFURLGetBytes!
 329
 330 If non-NULL, rangeIncludingSeparators gives the range of component
 331 including the sequences that separate component from the previous and
 332 next components.  If there is no previous or next component, that end of
 333 rangeIncludingSeparators will match the range of the component itself.
 334 If url does not contain the given component type, (kCFNotFound, 0) is
 335 returned, and rangeIncludingSeparators is set to the location where the
 336 component would be inserted.  Some examples -
 337
 338 For the URL http://www.apple.com/hotnews/
 339
 340 Component           returned range      rangeIncludingSeparators
 341 scheme              (0, 4)              (0, 7)
 342 net location        (7, 13)             (4, 16)
 343 path                (20, 9)             (20, 9)
 344 resource specifier  (kCFNotFound, 0)    (29, 0)
 345 user                (kCFNotFound, 0)    (7, 0)
 346 password            (kCFNotFound, 0)    (7, 0)
 347 user info           (kCFNotFound, 0)    (7, 0)
 348 host                (7, 13)             (4, 16)
 349 port                (kCFNotFound, 0)    (20, 0)
 350 parameter           (kCFNotFound, 0)    (29, 0)
 351 query               (kCFNotFound, 0)    (29, 0)
 352 fragment            (kCFNotFound, 0)    (29, 0)
 353
 354
 355 For the URL ./relPath/file.html#fragment
 356
 357 Component           returned range      rangeIncludingSeparators
 358 scheme              (kCFNotFound, 0)    (0, 0)
 359 net location        (kCFNotFound, 0)    (0, 0)
 360 path                (0, 19)             (0, 20)
 361 resource specifier  (20, 8)             (19, 9)
 362 user                (kCFNotFound, 0)    (0, 0)
 363 password            (kCFNotFound, 0)    (0, 0)
 364 user info           (kCFNotFound, 0)    (0, 0)
 365 host                (kCFNotFound, 0)    (0, 0)
 366 port                (kCFNotFound, 0)    (0, 0)
 367 parameter           (kCFNotFound, 0)    (19, 0)
 368 query               (kCFNotFound, 0)    (19, 0)
 369 fragment            (20, 8)             (19, 9)
 370
 371
 372 For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment
 373
 374 Component           returned range      rangeIncludingSeparators
 375 scheme              (0, 6)              (0, 9)
 376 net location        (9, 16)             (6, 19)
 377 path                (25, 21)            (25, 22)
 378 resource specifier  (47, 21)            (46, 22)
 379 user                (9, 4)              (6, 8)
 380 password            (14, 4)             (13, 6)
 381 user info           (9, 9)              (6, 13)
 382 host                (19, 4)             (18, 6)
 383 port                (24, 1)             (23, 2)
 384 parameter           (47, 6)             (46, 8)
 385 query               (54, 5)             (53, 7)
 386 fragment            (60, 8)             (59, 9)
 387 */
 388 CF_EXPORT
 389 CFRange CFURLGetByteRangeForComponent(CFURLRef url, CFURLComponentType component, CFRange *rangeIncludingSeparators);
 390
 391 /* Returns a string with any percent escape sequences that do NOT */
 392 /* correspond to characters in charactersToLeaveEscaped with their */
 393 /* equivalent.  Returns NULL on failure (if an invalid percent sequence */
 394 /* is encountered), or the original string (retained) if no characters */
 395 /* need to be replaced. Pass NULL to request that no percent escapes be */
 396 /* replaced, or the empty string (CFSTR("")) to request that all percent */
 397 /* escapes be replaced.  Uses UTF8 to interpret percent escapes. */
 398 CF_EXPORT
 399 CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
 400
 401 /* As above, but allows you to specify the encoding to use when interpreting percent escapes */
 402 CF_EXPORT
 403 CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding(CFAllocatorRef allocator, CFStringRef origString, CFStringRef charsToLeaveEscaped, CFStringEncoding encoding);
 404
 405 /* Creates a copy or originalString, replacing certain characters with */
 406 /* the equivalent percent escape sequence based on the encoding specified. */
 407 /* If the originalString does not need to be modified (no percent escape */
 408 /* sequences are missing), may retain and return originalString. */
 409 /* If you are uncertain of the correct encoding, you should use UTF-8, */
 410 /* which is the encoding designated by RFC 2396 as the correct encoding */
 411 /* for use in URLs.  The characters so escaped are all characters that */
 412 /* are not legal URL characters (based on RFC 2396), plus any characters */
 413 /* in legalURLCharactersToBeEscaped, less any characters in */
 414 /* charactersToLeaveUnescaped.  To simply correct any non-URL characters */
 415 /* in an otherwise correct URL string, do: */
 416
 417 /* newString = CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, origString, NULL, NULL, kCFStringEncodingUTF8); */
 418 CF_EXPORT
 419 CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding);
 420
 421
 422 #if (TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE) || CF_BUILDING_CF || NSBUILDINGFOUNDATION
 423 CF_IMPLICIT_BRIDGING_DISABLED
 424
 425 /*
 426     CFURLIsFileReferenceURL
 427
 428     Returns whether the URL is a file reference URL.
 429
 430     Parameters
 431         url
 432             The URL specifying the resource.
 433  */
 434 CF_EXPORT
 435 Boolean CFURLIsFileReferenceURL(CFURLRef url) CF_AVAILABLE(10_9, 7_0);
 436
 437 /*
 438     CFURLCreateFileReferenceURL
 439
 440     Returns a new file reference URL that refers to the same resource as a specified URL.
 441
 442     Parameters
 443         allocator
 444             The memory allocator for creating the new URL.
 445         url
 446             The file URL specifying the resource.
 447         error
 448             On output when the result is NULL, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 449
 450     Return Value
 451         The new file reference URL, or NULL if an error occurs.
 452
 453     Discussion
 454         File reference URLs use a URL path syntax that identifies a file system object by reference, not by path. This form of file URL remains valid when the file system path of the URL’s underlying resource changes. An error will occur if the url parameter is not a file URL. File reference URLs cannot be created to file system objects which do not exist or are not reachable. In some areas of the file system hierarchy, file reference URLs cannot be generated to the leaf node of the URL path. A file reference URL's path should never be persistently stored because is not valid across system restarts, and across remounts of volumes -- if you want to create a persistent reference to a file system object, use a bookmark (see CFURLCreateBookmarkData). If this function returns NULL, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 455         Symbol is present in iOS 4, but performs no operation.
 456  */
 457 CF_EXPORT
 458 CFURLRef CFURLCreateFileReferenceURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 459
 460
 461 /*
 462     CFURLCreateFilePathURL
 463
 464     Returns a new file path URL that refers to the same resource as a specified URL.
 465
 466     Parameters
 467         allocator
 468             The memory allocator for creating the new URL.
 469         url
 470             The file URL specifying the resource.
 471         error
 472             On output when the result is NULL, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 473
 474     Return Value
 475         The new file path URL, or NULL if an error occurs.
 476
 477     Discussion
 478         File path URLs use a file system style path. An error will occur if the url parameter is not a file URL. A file reference URL's resource must exist and be reachable to be converted to a file path URL. If this function returns NULL, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 479         Symbol is present in iOS 4, but performs no operation.
 480  */
 481 CF_EXPORT
 482 CFURLRef CFURLCreateFilePathURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 483
 484 CF_IMPLICIT_BRIDGING_ENABLED
 485 #endif
 486
 487
 488
 489 #if (TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE) || CF_BUILDING_CF || NSBUILDINGFOUNDATION
 490 CF_IMPLICIT_BRIDGING_DISABLED
 491
 492 /* Resource access
 493
 494     The behavior of resource value caching is slightly different between the NSURL and CFURL API.
 495
 496     When the NSURL methods which get, set, or use cached resource values are used from the main thread, resource values cached by the URL (except those added as temporary properties) are invalidated the next time the main thread's run loop runs.
 497
 498     The CFURL functions do not automatically clear any resource values cached by the URL. The client has complete control over the cache lifetime. If you are using CFURL API, you must use CFURLClearResourcePropertyCacheForKey or CFURLClearResourcePropertyCache to clear cached resource values.
 499  */
 500
 501
 502 /*
 503     CFURLCopyResourcePropertyForKey
 504
 505     Returns the resource value identified by a given resource key.
 506
 507     Parameters
 508         url
 509             The URL specifying the resource.
 510         key
 511             The resource key that identifies the resource property.
 512         propertyValueTypeRefPtr
 513             On output when the result is true, the resource value or NULL.
 514         error
 515             On output when the result is false, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 516
 517     Return Value
 518         true if propertyValueTypeRefPtr is successfully populated; false if an error occurs.
 519
 520     Discussion
 521         CFURLCopyResourcePropertyForKey first checks if the URL object already caches the resource value. If so, it returns the cached resource value to the caller. If not, then CFURLCopyResourcePropertyForKey synchronously obtains the resource value from the backing store, adds the resource value to the URL object's cache, and returns the resource value to the caller. The type of the resource value varies by resource property (see resource key definitions). If this function returns true and propertyValueTypeRefPtr is populated with NULL, it means the resource property is not available for the specified resource and no errors occurred when determining the resource property was not available. If this function returns false, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 522         Symbol is present in iOS 4, but performs no operation.
 523  */
 524 CF_EXPORT
 525 Boolean CFURLCopyResourcePropertyForKey(CFURLRef url, CFStringRef key, void *propertyValueTypeRefPtr, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 526
 527
 528 /*
 529     CFURLCopyResourcePropertiesForKeys
 530
 531     Returns the resource values identified by specified array of resource keys.
 532
 533     Parameters
 534         url
 535             The URL specifying the resource.
 536         keys
 537             An array of resource keys that identify the resource properties.
 538         error
 539             On output when the result is NULL, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 540
 541     Return Value
 542         A dictionary of resource values indexed by resource key; NULL if an error occurs.
 543
 544     Discussion
 545         CFURLCopyResourcePropertiesForKeys first checks if the URL object already caches the resource values. If so, it returns the cached resource values to the caller. If not, then CFURLCopyResourcePropertyForKey synchronously obtains the resource values from the backing store, adds the resource values to the URL object's cache, and returns the resource values to the caller. The type of the resource values vary by property (see resource key definitions). If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available for the specified resource and no errors occurred when determining those resource properties were not available. If this function returns NULL, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 546         Symbol is present in iOS 4, but performs no operation.
 547  */
 548 CF_EXPORT
 549 CFDictionaryRef CFURLCopyResourcePropertiesForKeys(CFURLRef url, CFArrayRef keys, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 550
 551
 552 /*
 553     CFURLSetResourcePropertyForKey
 554
 555     Sets the resource value identified by a given resource key.
 556
 557     Parameters
 558         url
 559             The URL specifying the resource.
 560         key
 561             The resource key that identifies the resource property.
 562         propertyValue
 563             The resource value.
 564         error
 565             On output when the result is false, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 566
 567     Return Value
 568         true if the attempt to set the resource value completed with no errors; otherwise, false.
 569
 570     Discussion
 571         CFURLSetResourcePropertyForKey writes the new resource value out to the backing store. Attempts to set a read-only resource property or to set a resource property not supported by the resource are ignored and are not considered errors. If this function returns false, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 572         Symbol is present in iOS 4, but performs no operation.
 573  */
 574 CF_EXPORT
 575 Boolean CFURLSetResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertyValue, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 576
 577
 578 /*
 579     CFURLSetResourcePropertiesForKeys
 580
 581     Sets any number of resource values of a URL's resource.
 582
 583     Parameters
 584         url
 585             The URL specifying the resource.
 586         keyedPropertyValues
 587             A dictionary of resource values indexed by resource keys.
 588         error
 589             On output when the result is false, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 590
 591     Return Value
 592         true if the attempt to set the resource values completed with no errors; otherwise, false.
 593
 594     Discussion
 595         CFURLSetResourcePropertiesForKeys writes the new resource values out to the backing store. Attempts to set read-only resource properties or to set resource properties not supported by the resource are ignored and are not considered errors. If an error occurs after some resource properties have been successfully changed, the userInfo dictionary in the returned error contains an array of resource keys that were not set with the key kCFURLKeysOfUnsetValuesKey. The order in which the resource values are set is not defined. If you need to guarantee the order resource values are set, you should make multiple requests to CFURLSetResourcePropertiesForKeys or CFURLSetResourcePropertyForKey to guarantee the order. If this function returns false, the optional error is populated. This function is currently applicable only to URLs for file system resources.
 596         Symbol is present in iOS 4, but performs no operation.
 597  */
 598 CF_EXPORT
 599 Boolean CFURLSetResourcePropertiesForKeys(CFURLRef url, CFDictionaryRef keyedPropertyValues, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 600
 601
 602 CF_EXPORT
 603 const CFStringRef kCFURLKeysOfUnsetValuesKey CF_AVAILABLE(10_7, 5_0);
 604     /* Key for the resource properties that have not been set after the CFURLSetResourcePropertiesForKeys function returns an error, returned as an array of of CFString objects. */
 605
 606
 607 /*
 608     CFURLClearResourcePropertyCacheForKey
 609
 610     Discards a cached resource value of a URL.
 611
 612     Parameters
 613         url
 614             The URL specifying the resource.
 615         key
 616             The resource key that identifies the resource property.
 617
 618     Discussion
 619         Discarding a cached resource value may discard other cached resource values, because some resource values are cached as a set of values and because some resource values depend on other resource values (temporary properties have no dependencies). This function is currently applicable only to URLs for file system resources.
 620         Symbol is present in iOS 4, but performs no operation.
 621  */
 622 CF_EXPORT
 623 void CFURLClearResourcePropertyCacheForKey(CFURLRef url, CFStringRef key) CF_AVAILABLE(10_6, 4_0);
 624
 625
 626 /*
 627     CFURLClearResourcePropertyCache
 628
 629     Discards all cached resource values of a URL.
 630
 631     Parameters
 632         url
 633             The URL specifying the resource.
 634
 635     Discussion
 636         All temporary properties are also cleared from the URL object's cache. This function is currently applicable only to URLs for file system resources.
 637         Symbol is present in iOS 4, but performs no operation.
 638  */
 639 CF_EXPORT
 640 void CFURLClearResourcePropertyCache(CFURLRef url) CF_AVAILABLE(10_6, 4_0);
 641
 642
 643 /*
 644     CFURLSetTemporaryResourcePropertyForKey
 645
 646     Sets a temporary resource value on the URL object.
 647
 648     Parameters
 649         url
 650             The URL object.
 651         key
 652             The resource key that identifies the temporary resource property.
 653         propertyValue
 654             The resource value.
 655
 656     Discussion
 657         Temporary properties are for client use. Temporary properties exist only in memory and are never written to the resource's backing store. Once set, a temporary value can be copied from the URL object with CFURLCopyResourcePropertyForKey and CFURLCopyResourcePropertiesForKeys. To remove a temporary value from the URL object, use CFURLClearResourcePropertyCacheForKey. Temporary values must be valid Core Foundation types, and will be retained by CFURLSetTemporaryResourcePropertyForKey. Care should be taken to ensure the key that identifies a temporary resource property is unique and does not conflict with system defined keys (using reverse domain name notation in your temporary resource property keys is recommended). This function is currently applicable only to URLs for file system resources.
 658         Symbol is present in iOS 4, but performs no operation.
 659  */
 660 CF_EXPORT
 661 void CFURLSetTemporaryResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertyValue) CF_AVAILABLE(10_6, 4_0);
 662
 663
 664 /*
 665     CFURLResourceIsReachable
 666
 667     Returns whether the URL's resource exists and is reachable.
 668
 669     Parameters
 670         url
 671             The URL object.
 672         error
 673             On output when the result is false, the error that occurred. This parameter is optional; if you do not wish the error returned, pass NULL here. The caller is responsible for releasing a valid output error.
 674
 675     Return Value
 676         true if the resource is reachable; otherwise, false.
 677
 678     Discussion
 679         CFURLResourceIsReachable synchronously checks if the resource's backing store is reachable. Checking reachability is appropriate when making decisions that do not require other immediate operations on the resource, e.g. periodic maintenance of UI state that depends on the existence of a specific document. When performing operations such as opening a file or copying resource properties, it is more efficient to simply try the operation and handle failures. This function is currently applicable only to URLs for file system resources. If this function returns false, the optional error is populated. For other URL types, false is returned.
 680         Symbol is present in iOS 4, but performs no operation.
 681  */
 682 CF_EXPORT
 683 Boolean CFURLResourceIsReachable(CFURLRef url, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0);
 684
 685 CF_IMPLICIT_BRIDGING_ENABLED
 686
 687
 688 /* Properties of File System Resources */
 689
 690 CF_EXPORT
 691 const CFStringRef kCFURLNameKey CF_AVAILABLE(10_6, 4_0);
 692     /* The resource name provided by the file system (Read-write, value type CFString) */
 693
 694 CF_EXPORT
 695 const CFStringRef kCFURLLocalizedNameKey CF_AVAILABLE(10_6, 4_0);
 696     /* Localized or extension-hidden name as displayed to users (Read-only, value type CFString) */
 697
 698 CF_EXPORT
 699 const CFStringRef kCFURLIsRegularFileKey CF_AVAILABLE(10_6, 4_0);
 700     /* True for regular files (Read-only, value type CFBoolean) */
 701
 702 CF_EXPORT
 703 const CFStringRef kCFURLIsDirectoryKey CF_AVAILABLE(10_6, 4_0);
 704     /* True for directories (Read-only, CFBoolean) */
 705
 706 CF_EXPORT
 707 const CFStringRef kCFURLIsSymbolicLinkKey CF_AVAILABLE(10_6, 4_0);
 708     /* True for symlinks (Read-only, value type CFBoolean) */
 709
 710 CF_EXPORT
 711 const CFStringRef kCFURLIsVolumeKey CF_AVAILABLE(10_6, 4_0);
 712     /* True for the root directory of a volume (Read-only, value type CFBoolean) */
 713
 714 CF_EXPORT
 715 const CFStringRef kCFURLIsPackageKey CF_AVAILABLE(10_6, 4_0);
 716     /* True for packaged directories (Read-only 10_6 and 10_7, read-write 10_8, value type CFBoolean). Note: You can only set or clear this property on directories; if you try to set this property on non-directory objects, the property is ignored. If the directory is a package for some other reason (extension type, etc), setting this property to false will have no effect. */
 717
 718 CF_EXPORT
 719 const CFStringRef kCFURLIsSystemImmutableKey CF_AVAILABLE(10_6, 4_0);
 720     /* True for system-immutable resources (Read-write, value type CFBoolean) */
 721
 722 CF_EXPORT
 723 const CFStringRef kCFURLIsUserImmutableKey CF_AVAILABLE(10_6, 4_0);
 724     /* True for user-immutable resources (Read-write, value type CFBoolean) */
 725
 726 CF_EXPORT
 727 const CFStringRef kCFURLIsHiddenKey CF_AVAILABLE(10_6, 4_0);
 728     /* True for resources normally not displayed to users (Read-write, value type CFBoolean). Note: If the resource is a hidden because its name starts with a period, setting this property to false will not change the property. */
 729
 730 CF_EXPORT
 731 const CFStringRef kCFURLHasHiddenExtensionKey CF_AVAILABLE(10_6, 4_0);
 732     /* True for resources whose filename extension is removed from the localized name property (Read-write, value type CFBoolean) */
 733
 734 CF_EXPORT
 735 const CFStringRef kCFURLCreationDateKey CF_AVAILABLE(10_6, 4_0);
 736     /* The date the resource was created (Read-write, value type CFDate) */
 737
 738 CF_EXPORT
 739 const CFStringRef kCFURLContentAccessDateKey CF_AVAILABLE(10_6, 4_0);
 740     /* The date the resource was last accessed (Read-only, value type CFDate) */
 741
 742 CF_EXPORT
 743 const CFStringRef kCFURLContentModificationDateKey CF_AVAILABLE(10_6, 4_0);
 744     /* The time the resource content was last modified (Read-write, value type CFDate) */
 745
 746 CF_EXPORT
 747 const CFStringRef kCFURLAttributeModificationDateKey CF_AVAILABLE(10_6, 4_0);
 748     /* The time the resource's attributes were last modified (Read-write, value type CFDate) */
 749
 750 CF_EXPORT
 751 const CFStringRef kCFURLLinkCountKey CF_AVAILABLE(10_6, 4_0);
 752     /* Number of hard links to the resource (Read-only, value type CFNumber) */
 753
 754 CF_EXPORT
 755 const CFStringRef kCFURLParentDirectoryURLKey CF_AVAILABLE(10_6, 4_0);
 756     /* The resource's parent directory, if any (Read-only, value type CFURL) */
 757
 758 CF_EXPORT
 759 const CFStringRef kCFURLVolumeURLKey CF_AVAILABLE(10_6, 4_0);
 760     /* URL of the volume on which the resource is stored (Read-only, value type CFURL) */
 761
 762 CF_EXPORT
 763 const CFStringRef kCFURLTypeIdentifierKey CF_AVAILABLE(10_6, 4_0);
 764     /* Uniform type identifier (UTI) for the resource (Read-only, value type CFString) */
 765
 766 CF_EXPORT
 767 const CFStringRef kCFURLLocalizedTypeDescriptionKey CF_AVAILABLE(10_6, 4_0);
 768     /* User-visible type or "kind" description (Read-only, value type CFString) */
 769
 770 CF_EXPORT
 771 const CFStringRef kCFURLLabelNumberKey CF_AVAILABLE(10_6, 4_0);
 772     /* The label number assigned to the resource (Read-write, value type CFNumber) */
 773
 774 CF_EXPORT
 775 const CFStringRef kCFURLLabelColorKey CF_AVAILABLE(10_6, 4_0);
 776     /* The color of the assigned label (Currently not implemented, value type CGColorRef, must link with Application Services) */
 777
 778 CF_EXPORT
 779 const CFStringRef kCFURLLocalizedLabelKey CF_AVAILABLE(10_6, 4_0);
 780     /* The user-visible label text (Read-only, value type CFString) */
 781
 782 CF_EXPORT
 783 const CFStringRef kCFURLEffectiveIconKey CF_AVAILABLE(10_6, 4_0);
 784     /* The icon normally displayed for the resource (Read-only, value type CGImageRef, must link with Application Services) */
 785
 786 CF_EXPORT
 787 const CFStringRef kCFURLCustomIconKey CF_AVAILABLE(10_6, 4_0);
 788     /* The custom icon assigned to the resource, if any (Currently not implemented, value type CGImageRef, must link with Application Services) */
 789
 790 CF_EXPORT
 791 const CFStringRef kCFURLFileResourceIdentifierKey CF_AVAILABLE(10_7, 5_0);
 792     /* An identifier which can be used to compare two file system objects for equality using CFEqual (i.e, two object identifiers are equal if they have the same file system path or if the paths are linked to same inode on the same file system). This identifier is not persistent across system restarts. (Read-only, value type CFType) */
 793
 794 CF_EXPORT
 795 const CFStringRef kCFURLVolumeIdentifierKey CF_AVAILABLE(10_7, 5_0);
 796     /* An identifier that can be used to identify the volume the file system object is on. Other objects on the same volume will have the same volume identifier and can be compared using for equality using CFEqual. This identifier is not persistent across system restarts. (Read-only, value type CFType) */
 797
 798 CF_EXPORT
 799 const CFStringRef kCFURLPreferredIOBlockSizeKey CF_AVAILABLE(10_7, 5_0);
 800     /* The optimal block size when reading or writing this file's data, or NULL if not available. (Read-only, value type CFNumber) */
 801
 802 CF_EXPORT
 803 const CFStringRef kCFURLIsReadableKey CF_AVAILABLE(10_7, 5_0);
 804     /* true if this process (as determined by EUID) can read the resource. (Read-only, value type CFBoolean) */
 805
 806 CF_EXPORT
 807 const CFStringRef kCFURLIsWritableKey CF_AVAILABLE(10_7, 5_0);
 808     /* true if this process (as determined by EUID) can write to the resource. (Read-only, value type CFBoolean) */
 809
 810 CF_EXPORT
 811 const CFStringRef kCFURLIsExecutableKey CF_AVAILABLE(10_7, 5_0);
 812     /* true if this process (as determined by EUID) can execute a file resource or search a directory resource. (Read-only, value type CFBoolean) */
 813
 814 CF_EXPORT
 815 const CFStringRef kCFURLFileSecurityKey CF_AVAILABLE(10_7, 5_0);
 816     /* The file system object's security information encapsulated in a CFFileSecurity object. (Read-write, value type CFFileSecurity) */
 817
 818 CF_EXPORT
 819 const CFStringRef kCFURLIsExcludedFromBackupKey CF_AVAILABLE(10_8, 5_1);
 820     /* true if resource should be excluded from backups, false otherwise (Read-write, value type CFBoolean). This property is only useful for excluding cache and other application support files which are not needed in a backup. Some operations commonly made to user documents will cause this property to be reset to false and so this property should not be used on user documents. */
 821
 822 CF_EXPORT
 823 const CFStringRef kCFURLTagNamesKey CF_AVAILABLE(10_9, NA);
 824     /* The array of Tag names (Read-write, value type CFArray of CFString) */
 825
 826 CF_EXPORT
 827 const CFStringRef kCFURLPathKey CF_AVAILABLE(10_8, 6_0);
 828     /* the URL's path as a file system path (Read-only, value type CFString) */
 829
 830 CF_EXPORT
 831 const CFStringRef kCFURLIsMountTriggerKey CF_AVAILABLE(10_7, 4_0);
 832     /* true if this URL is a file system trigger directory. Traversing or opening a file system trigger will cause an attempt to mount a file system on the trigger directory. (Read-only, value type CFBoolean) */
 833
 834 CF_EXPORT
 835 const CFStringRef kCFURLGenerationIdentifierKey CF_AVAILABLE(10_10, 8_0);
 836     /* An opaque generation identifier which can be compared using CFEqual() to determine if the data in a document has been modified. For URLs which refer to the same file inode, the generation identifier will change when the data in the file's data fork is changed (changes to extended attributes or other file system metadata do not change the generation identifier). For URLs which refer to the same directory inode, the generation identifier will change when direct children of that directory are added, removed or renamed (changes to the data of the direct children of that directory will not change the generation identifier). The generation identifier is persistent across system restarts. The generation identifier is tied to a specific document on a specific volume and is not transferred when the document is copied to another volume. This property is not supported by all volumes. (Read-only, value type CFType) */
 837
 838 CF_EXPORT
 839 const CFStringRef kCFURLDocumentIdentifierKey CF_AVAILABLE(10_10, 8_0);
 840     /* The document identifier -- a value assigned by the kernel to a document (which can be either a file or directory) and is used to identify the document regardless of where it gets moved on a volume. The document identifier survives "safe save” operations; i.e it is sticky to the path it was assigned to (-replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error: is the preferred safe-save API). The document identifier is persistent across system restarts. The document identifier is not transferred when the file is copied. Document identifiers are only unique within a single volume. This property is not supported by all volumes. (Read-only, value type CFNumber) */
 841
 842 CF_EXPORT
 843 const CFStringRef kCFURLAddedToDirectoryDateKey CF_AVAILABLE(10_10, 8_0);
 844     /* The date the resource was created, or renamed into or within its parent directory. Note that inconsistent behavior may be observed when this attribute is requested on hard-linked items. This property is not supported by all volumes. (Read-only, value type CFDate) */
 845
 846 CF_EXPORT
 847 const CFStringRef kCFURLQuarantinePropertiesKey CF_AVAILABLE(10_10, NA);
 848     /* The quarantine properties as defined in LSQuarantine.h. To remove quarantine information from a file, pass kCFNull as the value when setting this property. (Read-write, value type CFDictionary) */
 849
 850 CF_EXPORT
 851 const CFStringRef kCFURLFileResourceTypeKey CF_AVAILABLE(10_7, 5_0);
 852     /* Returns the file system object type. (Read-only, value type CFString) */
 853
 854 /* The file system object type values returned for the kCFURLFileResourceTypeKey */
 855 CF_EXPORT
 856 const CFStringRef kCFURLFileResourceTypeNamedPipe CF_AVAILABLE(10_7, 5_0);
 857 CF_EXPORT
 858 const CFStringRef kCFURLFileResourceTypeCharacterSpecial CF_AVAILABLE(10_7, 5_0);
 859 CF_EXPORT
 860 const CFStringRef kCFURLFileResourceTypeDirectory CF_AVAILABLE(10_7, 5_0);
 861 CF_EXPORT
 862 const CFStringRef kCFURLFileResourceTypeBlockSpecial CF_AVAILABLE(10_7, 5_0);
 863 CF_EXPORT
 864 const CFStringRef kCFURLFileResourceTypeRegular CF_AVAILABLE(10_7, 5_0);
 865 CF_EXPORT
 866 const CFStringRef kCFURLFileResourceTypeSymbolicLink CF_AVAILABLE(10_7, 5_0);
 867 CF_EXPORT
 868 const CFStringRef kCFURLFileResourceTypeSocket CF_AVAILABLE(10_7, 5_0);
 869 CF_EXPORT
 870 const CFStringRef kCFURLFileResourceTypeUnknown CF_AVAILABLE(10_7, 5_0);
 871
 872 /* File Properties */
 873
 874 CF_EXPORT
 875 const CFStringRef kCFURLFileSizeKey CF_AVAILABLE(10_6, 4_0);
 876     /* Total file size in bytes (Read-only, value type CFNumber) */
 877
 878 CF_EXPORT
 879 const CFStringRef kCFURLFileAllocatedSizeKey CF_AVAILABLE(10_6, 4_0);
 880     /* Total size allocated on disk for the file in bytes (number of blocks times block size) (Read-only, value type CFNumber) */
 881
 882 CF_EXPORT
 883 const CFStringRef kCFURLTotalFileSizeKey CF_AVAILABLE(10_7, 5_0);
 884     /* Total displayable size of the file in bytes (this may include space used by metadata), or NULL if not available. (Read-only, value type CFNumber) */
 885
 886 CF_EXPORT
 887 const CFStringRef kCFURLTotalFileAllocatedSizeKey CF_AVAILABLE(10_7, 5_0);
 888     /* Total allocated size of the file in bytes (this may include space used by metadata), or NULL if not available. This can be less than the value returned by kCFURLTotalFileSizeKey if the resource is compressed. (Read-only, value type CFNumber) */
 889
 890 CF_EXPORT
 891 const CFStringRef kCFURLIsAliasFileKey CF_AVAILABLE(10_6, 4_0);
 892     /*  true if the resource is a Finder alias file or a symlink, false otherwise ( Read-only, value type CFBooleanRef) */
 893
 894
 895 /* Volume Properties */
 896
 897 /* As a convenience, volume properties can be requested from any file system URL. The value returned will reflect the property value for the volume on which the resource is located. */
 898
 899 CF_EXPORT
 900 const CFStringRef kCFURLVolumeLocalizedFormatDescriptionKey CF_AVAILABLE(10_6, 4_0);
 901     /* The user-visible volume format (Read-only, value type CFString) */
 902
 903 CF_EXPORT
 904 const CFStringRef kCFURLVolumeTotalCapacityKey CF_AVAILABLE(10_6, 4_0);
 905     /* Total volume capacity in bytes (Read-only, value type CFNumber) */
 906
 907 CF_EXPORT
 908 const CFStringRef kCFURLVolumeAvailableCapacityKey CF_AVAILABLE(10_6, 4_0);
 909     /* Total free space in bytes (Read-only, value type CFNumber) */
 910
 911 CF_EXPORT
 912 const CFStringRef kCFURLVolumeResourceCountKey CF_AVAILABLE(10_6, 4_0);
 913     /* Total number of resources on the volume (Read-only, value type CFNumber) */
 914
 915 CF_EXPORT
 916 const CFStringRef kCFURLVolumeSupportsPersistentIDsKey CF_AVAILABLE(10_6, 4_0);
 917     /* true if the volume format supports persistent object identifiers and can look up file system objects by their IDs (Read-only, value type CFBoolean) */
 918
 919 CF_EXPORT
 920 const CFStringRef kCFURLVolumeSupportsSymbolicLinksKey CF_AVAILABLE(10_6, 4_0);
 921     /* true if the volume format supports symbolic links (Read-only, value type CFBoolean) */
 922
 923 CF_EXPORT
 924 const CFStringRef kCFURLVolumeSupportsHardLinksKey CF_AVAILABLE(10_6, 4_0);
 925     /* true if the volume format supports hard links (Read-only, value type CFBoolean) */
 926
 927 CF_EXPORT
 928 const CFStringRef kCFURLVolumeSupportsJournalingKey CF_AVAILABLE(10_6, 4_0);
 929     /* true if the volume format supports a journal used to speed recovery in case of unplanned restart (such as a power outage or crash). This does not necessarily mean the volume is actively using a journal. (Read-only, value type CFBoolean) */
 930
 931 CF_EXPORT
 932 const CFStringRef kCFURLVolumeIsJournalingKey CF_AVAILABLE(10_6, 4_0);
 933     /* true if the volume is currently using a journal for speedy recovery after an unplanned restart. (Read-only, value type CFBoolean) */
 934
 935 CF_EXPORT
 936 const CFStringRef kCFURLVolumeSupportsSparseFilesKey CF_AVAILABLE(10_6, 4_0);
 937     /* true if the volume format supports sparse files, that is, files which can have 'holes' that have never been written to, and thus do not consume space on disk. A sparse file may have an allocated size on disk that is less than its logical length. (Read-only, value type CFBoolean) */
 938
 939 CF_EXPORT
 940 const CFStringRef kCFURLVolumeSupportsZeroRunsKey CF_AVAILABLE(10_6, 4_0);
 941     /* For security reasons, parts of a file (runs) that have never been written to must appear to contain zeroes. true if the volume keeps track of allocated but unwritten runs of a file so that it can substitute zeroes without actually writing zeroes to the media. (Read-only, value type CFBoolean) */
 942
 943 CF_EXPORT
 944 const CFStringRef kCFURLVolumeSupportsCaseSensitiveNamesKey CF_AVAILABLE(10_6, 4_0);
 945     /* true if the volume format treats upper and lower case characters in file and directory names as different. Otherwise an upper case character is equivalent to a lower case character, and you can't have two names that differ solely in the case of the characters. (Read-only, value type CFBoolean) */
 946
 947 CF_EXPORT
 948 const CFStringRef kCFURLVolumeSupportsCasePreservedNamesKey CF_AVAILABLE(10_6, 4_0);
 949     /* true if the volume format preserves the case of file and directory names.  Otherwise the volume may change the case of some characters (typically making them all upper or all lower case). (Read-only, value type CFBoolean) */
 950
 951 CF_EXPORT
 952 const CFStringRef kCFURLVolumeSupportsRootDirectoryDatesKey CF_AVAILABLE(10_7, 5_0);
 953     /* true if the volume supports reliable storage of times for the root directory. (Read-only, value type CFBoolean) */
 954
 955 CF_EXPORT
 956 const CFStringRef kCFURLVolumeSupportsVolumeSizesKey CF_AVAILABLE(10_7, 5_0);
 957     /* true if the volume supports returning volume size values (kCFURLVolumeTotalCapacityKey and kCFURLVolumeAvailableCapacityKey). (Read-only, value type CFBoolean) */
 958
 959 CF_EXPORT
 960 const CFStringRef kCFURLVolumeSupportsRenamingKey CF_AVAILABLE(10_7, 5_0);
 961     /* true if the volume can be renamed. (Read-only, value type CFBoolean) */
 962
 963 CF_EXPORT
 964 const CFStringRef kCFURLVolumeSupportsAdvisoryFileLockingKey CF_AVAILABLE(10_7, 5_0);
 965     /* true if the volume implements whole-file flock(2) style advisory locks, and the O_EXLOCK and O_SHLOCK flags of the open(2) call. (Read-only, value type CFBoolean) */
 966
 967 CF_EXPORT
 968 const CFStringRef kCFURLVolumeSupportsExtendedSecurityKey CF_AVAILABLE(10_7, 5_0);
 969     /* true if the volume implements extended security (ACLs). (Read-only, value type CFBoolean) */
 970
 971 CF_EXPORT
 972 const CFStringRef kCFURLVolumeIsBrowsableKey CF_AVAILABLE(10_7, 5_0);
 973     /* true if the volume should be visible via the GUI (i.e., appear on the Desktop as a separate volume). (Read-only, value type CFBoolean) */
 974
 975 CF_EXPORT
 976 const CFStringRef kCFURLVolumeMaximumFileSizeKey CF_AVAILABLE(10_7, 5_0);
 977     /* The largest file size (in bytes) supported by this file system, or NULL if this cannot be determined. (Read-only, value type CFNumber) */
 978
 979 CF_EXPORT
 980 const CFStringRef kCFURLVolumeIsEjectableKey CF_AVAILABLE(10_7, 5_0);
 981     /* true if the volume's media is ejectable from the drive mechanism under software control. (Read-only, value type CFBoolean) */
 982
 983 CF_EXPORT
 984 const CFStringRef kCFURLVolumeIsRemovableKey CF_AVAILABLE(10_7, 5_0);
 985     /* true if the volume's media is removable from the drive mechanism. (Read-only, value type CFBoolean) */
 986
 987 CF_EXPORT
 988 const CFStringRef kCFURLVolumeIsInternalKey CF_AVAILABLE(10_7, 5_0);
 989     /* true if the volume's device is connected to an internal bus, false if connected to an external bus, or NULL if not available. (Read-only, value type CFBoolean) */
 990
 991 CF_EXPORT
 992 const CFStringRef kCFURLVolumeIsAutomountedKey CF_AVAILABLE(10_7, 5_0);
 993     /* true if the volume is automounted. Note: do not mistake this with the functionality provided by kCFURLVolumeSupportsBrowsingKey. (Read-only, value type CFBoolean) */
 994
 995 CF_EXPORT
 996 const CFStringRef kCFURLVolumeIsLocalKey CF_AVAILABLE(10_7, 5_0);
 997     /* true if the volume is stored on a local device. (Read-only, value type CFBoolean) */
 998
 999 CF_EXPORT
1000 const CFStringRef kCFURLVolumeIsReadOnlyKey CF_AVAILABLE(10_7, 5_0);
1001     /* true if the volume is read-only. (Read-only, value type CFBoolean) */
1002
1003 CF_EXPORT
1004 const CFStringRef kCFURLVolumeCreationDateKey CF_AVAILABLE(10_7, 5_0);
1005     /* The volume's creation date, or NULL if this cannot be determined. (Read-only, value type CFDate) */
1006
1007 CF_EXPORT
1008 const CFStringRef kCFURLVolumeURLForRemountingKey CF_AVAILABLE(10_7, 5_0);
1009     /* The CFURL needed to remount a network volume, or NULL if not available. (Read-only, value type CFURL) */
1010
1011 CF_EXPORT
1012 const CFStringRef kCFURLVolumeUUIDStringKey CF_AVAILABLE(10_7, 5_0);
1013     /* The volume's persistent UUID as a string, or NULL if a persistent UUID is not available for the volume. (Read-only, value type CFString) */
1014
1015 CF_EXPORT
1016 const CFStringRef kCFURLVolumeNameKey CF_AVAILABLE(10_7, 5_0);
1017     /* The name of the volume (Read-write, settable if kCFURLVolumeSupportsRenamingKey is true and permissions allow, value type CFString) */
1018
1019 CF_EXPORT
1020 const CFStringRef kCFURLVolumeLocalizedNameKey CF_AVAILABLE(10_7, 5_0);
1021     /* The user-presentable name of the volume (Read-only, value type CFString) */
1022
1023 /* UbiquitousItem Properties */
1024
1025 CF_EXPORT
1026 const CFStringRef kCFURLIsUbiquitousItemKey CF_AVAILABLE(10_7, 5_0);
1027     /* true if this item is synced to the cloud, false if it is only a local file. (Read-only, value type CFBoolean) */
1028
1029 CF_EXPORT
1030 const CFStringRef kCFURLUbiquitousItemHasUnresolvedConflictsKey CF_AVAILABLE(10_7, 5_0);
1031     /* true if this item has conflicts outstanding. (Read-only, value type CFBoolean) */
1032
1033 CF_EXPORT
1034 const CFStringRef kCFURLUbiquitousItemIsDownloadedKey CF_DEPRECATED(10_7, 10_9, 5_0, 7_0, "Use kCFURLUbiquitousItemDownloadingStatusKey instead");
1035     /* Equivalent to NSURLUbiquitousItemDownloadingStatusKey == NSURLUbiquitousItemDownloadingStatusCurrent. Has never behaved as documented in earlier releases, hence deprecated. (Read-only, value type CFBoolean) */
1036
1037 CF_EXPORT
1038 const CFStringRef kCFURLUbiquitousItemIsDownloadingKey CF_AVAILABLE(10_7, 5_0);
1039     /* true if data is being downloaded for this item. (Read-only, value type CFBoolean) */
1040
1041 CF_EXPORT
1042 const CFStringRef kCFURLUbiquitousItemIsUploadedKey CF_AVAILABLE(10_7, 5_0);
1043     /* true if there is data present in the cloud for this item. (Read-only, value type CFBoolean) */
1044
1045 CF_EXPORT
1046 const CFStringRef kCFURLUbiquitousItemIsUploadingKey CF_AVAILABLE(10_7, 5_0);
1047     /* true if data is being uploaded for this item. (Read-only, value type CFBoolean) */
1048
1049 CF_EXPORT
1050 const CFStringRef kCFURLUbiquitousItemPercentDownloadedKey CF_DEPRECATED(10_7, 10_8, 5_0, 6_0, "Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead");
1051     /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead */
1052
1053 CF_EXPORT
1054 const CFStringRef kCFURLUbiquitousItemPercentUploadedKey CF_DEPRECATED(10_7, 10_8, 5_0, 6_0, "Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead");
1055     /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead */
1056
1057 CF_EXPORT
1058 const CFStringRef kCFURLUbiquitousItemDownloadingStatusKey CF_AVAILABLE(10_9, 7_0);
1059     /* Returns the download status of this item. (Read-only, value type CFString). Possible values below. */
1060
1061 CF_EXPORT
1062 const CFStringRef kCFURLUbiquitousItemDownloadingErrorKey CF_AVAILABLE(10_9, 7_0);
1063     /* returns the error when downloading the item from iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. (Read-only, value type CFError) */
1064
1065 CF_EXPORT
1066 const CFStringRef kCFURLUbiquitousItemUploadingErrorKey CF_AVAILABLE(10_9, 7_0);
1067     /* returns the error when uploading the item to iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. (Read-only, value type CFError) */
1068
1069 /* The values returned for kCFURLUbiquitousItemDownloadingStatusKey
1070  */
1071 CF_EXPORT
1072 const CFStringRef kCFURLUbiquitousItemDownloadingStatusNotDownloaded CF_AVAILABLE(10_9, 7_0);
1073     /* this item has not been downloaded yet. Use NSFileManager's startDownloadingUbiquitousItemAtURL:error: to download it */
1074
1075 CF_EXPORT
1076 const CFStringRef kCFURLUbiquitousItemDownloadingStatusDownloaded CF_AVAILABLE(10_9, 7_0);
1077     /* there is a local version of this item available. The most current version will get downloaded as soon as possible. */
1078
1079 CF_EXPORT
1080 const CFStringRef kCFURLUbiquitousItemDownloadingStatusCurrent CF_AVAILABLE(10_9, 7_0);
1081     /* there is a local version of this item and it is the most up-to-date version known to this device. */
1082
1083
1084 typedef CF_OPTIONS(CFOptionFlags, CFURLBookmarkCreationOptions) {
1085     kCFURLBookmarkCreationMinimalBookmarkMask = ( 1UL << 9 ), // creates bookmark data with "less" information, which may be smaller but still be able to resolve in certain ways
1086     kCFURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), // include the properties required by CFURLWriteBookmarkDataToFile() in the bookmark data created
1087     kCFURLBookmarkCreationWithSecurityScope CF_ENUM_AVAILABLE(10_7, NA) = ( 1UL << 11 ), // Mac OS X 10.7.3 and later, include information in the bookmark data which allows the same sandboxed process to access the resource after being relaunched
1088     kCFURLBookmarkCreationSecurityScopeAllowOnlyReadAccess CF_ENUM_AVAILABLE(10_7, NA) = ( 1UL << 12 ), // Mac OS X 10.7.3 and later, if used with kCFURLBookmarkCreationWithSecurityScope, at resolution time only read access to the resource will be granted
1089
1090     // deprecated
1091     kCFURLBookmarkCreationPreferFileIDResolutionMask CF_ENUM_DEPRECATED(10_6, 10_9, 4_0, 7_0, "kCFURLBookmarkCreationPreferFileIDResolutionMask does nothing and has no effect on bookmark resolution" ) = ( 1UL << 8 ),
1092 } CF_ENUM_AVAILABLE(10_6, 4_0);
1093
1094 typedef CF_OPTIONS(CFOptionFlags, CFURLBookmarkResolutionOptions) {
1095     kCFURLBookmarkResolutionWithoutUIMask = ( 1UL << 8 ), // don't perform any user interaction during bookmark resolution
1096     kCFURLBookmarkResolutionWithoutMountingMask = ( 1UL << 9 ), // don't mount a volume during bookmark resolution
1097     kCFURLBookmarkResolutionWithSecurityScope CF_ENUM_AVAILABLE(10_7, NA) = ( 1UL << 10 ), // Mac OS X 10.7.3 and later, use the secure information included at creation time to provide the ability to access the resource in a sandboxed process.
1098
1099     kCFBookmarkResolutionWithoutUIMask = kCFURLBookmarkResolutionWithoutUIMask,
1100     kCFBookmarkResolutionWithoutMountingMask = kCFURLBookmarkResolutionWithoutMountingMask,
1101 } CF_ENUM_AVAILABLE(10_6, 4_0);
1102
1103 typedef CFOptionFlags CFURLBookmarkFileCreationOptions;
1104
1105 CF_IMPLICIT_BRIDGING_DISABLED
1106
1107 /* Returns bookmark data for the URL, created with specified options and resource properties. If this function returns NULL, the optional error is populated.
1108  */
1109 CF_EXPORT
1110 CFDataRef CFURLCreateBookmarkData ( CFAllocatorRef allocator, CFURLRef url, CFURLBookmarkCreationOptions options, CFArrayRef resourcePropertiesToInclude, CFURLRef relativeToURL, CFErrorRef* error ) CF_AVAILABLE(10_6, 4_0);
1111
1112 /* Return a URL that refers to a location specified by resolving bookmark data. If this function returns NULL, the optional error is populated.
1113  */
1114 CF_EXPORT
1115 CFURLRef CFURLCreateByResolvingBookmarkData ( CFAllocatorRef allocator, CFDataRef bookmark, CFURLBookmarkResolutionOptions options, CFURLRef relativeToURL, CFArrayRef resourcePropertiesToInclude, Boolean* isStale, CFErrorRef* error ) CF_AVAILABLE(10_6, 4_0);
1116
1117 /* Returns the resource propertyies identified by a specified array of keys contained in specified bookmark data. If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available in the bookmark data.
1118  */
1119 CF_EXPORT
1120 CFDictionaryRef CFURLCreateResourcePropertiesForKeysFromBookmarkData ( CFAllocatorRef allocator, CFArrayRef resourcePropertiesToReturn, CFDataRef bookmark ) CF_AVAILABLE(10_6, 4_0);
1121
1122 /*  Returns the resource property identified by a given resource key contained in specified bookmark data. If this function returns NULL, it means the resource property is not available in the bookmark data.
1123  */
1124 CF_EXPORT
1125 CFTypeRef  CFURLCreateResourcePropertyForKeyFromBookmarkData( CFAllocatorRef allocator, CFStringRef resourcePropertyKey, CFDataRef bookmark ) CF_AVAILABLE(10_6, 4_0);
1126
1127 /* Returns bookmark data derived from an alias file referred to by fileURL. If fileURL refers to an alias file created prior to OS X v10.6 that contains Alias Manager information but no bookmark data, this method synthesizes bookmark data for the file. If this method returns NULL, the optional error is populated.
1128  */
1129 CF_EXPORT
1130 CFDataRef CFURLCreateBookmarkDataFromFile(CFAllocatorRef allocator, CFURLRef fileURL, CFErrorRef *errorRef ) CF_AVAILABLE(10_6, 5_0);
1131
1132 /* Creates an alias file on disk at a specified location with specified bookmark data. The bookmark data must have been created with the kCFURLBookmarkCreationSuitableForBookmarkFile option. fileURL must either refer to an existing file (which will be overwritten), or to location in an existing directory. If this method returns FALSE, the optional error is populated.
1133  */
1134 CF_EXPORT
1135 Boolean CFURLWriteBookmarkDataToFile( CFDataRef bookmarkRef, CFURLRef fileURL, CFURLBookmarkFileCreationOptions options, CFErrorRef *errorRef ) CF_AVAILABLE(10_6, 5_0);
1136
1137 /* Returns bookmark data derived from an alias record.
1138  */
1139 CF_EXPORT
1140 CFDataRef CFURLCreateBookmarkDataFromAliasRecord ( CFAllocatorRef allocatorRef, CFDataRef aliasRecordDataRef ) CF_AVAILABLE_MAC(10_6);
1141
1142 CF_IMPLICIT_BRIDGING_ENABLED
1143
1144 /* Given a CFURLRef created by resolving a bookmark data created with security scope, make the resource referenced by the url accessible to the process. When access to this resource is no longer needed the client must call CFURLStopAccessingSecurityScopedResource(). Each call to CFURLStartAccessingSecurityScopedResource() must be balanced with a call to CFURLStopAccessingSecurityScopedResource() (Note: this is not reference counted).
1145  */
1146 CF_EXPORT
1147 Boolean CFURLStartAccessingSecurityScopedResource(CFURLRef url) CF_AVAILABLE(10_7, 8_0); // On OSX, available in MacOS X 10.7.3 and later
1148
1149 /* Revokes the access granted to the url by a prior successful call to CFURLStartAccessingSecurityScopedResource().
1150  */
1151 CF_EXPORT
1152 void CFURLStopAccessingSecurityScopedResource(CFURLRef url) CF_AVAILABLE(10_7, 8_0); // On OSX, available in MacOS X 10.7.3 and later
1153
1154 #endif /* TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE */
1155
1156 CF_EXTERN_C_END
1157 CF_IMPLICIT_BRIDGING_DISABLED
1158
1159 #endif /* ! __COREFOUNDATION_CFURL__ */
1160