CFURL Reference

Overview

The CFURL opaque type provides facilities for creating, parsing, and dereferencing URL strings. CFURL is useful to applications that need to use URLs to access resources, including local files.

A CFURL object is composed of two parts—a base URL, which can be NULL, and a string that is resolved relative to the base URL. A CFURL object whose string is fully resolved without a base URL is considered absolute; all others are considered relative.

CFURL is “toll-free bridged” with its Cocoa Foundation counterpart, NSURL. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. In other words, in a method where you see an NSURL * parameter, you can pass in a CFURLRef, and in a function where you see a CFURLRef parameter, you can pass in an NSURL instance. This also applies to concrete subclasses of NSURL. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Starting in OS X v10.6, the CFURL opaque type provides a facility for creating and using bookmarks. A bookmark provides a persistent reference to a file-system resource. When you resolve a bookmark, you obtain a URL to the resource’s current location. A bookmark’s association with a file-system resource (typically a file or folder) usually continues to work if the user moves or renames the resource, or if the user relaunches your app or restarts the system.

In an OS X app that adopts App Sandbox, to gain persistent access to a file-system resource you must use a security-scoped bookmark. Such a bookmark preserves, across app launches, a user’s intent to give your app access to a resource. For details on how this works, including information on the entitlements you need in your Xcode project, read “Security-Scoped Bookmarks and Persistent Resource Access” in App Sandbox Design Guide.

When you resolve a security-scoped bookmark, you get a security-scoped URL. The file system resource that the URL points to is not available for use inside your app’s sandbox until you call the CFURLStartAccessingSecurityScopedResource function (or its Cocoa equivalent, the startAccessingSecurityScopedResource method) on the URL.

When you no longer need access to a resource that you obtained using security scope (typically, after you close the resource) you must call the CFURLStopAccessingSecurityScopedResource method (or its Cocoa equivalent, the stopAccessingSecurityScopedResource method) on the resource’s URL.

The functions for using security-scoped bookmarks are described in this document in “Working with Bookmark Data.” For a general introduction to using bookmarks in OS X, read “Locating Files Using Bookmarks” in File System Programming Guide.

When you copy a security-scoped URL (as obtained from a security-scoped bookmark), the copy has the security scope of the original. You gain access to the file-system resource (that the URL points to) just as you would with the original URL: by calling the CFURLStartAccessingSecurityScopedResource function (or its Cocoa equivalent).

If you need a security-scoped URL’s path as a string value (as provided by the CFURLGetString function), such as to provide to an API that requires a string value, obtain the path from the URL as needed. Note, however, that a string-based path obtained from a security-scoped URL does not have security scope and you cannot use that string to obtain access a security-scoped resource.

CFURL fails to create an object if the string passed is not well-formed (that is, if it does not comply with RFC 2396). Examples of cases that will not succeed are strings containing space characters and high-bit characters. If a function fails to create a CFURL object, it returns NULL, which you must be prepared to handle. If you create CFURL objects using file system paths, you should use the CFURLCreateFromFileSystemRepresentation and CFURLCreateFromFileSystemRepresentationRelativeToBase functions, which handle the subtle differences between URL paths and file system paths.

For functions that read and write data from a URL, see Core Foundation URL Access Utilities Reference

Functions by Task

Creating a CFURL

• CFURLCopyAbsoluteURL
• CFURLCreateAbsoluteURLWithBytes
• CFURLCreateByResolvingBookmarkData
• CFURLCreateCopyAppendingPathComponent
• CFURLCreateCopyAppendingPathExtension
• CFURLCreateCopyDeletingLastPathComponent
• CFURLCreateCopyDeletingPathExtension
• CFURLCreateFilePathURL
• CFURLCreateFileReferenceURL
• CFURLCreateFromFileSystemRepresentation
• CFURLCreateFromFileSystemRepresentationRelativeToBase
• CFURLCreateFromFSRef
• CFURLCreateWithBytes
• CFURLCreateWithFileSystemPath
• CFURLCreateWithFileSystemPathRelativeToBase
• CFURLCreateWithString

Accessing the Parts of a URL

• CFURLCanBeDecomposed
• CFURLCopyFileSystemPath
• CFURLCopyFragment
• CFURLCopyHostName
• CFURLCopyLastPathComponent
• CFURLCopyNetLocation
• CFURLCopyParameterString
• CFURLCopyPassword
• CFURLCopyPath
• CFURLCopyPathExtension
• CFURLCopyQueryString
• CFURLCopyResourceSpecifier
• CFURLCopyScheme
• CFURLCopyStrictPath
• CFURLCopyUserName
• CFURLGetPortNumber
• CFURLHasDirectoryPath

Converting URLs to Other Representations

• CFURLCreateData
• CFURLCreateStringByAddingPercentEscapes
• CFURLCreateStringByReplacingPercentEscapes
• CFURLCreateStringByReplacingPercentEscapesUsingEncoding
• CFURLGetFileSystemRepresentation
• CFURLGetFSRef
• CFURLGetString

