1/* 2 * Copyright (c) 2014 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-2013, 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 36CF_IMPLICIT_BRIDGING_ENABLED 37CF_EXTERN_C_BEGIN 38 39typedef 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 45typedef const struct __CFURL * CFURLRef; 46 47/* CFURLs are composed of two fundamental pieces - their string, and a */ 48/* (possibly NULL) base URL. A relative URL is one in which the string */ 49/* by itself does not fully specify the URL (for instance "myDir/image.tiff"); */ 50/* an absolute URL is one in which the string does fully specify the URL */ 51/* ("file://localhost/myDir/image.tiff"). Absolute URLs always have NULL */ 52/* base URLs; however, it is possible for a URL to have a NULL base, and still */ 53/* not be absolute. Such a URL has only a relative string, and cannot be */ 54/* resolved. Two CFURLs are considered equal if and only if their strings */ 55/* are equal and their bases are equal. In other words, */ 56/* "file://localhost/myDir/image.tiff" is NOT equal to the URL with relative */ 57/* string "myDir/image.tiff" and base URL "file://localhost/". Clients that */ 58/* need these less strict form of equality should convert all URLs to their */ 59/* absolute form via CFURLCopyAbsoluteURL(), then compare the absolute forms. */ 60 61CF_EXPORT 62CFTypeID 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. */ 71CF_EXPORT 72CFURLRef 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) */ 78CF_EXPORT 79CFDataRef CFURLCreateData(CFAllocatorRef allocator, CFURLRef url, CFStringEncoding encoding, Boolean escapeWhitespace); 80 81/* Any escape sequences in URLString will be interpreted via UTF-8. */ 82CF_EXPORT 83CFURLRef 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. */ 101CF_EXPORT 102CFURLRef 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 */ 110CF_EXPORT 111CFURLRef CFURLCreateWithFileSystemPath(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory); 112 113CF_EXPORT 114CFURLRef 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. */ 122CF_EXPORT 123CFURLRef CFURLCreateWithFileSystemPathRelativeToBase(CFAllocatorRef allocator, CFStringRef filePath, CFURLPathStyle pathStyle, Boolean isDirectory, CFURLRef baseURL); 124 125CF_EXPORT 126CFURLRef 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. */ 135CF_EXPORT 136Boolean 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. */ 139CF_EXPORT 140CFURLRef CFURLCopyAbsoluteURL(CFURLRef relativeURL); 141 142/* Returns the URL's string. */ 143CF_EXPORT 144CFStringRef CFURLGetString(CFURLRef anURL); 145 146/* Returns the base URL if it exists */ 147CF_EXPORT 148CFURLRef CFURLGetBaseURL(CFURLRef anURL); 149 150/* 151All URLs can be broken into two pieces - the scheme (preceding the 152first colon) and the resource specifier (following the first colon). 153Most URLs are also "standard" URLs conforming to RFC 1808 (available 154from www.w3c.org). This category includes URLs of the file, http, 155https, and ftp schemes, to name a few. Standard URLs start the 156resource specifier with two slashes ("//"), and can be broken into 157four distinct pieces - the scheme, the net location, the path, and 158further resource specifiers (typically an optional parameter, query, 159and/or fragment). The net location appears immediately following 160the two slashes and goes up to the next slash; it's format is 161scheme-specific, but is usually composed of some or all of a username, 162password, host name, and port. The path is a series of path components 163separated by slashes; if the net location is present, the path always 164begins with a slash. Standard URLs can be relative to another URL, 165in which case at least the scheme and possibly other pieces as well 166come from the base URL (see RFC 1808 for precise details when resolving 167a 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 171If a given CFURL can be decomposed (that is, conforms to RFC 1808), you 172can ask for each of the four basic pieces (scheme, net location, path, 173and resource specifer) separately, as well as for its base URL. The 174basic pieces are returned with any percent escape sequences still in 175place (although note that the scheme may not legally include any 176percent escapes); this is to allow the caller to distinguish between 177percent sequences that may have syntactic meaning if replaced by the 178character being escaped (for instance, a '/' in a path component). 179Since only the individual schemes know which characters are 180syntactically significant, CFURL cannot safely replace any percent 181escape sequences. However, you can use 182CFURLCreateStringByReplacingPercentEscapes() to create a new string with 183the percent escapes removed; see below. 184 185If a given CFURL can not be decomposed, you can ask for its scheme and its 186resource specifier; asking it for its net location or path will return NULL. 187 188To get more refined information about the components of a decomposable 189CFURL, you may ask for more specific pieces of the URL, expressed with 190the percent escapes removed. The available functions are CFURLCopyHostName(), 191CFURLGetPortNumber() (returns an Int32), CFURLCopyUserName(), 192CFURLCopyPassword(), CFURLCopyQuery(), CFURLCopyParameters(), and 193CFURLCopyFragment(). Because the parameters, query, and fragment of an 194URL may contain scheme-specific syntaxes, these methods take a second 195argument, giving a list of characters which should NOT be replaced if 196percent escaped. For instance, the ftp parameter syntax gives simple 197key-value pairs as "<key>=<value>;" Clearly if a key or value includes 198either '=' or ';', it must be escaped to avoid corrupting the meaning of 199the parameters, so the caller may request the parameter string as 200 201CFStringRef myParams = CFURLCopyParameters(ftpURL, CFSTR("=;%")); 202 203requesting that all percent escape sequences be replaced by the represented 204characters, except for escaped '=', '%' or ';' characters. Pass the empty 205string (CFSTR("")) to request that all percent escapes be replaced, or NULL 206to request that none be. 207*/ 208 209/* Returns true if anURL conforms to RFC 1808 */ 210CF_EXPORT 211Boolean CFURLCanBeDecomposed(CFURLRef anURL); 212 213/* The next several methods leave any percent escape sequences intact */ 214 215CF_EXPORT 216CFStringRef CFURLCopyScheme(CFURLRef anURL); 217 218/* NULL if CFURLCanBeDecomposed(anURL) is false */ 219CF_EXPORT 220CFStringRef 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. */ 233CF_EXPORT 234CFStringRef CFURLCopyPath(CFURLRef anURL); 235 236CF_EXPORT 237CFStringRef CFURLCopyStrictPath(CFURLRef anURL, Boolean *isAbsolute); 238 239CF_EXPORT 240CFStringRef CFURLCopyFileSystemPath(CFURLRef anURL, CFURLPathStyle pathStyle); 241 242/* Returns whether anURL's path represents a directory */ 243/* (true returned) or a simple file (false returned) */ 244CF_EXPORT 245Boolean 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. */ 249CF_EXPORT 250CFStringRef CFURLCopyResourceSpecifier(CFURLRef anURL); 251 252CF_EXPORT 253CFStringRef CFURLCopyHostName(CFURLRef anURL); 254 255CF_EXPORT 256SInt32 CFURLGetPortNumber(CFURLRef anURL); /* Returns -1 if no port number is specified */ 257 258CF_EXPORT 259CFStringRef CFURLCopyUserName(CFURLRef anURL); 260 261CF_EXPORT 262CFStringRef 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 */ 269CF_EXPORT 270CFStringRef CFURLCopyParameterString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped); 271 272CF_EXPORT 273CFStringRef CFURLCopyQueryString(CFURLRef anURL, CFStringRef charactersToLeaveEscaped); 274 275CF_EXPORT 276CFStringRef CFURLCopyFragment(CFURLRef anURL, CFStringRef charactersToLeaveEscaped); 277 278CF_EXPORT 279CFStringRef CFURLCopyLastPathComponent(CFURLRef url); 280 281CF_EXPORT 282CFStringRef 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 288CF_EXPORT 289CFURLRef CFURLCreateCopyAppendingPathComponent(CFAllocatorRef allocator, CFURLRef url, CFStringRef pathComponent, Boolean isDirectory); 290 291CF_EXPORT 292CFURLRef CFURLCreateCopyDeletingLastPathComponent(CFAllocatorRef allocator, CFURLRef url); 293 294CF_EXPORT 295CFURLRef CFURLCreateCopyAppendingPathExtension(CFAllocatorRef allocator, CFURLRef url, CFStringRef extension); 296 297CF_EXPORT 298CFURLRef 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 */ 306CF_EXPORT 307CFIndex CFURLGetBytes(CFURLRef url, UInt8 *buffer, CFIndex bufferLength); 308 309typedef 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/* 326Gets the range of the requested component in the bytes of url, as 327returned by CFURLGetBytes(). This range is only good for use in the 328bytes returned by CFURLGetBytes! 329 330If non-NULL, rangeIncludingSeparators gives the range of component 331including the sequences that separate component from the previous and 332next components. If there is no previous or next component, that end of 333rangeIncludingSeparators will match the range of the component itself. 334If url does not contain the given component type, (kCFNotFound, 0) is 335returned, and rangeIncludingSeparators is set to the location where the 336component would be inserted. Some examples - 337 338For the URL http://www.apple.com/hotnews/ 339 340Component returned range rangeIncludingSeparators 341scheme (0, 4) (0, 7) 342net location (7, 13) (4, 16) 343path (20, 9) (20, 9) 344resource specifier (kCFNotFound, 0) (29, 0) 345user (kCFNotFound, 0) (7, 0) 346password (kCFNotFound, 0) (7, 0) 347user info (kCFNotFound, 0) (7, 0) 348host (7, 13) (4, 16) 349port (kCFNotFound, 0) (20, 0) 350parameter (kCFNotFound, 0) (29, 0) 351query (kCFNotFound, 0) (29, 0) 352fragment (kCFNotFound, 0) (29, 0) 353 354 355For the URL ./relPath/file.html#fragment 356 357Component returned range rangeIncludingSeparators 358scheme (kCFNotFound, 0) (0, 0) 359net location (kCFNotFound, 0) (0, 0) 360path (0, 19) (0, 20) 361resource specifier (20, 8) (19, 9) 362user (kCFNotFound, 0) (0, 0) 363password (kCFNotFound, 0) (0, 0) 364user info (kCFNotFound, 0) (0, 0) 365host (kCFNotFound, 0) (0, 0) 366port (kCFNotFound, 0) (0, 0) 367parameter (kCFNotFound, 0) (19, 0) 368query (kCFNotFound, 0) (19, 0) 369fragment (20, 8) (19, 9) 370 371 372For the URL scheme://user:pass@host:1/path/path2/file.html;params?query#fragment 373 374Component returned range rangeIncludingSeparators 375scheme (0, 6) (0, 9) 376net location (9, 16) (6, 19) 377path (25, 21) (25, 22) 378resource specifier (47, 21) (46, 22) 379user (9, 4) (6, 8) 380password (14, 4) (13, 6) 381user info (9, 9) (6, 13) 382host (19, 4) (18, 6) 383port (24, 1) (23, 2) 384parameter (47, 6) (46, 8) 385query (54, 5) (53, 7) 386fragment (60, 8) (59, 9) 387*/ 388CF_EXPORT 389CFRange 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. */ 398CF_EXPORT 399CFStringRef CFURLCreateStringByReplacingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveEscaped); 400 401/* As above, but allows you to specify the encoding to use when interpreting percent escapes */ 402CF_EXPORT 403CFStringRef 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); */ 418CF_EXPORT 419CFStringRef 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 423CF_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 */ 434CF_EXPORT 435Boolean 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 */ 457CF_EXPORT 458CFURLRef 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 */ 481CF_EXPORT 482CFURLRef CFURLCreateFilePathURL(CFAllocatorRef allocator, CFURLRef url, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0); 483 484CF_IMPLICIT_BRIDGING_ENABLED 485#endif 486 487 488 489#if (TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE) || CF_BUILDING_CF || NSBUILDINGFOUNDATION 490CF_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 */ 524CF_EXPORT 525Boolean 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 */ 548CF_EXPORT 549CFDictionaryRef 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 */ 574CF_EXPORT 575Boolean 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 */ 598CF_EXPORT 599Boolean CFURLSetResourcePropertiesForKeys(CFURLRef url, CFDictionaryRef keyedPropertyValues, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0); 600 601 602CF_EXPORT 603const 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 */ 622CF_EXPORT 623void 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 */ 639CF_EXPORT 640void 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 */ 660CF_EXPORT 661void 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 */ 682CF_EXPORT 683Boolean CFURLResourceIsReachable(CFURLRef url, CFErrorRef *error) CF_AVAILABLE(10_6, 4_0); 684 685CF_IMPLICIT_BRIDGING_ENABLED 686 687 688/* Properties of File System Resources */ 689 690CF_EXPORT 691const CFStringRef kCFURLNameKey CF_AVAILABLE(10_6, 4_0); 692 /* The resource name provided by the file system (Read-write, value type CFString) */ 693 694CF_EXPORT 695const CFStringRef kCFURLLocalizedNameKey CF_AVAILABLE(10_6, 4_0); 696 /* Localized or extension-hidden name as displayed to users (Read-only, value type CFString) */ 697 698CF_EXPORT 699const CFStringRef kCFURLIsRegularFileKey CF_AVAILABLE(10_6, 4_0); 700 /* True for regular files (Read-only, value type CFBoolean) */ 701 702CF_EXPORT 703const CFStringRef kCFURLIsDirectoryKey CF_AVAILABLE(10_6, 4_0); 704 /* True for directories (Read-only, CFBoolean) */ 705 706CF_EXPORT 707const CFStringRef kCFURLIsSymbolicLinkKey CF_AVAILABLE(10_6, 4_0); 708 /* True for symlinks (Read-only, value type CFBoolean) */ 709 710CF_EXPORT 711const CFStringRef kCFURLIsVolumeKey CF_AVAILABLE(10_6, 4_0); 712 /* True for the root directory of a volume (Read-only, value type CFBoolean) */ 713 714CF_EXPORT 715const 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 718CF_EXPORT 719const CFStringRef kCFURLIsSystemImmutableKey CF_AVAILABLE(10_6, 4_0); 720 /* True for system-immutable resources (Read-write, value type CFBoolean) */ 721 722CF_EXPORT 723const CFStringRef kCFURLIsUserImmutableKey CF_AVAILABLE(10_6, 4_0); 724 /* True for user-immutable resources (Read-write, value type CFBoolean) */ 725 726CF_EXPORT 727const 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 730CF_EXPORT 731const 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 734CF_EXPORT 735const CFStringRef kCFURLCreationDateKey CF_AVAILABLE(10_6, 4_0); 736 /* The date the resource was created (Read-write, value type CFDate) */ 737 738CF_EXPORT 739const CFStringRef kCFURLContentAccessDateKey CF_AVAILABLE(10_6, 4_0); 740 /* The date the resource was last accessed (Read-only, value type CFDate) */ 741 742CF_EXPORT 743const CFStringRef kCFURLContentModificationDateKey CF_AVAILABLE(10_6, 4_0); 744 /* The time the resource content was last modified (Read-write, value type CFDate) */ 745 746CF_EXPORT 747const CFStringRef kCFURLAttributeModificationDateKey CF_AVAILABLE(10_6, 4_0); 748 /* The time the resource's attributes were last modified (Read-write, value type CFDate) */ 749 750CF_EXPORT 751const CFStringRef kCFURLLinkCountKey CF_AVAILABLE(10_6, 4_0); 752 /* Number of hard links to the resource (Read-only, value type CFNumber) */ 753 754CF_EXPORT 755const CFStringRef kCFURLParentDirectoryURLKey CF_AVAILABLE(10_6, 4_0); 756 /* The resource's parent directory, if any (Read-only, value type CFURL) */ 757 758CF_EXPORT 759const 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 762CF_EXPORT 763const CFStringRef kCFURLTypeIdentifierKey CF_AVAILABLE(10_6, 4_0); 764 /* Uniform type identifier (UTI) for the resource (Read-only, value type CFString) */ 765 766CF_EXPORT 767const CFStringRef kCFURLLocalizedTypeDescriptionKey CF_AVAILABLE(10_6, 4_0); 768 /* User-visible type or "kind" description (Read-only, value type CFString) */ 769 770CF_EXPORT 771const CFStringRef kCFURLLabelNumberKey CF_AVAILABLE(10_6, 4_0); 772 /* The label number assigned to the resource (Read-write, value type CFNumber) */ 773 774CF_EXPORT 775const 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 778CF_EXPORT 779const CFStringRef kCFURLLocalizedLabelKey CF_AVAILABLE(10_6, 4_0); 780 /* The user-visible label text (Read-only, value type CFString) */ 781 782CF_EXPORT 783const 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 786CF_EXPORT 787const 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 790CF_EXPORT 791const 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 794CF_EXPORT 795const 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 798CF_EXPORT 799const 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 802CF_EXPORT 803const 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 806CF_EXPORT 807const 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 810CF_EXPORT 811const 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 814CF_EXPORT 815const 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 818CF_EXPORT 819const 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 822CF_EXPORT 823const CFStringRef kCFURLTagNamesKey CF_AVAILABLE(10_9, NA); 824 /* The array of Tag names (Read-write, value type CFArray of CFString) */ 825 826CF_EXPORT 827const CFStringRef kCFURLPathKey CF_AVAILABLE(10_8, 6_0); 828 /* the URL's path as a file system path (Read-only, value type CFString) */ 829 830CF_EXPORT 831const 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 834CF_EXPORT 835const CFStringRef kCFURLFileResourceTypeKey CF_AVAILABLE(10_7, 5_0); 836 /* Returns the file system object type. (Read-only, value type CFString) */ 837 838/* The file system object type values returned for the kCFURLFileResourceTypeKey */ 839CF_EXPORT 840const CFStringRef kCFURLFileResourceTypeNamedPipe CF_AVAILABLE(10_7, 5_0); 841CF_EXPORT 842const CFStringRef kCFURLFileResourceTypeCharacterSpecial CF_AVAILABLE(10_7, 5_0); 843CF_EXPORT 844const CFStringRef kCFURLFileResourceTypeDirectory CF_AVAILABLE(10_7, 5_0); 845CF_EXPORT 846const CFStringRef kCFURLFileResourceTypeBlockSpecial CF_AVAILABLE(10_7, 5_0); 847CF_EXPORT 848const CFStringRef kCFURLFileResourceTypeRegular CF_AVAILABLE(10_7, 5_0); 849CF_EXPORT 850const CFStringRef kCFURLFileResourceTypeSymbolicLink CF_AVAILABLE(10_7, 5_0); 851CF_EXPORT 852const CFStringRef kCFURLFileResourceTypeSocket CF_AVAILABLE(10_7, 5_0); 853CF_EXPORT 854const CFStringRef kCFURLFileResourceTypeUnknown CF_AVAILABLE(10_7, 5_0); 855 856/* File Properties */ 857 858CF_EXPORT 859const CFStringRef kCFURLFileSizeKey CF_AVAILABLE(10_6, 4_0); 860 /* Total file size in bytes (Read-only, value type CFNumber) */ 861 862CF_EXPORT 863const CFStringRef kCFURLFileAllocatedSizeKey CF_AVAILABLE(10_6, 4_0); 864 /* Total size allocated on disk for the file in bytes (number of blocks times block size) (Read-only, value type CFNumber) */ 865 866CF_EXPORT 867const CFStringRef kCFURLTotalFileSizeKey CF_AVAILABLE(10_7, 5_0); 868 /* 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) */ 869 870CF_EXPORT 871const CFStringRef kCFURLTotalFileAllocatedSizeKey CF_AVAILABLE(10_7, 5_0); 872 /* 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) */ 873 874CF_EXPORT 875const CFStringRef kCFURLIsAliasFileKey CF_AVAILABLE(10_6, 4_0); 876 /* true if the resource is a Finder alias file or a symlink, false otherwise ( Read-only, value type CFBooleanRef) */ 877 878 879/* Volume Properties */ 880 881/* 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. */ 882 883CF_EXPORT 884const CFStringRef kCFURLVolumeLocalizedFormatDescriptionKey CF_AVAILABLE(10_6, 4_0); 885 /* The user-visible volume format (Read-only, value type CFString) */ 886 887CF_EXPORT 888const CFStringRef kCFURLVolumeTotalCapacityKey CF_AVAILABLE(10_6, 4_0); 889 /* Total volume capacity in bytes (Read-only, value type CFNumber) */ 890 891CF_EXPORT 892const CFStringRef kCFURLVolumeAvailableCapacityKey CF_AVAILABLE(10_6, 4_0); 893 /* Total free space in bytes (Read-only, value type CFNumber) */ 894 895CF_EXPORT 896const CFStringRef kCFURLVolumeResourceCountKey CF_AVAILABLE(10_6, 4_0); 897 /* Total number of resources on the volume (Read-only, value type CFNumber) */ 898 899CF_EXPORT 900const CFStringRef kCFURLVolumeSupportsPersistentIDsKey CF_AVAILABLE(10_6, 4_0); 901 /* true if the volume format supports persistent object identifiers and can look up file system objects by their IDs (Read-only, value type CFBoolean) */ 902 903CF_EXPORT 904const CFStringRef kCFURLVolumeSupportsSymbolicLinksKey CF_AVAILABLE(10_6, 4_0); 905 /* true if the volume format supports symbolic links (Read-only, value type CFBoolean) */ 906 907CF_EXPORT 908const CFStringRef kCFURLVolumeSupportsHardLinksKey CF_AVAILABLE(10_6, 4_0); 909 /* true if the volume format supports hard links (Read-only, value type CFBoolean) */ 910 911CF_EXPORT 912const CFStringRef kCFURLVolumeSupportsJournalingKey CF_AVAILABLE(10_6, 4_0); 913 /* 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) */ 914 915CF_EXPORT 916const CFStringRef kCFURLVolumeIsJournalingKey CF_AVAILABLE(10_6, 4_0); 917 /* true if the volume is currently using a journal for speedy recovery after an unplanned restart. (Read-only, value type CFBoolean) */ 918 919CF_EXPORT 920const CFStringRef kCFURLVolumeSupportsSparseFilesKey CF_AVAILABLE(10_6, 4_0); 921 /* 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) */ 922 923CF_EXPORT 924const CFStringRef kCFURLVolumeSupportsZeroRunsKey CF_AVAILABLE(10_6, 4_0); 925 /* 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) */ 926 927CF_EXPORT 928const CFStringRef kCFURLVolumeSupportsCaseSensitiveNamesKey CF_AVAILABLE(10_6, 4_0); 929 /* 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) */ 930 931CF_EXPORT 932const CFStringRef kCFURLVolumeSupportsCasePreservedNamesKey CF_AVAILABLE(10_6, 4_0); 933 /* 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) */ 934 935CF_EXPORT 936const CFStringRef kCFURLVolumeSupportsRootDirectoryDatesKey CF_AVAILABLE(10_7, 5_0); 937 /* true if the volume supports reliable storage of times for the root directory. (Read-only, value type CFBoolean) */ 938 939CF_EXPORT 940const CFStringRef kCFURLVolumeSupportsVolumeSizesKey CF_AVAILABLE(10_7, 5_0); 941 /* true if the volume supports returning volume size values (kCFURLVolumeTotalCapacityKey and kCFURLVolumeAvailableCapacityKey). (Read-only, value type CFBoolean) */ 942 943CF_EXPORT 944const CFStringRef kCFURLVolumeSupportsRenamingKey CF_AVAILABLE(10_7, 5_0); 945 /* true if the volume can be renamed. (Read-only, value type CFBoolean) */ 946 947CF_EXPORT 948const CFStringRef kCFURLVolumeSupportsAdvisoryFileLockingKey CF_AVAILABLE(10_7, 5_0); 949 /* 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) */ 950 951CF_EXPORT 952const CFStringRef kCFURLVolumeSupportsExtendedSecurityKey CF_AVAILABLE(10_7, 5_0); 953 /* true if the volume implements extended security (ACLs). (Read-only, value type CFBoolean) */ 954 955CF_EXPORT 956const CFStringRef kCFURLVolumeIsBrowsableKey CF_AVAILABLE(10_7, 5_0); 957 /* 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) */ 958 959CF_EXPORT 960const CFStringRef kCFURLVolumeMaximumFileSizeKey CF_AVAILABLE(10_7, 5_0); 961 /* The largest file size (in bytes) supported by this file system, or NULL if this cannot be determined. (Read-only, value type CFNumber) */ 962 963CF_EXPORT 964const CFStringRef kCFURLVolumeIsEjectableKey CF_AVAILABLE(10_7, 5_0); 965 /* true if the volume's media is ejectable from the drive mechanism under software control. (Read-only, value type CFBoolean) */ 966 967CF_EXPORT 968const CFStringRef kCFURLVolumeIsRemovableKey CF_AVAILABLE(10_7, 5_0); 969 /* true if the volume's media is removable from the drive mechanism. (Read-only, value type CFBoolean) */ 970 971CF_EXPORT 972const CFStringRef kCFURLVolumeIsInternalKey CF_AVAILABLE(10_7, 5_0); 973 /* 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) */ 974 975CF_EXPORT 976const CFStringRef kCFURLVolumeIsAutomountedKey CF_AVAILABLE(10_7, 5_0); 977 /* true if the volume is automounted. Note: do not mistake this with the functionality provided by kCFURLVolumeSupportsBrowsingKey. (Read-only, value type CFBoolean) */ 978 979CF_EXPORT 980const CFStringRef kCFURLVolumeIsLocalKey CF_AVAILABLE(10_7, 5_0); 981 /* true if the volume is stored on a local device. (Read-only, value type CFBoolean) */ 982 983CF_EXPORT 984const CFStringRef kCFURLVolumeIsReadOnlyKey CF_AVAILABLE(10_7, 5_0); 985 /* true if the volume is read-only. (Read-only, value type CFBoolean) */ 986 987CF_EXPORT 988const CFStringRef kCFURLVolumeCreationDateKey CF_AVAILABLE(10_7, 5_0); 989 /* The volume's creation date, or NULL if this cannot be determined. (Read-only, value type CFDate) */ 990 991CF_EXPORT 992const CFStringRef kCFURLVolumeURLForRemountingKey CF_AVAILABLE(10_7, 5_0); 993 /* The CFURL needed to remount a network volume, or NULL if not available. (Read-only, value type CFURL) */ 994 995CF_EXPORT 996const CFStringRef kCFURLVolumeUUIDStringKey CF_AVAILABLE(10_7, 5_0); 997 /* 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) */ 998 999CF_EXPORT 1000const CFStringRef kCFURLVolumeNameKey CF_AVAILABLE(10_7, 5_0); 1001 /* The name of the volume (Read-write, settable if kCFURLVolumeSupportsRenamingKey is true and permissions allow, value type CFString) */ 1002 1003CF_EXPORT 1004const CFStringRef kCFURLVolumeLocalizedNameKey CF_AVAILABLE(10_7, 5_0); 1005 /* The user-presentable name of the volume (Read-only, value type CFString) */ 1006 1007/* UbiquitousItem Properties */ 1008 1009CF_EXPORT 1010const CFStringRef kCFURLIsUbiquitousItemKey CF_AVAILABLE(10_7, 5_0); 1011 /* true if this item is synced to the cloud, false if it is only a local file. (Read-only, value type CFBoolean) */ 1012 1013CF_EXPORT 1014const CFStringRef kCFURLUbiquitousItemHasUnresolvedConflictsKey CF_AVAILABLE(10_7, 5_0); 1015 /* true if this item has conflicts outstanding. (Read-only, value type CFBoolean) */ 1016 1017CF_EXPORT 1018const CFStringRef kCFURLUbiquitousItemIsDownloadedKey CF_DEPRECATED(10_7, 10_9, 5_0, 7_0, "Use kCFURLUbiquitousItemDownloadingStatusKey instead"); 1019 /* Equivalent to NSURLUbiquitousItemDownloadingStatusKey == NSURLUbiquitousItemDownloadingStatusCurrent. Has never behaved as documented in earlier releases, hence deprecated. (Read-only, value type CFBoolean) */ 1020 1021CF_EXPORT 1022const CFStringRef kCFURLUbiquitousItemIsDownloadingKey CF_AVAILABLE(10_7, 5_0); 1023 /* true if data is being downloaded for this item. (Read-only, value type CFBoolean) */ 1024 1025CF_EXPORT 1026const CFStringRef kCFURLUbiquitousItemIsUploadedKey CF_AVAILABLE(10_7, 5_0); 1027 /* true if there is data present in the cloud for this item. (Read-only, value type CFBoolean) */ 1028 1029CF_EXPORT 1030const CFStringRef kCFURLUbiquitousItemIsUploadingKey CF_AVAILABLE(10_7, 5_0); 1031 /* true if data is being uploaded for this item. (Read-only, value type CFBoolean) */ 1032 1033CF_EXPORT 1034const CFStringRef kCFURLUbiquitousItemPercentDownloadedKey CF_DEPRECATED(10_7, 10_8, 5_0, 6_0, "Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead"); 1035 /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead */ 1036 1037CF_EXPORT 1038const CFStringRef kCFURLUbiquitousItemPercentUploadedKey CF_DEPRECATED(10_7, 10_8, 5_0, 6_0, "Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead"); 1039 /* Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead */ 1040 1041CF_EXPORT 1042const CFStringRef kCFURLUbiquitousItemDownloadingStatusKey CF_AVAILABLE(10_9, 7_0); 1043 /* Returns the download status of this item. (Read-only, value type CFString). Possible values below. */ 1044 1045CF_EXPORT 1046const CFStringRef kCFURLUbiquitousItemDownloadingErrorKey CF_AVAILABLE(10_9, 7_0); 1047 /* returns the error when downloading the item from iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. */ 1048 1049CF_EXPORT 1050const CFStringRef kCFURLUbiquitousItemUploadingErrorKey CF_AVAILABLE(10_9, 7_0); 1051 /* returns the error when uploading the item to iCloud failed. See the NSUbiquitousFile section in FoundationErrors.h. */ 1052 1053/* The values returned for kCFURLUbiquitousItemDownloadingStatusKey 1054 */ 1055CF_EXPORT 1056const CFStringRef kCFURLUbiquitousItemDownloadingStatusNotDownloaded CF_AVAILABLE(10_9, 7_0); 1057 /* this item has not been downloaded yet. Use NSFileManager's startDownloadingUbiquitousItemAtURL:error: to download it */ 1058 1059CF_EXPORT 1060const CFStringRef kCFURLUbiquitousItemDownloadingStatusDownloaded CF_AVAILABLE(10_9, 7_0); 1061 /* there is a local version of this item available. The most current version will get downloaded as soon as possible. */ 1062 1063CF_EXPORT 1064const CFStringRef kCFURLUbiquitousItemDownloadingStatusCurrent CF_AVAILABLE(10_9, 7_0); 1065 /* there is a local version of this item and it is the most up-to-date version known to this device. */ 1066 1067 1068typedef CF_OPTIONS(CFOptionFlags, CFURLBookmarkCreationOptions) { 1069 kCFURLBookmarkCreationPreferFileIDResolutionMask CF_ENUM_DEPRECATED(10_6, 10_9, 4_0, 7_0, "kCFURLBookmarkCreationPreferFileIDResolutionMask does nothing and has no effect on bookmark resolution" ) = ( 1UL << 8 ), // This option does nothing and has no effect on bookmark resolution 1070 kCFURLBookmarkCreationMinimalBookmarkMask = ( 1UL << 9 ), // Creates a bookmark with "less" information, which may be smaller but still be able to resolve in certain ways 1071 kCFURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), // includes in the created bookmark those properties which are needed for a bookmark/alias file 1072 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 1073 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 1074}; 1075 1076enum { 1077 kCFBookmarkResolutionWithoutUIMask = ( 1UL << 8 ), // don't perform any UI during bookmark resolution 1078 kCFBookmarkResolutionWithoutMountingMask = ( 1UL << 9 ), // don't mount a volume during bookmark resolution 1079}; 1080 1081enum { 1082 kCFURLBookmarkResolutionWithSecurityScope CF_ENUM_AVAILABLE(10_7,NA) = ( 1UL << 10 ), // Mac OS X 10.7.3 and later, extract the security scope included at creation time to provide the ability to access the resource. 1083}; 1084 1085typedef CFOptionFlags CFURLBookmarkResolutionOptions; 1086 1087typedef CFOptionFlags CFURLBookmarkFileCreationOptions; 1088 1089CF_IMPLICIT_BRIDGING_DISABLED 1090 1091/* @function CFURLCreateBookmarkData 1092 @discussion Create a CFDataRef containing an externalizable representation from a CFURLRef, modified with the given options, including ( at the minimum ) any 1093 properties in the propertiesToInclude array which are retrievable from the given url. 1094 @param allocator the CFAllocator to use to create this object 1095 @param url the CFURLRef to create a bookmark data from. 1096 @param options a set of options which control creation of the bookmark data 1097 @param resourcePropertiesToInclude If non-NULL, an CFArrayRef of additional properties copied from the url to include in the created bookmark data. 1098 @param relativeToURL If non-NULL, the created bookmark will be relative to the given url. If kCFURLBookmarkCreationWithSecurityScope is given as 1099 an option and relativeToURL is non-NULL, then a collection-scoped bookmark is created which enables future access to url provided the caller has 1100 access to relativeURL. 1101 @param error If non-NULL, on exit will be filled in with a CFErrorRef representing any error which occured during creation of the bookmark data 1102 @result A CFDataRef containing an data, which can be later be passed to CFURLCreateByResolvingBookmarkData() or to CFURLCopyPropertiesForKeysFromBookmarkData() / CFURLCopyPropertyForKeyFromBookmarkData() */ 1103CF_EXPORT 1104CFDataRef CFURLCreateBookmarkData ( CFAllocatorRef allocator, CFURLRef url, CFURLBookmarkCreationOptions options, CFArrayRef resourcePropertiesToInclude, CFURLRef relativeToURL, CFErrorRef* error ) CF_AVAILABLE(10_6, 4_0); 1105 1106/* @function CFURLCreateByResolvingBookmarkData 1107 @discussion Given a CFDataRef created with CFURLCreateBookmarkRepresentation(), return a CFURLRef of the item it was a bookmark to, and 1108 attempt to pre-cache those properties in propertiesToInclude in the resulting url. If in the process of resolving the bookmark into the CFURLRef 1109 it points to this determines that some properties in the bookmark are out of date or not correct for the item it resolves to, set *isStale to YES, 1110 which the client may want to use to decide to make a new bookmark from the returned item and replace the saved bookmark it has. If the bookmarked 1111 item cannot be found, return NULL. A bookmark created with security scope may fail to resolve if the caller does not have the same code signing identity 1112 as the caller which created the bookmark. 1113 After resolving a security scoped bookmark, the caller must call CFURLStartAccessingSecurityScopedResource() in order to gain access to the resource. 1114 If an error ( other than "original item can not be found" ) occurs during the process, return NULL and fill in error ) 1115 @param allocator the CFAllocator to use to create this object 1116 @param bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData 1117 @param options options which affect the resolution 1118 @param relativeToURL If non-NULL, and if the bookmark was created relative to another url, then resolve it relative to this url. If 1119 kCFURLBookmarkCreationWithSecurityScope was provided at creation, and kCFURLBookmarkResolutionWithSecurityScope is set, then relativeURL 1120 should point to the same item which was passed as relavitiveURL at creation time. 1121 @param resourcePropertiesToInclude If non-NULL, a CFArray containing those properties which the caller would like to already be cached on the given url 1122 @param isStale If non-NULL, on exit will be set to true if during resolution any of the properties in the bookmark no longer seemed to match the 1123 corresponding properties on the returned file. Clients, upon seeing a stale representation, may want to replace whatever stored bookmark data they 1124 have saved and create a new one. 1125 @param error If non-NULL, on exit will be filled in with a CFErrorRef representing any error which occured during resolution of the bookmark data 1126 @result A CFURLRef of a file which is the closest match to the file the bookmark data */ 1127CF_EXPORT 1128CFURLRef CFURLCreateByResolvingBookmarkData ( CFAllocatorRef allocator, CFDataRef bookmark, CFURLBookmarkResolutionOptions options, CFURLRef relativeToURL, CFArrayRef resourcePropertiesToInclude, Boolean* isStale, CFErrorRef* error ) CF_AVAILABLE(10_6, 4_0); 1129 1130/* @function CFURLCreatePropertiesForKeysFromBookmarkData 1131 @discussion Given a bookmark, return a dictionary of properties . 1132 This returns only the properties stored within the bookmark and will not attempt to resolve the bookmark or do i/o. 1133 @param allocator the CFAllocator to use to create this object 1134 @param bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData 1135 @param propertiesToReturn a CFArrayRef of the properties of the bookmark data which the client would like returned. 1136 @result a CFDictionaryRef containing the values for the properties passed in obtained from the bookmark data ( not by attempting to resolve it or do i/o in any way ) */ 1137CF_EXPORT 1138CFDictionaryRef CFURLCreateResourcePropertiesForKeysFromBookmarkData ( CFAllocatorRef allocator, CFArrayRef resourcePropertiesToReturn, CFDataRef bookmark ) CF_AVAILABLE(10_6, 4_0); 1139 1140/* @function CFURLCreatePropertyForKeyFromBookmarkData 1141 @discussion Given a bookmark, return the value for a given property from the bookmark data 1142 This returns only the properties stored within the bookmark and will not attempt to resolve the bookmark or do i/o. 1143 @param allocator the CFAllocator to use to create this object 1144 @param bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData 1145 @param propertyKey the property key to return. 1146 @result a CFTypeRef value for the property passed in obtained from the bookmark data ( not by attempting to resolve it or do i/o in any way ) */ 1147CF_EXPORT 1148CFTypeRef CFURLCreateResourcePropertyForKeyFromBookmarkData( CFAllocatorRef allocator, CFStringRef resourcePropertyKey, CFDataRef bookmark ) CF_AVAILABLE(10_6, 4_0); 1149 1150/*! @function CFURLCreateBookmarkDataFromFile 1151 @description Given a fileURL of a file which is a Finder "alias" file, return a CFDataRef with the bookmark data from the file. If urlRef points to an alias file 1152 created before SnowLeopard which contains Alias Manager information and no bookmark data, then a CFDataRef will be synthesized which contains 1153 a approximation of the alias information in a format which can be used to resolve the bookmark. If an error prevents reading the data or 1154 if it is corrupt, NULL will be returned and error will be filled in if errorRef is non-NULL. 1155 @param allocator the CFAllocator to use to create this object 1156 @param fileURL a CFURLRef to to the alias file to create the bookmark data from 1157 @param errorRef if non-NULL, on exit will be filled in with a CFErrorRef representing any error which occurred during the creation of the bookmark data from the file 1158 @result A CFDataRef containing bookmark data, or NULL if there was an error creating bookmark data from the file, such as if the file is not an alias file. 1159 */ 1160CF_EXPORT 1161CFDataRef CFURLCreateBookmarkDataFromFile(CFAllocatorRef allocator, CFURLRef fileURL, CFErrorRef *errorRef ) CF_AVAILABLE(10_6, 5_0); 1162 1163/*! @function CFURLWriteBookmarkDataToFile 1164 @description Given a created bookmarkData object, create a new Finder "alias" file at fileURL which contains the bookmark data. If fileURL is a url to a directory, an alias file 1165 will be created with the same name as the bookmarked item and a ".alias" extension. If fileURL is a url for a file and it exists it will be overwritten. If a 1166 .alias extension is not present it will be added. In addition to the bookmark data, sufficient pre-SnowLeopard alias data will added to the file to allow 1167 systems running something before SnowLeopard to resolve this file using Alias Manager routines and get back the same file as the bookmark routines. 1168 The bookmark data must have been created with the kCFURLBookmarkCreationSuitableForBookmarkFile option and an error will be returned if not. 1169 @param allocator the CFAllocator to use to create this object 1170 @param bookmark a CFDataRef containing a bookmark data, created with CFURLCreateBookmarkData 1171 @param options options flags 1172 @param errorRef if non-NULL, on exit will be filled in with a CFErrorRef representing any error which occurred during the creation of the alias file 1173 */ 1174CF_EXPORT 1175Boolean CFURLWriteBookmarkDataToFile( CFDataRef bookmarkRef, CFURLRef fileURL, CFURLBookmarkFileCreationOptions options, CFErrorRef *errorRef ) CF_AVAILABLE(10_6, 5_0); 1176 1177/*! @function CFURLCreateBookmarkDataFromAliasRecord 1178 @discussion Create a CFDataRef containing bookmarkdata by converting the alias data in aliasRecordDataRef, which should be the contents of an AliasRecord copied into a CFDataRef object. 1179 The created bookmarkdata can be passed into CFURLCreateByResolvingBookmarkData() to resolve the item into a CFURLRef, or a small set of information can be returned from 1180 CFURLCreateResourcePropertiesForKeysFromBookmarkData() / CFURLCreateResourcePropertyForKeyFromBookmarkData(). 1181 @param allocator the CFAllocator to use to create this object 1182 @param aliasRecordDataRef the contents of an AliasRecord to create bookmark data for 1183 @result A CFDataRef containing an data, which can be later be passed to CFURLCreateByResolvingBookmarkData() or to CFURLCopyPropertiesForKeysFromBookmarkData() / CFURLCopyPropertyForKeyFromBookmarkData() 1184 */ 1185CF_EXPORT 1186CFDataRef CFURLCreateBookmarkDataFromAliasRecord ( CFAllocatorRef allocatorRef, CFDataRef aliasRecordDataRef ) CF_AVAILABLE_MAC(10_6); 1187 1188CF_IMPLICIT_BRIDGING_ENABLED 1189 1190/*! @function CFURLStartAccessingSecurityScopedResource 1191 @discussion Given a CFURLRef created by resolving a bookmark data created with security scope, make the resource referenced by the 1192 url accessible to the process. When access to this resource is no longer needed the client should call 1193 CFURLStopAccessingSecurityScopedResource(). Each call to CFURLStartAccessingSecurityScopedResource() must be balanced 1194 with a call to CFURLStopAccessingSecurityScopedResource(). 1195 @param url the CFURLRef for the resource returned by CFURLCreateByResolvingBookmarkData() using kCFURLBookmarkResolutionWithSecurityScope. 1196 @result returns TRUE if access was granted and FALSE if the url does not reference a security scoped resource, or if some error occurred 1197 which didn't allow access to be granted 1198 */ 1199CF_EXPORT 1200Boolean CFURLStartAccessingSecurityScopedResource(CFURLRef url) CF_AVAILABLE(10_7, NA); // Available in MacOS X 10.7.3 and later 1201 1202/*! @function CFURLStopAccessingSecurityScopedResource 1203 @discussion Revokes the access granted to the url by a prior successful call to CFURLStartAccessingSecurityScopedResource(). 1204 @param url the CFURLRef for the resource to stop accessing. 1205 */ 1206CF_EXPORT 1207void CFURLStopAccessingSecurityScopedResource(CFURLRef url) CF_AVAILABLE(10_7, NA); 1208 1209#endif /* TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE */ 1210 1211CF_EXTERN_C_END 1212CF_IMPLICIT_BRIDGING_DISABLED 1213 1214#endif /* ! __COREFOUNDATION_CFURL__ */ 1215 1216