1  /*	CFURL.h
   2  	Copyright (c) 1998-2019, Apple Inc. and the Swift project authors
   3   
   4  	Portions Copyright (c) 2014-2019, Apple Inc. and the Swift project authors
   5  	Licensed under Apache License v2.0 with Runtime Library Exception
   6  	See http://swift.org/LICENSE.txt for license information
   7  	See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
   8  */
   9  
  10  #if !defined(__COREFOUNDATION_CFURL__)
  11  #define __COREFOUNDATION_CFURL__ 1
  12  
  13  #include <CoreFoundation/CFBase.h>
  14  #include <CoreFoundation/CFData.h>
  15  #include <CoreFoundation/CFError.h>
  16  #include <CoreFoundation/CFString.h>
  17  
  18  CF_IMPLICIT_BRIDGING_ENABLED
  19  CF_EXTERN_C_BEGIN
  20  
  21  typedef CF_ENUM(CFIndex, CFURLPathStyle) {
  22      kCFURLPOSIXPathStyle = 0,
  23      kCFURLHFSPathStyle API_DEPRECATED("Carbon File Manager is deprecated, use kCFURLPOSIXPathStyle where possible", macos(10.0,10.9), ios(2.0,7.0), watchos(2.0,2.0), tvos(9.0,9.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. */
  24      kCFURLWindowsPathStyle
  25  };
  26      
  27  typedef const struct CF_BRIDGED_TYPE(NSURL) __CFURL * CFURLRef;
  28  
  29  /* CFURLs are composed of two fundamental pieces - their string, and a */
  30  /* (possibly NULL) base URL.  A relative URL is one in which the string */
  31  /* by itself does not fully specify the URL (for instance "myDir/image.tiff"); */
  32  /* an absolute URL is one in which the string does fully specify the URL */
  33  /* ("file://localhost/myDir/image.tiff").  Absolute URLs always have NULL */
  34  /* base URLs; however, it is possible for a URL to have a NULL base, and still */
  35  /* not be absolute.  Such a URL has only a relative string, and cannot be */
  36  /* resolved.  Two CFURLs are considered equal if and only if their strings */
  37  /* are equal and their bases are equal.  In other words, */
  38  /* "file://localhost/myDir/image.tiff" is NOT equal to the URL with relative */
  39  /* string "myDir/image.tiff" and base URL "file://localhost/".  Clients that */
  40  /* need these less strict form of equality should convert all URLs to their */
  41  /* absolute form via CFURLCopyAbsoluteURL(), then compare the absolute forms. */
  42  
  43  CF_EXPORT
  44  CFTypeID CFURLGetTypeID(void);
  45  
  46  /* encoding will be used both to interpret the bytes of URLBytes, and to */
  47  /* interpret any percent-escapes within the bytes. */
  48  /* Using a string encoding which isn't a superset of ASCII encoding is not */
  49  /* supported because CFURLGetBytes and CFURLGetByteRangeForComponent require */
  50  /* 7-bit ASCII characters to be stored in a single 8-bit byte. */
  51  /* CFStringEncodings which are a superset of ASCII encoding include MacRoman, */
  52  /* WindowsLatin1, ISOLatin1, NextStepLatin, ASCII, and UTF8. */
  53  CF_EXPORT
  54  CFURLRef CFURLCreateWithBytes(CFAllocatorRef allocator, const UInt8 *URLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL);
  55  
  56  /* Escapes any character that is not 7-bit ASCII with the byte-code */
  57  /* for the given encoding.  If escapeWhitespace is true, whitespace */
  58  /* characters (' ', '\t', '\r', '\n') will be escaped also (desirable */
  59  /* if embedding the URL into a larger text stream like HTML) */
  60  CF_EXPORT
  61  CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace);
  62  
  63  /* Any percent-escape sequences in URLString will be interpreted via UTF-8. URLString must be a valid URL string. */
  64  CF_EXPORT
  65  CFURLRef CFURLCreateWithString(CFAllocatorRef allocator, CFStringRef URLString, CFURLRef baseURL);
  66  
  67  /* Create an absolute URL directly, without requiring the extra step */
  68  /* of calling CFURLCopyAbsoluteURL().  If useCompatibilityMode is  */
  69  /* true, the rules historically used on the web are used to resolve */
  70  /* relativeString against baseURL - these rules are generally listed */
  71  /* in the RFC as optional or alternate interpretations.  Otherwise, */
  72  /* the strict rules from the RFC are used.  The major differences are */
  73  /* that in compatibility mode, we are lenient of the scheme appearing */
  74  /* in relative portion, leading "../" components are removed from the */
  75  /* final URL's path, and if the relative portion contains only */
  76  /* resource specifier pieces (query, parameters, and fragment), then */
  77  /* the last path component of the base URL will not be deleted.  */
  78  /* Using a string encoding which isn't a superset of ASCII encoding is not */
  79  /* supported because CFURLGetBytes and CFURLGetByteRangeForComponent require */
  80  /* 7-bit ASCII characters to be stored in a single 8-bit byte. */
  81  /* CFStringEncodings which are a superset of ASCII encoding include MacRoman, */
  82  /* WindowsLatin1, ISOLatin1, NextStepLatin, ASCII, and UTF8. */
  83  CF_EXPORT
  84  CFURLRef CFURLCreateAbsoluteURLWithBytes(CFAllocatorRef alloc, const UInt8 *relativeURLBytes, CFIndex length, CFStringEncoding encoding, CFURLRef baseURL, Boolean useCompatibilityMode);
  85  
  86  /* filePath should be the URL's path expressed as a path of the type */
  87  /* fsType.  If filePath is not absolute, the resulting URL will be */
  88  /* considered relative to the current working directory (evaluated */
  89  /* at creation time).  isDirectory determines whether filePath is */
  90  /* treated as a directory path when resolving against relative path */
  91  /* components */
  92  CF_EXPORT
  93  CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory);
  94  
  95  CF_EXPORT
  96  CFURLRef CFURLCreateFromFileSystemRepresentation(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory);
  97  
  98  /* The path style of the baseURL must match the path style of the relative */
  99  /* url or the results are undefined.  If the provided filePath looks like an */
 100  /* absolute path ( starting with '/' if pathStyle is kCFURLPosixPathStyle, */
 101  /* not starting with ':' for kCFURLHFSPathStyle, or starting with what looks */
 102  /* like a drive letter and colon for kCFURLWindowsPathStyle ) then the baseURL */
 103  /* is ignored. */
 104  CF_EXPORT
 105  CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL); 
 106  
 107  CF_EXPORT
 108  CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase(CFAllocatorRef allocator, const UInt8 *buffer, CFIndex bufLen, Boolean isDirectory, CFURLRef baseURL);
 109                                                                           
 110  /* Fills buffer with the file system's native representation of */
 111  /* url's path. No more than maxBufLen bytes are written to buffer. */
 112  /* The buffer should be at least the maximum path length for */
 113  /* the file system in question to avoid failures for insufficiently */
 114  /* large buffers.  If resolveAgainstBase is true, the url's relative */
 115  /* portion is resolved against its base before the path is computed. */
 116  /* Returns success or failure. */
 117  CF_EXPORT
 118  Boolean CFURLGetFileSystemRepresentation(CFURLRef url, Boolean resolveAgainstBase, UInt8 *buffer, CFIndex maxBufLen);
 119  
 120  /* Creates a new URL by resolving the relative portion of relativeURL against its base. */
 121  CF_EXPORT
 122  CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL);
 123  
 124  /* Returns the URL's string. Percent-escape sequences are not removed. */
 125  CF_EXPORT
 126  CFStringRef CFURLGetString(CFURLRef anURL);
 127  
 128  /* Returns the base URL if it exists */
 129  CF_EXPORT
 130  CFURLRef CFURLGetBaseURL(CFURLRef anURL);
 131  
 132  /*
 133  All URLs can be broken into two pieces - the scheme (preceding the
 134  first colon) and the resource specifier (following the first colon).
 135  Most URLs are also "standard" URLs conforming to RFC 1808 (available
 136  from www.w3c.org).  This category includes URLs of the file, http,
 137  https, and ftp schemes, to name a few.  Standard URLs start the
 138  resource specifier with two slashes ("//"), and can be broken into
 139  four distinct pieces - the scheme, the net location, the path, and
 140  further resource specifiers (typically an optional parameter, query,
 141  and/or fragment).  The net location appears immediately following
 142  the two slashes and goes up to the next slash; it's format is
 143  scheme-specific, but is usually composed of some or all of a username,
 144  password, host name, and port.  The path is a series of path components
 145  separated by slashes; if the net location is present, the path always
 146  begins with a slash.  Standard URLs can be relative to another URL,
 147  in which case at least the scheme and possibly other pieces as well
 148  come from the base URL (see RFC 1808 for precise details when resolving
 149  a relative URL against its base).  The full URL is therefore
 150  
 151  <scheme> "://" <net location> <path, always starting with slash> <add'l resource specifiers>
 152  
 153  If a given CFURL can be decomposed (that is, conforms to RFC 1808), you
 154  can ask for each of the four basic pieces (scheme, net location, path,
 155  and resource specifer) separately, as well as for its base URL.  The
 156  basic pieces are returned with any percent-escape sequences still in
 157  place (although note that the scheme may not legally include any
 158  percent-escapes); this is to allow the caller to distinguish between
 159  percent-escape sequences that may have syntactic meaning if replaced by the
 160  character being escaped (for instance, a '/' in a path component).
 161  Since only the individual schemes know which characters are
 162  syntactically significant, CFURL cannot safely replace any percent-
 163  escape sequences.  However, you can use
 164  CFURLCreateStringByReplacingPercentEscapes() to create a new string with
 165  the percent-escapes removed; see below.
 166  
 167  If a given CFURL can not be decomposed, you can ask for its scheme and its
 168  resource specifier; asking it for its net location or path will return NULL.
 169  
 170  To get more refined information about the components of a decomposable
 171  CFURL, you may ask for more specific pieces of the URL, expressed with
 172  the percent-escapes removed.  The available functions are CFURLCopyHostName(),
 173  CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(),
 174  CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and
 175  CFURLCopyFragment().  Because the parameters, query, and fragment of an
 176  URL may contain scheme-specific syntaxes, these methods take a second
 177  argument, giving a list of characters which should NOT be replaced if
 178  percent-escaped.  For instance, the ftp parameter syntax gives simple
 179  key-value pairs as "<key>=<value>;"  Clearly if a key or value includes
 180  either '=' or ';', it must be escaped to avoid corrupting the meaning of
 181  the parameters, so the caller may request the parameter string as
 182  
 183  CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%"));
 184  
 185  requesting that all percent-escape sequences be replaced by the represented
 186  characters, except for escaped '=', '%' or ';' characters.  Pass the empty
 187  string (CFSTR("")) to request that all percent-escapes be replaced, or NULL
 188  to request that none be.
 189  */
 190  
 191  /* Returns true if anURL conforms to RFC 1808 */
 192  CF_EXPORT
 193  Boolean CFURLCanBeDecomposed(CFURLRef anURL); 
 194  
 195  CF_EXPORT
 196  CFStringRef CFURLCopyScheme(CFURLRef anURL);
 197  
 198  /* Percent-escape sequences are not removed. NULL if CFURLCanBeDecomposed(anURL) is false */
 199  CF_EXPORT
 200  CFStringRef CFURLCopyNetLocation(CFURLRef anURL); 
 201  
 202  /* NULL if CFURLCanBeDecomposed(anURL) is false; also does not resolve the URL */
 203  /* against its base.  See also CFURLCopyAbsoluteURL().  Note that, strictly */
 204  /* speaking, any leading '/' is not considered part of the URL's path, although */
 205  /* its presence or absence determines whether the path is absolute. */
 206  /* CFURLCopyPath()'s return value includes any leading slash (giving the path */
 207  /* the normal POSIX appearance); CFURLCopyStrictPath()'s return value omits any */
 208  /* leading slash, and uses isAbsolute to report whether the URL's path is absolute. */
 209  
 210  /* Percent-escape sequences are not removed. */
 211  CF_EXPORT
 212  CFStringRef CFURLCopyPath(CFURLRef anURL);
 213  
 214  /* Percent-escape sequences are not removed. */
 215  CF_EXPORT
 216  CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute);
 217  
 218  /* CFURLCopyFileSystemPath() returns the URL's path as a file system path for the */
 219  /* given path style.  All percent-escape sequences are removed.  The URL is not */
 220  /* resolved against its base before computing the path. */
 221  CF_EXPORT
 222  CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle);
 223  
 224  /* Returns whether anURL's path represents a directory */
 225  /* (true returned) or a simple file (false returned) */
 226  CF_EXPORT
 227  Boolean CFURLHasDirectoryPath(CFURLRef anURL);
 228  
 229  /* Any additional resource specifiers after the path.  For URLs */
 230  /* that cannot be decomposed, this is everything except the scheme itself. */
 231  /* Percent-escape sequences are not removed. */
 232  CF_EXPORT
 233  CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL); 
 234  
 235  /* Percent-escape sequences are removed. */
 236  CF_EXPORT
 237  CFStringRef CFURLCopyHostName(CFURLRef anURL);
 238  
 239  CF_EXPORT
 240  SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */
 241  
 242  /* Percent-escape sequences are removed. */
 243  CF_EXPORT
 244  CFStringRef CFURLCopyUserName(CFURLRef anURL);
 245  
 246  /* Percent-escape sequences are removed. */
 247  CF_EXPORT
 248  CFStringRef CFURLCopyPassword(CFURLRef anURL);
 249  
 250  /* CFURLCopyParameterString, CFURLCopyQueryString, and CFURLCopyFragment */
 251  /* remove all percent-escape sequences except those for */
 252  /* characters in charactersToLeaveEscaped.  If charactersToLeaveEscaped */
 253  /* is empty (""), all percent-escape sequences are replaced by their */
 254  /* corresponding characters.  If charactersToLeaveEscaped is NULL, */
 255  /* then no escape sequences are removed at all */
 256  CF_EXPORT
 257  CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped) API_DEPRECATED("The CFURLCopyParameterString function is deprecated. Post deprecation for applications linked with or after the macOS 10.15, and for all iOS, watchOS, and tvOS applications, CFURLCopyParameterString will always return NULL, and the CFURLCopyPath(), CFURLCopyStrictPath(), and CFURLCopyFileSystemPath() functions will return the complete path including the semicolon separator and params component if the URL string contains them.", macosx(10.2,10.15), ios(2.0,13.0), watchos(2.0,6.0), tvos(9.0,13.0));
 258  CF_EXPORT
 259  CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 260  
 261  CF_EXPORT
 262  CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped);
 263  
 264  /* Percent-escape sequences are removed. */
 265  CF_EXPORT
 266  CFStringRef CFURLCopyLastPathComponent(CFURLRef url);
 267  
 268  /* Percent-escape sequences are removed. */
 269  CF_EXPORT
 270  CFStringRef CFURLCopyPathExtension(CFURLRef url);
 271  
 272  CF_EXPORT
 273  CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory);
 274  
 275  CF_EXPORT
 276  CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url);
 277  
 278  CF_EXPORT
 279  CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension);
 280  
 281  CF_EXPORT
 282  CFURLRef CFURLCreateCopyDeletingPathExtension(CFAllocatorRef allocator, CFURLRef url);
 283  
 284  /* Fills buffer with the bytes for url, returning the number of bytes */
 285  /* filled.  If buffer is of insufficient size, returns -1 and no bytes */
 286  /* are placed in buffer.  If buffer is NULL, the needed length is */
 287  /* computed and returned.  The returned bytes are the original bytes */ 
 288  /* from which the URL was created; if the URL was created from a */
 289  /* string, the bytes will be the bytes of the string encoded via UTF-8. */
 290  /* */
 291  /* Note: Due to incompatibilities between encodings, it might be impossible to */
 292  /* generate bytes from the base URL in the encoding of the relative URL or relative bytes, */
 293  /* which will cause this method to fail and return -1, even if a NULL buffer is passed.  */
 294  /* To avoid this scenario, use UTF-8, UTF-16, or UTF-32 encodings exclusively, or */
 295  /* use one non-Unicode encoding exclusively. */
 296  CF_EXPORT
 297  CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength);
 298  
 299  typedef CF_ENUM(CFIndex, CFURLComponentType) {
 300  	kCFURLComponentScheme = 1,
 301  	kCFURLComponentNetLocation = 2,
 302  	kCFURLComponentPath = 3,
 303  	kCFURLComponentResourceSpecifier = 4,
 304  
 305  	kCFURLComponentUser = 5,
 306  	kCFURLComponentPassword = 6,
 307  	kCFURLComponentUserInfo = 7,
 308  	kCFURLComponentHost = 8,
 309  	kCFURLComponentPort = 9,
 310  	kCFURLComponentParameterString = 10,
 311  	kCFURLComponentQuery = 11,
 312  	kCFURLComponentFragment = 12
 313  };
 314   
 315  /* 
 316  Gets the  range of the requested component in the bytes of url, as
 317  returned by CFURLGetBytes().  This range is only good for use in the
 318  bytes returned by CFURLGetBytes!
 319  
 320  If non-NULL, rangeIncludingSeparators gives the range of component
 321  including the sequences that separate component from the previous and
 322  next components.  If there is no previous or next component, that end of
 323  rangeIncludingSeparators will match the range of the component itself.
 324  If url does not contain the given component type, (kCFNotFound, 0) is
 325  returned, and rangeIncludingSeparators is set to the location where the
 326  component would be inserted.  Some examples -
 327  
 328  For the URL http://www.apple.com/hotnews/
 329  
 330  Component           returned range      rangeIncludingSeparators
 331  scheme              (0, 4)              (0, 7)
 332  net location        (7, 13)             (4, 16)
 333  path                (20, 9)             (20, 9)    
 334  resource specifier  (kCFNotFound, 0)    (29, 0)
 335  user                (kCFNotFound, 0)    (7, 0)
 336  password            (kCFNotFound, 0)    (7, 0)
 337  user info           (kCFNotFound, 0)    (7, 0)
 338  host                (7, 13)             (4, 16)
 339  port                (kCFNotFound, 0)    (20, 0)
 340  parameter           (kCFNotFound, 0)    (29, 0)
 341  query               (kCFNotFound, 0)    (29, 0)
 342  fragment            (kCFNotFound, 0)    (29, 0)
 343  
 344  
 345  For the URL ./relPath/file.html#fragment
 346  
 347  Component           returned range      rangeIncludingSeparators
 348  scheme              (kCFNotFound, 0)    (0, 0)
 349  net location        (kCFNotFound, 0)    (0, 0)
 350  path                (0, 19)             (0, 20)
 351  resource specifier  (20, 8)             (19, 9)
 352  user                (kCFNotFound, 0)    (0, 0)
 353  password            (kCFNotFound, 0)    (0, 0)
 354  user info           (kCFNotFound, 0)    (0, 0)
 355  host                (kCFNotFound, 0)    (0, 0)
 356  port                (kCFNotFound, 0)    (0, 0)
 357  parameter           (kCFNotFound, 0)    (19, 0)
 358  query               (kCFNotFound, 0)    (19, 0)
 359  fragment            (20, 8)             (19, 9)
 360  
 361  
 362  For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment
 363  
 364  Component           returned range      rangeIncludingSeparators
 365  scheme              (0, 6)              (0, 9)
 366  net location        (9, 16)             (6, 19)
 367  path                (25, 21)            (25, 22) 
 368  resource specifier  (47, 21)            (46, 22)
 369  user                (9, 4)              (6, 8)
 370  password            (14, 4)             (13, 6)
 371  user info           (9, 9)              (6, 13)
 372  host                (19, 4)             (18, 6)
 373  port                (24, 1)             (23, 2)
 374  parameter           (47, 6)             (46, 8)
 375  query               (54, 5)             (53, 7)
 376  fragment            (60, 8)             (59, 9)
 377  */
 378  CF_EXPORT
 379  CFRange CFURLGetByteRangeForComponent(CFURLRef url, CFURLComponentType component, CFRange *rangeIncludingSeparators);
 380  
 381  /* Returns a string with any percent-escape sequences that do NOT */
 382  /* correspond to characters in charactersToLeaveEscaped with their */
 383  /* equivalent.  Returns NULL on failure (if an invalid percent-escape sequence */
 384  /* is encountered), or the original string (retained) if no characters */
 385  /* need to be replaced. Pass NULL to request that no percent-escapes be */
 386  /* replaced, or the empty string (CFSTR("")) to request that all percent- */
 387  /* escapes be replaced.  Uses UTF8 to interpret percent-escapes. */
 388  CF_EXPORT
 389  CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped);
 390  
 391  /* As above, but allows you to specify the encoding to use when interpreting percent-escapes */
 392  CF_EXPORT
 393  CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding(CFAllocatorRef allocator, CFStringRef origString, CFStringRef charsToLeaveEscaped, CFStringEncoding encoding) API_DEPRECATED("Use [NSString stringByRemovingPercentEncoding] or CFURLCreateStringByReplacingPercentEscapes() instead, which always uses the recommended UTF-8 encoding.", macos(10.0,10.11), ios(2.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0));
 394  
 395  /* Creates a copy or originalString, replacing certain characters with */
 396  /* the equivalent percent-escape sequence based on the encoding specified. */
 397  /* If the originalString does not need to be modified (no percent-escape */
 398  /* sequences are missing), may retain and return originalString. */
 399  /* If you are uncertain of the correct encoding, you should use UTF-8, */
 400  /* which is the encoding designated by RFC 2396 as the correct encoding */
 401  /* for use in URLs.  The characters so escaped are all characters that */
 402  /* are not legal URL characters (based on RFC 2396), plus any characters */
 403  /* in legalURLCharactersToBeEscaped, less any characters in */
 404  /* charactersToLeaveUnescaped.  To simply correct any non-URL characters */
 405  /* in an otherwise correct URL string, do: */
 406  /*      newString = CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, origString, NULL, NULL, kCFStringEncodingUTF8); */
 407  CF_EXPORT
 408  CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding) API_DEPRECATED("Use [NSString stringByAddingPercentEncodingWithAllowedCharacters:] instead, which always uses the recommended UTF-8 encoding, and which encodes for a specific URL component or subcomponent (since each URL component or subcomponent has different rules for what characters are valid).", macos(10.0,10.11), ios(2.0,9.0), watchos(2.0,2.0), tvos(9.0,9.0));
 409  
 410  
 411  #if TARGET_OS_MAC || CF_BUILDING_CF || NSBUILDINGFOUNDATION
 412  CF_IMPLICIT_BRIDGING_DISABLED
 413  
 414  /*
 415      CFURLIsFileReferenceURL
 416  
 417      Returns whether the URL is a file reference URL.
 418  
 419      Parameters
 420          url
 421              The URL specifying the resource.
 422   */
 423  CF_EXPORT
 424  Boolean CFURLIsFileReferenceURL(CFURLRef url) API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
 425  
 426  /*
 427      CFURLCreateFileReferenceURL
 428      
 429      Returns a new file reference URL that refers to the same resource as a specified URL.
 430  
 431      Parameters
 432          allocator
 433              The memory allocator for creating the new URL.
 434          url
 435              The file URL specifying the resource.
 436          error
 437              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.
 438  
 439      Return Value
 440          The new file reference URL, or NULL if an error occurs.
 441  
 442      Discussion
 443          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.
 444          Symbol is present in iOS 4, but performs no operation.
 445   */
 446  CF_EXPORT
 447  CFURLRef CFURLCreateFileReferenceURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 448  
 449  
 450  /*
 451      CFURLCreateFilePathURL
 452      
 453      Returns a new file path URL that refers to the same resource as a specified URL.
 454  
 455      Parameters
 456          allocator
 457              The memory allocator for creating the new URL.
 458          url
 459              The file URL specifying the resource.
 460          error
 461              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.
 462  
 463      Return Value
 464          The new file path URL, or NULL if an error occurs.
 465  
 466      Discussion
 467          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.
 468          Symbol is present in iOS 4, but performs no operation.
 469   */
 470  CF_EXPORT
 471  CFURLRef CFURLCreateFilePathURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 472  
 473  CF_IMPLICIT_BRIDGING_ENABLED
 474  #endif
 475  
 476  
 477  
 478  #if TARGET_OS_MAC || CF_BUILDING_CF || NSBUILDINGFOUNDATION || DEPLOYMENT_RUNTIME_SWIFT
 479  CF_IMPLICIT_BRIDGING_DISABLED
 480  
 481  /* Resource access
 482  
 483      The behavior of resource value caching is slightly different between the NSURL and CFURL API.
 484  
 485      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.
 486  
 487      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.
 488   */
 489  
 490  
 491  /*
 492      CFURLCopyResourcePropertyForKey
 493      
 494      Returns the resource value identified by a given resource key.
 495  
 496      Parameters
 497          url
 498              The URL specifying the resource.
 499          key
 500              The resource key that identifies the resource property.
 501          propertyValueTypeRefPtr
 502              On output when the result is true, the resource value or NULL.
 503          error
 504              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.
 505  
 506      Return Value
 507          true if propertyValueTypeRefPtr is successfully populated; false if an error occurs.
 508  
 509      Discussion
 510          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.
 511          Symbol is present in iOS 4, but performs no operation.
 512   */
 513  CF_EXPORT
 514  Boolean CFURLCopyResourcePropertyForKey(CFURLRef url, CFStringRef key, void *propertyValueTypeRefPtr, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 515  
 516  
 517  /*
 518      CFURLCopyResourcePropertiesForKeys
 519      
 520      Returns the resource values identified by specified array of resource keys.
 521  
 522      Parameters
 523          url
 524              The URL specifying the resource.
 525          keys
 526              An array of resource keys that identify the resource properties.
 527          error
 528              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.
 529  
 530      Return Value
 531          A dictionary of resource values indexed by resource key; NULL if an error occurs.
 532  
 533      Discussion
 534          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.
 535          Symbol is present in iOS 4, but performs no operation.
 536   */
 537  CF_EXPORT
 538  CFDictionaryRef CFURLCopyResourcePropertiesForKeys(CFURLRef url, CFArrayRef keys, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 539  
 540  
 541  /*
 542      CFURLSetResourcePropertyForKey
 543      
 544      Sets the resource value identified by a given resource key.
 545  
 546      Parameters
 547          url
 548              The URL specifying the resource.
 549          key
 550              The resource key that identifies the resource property.
 551          propertyValue
 552              The resource value.
 553          error
 554              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.
 555  
 556      Return Value
 557          true if the attempt to set the resource value completed with no errors; otherwise, false.
 558  
 559      Discussion
 560          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.
 561          Symbol is present in iOS 4, but performs no operation.
 562   */
 563  CF_EXPORT
 564  Boolean CFURLSetResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertyValue, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 565  
 566  
 567  /*
 568      CFURLSetResourcePropertiesForKeys
 569      
 570      Sets any number of resource values of a URL's resource.
 571  
 572      Parameters
 573          url
 574              The URL specifying the resource.
 575          keyedPropertyValues
 576              A dictionary of resource values indexed by resource keys.
 577          error
 578              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.
 579  
 580      Return Value
 581          true if the attempt to set the resource values completed with no errors; otherwise, false.
 582  
 583      Discussion
 584          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.
 585          Symbol is present in iOS 4, but performs no operation.
 586   */
 587  CF_EXPORT
 588  Boolean CFURLSetResourcePropertiesForKeys(CFURLRef url, CFDictionaryRef keyedPropertyValues, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 589  
 590  
 591  CF_EXPORT
 592  const CFStringRef kCFURLKeysOfUnsetValuesKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 593      /* 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. */
 594  
 595  
 596  /*
 597      CFURLClearResourcePropertyCacheForKey
 598      
 599      Discards a cached resource value of a URL.
 600  
 601      Parameters
 602          url
 603              The URL specifying the resource.
 604          key
 605              The resource key that identifies the resource property.
 606  
 607      Discussion
 608          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.
 609          Symbol is present in iOS 4, but performs no operation.
 610   */
 611  CF_EXPORT
 612  void CFURLClearResourcePropertyCacheForKey(CFURLRef url, CFStringRef key) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 613  
 614  
 615  /*
 616      CFURLClearResourcePropertyCache
 617      
 618      Discards all cached resource values of a URL.
 619  
 620      Parameters
 621          url
 622              The URL specifying the resource.
 623  
 624      Discussion
 625          All temporary properties are also cleared from the URL object's cache. This function is currently applicable only to URLs for file system resources.
 626          Symbol is present in iOS 4, but performs no operation.
 627   */
 628  CF_EXPORT
 629  void CFURLClearResourcePropertyCache(CFURLRef url) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 630  
 631  
 632  /*
 633      CFURLSetTemporaryResourcePropertyForKey
 634      
 635      Sets a temporary resource value on the URL object.
 636  
 637      Parameters
 638          url
 639              The URL object.
 640          key
 641              The resource key that identifies the temporary resource property.
 642          propertyValue
 643              The resource value.
 644  
 645      Discussion
 646          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.
 647          Symbol is present in iOS 4, but performs no operation.
 648   */
 649  CF_EXPORT
 650  void CFURLSetTemporaryResourcePropertyForKey(CFURLRef url, CFStringRef key, CFTypeRef propertyValue) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 651  
 652  
 653  /*
 654      CFURLResourceIsReachable
 655      
 656      Returns whether the URL's resource exists and is reachable.
 657  
 658      Parameters
 659          url
 660              The URL object.
 661          error
 662              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.
 663  
 664      Return Value
 665          true if the resource is reachable; otherwise, false.
 666  
 667      Discussion
 668          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. 
 669          Symbol is present in iOS 4, but performs no operation.
 670   */
 671  CF_EXPORT
 672  Boolean CFURLResourceIsReachable(CFURLRef url, CFErrorRef *error) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 673  
 674  CF_IMPLICIT_BRIDGING_ENABLED
 675  
 676  
 677  /* Properties of File System Resources */
 678  
 679  CF_EXPORT 
 680  const CFStringRef kCFURLNameKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 681      /* The resource name provided by the file system (Read-write, value type CFString) */
 682  
 683  CF_EXPORT
 684  const CFStringRef kCFURLLocalizedNameKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 685      /* Localized or extension-hidden name as displayed to users (Read-only, value type CFString) */
 686  
 687  CF_EXPORT
 688  const CFStringRef kCFURLIsRegularFileKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 689      /* True for regular files (Read-only, value type CFBoolean) */
 690  
 691  CF_EXPORT
 692  const CFStringRef kCFURLIsDirectoryKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 693      /* True for directories (Read-only, CFBoolean) */
 694  
 695  CF_EXPORT
 696  const CFStringRef kCFURLIsSymbolicLinkKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 697      /* True for symlinks (Read-only, value type CFBoolean) */
 698  
 699  CF_EXPORT
 700  const CFStringRef kCFURLIsVolumeKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 701      /* True for the root directory of a volume (Read-only, value type CFBoolean) */
 702  
 703  CF_EXPORT
 704  const CFStringRef kCFURLIsPackageKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 705      /* 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. */
 706  
 707  CF_EXPORT
 708  const CFStringRef kCFURLIsApplicationKey API_AVAILABLE(macos(10.11), ios(9.0), watchos(2.0), tvos(9.0));
 709      /* True if resource is an application (Read-only, value type CFBoolean) */
 710  
 711  CF_EXPORT
 712  const CFStringRef kCFURLApplicationIsScriptableKey API_AVAILABLE(macos(10.11)) API_UNAVAILABLE(ios, watchos, tvos);
 713      /* True if the resource is scriptable. Only applies to applications. (Read-only, value type CFBoolean) */
 714  
 715  CF_EXPORT
 716  const CFStringRef kCFURLIsSystemImmutableKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 717      /* True for system-immutable resources (Read-write, value type CFBoolean) */
 718  
 719  CF_EXPORT
 720  const CFStringRef kCFURLIsUserImmutableKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 721      /* True for user-immutable resources (Read-write, value type CFBoolean) */
 722  
 723  CF_EXPORT
 724  const CFStringRef kCFURLIsHiddenKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 725      /* 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. */
 726  
 727  CF_EXPORT
 728  const CFStringRef kCFURLHasHiddenExtensionKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 729      /* True for resources whose filename extension is removed from the localized name property (Read-write, value type CFBoolean) */
 730  
 731  CF_EXPORT
 732  const CFStringRef kCFURLCreationDateKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 733      /* The date the resource was created (Read-write, value type CFDate) */
 734  
 735  CF_EXPORT
 736  const CFStringRef kCFURLContentAccessDateKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 737      /* The date the resource was last accessed (Read-write, value type CFDate) */
 738  
 739  CF_EXPORT
 740  const CFStringRef kCFURLContentModificationDateKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 741      /* The time the resource content was last modified (Read-write, value type CFDate) */
 742  
 743  CF_EXPORT
 744  const CFStringRef kCFURLAttributeModificationDateKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 745      /* The time the resource's attributes were last modified (Read-only, value type CFDate) */
 746  
 747  CF_EXPORT
 748  const CFStringRef kCFURLFileContentIdentifierKey API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0));
 749      /* A 64-bit value assigned by APFS that identifies a file's content data stream. Only cloned files and their originals can have the same identifier. (CFNumber) */
 750  
 751  CF_EXPORT
 752  const CFStringRef kCFURLMayShareFileContentKey API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0));
 753      /* True for cloned files and their originals that may share all, some, or no data blocks. (CFBoolean) */
 754  
 755  CF_EXPORT
 756  const CFStringRef kCFURLMayHaveExtendedAttributesKey API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0));
 757      /* True if the file has extended attributes. False guarantees there are none. (CFBoolean) */
 758  
 759  CF_EXPORT
 760  const CFStringRef kCFURLIsPurgeableKey API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0));
 761      /* True if the file can be deleted by the file system when asked to free space. (CFBoolean) */
 762  
 763  CF_EXPORT
 764  const CFStringRef kCFURLIsSparseKey API_AVAILABLE(macos(10.16), ios(14.0), watchos(7.0), tvos(14.0));
 765      /* True if the file has sparse regions. (CFBoolean) */
 766  
 767  CF_EXPORT
 768  const CFStringRef kCFURLLinkCountKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 769      /* Number of hard links to the resource (Read-only, value type CFNumber) */
 770  
 771  CF_EXPORT
 772  const CFStringRef kCFURLParentDirectoryURLKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 773      /* The resource's parent directory, if any (Read-only, value type CFURL) */
 774  
 775  CF_EXPORT
 776  const CFStringRef kCFURLVolumeURLKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 777      /* URL of the volume on which the resource is stored (Read-only, value type CFURL) */
 778  
 779  CF_EXPORT
 780  const CFStringRef kCFURLTypeIdentifierKey API_DEPRECATED("Use NSURLContentTypeKey instead", macos(10.6, API_TO_BE_DEPRECATED), ios(4.0, API_TO_BE_DEPRECATED), watchos(2.0, API_TO_BE_DEPRECATED), tvos(9.0, API_TO_BE_DEPRECATED));
 781      /* Uniform type identifier (UTI) for the resource (Read-only, value type CFString) */
 782  
 783  CF_EXPORT
 784  const CFStringRef kCFURLLocalizedTypeDescriptionKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 785      /* User-visible type or "kind" description (Read-only, value type CFString) */
 786  
 787  CF_EXPORT
 788  const CFStringRef kCFURLLabelNumberKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 789      /* The label number assigned to the resource (Read-write, value type CFNumber) */
 790  
 791  CF_EXPORT
 792  const CFStringRef kCFURLLabelColorKey API_DEPRECATED("Use NSURLLabelColorKey", macosx(10.6, 10.12), ios(4.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0));
 793      /* not implemented */
 794  
 795  CF_EXPORT
 796  const CFStringRef kCFURLLocalizedLabelKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 797      /* The user-visible label text (Read-only, value type CFString) */
 798  
 799  CF_EXPORT
 800  const CFStringRef kCFURLEffectiveIconKey API_DEPRECATED("Use NSURLEffectiveIconKey", macosx(10.6, 10.12), ios(4.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0));
 801      /* not implemented */
 802  
 803  CF_EXPORT
 804  const CFStringRef kCFURLCustomIconKey API_DEPRECATED("Use NSURLCustomIconKey", macosx(10.6, 10.12), ios(4.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0));
 805      /* not implemented */
 806  
 807  CF_EXPORT
 808  const CFStringRef kCFURLFileResourceIdentifierKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 809      /* 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) */
 810  
 811  CF_EXPORT
 812  const CFStringRef kCFURLVolumeIdentifierKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 813      /* 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) */
 814  
 815  CF_EXPORT
 816  const CFStringRef kCFURLPreferredIOBlockSizeKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 817      /* The optimal block size when reading or writing this file's data, or NULL if not available. (Read-only, value type CFNumber) */
 818  
 819  CF_EXPORT
 820  const CFStringRef kCFURLIsReadableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 821      /* true if this process (as determined by EUID) can read the resource. (Read-only, value type CFBoolean) */
 822  
 823  CF_EXPORT
 824  const CFStringRef kCFURLIsWritableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 825      /* true if this process (as determined by EUID) can write to the resource. (Read-only, value type CFBoolean) */
 826  
 827  CF_EXPORT
 828  const CFStringRef kCFURLIsExecutableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 829      /* true if this process (as determined by EUID) can execute a file resource or search a directory resource. (Read-only, value type CFBoolean) */
 830  
 831  CF_EXPORT
 832  const CFStringRef kCFURLFileSecurityKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 833      /* The file system object's security information encapsulated in a CFFileSecurity object. (Read-write, value type CFFileSecurity) */
 834  
 835  CF_EXPORT
 836  const CFStringRef kCFURLIsExcludedFromBackupKey API_AVAILABLE(macos(10.8), ios(5.1), watchos(2.0), tvos(9.0));
 837      /* 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. */
 838  
 839  CF_EXPORT
 840  const CFStringRef kCFURLTagNamesKey API_AVAILABLE(macos(10.9)) API_UNAVAILABLE(ios, watchos, tvos);
 841      /* The array of Tag names (Read-write, value type CFArray of CFString) */
 842      
 843  CF_EXPORT
 844  const CFStringRef kCFURLPathKey API_AVAILABLE(macos(10.8), ios(6.0), watchos(2.0), tvos(9.0));
 845      /* the URL's path as a file system path (Read-only, value type CFString) */
 846  
 847  CF_EXPORT
 848  const CFStringRef kCFURLCanonicalPathKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
 849      /* the URL's path as a canonical absolute file system path (Read-only, value type CFString) */
 850  
 851  CF_EXPORT
 852  const CFStringRef kCFURLIsMountTriggerKey API_AVAILABLE(macos(10.7), ios(4.0), watchos(2.0), tvos(9.0));
 853      /* 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) */
 854  
 855  CF_EXPORT
 856  const CFStringRef kCFURLGenerationIdentifierKey API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
 857      /* 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) */
 858  
 859  CF_EXPORT
 860  const CFStringRef kCFURLDocumentIdentifierKey API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
 861      /* 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) */
 862  
 863  CF_EXPORT
 864  const CFStringRef kCFURLAddedToDirectoryDateKey API_AVAILABLE(macos(10.10), ios(8.0), watchos(2.0), tvos(9.0));
 865      /* 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 before macOS 10.15, iOS 13.0, watchOS 6.0, and tvOS 13.0; Read-write after, value type CFDate) */
 866  
 867  CF_EXPORT
 868  const CFStringRef kCFURLQuarantinePropertiesKey API_AVAILABLE(macos(10.10)) API_UNAVAILABLE(ios, watchos, tvos);
 869      /* 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) */
 870  
 871  CF_EXPORT
 872  const CFStringRef kCFURLFileResourceTypeKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 873      /* Returns the file system object type. (Read-only, value type CFString) */
 874  
 875  /* The file system object type values returned for the kCFURLFileResourceTypeKey */
 876  CF_EXPORT
 877  const CFStringRef kCFURLFileResourceTypeNamedPipe API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 878  CF_EXPORT
 879  const CFStringRef kCFURLFileResourceTypeCharacterSpecial API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 880  CF_EXPORT
 881  const CFStringRef kCFURLFileResourceTypeDirectory API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 882  CF_EXPORT
 883  const CFStringRef kCFURLFileResourceTypeBlockSpecial API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 884  CF_EXPORT
 885  const CFStringRef kCFURLFileResourceTypeRegular API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 886  CF_EXPORT
 887  const CFStringRef kCFURLFileResourceTypeSymbolicLink API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 888  CF_EXPORT
 889  const CFStringRef kCFURLFileResourceTypeSocket API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 890  CF_EXPORT
 891  const CFStringRef kCFURLFileResourceTypeUnknown API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 892  
 893  /* File Properties */
 894  
 895  CF_EXPORT
 896  const CFStringRef kCFURLFileSizeKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 897      /* Total file size in bytes (Read-only, value type CFNumber) */
 898  
 899  CF_EXPORT
 900  const CFStringRef kCFURLFileAllocatedSizeKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 901      /* Total size allocated on disk for the file in bytes (number of blocks times block size) (Read-only, value type CFNumber) */
 902  
 903  CF_EXPORT
 904  const CFStringRef kCFURLTotalFileSizeKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 905      /* 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) */
 906  
 907  CF_EXPORT
 908  const CFStringRef kCFURLTotalFileAllocatedSizeKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
 909      /* 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) */
 910  
 911  CF_EXPORT
 912  const CFStringRef kCFURLIsAliasFileKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 913      /*  true if the resource is a Finder alias file or a symlink, false otherwise ( Read-only, value type CFBooleanRef) */
 914  
 915  CF_EXPORT
 916  const CFStringRef kCFURLFileProtectionKey API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos);
 917      /* The protection level for this file */
 918  
 919  /* The protection level values returned for the kCFURLFileProtectionKey */
 920  CF_EXPORT
 921  const CFStringRef kCFURLFileProtectionNone API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos); // The file has no special protections associated with it. It can be read from or written to at any time.
 922  
 923  CF_EXPORT
 924  const CFStringRef kCFURLFileProtectionComplete API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos); // The file is stored in an encrypted format on disk and cannot be read from or written to while the device is locked or booting.
 925  
 926  CF_EXPORT
 927  const CFStringRef kCFURLFileProtectionCompleteUnlessOpen API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos); // The file is stored in an encrypted format on disk. Files can be created while the device is locked, but once closed, cannot be opened again until the device is unlocked. If the file is opened when unlocked, you may continue to access the file normally, even if the user locks the device. There is a small performance penalty when the file is created and opened, though not when being written to or read from. This can be mitigated by changing the file protection to kCFURLFileProtectionComplete when the device is unlocked.
 928  
 929  CF_EXPORT
 930  const CFStringRef kCFURLFileProtectionCompleteUntilFirstUserAuthentication API_AVAILABLE(ios(9.0), watchos(2.0), tvos(9.0)) API_UNAVAILABLE(macos); // The file is stored in an encrypted format on disk and cannot be accessed until after the device has booted. After the user unlocks the device for the first time, your app can access the file and continue to access it even if the user subsequently locks the device.
 931  
 932  /* Volume Properties */
 933  
 934  /* 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. */
 935  
 936  CF_EXPORT
 937  const CFStringRef kCFURLVolumeLocalizedFormatDescriptionKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 938      /* The user-visible volume format (Read-only, value type CFString) */
 939  
 940  CF_EXPORT
 941  const CFStringRef kCFURLVolumeTotalCapacityKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 942      /* Total volume capacity in bytes (Read-only, value type CFNumber) */
 943  
 944  CF_EXPORT
 945  const CFStringRef kCFURLVolumeAvailableCapacityKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 946      /* Total free space in bytes (Read-only, value type CFNumber) */
 947  
 948  CF_EXPORT
 949  const CFStringRef kCFURLVolumeAvailableCapacityForImportantUsageKey API_AVAILABLE(macos(10.13), ios(11.0)) API_UNAVAILABLE(watchos, tvos);
 950      /* Total available capacity in bytes for "Important" resources, including space expected to be cleared by purging non-essential and cached resources. "Important" means something that the user or application clearly expects to be present on the local system, but is ultimately replaceable. This would include items that the user has explicitly requested via the UI, and resources that an application requires in order to provide functionality.
 951   
 952       Examples: A video that the user has explicitly requested to watch but has not yet finished watching or an audio file that the user has requested to download.
 953   
 954       This value should not be used in determining if there is room for an irreplaceable resource. In the case of irreplaceable resources, always attempt to save the resource regardless of available capacity and handle failure as gracefully as possible. (Read-only, value type CFNumber) */
 955  
 956  CF_EXPORT
 957  const CFStringRef kCFURLVolumeAvailableCapacityForOpportunisticUsageKey API_AVAILABLE(macos(10.13), ios(11.0)) API_UNAVAILABLE(watchos, tvos);
 958      /* Total available capacity in bytes for "Opportunistic" resources, including space expected to be cleared by purging non-essential and cached resources. "Opportunistic" means something that the user is likely to want but does not expect to be present on the local system, but is ultimately non-essential and replaceable. This would include items that will be created or downloaded without an explicit request from the user on the current device.
 959   
 960       Examples: A background download of a newly available episode of a TV series that a user has been recently watching, a piece of content explicitly requested on another device, or a new document saved to a network server by the current user from another device. (Read-only, value type CFNumber) */
 961  
 962  CF_EXPORT
 963  const CFStringRef kCFURLVolumeResourceCountKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 964      /* Total number of resources on the volume (Read-only, value type CFNumber) */
 965  
 966  CF_EXPORT
 967  const CFStringRef kCFURLVolumeSupportsPersistentIDsKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 968      /* true if the volume format supports persistent object identifiers and can look up file system objects by their IDs (Read-only, value type CFBoolean) */
 969  
 970  CF_EXPORT
 971  const CFStringRef kCFURLVolumeSupportsSymbolicLinksKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 972      /* true if the volume format supports symbolic links (Read-only, value type CFBoolean) */
 973  
 974  CF_EXPORT
 975  const CFStringRef kCFURLVolumeSupportsHardLinksKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 976      /* true if the volume format supports hard links (Read-only, value type CFBoolean) */
 977  
 978  CF_EXPORT
 979  const CFStringRef kCFURLVolumeSupportsJournalingKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 980      /* 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) */
 981  
 982  CF_EXPORT
 983  const CFStringRef kCFURLVolumeIsJournalingKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 984      /* true if the volume is currently using a journal for speedy recovery after an unplanned restart. (Read-only, value type CFBoolean) */
 985  
 986  CF_EXPORT
 987  const CFStringRef kCFURLVolumeSupportsSparseFilesKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 988      /* 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) */
 989  
 990  CF_EXPORT
 991  const CFStringRef kCFURLVolumeSupportsZeroRunsKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 992      /* 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) */
 993  
 994  CF_EXPORT
 995  const CFStringRef kCFURLVolumeSupportsCaseSensitiveNamesKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
 996      /* 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) */
 997  
 998  CF_EXPORT
 999  const CFStringRef kCFURLVolumeSupportsCasePreservedNamesKey API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1000      /* 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) */