Getting URL Properties

• CFURLGetBaseURL
• CFURLGetBytes
• CFURLGetByteRangeForComponent
• CFURLGetTypeID
• CFURLResourceIsReachable

Getting and Setting File System Resource Properties

• CFURLClearResourcePropertyCache
• CFURLClearResourcePropertyCacheForKey
• CFURLCopyResourcePropertiesForKeys
• CFURLCopyResourcePropertyForKey
• CFURLCreateResourcePropertiesForKeysFromBookmarkData
• CFURLCreateResourcePropertyForKeyFromBookmarkData
• CFURLSetResourcePropertiesForKeys
• CFURLSetResourcePropertyForKey
• CFURLSetTemporaryResourcePropertyForKey

Working with Bookmark Data

• CFURLCreateBookmarkData
• CFURLCreateBookmarkDataFromAliasRecord
• CFURLCreateBookmarkDataFromFile
• CFURLWriteBookmarkDataToFile
• CFURLStartAccessingSecurityScopedResource
• CFURLStopAccessingSecurityScopedResource

Functions

CFURLCanBeDecomposed

Determines if the given URL conforms to RFC 1808 and therefore can be decomposed.

Boolean CFURLCanBeDecomposed (
   CFURLRef anURL
);

CFURLClearResourcePropertyCache

Clears all cached resource property values of a given URL.

void CFURLClearResourcePropertyCache (
   CFURLRef url
);

CFURLClearResourcePropertyCacheForKey

Discards a cached property value for a given key of a given URL.

void CFURLClearResourcePropertyCacheForKey (
   CFURLRef url,
   CFStringRef key
);

CFURLCopyAbsoluteURL

Creates a new CFURL object by resolving the relative portion of a URL against its base.

CFURLRef CFURLCopyAbsoluteURL (
   CFURLRef relativeURL
);

CFURLCopyFileSystemPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyFileSystemPath (
   CFURLRef       anURL,
   CFURLPathStyle pathStyle
);

CFURLCopyFragment

Returns the fragment from a given URL.

CFStringRef CFURLCopyFragment (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);

CFURLCopyHostName

Returns the host name of a given URL.

CFStringRef CFURLCopyHostName (
   CFURLRef anURL
);

CFURLCopyLastPathComponent

Returns the last path component of a given URL.

CFStringRef CFURLCopyLastPathComponent (
   CFURLRef url
);

CFStringRef urlString = CFSTR("http://www.apple.com");

CFURLRef url = CFURLCreateWithString(NULL, urlString, NULL);

CFStringRef lastPathComponent = CFURLCopyLastPathComponent (url);

CFURLCopyNetLocation

Returns the net location portion of a given URL.

CFStringRef CFURLCopyNetLocation (
   CFURLRef anURL
);

CFURLCopyParameterString

Returns the parameter string from a given URL.

CFStringRef CFURLCopyParameterString (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);

CFURLCopyPassword

Returns the password of a given URL.

CFStringRef CFURLCopyPassword (
   CFURLRef anURL
);

CFURLCopyPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyPath (
   CFURLRef anURL
);

CFURLCopyPathExtension

Returns the path extension of a given URL.

CFStringRef CFURLCopyPathExtension (
   CFURLRef url
);

CFURLCopyQueryString

Returns the query string of a given URL.

CFStringRef CFURLCopyQueryString (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);

CFURLCopyResourcePropertiesForKeys

Returns any number of resource property values of a URL as a dictionary.

CFDictionaryRef CFURLCopyResourcePropertiesForKeys (
   CFURLRef   url,
   CFArrayRef keys,
   CFErrorRef *error
);

CFURLCopyResourcePropertyForKey

Returns the value of a given resource property of a given URL.

Boolean CFURLCopyResourcePropertyForKey (
   CFURLRef    url,
   CFStringRef key,
   void        *propertyValueTypeRefPtr,
   CFErrorRef  *error
);

CFURLCopyResourceSpecifier

Returns any additional resource specifiers after the path.

CFStringRef CFURLCopyResourceSpecifier (
   CFURLRef anURL
);

CFURLCopyScheme

Returns the scheme portion of a given URL.

CFStringRef CFURLCopyScheme (
   CFURLRef anURL
);

CFURLCopyStrictPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyStrictPath (
   CFURLRef anURL,
   Boolean  *isAbsolute
);

CFURLCopyUserName

Returns the user name from a given URL.

CFStringRef CFURLCopyUserName (
   CFURLRef anURL
);

CFURLCreateAbsoluteURLWithBytes

Creates a new CFURL object by resolving the relative portion of a URL, specified as bytes, against its given base URL.

CFURLRef CFURLCreateAbsoluteURLWithBytes (
   CFAllocatorRef   alloc,
   const UInt8      *relativeURLBytes,
   CFIndex          length,
   CFStringEncoding encoding,
   CFURLRef         baseURL,
   Boolean          useCompatibilityMode
);

CFURLCreateBookmarkData

Returns bookmark data for a URL, created with specified options and resource values.

CFDataRef CFURLCreateBookmarkData (
   CFAllocatorRef               allocator,
   CFURLRef                     url,
   CFURLBookmarkCreationOptions options,
   CFArrayRef                   resourcePropertiesToInclude,
   CFURLRef                     relativeToURL,
   CFErrorRef                   *error
);

CFURLCreateBookmarkDataFromAliasRecord

Initializes and returns bookmark data derived from an alias record.

CFDataRef CFURLCreateBookmarkDataFromAliasRecord (
   CFAllocatorRef allocatorRef,
   CFDataRef      aliasRecordDataRef
);

CFURLCreateBookmarkDataFromFile

Initializes and returns bookmark data derived from a file pointed to by a specified URL.

CFDataRef CFURLCreateBookmarkDataFromFile (
   CFAllocatorRef allocator,
   CFURLRef       fileURL,
   CFErrorRef     *errorRef
);

CFURLCreateByResolvingBookmarkData

Returns a new URL made by resolving bookmark data.

CFURLRef CFURLCreateByResolvingBookmarkData (
   CFAllocatorRef                 allocator,
   CFDataRef                      bookmark,
   CFURLBookmarkResolutionOptions options,
   CFURLRef                       relativeToURL,
   CFArrayRef                     resourcePropertiesToInclude,
   Boolean                        *isStale,
   CFErrorRef                     *error
);

CFURLCreateCopyAppendingPathComponent

Creates a copy of a given URL and appends a path component.

CFURLRef CFURLCreateCopyAppendingPathComponent (
   CFAllocatorRef allocator,
   CFURLRef       url,
   CFStringRef    pathComponent,
   Boolean        isDirectory
);

CFURLCreateCopyAppendingPathExtension

Creates a copy of a given URL and appends a path extension.

CFURLRef CFURLCreateCopyAppendingPathExtension (
   CFAllocatorRef allocator,
   CFURLRef       url,
   CFStringRef    extension
);

CFURLCreateCopyDeletingLastPathComponent

Creates a copy of a given URL with the last path component deleted.

CFURLRef CFURLCreateCopyDeletingLastPathComponent (
   CFAllocatorRef allocator,
   CFURLRef       url
);

CFURLCreateCopyDeletingPathExtension

Creates a copy of a given URL with its last path extension removed.

CFURLRef CFURLCreateCopyDeletingPathExtension (
   CFAllocatorRef allocator,
   CFURLRef       url
);

CFURLCreateData

Creates a CFData object containing the content of a given URL.

CFDataRef CFURLCreateData (
   CFAllocatorRef   allocator,
   CFURLRef         url,
   CFStringEncoding encoding,
   Boolean          escapeWhitespace
);

CFURLCreateFilePathURL

Initializes and returns a newly created CFURL object as a file URL with a specified path.

CFURLRef CFURLCreateFilePathURL (
   CFAllocatorRef allocator,
   CFURLRef       url,
   CFErrorRef     *error
);

CFURLCreateFileReferenceURL

Returns a new file reference URL that points to the same resource as a specified URL.

CFURLRef CFURLCreateFileReferenceURL (
   CFAllocatorRef allocator,
   CFURLRef       url,
   CFErrorRef     *error
);

CFURLCreateFromFileSystemRepresentation

Creates a new CFURL object for a file system entity using the native representation.

CFURLRef CFURLCreateFromFileSystemRepresentation (
   CFAllocatorRef allocator,
   const UInt8    *buffer,
   CFIndex        bufLen,
   Boolean        isDirectory
);

CFURLCreateFromFileSystemRepresentationRelativeToBase

Creates a CFURL object from a native character string path relative to a base URL.

CFURLRef CFURLCreateFromFileSystemRepresentationRelativeToBase (
   CFAllocatorRef allocator,
   const UInt8    *buffer,
   CFIndex        bufLen,
   Boolean        isDirectory,
   CFURLRef       baseURL
);

CFURLCreateFromFSRef

Creates a URL from a given directory or file.

CFURLRef CFURLCreateFromFSRef (
   CFAllocatorRef     allocator,
   const struct FSRef *fsRef
);

CFURLCreateResourcePropertiesForKeysFromBookmarkData

Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data.

CFDictionaryRef CFURLCreateResourcePropertiesForKeysFromBookmarkData (
   CFAllocatorRef allocator,
   CFArrayRef     resourcePropertiesToReturn,
   CFDataRef      bookmark
);

CFURLCreateResourcePropertyForKeyFromBookmarkData

Returns the value of a resource property from specified bookmark data.

CFTypeRef CFURLCreateResourcePropertyForKeyFromBookmarkData (
   CFAllocatorRef allocator,
   CFStringRef    resourcePropertyKey,
   CFDataRef      bookmark
);