1001  
1002  CF_EXPORT
1003  const CFStringRef kCFURLVolumeSupportsRootDirectoryDatesKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1004      /* true if the volume supports reliable storage of times for the root directory. (Read-only, value type CFBoolean) */
1005  
1006  CF_EXPORT
1007  const CFStringRef kCFURLVolumeSupportsVolumeSizesKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1008      /* true if the volume supports returning volume size values (kCFURLVolumeTotalCapacityKey and kCFURLVolumeAvailableCapacityKey). (Read-only, value type CFBoolean) */
1009  
1010  CF_EXPORT
1011  const CFStringRef kCFURLVolumeSupportsRenamingKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1012      /* true if the volume can be renamed. (Read-only, value type CFBoolean) */
1013  
1014  CF_EXPORT
1015  const CFStringRef kCFURLVolumeSupportsAdvisoryFileLockingKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1016      /* 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) */
1017  
1018  CF_EXPORT
1019  const CFStringRef kCFURLVolumeSupportsExtendedSecurityKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1020      /* true if the volume implements extended security (ACLs). (Read-only, value type CFBoolean) */
1021  
1022  CF_EXPORT
1023  const CFStringRef kCFURLVolumeIsBrowsableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1024      /* 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) */
1025  
1026  CF_EXPORT
1027  const CFStringRef kCFURLVolumeMaximumFileSizeKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1028      /* The largest file size (in bytes) supported by this file system, or NULL if this cannot be determined. (Read-only, value type CFNumber) */
1029  
1030  CF_EXPORT
1031  const CFStringRef kCFURLVolumeIsEjectableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1032      /* true if the volume's media is ejectable from the drive mechanism under software control. (Read-only, value type CFBoolean) */
1033  
1034  CF_EXPORT
1035  const CFStringRef kCFURLVolumeIsRemovableKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1036      /* true if the volume's media is removable from the drive mechanism. (Read-only, value type CFBoolean) */
1037  
1038  CF_EXPORT
1039  const CFStringRef kCFURLVolumeIsInternalKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1040      /* 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) */
1041  
1042  CF_EXPORT
1043  const CFStringRef kCFURLVolumeIsAutomountedKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1044      /* true if the volume is automounted. Note: do not mistake this with the functionality provided by kCFURLVolumeSupportsBrowsingKey. (Read-only, value type CFBoolean) */
1045  
1046  CF_EXPORT
1047  const CFStringRef kCFURLVolumeIsLocalKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1048      /* true if the volume is stored on a local device. (Read-only, value type CFBoolean) */
1049  
1050  CF_EXPORT
1051  const CFStringRef kCFURLVolumeIsReadOnlyKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1052      /* true if the volume is read-only. (Read-only, value type CFBoolean) */
1053  
1054  CF_EXPORT
1055  const CFStringRef kCFURLVolumeCreationDateKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1056      /* The volume's creation date, or NULL if this cannot be determined. (Read-only, value type CFDate) */
1057  
1058  CF_EXPORT
1059  const CFStringRef kCFURLVolumeURLForRemountingKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1060      /* The CFURL needed to remount a network volume, or NULL if not available. (Read-only, value type CFURL) */
1061  
1062  CF_EXPORT
1063  const CFStringRef kCFURLVolumeUUIDStringKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1064      /* 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) */
1065  
1066  CF_EXPORT
1067  const CFStringRef kCFURLVolumeNameKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1068      /* The name of the volume (Read-write, settable if kCFURLVolumeSupportsRenamingKey is true and permissions allow, value type CFString) */
1069  
1070  CF_EXPORT
1071  const CFStringRef kCFURLVolumeLocalizedNameKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1072      /* The user-presentable name of the volume (Read-only, value type CFString) */
1073  
1074  CF_EXPORT
1075  const CFStringRef kCFURLVolumeIsEncryptedKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1076      /* true if the volume is encrypted. (Read-only, value type CFBoolean) */
1077  
1078  CF_EXPORT
1079  const CFStringRef kCFURLVolumeIsRootFileSystemKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1080      /* true if the volume is the root filesystem. (Read-only, value type CFBoolean) */
1081  
1082  CF_EXPORT
1083  const CFStringRef kCFURLVolumeSupportsCompressionKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1084      /* true if the volume supports transparent decompression of compressed files using decmpfs. (Read-only, value type CFBoolean) */
1085  
1086  CF_EXPORT
1087  const CFStringRef kCFURLVolumeSupportsFileCloningKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1088      /* true if the volume supports clonefile(2) (Read-only, value type CFBoolean) */
1089  
1090  CF_EXPORT
1091  const CFStringRef kCFURLVolumeSupportsSwapRenamingKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1092      /* true if the volume supports renamex_np(2)'s RENAME_SWAP option (Read-only, value type CFBoolean) */
1093  
1094  CF_EXPORT
1095  const CFStringRef kCFURLVolumeSupportsExclusiveRenamingKey API_AVAILABLE(macosx(10.12), ios(10.0), watchos(3.0), tvos(10.0));
1096      /* true if the volume supports renamex_np(2)'s RENAME_EXCL option (Read-only, value type CFBoolean) */
1097  
1098  CF_EXPORT
1099  const CFStringRef kCFURLVolumeSupportsImmutableFilesKey API_AVAILABLE(macosx(10.13), ios(11.0), watchos(4.0), tvos(11.0));
1100      /* true if the volume supports making files immutable with the kCFURLIsUserImmutableKey or kCFURLIsSystemImmutableKey properties (Read-only, value type CFBoolean) */
1101  
1102  CF_EXPORT
1103  const CFStringRef kCFURLVolumeSupportsAccessPermissionsKey API_AVAILABLE(macosx(10.13), ios(11.0), watchos(4.0), tvos(11.0));
1104      /* true if the volume supports setting POSIX access permissions with the kCFURLFileSecurityKey property (Read-only, value type CFBoolean) */
1105  
1106  CF_EXPORT
1107  const CFStringRef kCFURLVolumeSupportsFileProtectionKey API_AVAILABLE(macosx(10.16), ios(14.0), watchos(7.0), tvos(14.0));
1108      /* true if the volume supports data protection for files (see kCFURLFileProtectionKey). (Read-only, value type CFBoolean) */
1109  
1110  /* UbiquitousItem Properties */
1111  
1112  CF_EXPORT
1113  const CFStringRef kCFURLIsUbiquitousItemKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1114      /* true if this item is synced to the cloud, false if it is only a local file. (Read-only, value type CFBoolean) */
1115  
1116  CF_EXPORT
1117  const CFStringRef kCFURLUbiquitousItemHasUnresolvedConflictsKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1118      /* true if this item has conflicts outstanding. (Read-only, value type CFBoolean) */
1119  
1120  CF_EXPORT
1121  const CFStringRef kCFURLUbiquitousItemIsDownloadedKey API_DEPRECATED("Use kCFURLUbiquitousItemDownloadingStatusKey instead", macos(10.7,10.9), ios(5.0,7.0), watchos(2.0,2.0), tvos(9.0,9.0));
1122      /* Equivalent to NSURLUbiquitousItemDownloadingStatusKey == NSURLUbiquitousItemDownloadingStatusCurrent. Has never behaved as documented in earlier releases, hence deprecated. (Read-only, value type CFBoolean) */
1123  
1124  CF_EXPORT
1125  const CFStringRef kCFURLUbiquitousItemIsDownloadingKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1126      /* true if data is being downloaded for this item. (Read-only, value type CFBoolean) */
1127  
1128  CF_EXPORT
1129  const CFStringRef kCFURLUbiquitousItemIsUploadedKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1130      /* true if there is data present in the cloud for this item. (Read-only, value type CFBoolean) */
1131  
1132  CF_EXPORT
1133  const CFStringRef kCFURLUbiquitousItemIsUploadingKey API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0));
1134      /* true if data is being uploaded for this item. (Read-only, value type CFBoolean) */
1135  
1136  CF_EXPORT
1137  const CFStringRef kCFURLUbiquitousItemPercentDownloadedKey API_DEPRECATED("Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead", macos(10.7,10.8), ios(5.0,6.0), watchos(2.0,2.0), tvos(9.0,9.0));
1138      /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead */
1139  
1140  CF_EXPORT
1141  const CFStringRef kCFURLUbiquitousItemPercentUploadedKey API_DEPRECATED("Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead", macos(10.7,10.8), ios(5.0,6.0), watchos(2.0,2.0), tvos(9.0,9.0));
1142      /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead */
1143  
1144  CF_EXPORT
1145  const CFStringRef kCFURLUbiquitousItemDownloadingStatusKey API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1146      /* Returns the download status of this item. (Read-only, value type CFString). Possible values below. */
1147  
1148  CF_EXPORT
1149  const CFStringRef kCFURLUbiquitousItemDownloadingErrorKey API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1150      /* returns the error when downloading the item from iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. (Read-only, value type CFError) */
1151  
1152  CF_EXPORT
1153  const CFStringRef kCFURLUbiquitousItemUploadingErrorKey API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1154      /* returns the error when uploading the item to iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. (Read-only, value type CFError) */
1155  
1156  CF_EXPORT
1157  const CFStringRef kCFURLUbiquitousItemIsExcludedFromSyncKey API_AVAILABLE(macos(11.3), ios(14.5), watchos(7.4), tvos(14.5));
1158      /* the item is excluded from sync, which means it is locally on disk but won't be available on the server. An excluded item is no longer ubiquitous. */
1159  
1160  /* The values returned for kCFURLUbiquitousItemDownloadingStatusKey
1161   */
1162  CF_EXPORT
1163  const CFStringRef kCFURLUbiquitousItemDownloadingStatusNotDownloaded API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1164      /* this item has not been downloaded yet. Use NSFileManager's startDownloadingUbiquitousItemAtURL:error: to download it */
1165  
1166  CF_EXPORT
1167  const CFStringRef kCFURLUbiquitousItemDownloadingStatusDownloaded API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1168      /* there is a local version of this item available. The most current version will get downloaded as soon as possible. */
1169  
1170  CF_EXPORT
1171  const CFStringRef kCFURLUbiquitousItemDownloadingStatusCurrent API_AVAILABLE(macos(10.9), ios(7.0), watchos(2.0), tvos(9.0));
1172      /* there is a local version of this item and it is the most up-to-date version known to this device. */
1173  
1174  #if !DEPLOYMENT_TARGET_SWIFT
1175  
1176  typedef CF_OPTIONS(CFOptionFlags, CFURLBookmarkCreationOptions) {
1177      kCFURLBookmarkCreationMinimalBookmarkMask = ( 1UL << 9 ), // creates bookmark data with "less" information, which may be smaller but still be able to resolve in certain ways
1178      kCFURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), // include the properties required by CFURLWriteBookmarkDataToFile() in the bookmark data created
1179      kCFURLBookmarkCreationWithSecurityScope API_AVAILABLE(macos(10.7))  API_UNAVAILABLE(ios, watchos, tvos) = ( 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
1180      kCFURLBookmarkCreationSecurityScopeAllowOnlyReadAccess API_AVAILABLE(macos(10.7)) API_UNAVAILABLE(ios, watchos, tvos) = ( 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
1181      kCFURLBookmarkCreationWithoutImplicitSecurityScope  API_AVAILABLE(macos(10.7), ios(5.0), watchos(2.0), tvos(9.0)) = (1 << 29), // Disable automatic embedding of an implicit security scope. The resolving process will not be able gain access to the resource by security scope, either implicitly or explicitly, through the returned URL. Not applicable to security-scoped bookmarks.
1182      
1183      // deprecated
1184      kCFURLBookmarkCreationPreferFileIDResolutionMask
1185      API_DEPRECATED("kCFURLBookmarkCreationPreferFileIDResolutionMask does nothing and has no effect on bookmark resolution", macos(10.6,10.9), ios(4.0,7.0)) = ( 1UL << 8 ),
1186  } API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1187  
1188  typedef CF_OPTIONS(CFOptionFlags, CFURLBookmarkResolutionOptions) {
1189      kCFURLBookmarkResolutionWithoutUIMask = ( 1UL << 8 ), // don't perform any user interaction during bookmark resolution
1190      kCFURLBookmarkResolutionWithoutMountingMask = ( 1UL << 9 ), // don't mount a volume during bookmark resolution
1191      kCFURLBookmarkResolutionWithSecurityScope API_AVAILABLE(macos(10.7)) API_UNAVAILABLE(ios, watchos, tvos) = ( 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.
1192      kCFURLBookmarkResolutionWithoutImplicitStartAccessing API_AVAILABLE(macos(11.2), ios(14.2), watchos(7.2), tvos(14.2)) = ( 1 << 15 ), // Disable implicitly starting access of the ephemeral security-scoped resource during resolution. Instead, call `CFURLStartAccessingSecurityScopedResource` on the returned URL when ready to use the resource. Not applicable to security-scoped bookmarks.
1193  
1194      kCFBookmarkResolutionWithoutUIMask = kCFURLBookmarkResolutionWithoutUIMask,
1195      kCFBookmarkResolutionWithoutMountingMask = kCFURLBookmarkResolutionWithoutMountingMask,
1196  } API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1197  
1198  typedef CFOptionFlags CFURLBookmarkFileCreationOptions;
1199  
1200  CF_IMPLICIT_BRIDGING_DISABLED
1201  
1202  /* Returns bookmark data for the URL, created with specified options and resource properties. If this function returns NULL, the optional error is populated.
1203   */
1204  CF_EXPORT
1205  CFDataRef CFURLCreateBookmarkData ( CFAllocatorRef allocator, CFURLRef url, CFURLBookmarkCreationOptions options, CFArrayRef resourcePropertiesToInclude, CFURLRef relativeToURL, CFErrorRef* error ) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1206  
1207  /* Return a URL that refers to a location specified by resolving bookmark data. If this function returns NULL, the optional error is populated.
1208   */
1209  CF_EXPORT
1210  CFURLRef CFURLCreateByResolvingBookmarkData ( CFAllocatorRef allocator, CFDataRef bookmark, CFURLBookmarkResolutionOptions options, CFURLRef relativeToURL, CFArrayRef resourcePropertiesToInclude, Boolean* isStale, CFErrorRef* error ) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1211  
1212  /* 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.
1213   */
1214  CF_EXPORT
1215  CFDictionaryRef CFURLCreateResourcePropertiesForKeysFromBookmarkData ( CFAllocatorRef allocator, CFArrayRef resourcePropertiesToReturn, CFDataRef bookmark ) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1216  
1217  /*  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.
1218   */
1219  CF_EXPORT
1220  CFTypeRef  CFURLCreateResourcePropertyForKeyFromBookmarkData( CFAllocatorRef allocator, CFStringRef resourcePropertyKey, CFDataRef bookmark ) API_AVAILABLE(macos(10.6), ios(4.0), watchos(2.0), tvos(9.0));
1221  
1222  /* 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.
1223   */
1224  CF_EXPORT
1225  CFDataRef CFURLCreateBookmarkDataFromFile(CFAllocatorRef allocator, CFURLRef fileURL, CFErrorRef *errorRef ) API_AVAILABLE(macos(10.6), ios(5.0), watchos(2.0), tvos(9.0));
1226  
1227  /* 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.
1228   */
1229  CF_EXPORT
1230  Boolean CFURLWriteBookmarkDataToFile( CFDataRef bookmarkRef, CFURLRef fileURL, CFURLBookmarkFileCreationOptions options, CFErrorRef *errorRef ) API_AVAILABLE(macos(10.6), ios(5.0), watchos(2.0), tvos(9.0));
1231  
1232  /* Returns bookmark data derived from an alias record.
1233   */
1234  CF_EXPORT
1235  CFDataRef CFURLCreateBookmarkDataFromAliasRecord ( CFAllocatorRef allocatorRef, CFDataRef aliasRecordDataRef ) API_DEPRECATED("The Carbon Alias Manager is deprecated. This function should only be used to convert Carbon AliasRecords to bookmark data.", macos(10.6,10.16)) API_UNAVAILABLE(ios, watchos, tvos);
1236  
1237  CF_IMPLICIT_BRIDGING_ENABLED
1238  
1239  /* 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).
1240   */
1241  CF_EXPORT
1242  Boolean CFURLStartAccessingSecurityScopedResource(CFURLRef url) API_AVAILABLE(macos(10.7), ios(8.0), watchos(2.0), tvos(9.0)); // On OSX, available in MacOS X 10.7.3 and later
1243  
1244  /* Revokes the access granted to the url by a prior successful call to CFURLStartAccessingSecurityScopedResource().
1245   */
1246  CF_EXPORT
1247  void CFURLStopAccessingSecurityScopedResource(CFURLRef url) API_AVAILABLE(macos(10.7), ios(8.0), watchos(2.0), tvos(9.0)); // On OSX, available in MacOS X 10.7.3 and later
1248  
1249  #endif /* !DEPLOYMENT_TARGET_SWIFT */
1250  #endif /*  TARGET_OS_MAC || CF_BUILDING_CF || NSBUILDINGFOUNDATION || DEPLOYMENT_RUNTIME_SWIFT */
1251  
1252  CF_EXTERN_C_END
1253  CF_IMPLICIT_BRIDGING_DISABLED
1254  
1255  #endif /* ! __COREFOUNDATION_CFURL__ */
1256