CFURLCreateStringByAddingPercentEscapes

Creates a copy of a string, replacing certain characters with the equivalent percent escape sequence based on the specified encoding.

CFStringRef CFURLCreateStringByAddingPercentEscapes (
   CFAllocatorRef   allocator,
   CFStringRef      originalString,
   CFStringRef      charactersToLeaveUnescaped,
   CFStringRef      legalURLCharactersToBeEscaped,
   CFStringEncoding encoding
);

CFStringRef originalURLString = CFSTR("http://online.store.com/storefront/?request=get-document&doi=10.1175%2F1520-0426(2005)014%3C1157:DODADSS%3E2.0.CO%3B2");

CFStringRef preprocessedString =

    CFURLCreateStringByReplacingPercentEscapesUsingEncoding(kCFAllocatorDefault, originalURLString, CFSTR(""), kCFStringEncodingUTF8);

CFStringRef urlString =

    CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, preprocessedString, NULL, NULL, kCFStringEncodingUTF8);

url = CFURLCreateWithString(kCFAllocatorDefault, urlString, NULL);

CFURLCreateStringByReplacingPercentEscapes

Creates a new string by replacing any percent escape sequences with their character equivalent.

CFStringRef CFURLCreateStringByReplacingPercentEscapes (
   CFAllocatorRef allocator,
   CFStringRef    originalString,
   CFStringRef    charactersToLeaveEscaped
);

CFURLCreateStringByReplacingPercentEscapesUsingEncoding

Creates a new string by replacing any percent escape sequences with their character equivalent.

CFStringRef CFURLCreateStringByReplacingPercentEscapesUsingEncoding (
   CFAllocatorRef   allocator,
   CFStringRef      origString,
   CFStringRef      charsToLeaveEscaped,
   CFStringEncoding encoding
);

CFURLCreateWithBytes

Creates a CFURL object using a given character bytes.

CFURLRef CFURLCreateWithBytes (
   CFAllocatorRef   allocator,
   const UInt8      *URLBytes,
   CFIndex          length,
   CFStringEncoding encoding,
   CFURLRef         baseURL
);

CFURLCreateWithFileSystemPath

Creates a CFURL object using a local file system path string.

CFURLRef CFURLCreateWithFileSystemPath (
   CFAllocatorRef allocator,
   CFStringRef    filePath,
   CFURLPathStyle pathStyle,
   Boolean        isDirectory
);

CFURLCreateWithFileSystemPathRelativeToBase

Creates a CFURL object using a local file system path string relative to a base URL.

CFURLRef CFURLCreateWithFileSystemPathRelativeToBase (
   CFAllocatorRef allocator,
   CFStringRef    filePath,
   CFURLPathStyle pathStyle,
   Boolean        isDirectory,
   CFURLRef       baseURL
);

CFURLCreateWithString

Creates a CFURL object using a given CFString object.

CFURLRef CFURLCreateWithString (
   CFAllocatorRef allocator,
   CFStringRef    URLString,
   CFURLRef       baseURL
);

CFURLGetBaseURL

Returns the base URL of a given URL if it exists.

CFURLRef CFURLGetBaseURL (
   CFURLRef anURL
);

CFURLGetByteRangeForComponent

Returns the range of the specified component in the bytes of a URL.

CFRange CFURLGetByteRangeForComponent (
   CFURLRef           url,
   CFURLComponentType component,
   CFRange            *rangeIncludingSeparators
);

CFURLGetBytes

Returns by reference the byte representation of a URL object.

CFIndex CFURLGetBytes (
   CFURLRef url,
   UInt8    *buffer,
   CFIndex  bufferLength
);

CFURLGetFileSystemRepresentation

Fills a buffer with the file system's native string representation of a given URL's path.

Boolean CFURLGetFileSystemRepresentation (
   CFURLRef url,
   Boolean  resolveAgainstBase,
   UInt8    *buffer,
   CFIndex  maxBufLen
);

CFURLGetFSRef

Converts a given URL to a file or directory object.

Boolean CFURLGetFSRef (
   CFURLRef     url,
   struct FSRef *fsRef
);

CFURLGetPortNumber

Returns the port number from a given URL.

SInt32 CFURLGetPortNumber (
   CFURLRef anURL
);

CFURLGetString

Returns the URL as a CFString object.

CFStringRef CFURLGetString (
   CFURLRef anURL
);

CFURLGetTypeID

Returns the type identifier for the CFURL opaque type.

CFTypeID CFURLGetTypeID (
   void
);

CFURLHasDirectoryPath

Determines if a given URL's path represents a directory.

Boolean CFURLHasDirectoryPath (
   CFURLRef anURL
);

CFURLResourceIsReachable

Returns whether the resource pointed to by a file URL can be reached.

Boolean CFURLResourceIsReachable (
   CFURLRef   url,
   CFErrorRef *error
);

CFURLSetResourcePropertiesForKeys

Sets resource properties of a URL specified by a given dictionary of keys and values.

Boolean CFURLSetResourcePropertiesForKeys (
   CFURLRef url,
   CFDictionaryRef keyedPropertyValues,
   CFErrorRef      *error
);

CFURLSetResourcePropertyForKey

Sets the resource property of the URL specified by a given key to a given value.

Boolean CFURLSetResourcePropertyForKey (
   CFURLRef    url,
   CFStringRef key,
   CFTypeRef   propertyValue,
   CFErrorRef  *error
);

CFURLSetTemporaryResourcePropertyForKey

Sets the resource property of the URL specified by a given key to a given value without writing the assignment to the backing store.

void CFURLSetTemporaryResourcePropertyForKey (
   CFURLRef    url,
   CFStringRef key,
   CFTypeRef   propertyValue
);

CFURLStartAccessingSecurityScopedResource

In an app that has adopted App Sandbox, makes the resource pointed to by a security-scoped URL available to the app.

Boolean CFURLStartAccessingSecurityScopedResource (
   CFURLRef url
);

CFURLStopAccessingSecurityScopedResource

In an app that adopts App Sandbox, revokes access to the resource pointed to by a security-scoped URL.

void CFURLStopAccessingSecurityScopedResource (
   CFURLRef url
);

CFURLWriteBookmarkDataToFile

Creates an alias file on disk at a specified location with specified bookmark data.

Boolean CFURLWriteBookmarkDataToFile (
   CFDataRef                        bookmarkRef,
   CFURLRef                         fileURL,
   CFURLBookmarkFileCreationOptions options,
   CFErrorRef                       *errorRef
);

Data Types

Bookmark Data Types

CFURLBookmarkCreationOptions

Type for bookmark data creation options.

typedef CFOptionFlags CFURLBookmarkCreationOptions;

CFURLBookmarkFileCreationOptions

Type for bookmark file creation options.

typedef CFOptionFlags CFURLBookmarkFileCreationOptions;

CFURLBookmarkResolutionOptions

Type for bookmark data resolution options.

typedef CFOptionFlags CFURLBookmarkResolutionOptions;

Miscellaneous

CFURLRef

A reference to a CFURL object.

typedef const struct __CFURL *CFURLRef;

Constants

Bookmark Data Constants

Bookmark Data Creation Options

Options used when creating bookmark data.

enum {
   kCFURLBookmarkCreationPreferFileIDResolutionMask       = ( 1UL << 8 ),
   kCFURLBookmarkCreationMinimalBookmarkMask              = ( 1UL << 9 ),
   kCFURLBookmarkCreationSuitableForBookmarkFile          = ( 1UL << 10 ),
   kCFURLBookmarkCreationWithSecurityScope                = ( 1UL << 11 ),
   kCFURLBookmarkCreationSecurityScopeAllowOnlyReadAccess = ( 1UL << 12 )
};
typedef CFOptionFlags CFURLBookmarkCreationOptions;

Constants

kCFURLBookmarkCreationPreferFileIDResolutionMask

Specifies that an alias created with the bookmark data prefers resolving with its embedded file ID.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLBookmarkCreationMinimalBookmarkMask

Specifies that an alias created with the bookmark data be created with minimal information, which may make it smaller but still able to resolve in certain ways.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLBookmarkCreationSuitableForBookmarkFile

Specifies that the bookmark data include properties required to create Finder alias files.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLBookmarkCreationWithSecurityScope

Specifies that you want to create a security-scoped bookmark that, when resolved, provides a security-scoped URL allowing read/write access to a file-system resource; for use in an app that adopts App Sandbox.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLBookmarkCreationSecurityScopeAllowOnlyReadAccess

When combined with the kCFURLBookmarkCreationWithSecurityScope option, specifies that you want to create a security-scoped bookmark that, when resolved, provides a security-scoped URL allowing read-only access to a file-system resource; for use in an app that adopts App Sandbox.

Available in OS X v10.7 and later.

Declared in CFURL.h.

Bookmark Data Resolution Options

Options used when resolving bookmark data.

enum {
   kCFBookmarkResolutionWithoutUIMask        = ( 1UL << 8 ),
   kCFBookmarkResolutionWithoutMountingMask  = ( 1UL << 9 ),
   kCFURLBookmarkResolutionWithSecurityScope = ( 1UL << 10 )
};
typedef CFOptionFlags CFURLBookmarkResolutionOptions;
typedef CFOptionFlags CFURLBookmarkFileCreationOptions;

Constants

kCFBookmarkResolutionWithoutUIMask

Specifies that no UI feedback accompany resolution of the bookmark data.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFBookmarkResolutionWithoutMountingMask

Specifies that no volume should be mounted during resolution of the bookmark data.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLBookmarkResolutionWithSecurityScope

Specifies that the security scope, applied to the bookmark when it was created, should be used during resolution of the bookmark data.

Available in OS X v10.7 and later.

Declared in CFURL.h.

File System Constants

Common File System Resource Keys

Keys that are applicable to file system URLs.

kCFURLNameKey kCFURLLocalizedNameKey kCFURLIsRegularFileKey
kCFURLIsDirectoryKey
kCFURLIsSymbolicLinkKey kCFURLIsVolumeKey kCFURLIsPackageKey
kCFURLIsSystemImmutableKey
kCFURLIsUserImmutableKey kCFURLIsHiddenKey kCFURLHasHiddenExtensionKey
kCFURLCreationDateKey
kCFURLContentAccessDateKey kCFURLContentModificationDateKey kCFURLAttributeModificationDateKey
kCFURLLinkCountKey
kCFURLParentDirectoryURLKey kCFURLVolumeURLKey kCFURLTypeIdentifierKey
kCFURLLocalizedTypeDescriptionKey
kCFURLLabelNumberKey kCFURLLabelColorKey kCFURLLocalizedLabelKey
kCFURLEffectiveIconKey
kCFURLCustomIconKey kCFURLFileResourceIdentifierKey kCFURLVolumeIdentifierKey
kCFURLPreferredIOBlockSizeKey
kCFURLIsReadableKey kCFURLIsWritableKey kCFURLIsExecutableKey
kCFURLFileSecurityKey
const CFStringRef kCFURLIsExcludedFromBackupKey;
const CFStringRef kCFURLFileResourceTypeKey;
kCFURLFileResourceTypeKey

Constants

kCFURLNameKey

Key for the resource’s name in the file system, returned as a CFString object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLocalizedNameKey

Key for the resource’s localized or extension-hidden name, retuned as a CFString object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsRegularFileKey

Key for determining whether the resource is a regular file, as opposed to a directory or a symbolic link. Returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsDirectoryKey

Key for determining whether the resource is a directory, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsSymbolicLinkKey

Key for determining whether the resource is a symbolic link, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsVolumeKey

Key for determining whether the resource is the root directory of a volume, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsPackageKey

Key for determining whether the resource is a packaged directory, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsSystemImmutableKey

Key for determining whether the resource's system immutable bit is set, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsUserImmutableKey

Key for determining whether the resource's user immutable bit is set, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsHiddenKey

Key for determining whether the resource is normally not displayed to users, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLHasHiddenExtensionKey

Key for determining whether the resource’s extension is normally removed from its localized name, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLCreationDateKey

Key for the resource’s creation date, returned as a CFDate object if the volume supports creation dates, or nil if creation dates are unsupported.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLContentAccessDateKey

Key for the last time the resource was accessed, returned as a CFDate object if the volume supports access dates, or nil if access dates are unsupported.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLContentModificationDateKey

Key for the last time the resource was modified, returned as a CFDate object if the volume supports modification dates, or nil if modification dates are unsupported.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLAttributeModificationDateKey

Key for the last time the resource’s attributes were modified, returned as a CFDate object if the volume supports attribute modification dates, or nil if attribute modification dates are unsupported.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLinkCountKey

Key for the number of hard links to the resource, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLParentDirectoryURLKey

Key for the parent directory of the resource, returned as a CFURL object, or nil if the resource is the root directory of its volume.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeURLKey

Key for the root directory of the resource’s volume, returned as a CFURL object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLTypeIdentifierKey

Key for the resource’s uniform type identifier (UTI), returned as a CFString object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLocalizedTypeDescriptionKey

Key for the resource’s localized type description, returned as a CFString object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLabelNumberKey

Key for the resource’s label number, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLabelColorKey

Key for the resource’s label color, returned as a CFColorRef object, or NULL if the resource has no label color.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLLocalizedLabelKey

Key for the resource’s localized label text, returned as a CFString object, or NULL if the resource has no localized label text.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLEffectiveIconKey

Key for the resource’s normal icon, returned as a CGImageRef object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLCustomIconKey

Key for the icon stored with the resource, returned as a CGImageRef object, or NULL if the resource has no custom icon.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLFileResourceIdentifierKey

Key for the resource’s unique identifier, returned as a CFType object.

This identifier can be used to determine equality between file system resources with the CFEqual function. Two resources are equal if they have the same file-system path or if their paths link to the same inode on the same file system.

The value of this identifier is not persistent across system restarts.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIdentifierKey

Key for the unique identifier of the resource’s volume, returned as a CFType object.

This identifier can be used with the CFEqual function to determine whether two file system resources are on the same volume.

The value of this identifier is not persistent across system restarts.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLPreferredIOBlockSizeKey

Key for the optimal block size to use when reading or writing this file's data, returned as a CFNumber object, or NULL if the preferred size is not available.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLIsReadableKey

Key for determining whether the current process (as determined by the EUID) can read the resource, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLIsWritableKey

Key for determining whether the current process (as determined by the EUID) can write to the resource, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLIsExecutableKey

Key for determining whether the current process (as determined by the EUID) can execute the resource (if it is a file) or search the resource (if it is a directory), returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileSecurityKey

Key for the resource’s security information, returned as a CFFileSecurity object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLIsExcludedFromBackupKey

Key for determining whether the resource is excluded from all backups of app data, returned as a CFBoolean object.

Available in OS X v10.8 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeKey

Key for the resource’s object type, returned as a CFString object. See “File Resource Types” for possible values.

Available in OS X v10.7 and later.

Declared in CFURL.h.

File Resource Types

Possible values for the kCFURLFileResourceTypeKey key.

kCFURLFileResourceTypeBlockSpecial kCFURLFileResourceTypeCharacterSpecial
kCFURLFileResourceTypeDirectory
kCFURLFileResourceTypeNamedPipe kCFURLFileResourceTypeRegular
kCFURLFileResourceTypeSocket
kCFURLFileResourceTypeSymbolicLink kCFURLFileResourceTypeUnknown

Constants

kCFURLFileResourceTypeBlockSpecial

The resource is a block special file.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeCharacterSpecial

The resource is a character special file.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeDirectory

The resource is a directory.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeNamedPipe

The resource is a named pipe.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeRegular

The resource is a regular file.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeSocket

The resource is a socket.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeSymbolicLink

The resource is a symbolic link.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeUnknown

The resource’s type is unknown.

Available in OS X v10.7 and later.

Declared in CFURL.h.

File Property Keys

Keys that apply to properties of files.

kCFURLFileAllocatedSizeKey kCFURLFileSizeKey
kCFURLIsAliasFileKey
kCFURLIsMountTriggerKey kCFURLTotalFileAllocatedSizeKey
kCFURLTotalFileSizeKey

Constants

kCFURLFileAllocatedSizeKey

Key for the total size allocated on disk for the file, returned as an CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLFileSizeKey

Key for the file’s size in bytes, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsAliasFileKey

Key for determining whether the file is an alias, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLIsMountTriggerKey

Key for determining whether the URL is a file system trigger directory, returned as a CFBoolean object. Traversing or opening a file system trigger directory causes an attempt to mount a file system on the directory.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLTotalFileAllocatedSizeKey

Key for the total allocated size of the file in bytes, returned as a CFNumber object. This includes the size of any file metadata.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLTotalFileSizeKey

Key for the total displayable size of the file in bytes, returned as a CFNumber object. This includes the size of any file metadata.

Available in OS X v10.7 and later.

Declared in CFURL.h.

Volume Property Keys

Keys that apply to volumes.

kCFURLVolumeNameKey kCFURLVolumeLocalizedNameKey
kCFURLVolumeLocalizedFormatDescriptionKey
kCFURLVolumeTotalCapacityKey kCFURLVolumeAvailableCapacityKey
kCFURLVolumeResourceCountKey
kCFURLVolumeSupportsPersistentIDsKey kCFURLVolumeSupportsSymbolicLinksKey
kCFURLVolumeSupportsHardLinksKey
kCFURLVolumeSupportsJournalingKey kCFURLVolumeIsJournalingKey
kCFURLVolumeSupportsSparseFilesKey
kCFURLVolumeSupportsZeroRunsKey kCFURLVolumeSupportsCaseSensitiveNamesKey
kCFURLVolumeSupportsCasePreservedNamesKey
kCFURLVolumeSupportsRootDirectoryDatesKey kCFURLVolumeSupportsVolumeSizesKey
kCFURLVolumeSupportsRenamingKey
kCFURLVolumeSupportsAdvisoryFileLockingKey kCFURLVolumeSupportsExtendedSecurityKey
kCFURLVolumeIsBrowsableKey
kCFURLVolumeMaximumFileSizeKey kCFURLVolumeIsEjectableKey
kCFURLVolumeIsRemovableKey
kCFURLVolumeIsInternalKey kCFURLVolumeIsAutomountedKey
kCFURLVolumeIsLocalKey
kCFURLVolumeIsReadOnlyKey kCFURLVolumeCreationDateKey
kCFURLVolumeURLForRemountingKey
kCFURLVolumeUUIDStringKe y

Constants

kCFURLVolumeNameKey

The name of the volume, returned as a CFString object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeLocalizedNameKey

The user-presentable name of the volume, returned as a CFString object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeLocalizedFormatDescriptionKey

Key for the volume’s descriptive format name, returned as a CFString object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeTotalCapacityKey

Key for the volume’s capacity in bytes, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeAvailableCapacityKey

Key for the volume’s available capacity in bytes, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeResourceCountKey

Key for the total number of resources on the volume, returned as a CFNumber object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsPersistentIDsKey

Key for determining whether the volume supports persistent IDs, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsSymbolicLinksKey

Key for determining whether the volume supports symbolic links, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsHardLinksKey

Key for determining whether the volume supports hard links, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsJournalingKey

Key for determining whether the volume supports journaling, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeIsJournalingKey

Key for determining whether the volume is currently journaling, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsSparseFilesKey

Key for determining whether the volume supports sparse files, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsZeroRunsKey

Key for determining whether the volume supports zero runs, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsCaseSensitiveNamesKey

Key for determining whether the volume supports case-sensitive names, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsCasePreservedNamesKey

Key for determining whether the volume supports case-preserved names, returned as a CFBoolean object.

Available in OS X v10.6 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsRootDirectoryDatesKey

Key for determining whether the volume supports reliable storage of times for the root directory, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsVolumeSizesKey

Key for determining whether the volume supports returning volume size information, returned as a CFBoolean object. If true, volume size information is available as values of the kCFURLVolumeTotalCapacityKey and kCFURLVolumeAvailableCapacityKey keys.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsRenamingKey

Key for determining whether the volume can be renamed, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsAdvisoryFileLockingKey

Key for determining whether the volume implements whole-file advisory locks in the style of flock, along with the O_EXLOCK and O_SHLOCK flags of the open function, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsExtendedSecurityKey

Key for determining whether the volume supports extended security (access control lists), returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsBrowsableKey

Key for determining whether the volume is visible in GUI-based file-browsing environments, such as the Desktop or the Finder application, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeMaximumFileSizeKey

Key for the largest file size supported by the volume in bytes, returned as a CFNumber object, or NULL if it cannot be determined.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsEjectableKey

Key for determining whether the volume is ejectable from the drive mechanism under software control, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsRemovableKey

Key for determining whether the volume is removable from the drive mechanism, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsInternalKey

Key for determining whether the volume is connected to an internal bus, returned as a CFBoolean object, or NULL if it cannot be determined.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsAutomountedKey

Key for determining whether the volume is automounted, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsLocalKey

Key for determining whether the volume is stored on a local device, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeIsReadOnlyKey

Key for determining whether the volume is read-only, returned as a CFBoolean object.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeCreationDateKey

Key for the volume’s creation date, returned as a CFDate object, or NULL if it cannot be determined.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeURLForRemountingKey

Key for the URL needed to remount the network volume, returned as a CFURL object, or NULL if a URL is not available.

Available in OS X v10.7 and later.

Declared in CFURL.h.

kCFURLVolumeUUIDStringKey

Key for the volume’s persistent UUID, returned as a CFString object, or NULL if a persistent UUID is not available.

Available in OS X v10.7 and later.

Declared in CFURL.h.

CFError userInfo Dictionary Keys

Keys in the userInfo dictionary of a CFError object when certain CFURL functions return an error.

kCFURLKeysOfUnsetValuesKe y

Constants

kCFURLKeysOfUnsetValuesKey

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.

Available in OS X v10.7 and later.

Declared in CFURL.h.

Miscellaneous

Component Type

The types of components in a URL.

typedef enum {
   kCFURLComponentScheme = 1,
   kCFURLComponentNetLocation = 2,
   kCFURLComponentPath = 3,
   kCFURLComponentResourceSpecifier = 4,
   kCFURLComponentUser = 5,
   kCFURLComponentPassword = 6,
   kCFURLComponentUserInfo = 7,
   kCFURLComponentHost = 8,
   kCFURLComponentPort = 9,
   kCFURLComponentParameterString = 10,
   kCFURLComponentQuery = 11,
   kCFURLComponentFragment = 12
} CFURLComponentType;
typedef enum CFURLPathStyle CFURLPathStyle;

Constants

kCFURLComponentScheme

The URL’s scheme.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentNetLocation

The URL’s network location.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentPath

The URL’s path component.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentResourceSpecifier

The URL’s resource specifier.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentUser

The URL’s user.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentPassword

The user’s password.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentUserInfo

The user’s information.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentHost

The URL’s host.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentPort

The URL’s port.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentParameterString

The URL’s parameter string.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentQuery

The URL’s query.

Available in OS X v10.3 and later.

Declared in CFURL.h.

kCFURLComponentFragment

The URL’s fragment.

Available in OS X v10.3 and later.

Declared in CFURL.h.

Path Style

Options you can use to determine how CFURL functions parse a file system path name.

enum CFURLPathStyle {
   kCFURLPOSIXPathStyle = 0,
   kCFURLHFSPathStyle = 1,
   kCFURLWindowsPathStyle = 2
};
typedef enum CFURLPathStyle CFURLPathStyle;

Constants

kCFURLPOSIXPathStyle

Indicates a POSIX style path name. Components are slash delimited. A leading slash indicates an absolute path; a trailing slash is not significant.

Available in OS X v10.0 and later.

Declared in CFURL.h.

kCFURLHFSPathStyle

Indicates a HFS style path name. Components are colon delimited. A leading colon indicates a relative path, otherwise the first path component denotes the volume.

Available in OS X v10.0 and later.

Declared in CFURL.h.

kCFURLWindowsPathStyle

Indicates a Windows style path name.

Available in OS X v10.0 and later.

Declared in CFURL.h.