CFURL Reference

Derived from
Framework
CoreFoundation/Headers/CoreFoundation.h
Declared in
CFURL.h

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

Accessing the Parts of a URL

Converting URLs to Other Representations

Getting URL Properties

Getting and Setting File System Resource Properties

Working with Bookmark Data

Functions

CFURLCanBeDecomposed

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

Boolean CFURLCanBeDecomposed (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to test.

Return Value

true if anURL conforms to RFC 1808, false otherwise.

Discussion

If a CFURL object can be decomposed, you can retrieve separately each of the four components (scheme, net location, path, and resource specifier), as well as the base URL.

Relative URLs are permitted to have only paths (or a variety of other configurations); these are considered decomposable if their base URL is decomposable. If no base URL is present, they are considered decomposable.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLClearResourcePropertyCache

Clears all cached resource property values of a given URL.

void CFURLClearResourcePropertyCache (
   CFURLRef url
);
Parameters
url

The URL.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLClearResourcePropertyCacheForKey

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

void CFURLClearResourcePropertyCacheForKey (
   CFURLRef url,
   CFStringRef key
);
Parameters
url

The URL.

key

The property value key.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLCopyAbsoluteURL

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

CFURLRef CFURLCopyAbsoluteURL (
   CFURLRef relativeURL
);
Parameters
relativeURL

The CFURL object to resolve.

Return Value

A new CFURL object, or NULL if relativeURL cannot be made absolute. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyFileSystemPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyFileSystemPath (
   CFURLRef       anURL,
   CFURLPathStyle pathStyle
);
Parameters
anURL

The CFURL object whose path you want to obtain.

pathStyle

The operating system path style to be used to create the path. See “Path Style” for a list of possible values.

Return Value

The URL's path in the format specified by pathStyle. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function returns the URL's path as a file system path for a given path style.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyFragment

Returns the fragment from a given URL.

CFStringRef CFURLCopyFragment (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);
Parameters
anURL

The CFURL object whose fragment you want to obtain.

charactersToLeaveEscaped

Characters whose percent escape sequences, such as %20 for a space character, you want to leave intact. Pass NULL to specify that no percent escapes be replaced, or the empty string (CFSTR("")) to specify that all be replaced.

Return Value

The fragment, or NULL if no fragment exists. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

A fragment is the text following a "#". These are generally used to indicate locations within a single file. This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyHostName

Returns the host name of a given URL.

CFStringRef CFURLCopyHostName (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The host name of anURL. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyLastPathComponent

Returns the last path component of a given URL.

CFStringRef CFURLCopyLastPathComponent (
   CFURLRef url
);
Parameters
url

The CFURL object to examine.

Return Value

The last path component of url. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

Note that if there is no last path component, this function returns an empty string. In the code sample shown in Listing 1, lastPathComponent is an empty string.

Listing 1  Code sample illustrating CFURLCopyLastPathComponent

CFStringRef urlString = CFSTR("http://www.apple.com");
CFURLRef url = CFURLCreateWithString(NULL, urlString, NULL);
CFStringRef lastPathComponent = CFURLCopyLastPathComponent (url);

If urlString were created with CFSTR("http://www.apple.com/"), then lastPathComponent would be a CFString object containing the character “/“.

See also CFURLCopyPathExtension.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLCopyNetLocation

Returns the net location portion of a given URL.

CFStringRef CFURLCopyNetLocation (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The net location of anURL, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808). Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The URL net location is the portion of the URL that identifies the network address of the resource. It includes the optional username and password, as well as the target machine’s IP address or host name.

This function leaves any percent escape sequences intact.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyParameterString

Returns the parameter string from a given URL.

CFStringRef CFURLCopyParameterString (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);
Parameters
anURL

The CFURL object to examine.

charactersToLeaveEscaped

Characters whose percent escape sequences, such as %20 for a space character, you want to leave intact. Pass NULL to specify that no percent escapes be replaced, or the empty string (CFSTR("")) to specify that all be replaced.

Return Value

The parameter string (as defined in RFC 1738), or NULL if no parameter string exists. For example, in the URL myproto://www.example.com/;command=laugh, the parameter string is command=laugh. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyPassword

Returns the password of a given URL.

CFStringRef CFURLCopyPassword (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The password, or NULL if no password exists. In some cases, this function may also return the empty string (CFSTR("")) if no password exists. You should consider NULL and the empty string to be equivalent. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyPath (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The path of anURL, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808). Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function does not resolve the URL against its base, nor does it replace percent escape sequences. This function's return value includes any leading slash (giving the path the normal POSIX appearance), if present. If this behavior is not appropriate, use CFURLCopyStrictPath whose return value omits any leading slash. You may also want to use the function CFURLCopyFileSystemPath, which returns the URL's path as a file system path for the given path style. If the path is to be passed to file system calls, you may also want to use the function CFURLGetFileSystemRepresentation, which returns a C string.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyPathExtension

Returns the path extension of a given URL.

CFStringRef CFURLCopyPathExtension (
   CFURLRef url
);
Parameters
url

The CFURL object to examine.

Return Value

The path extension of url, or NULL if no extension exists. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The path extension is the portion of the last path component which follows the final period, if there is one. For example, for http:/www.apple.com/developer/macosx.today.html, the extension is html, and for http:/www.apple.com/developer, there is no path extension.

See also CFURLCopyLastPathComponent.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyQueryString

Returns the query string of a given URL.

CFStringRef CFURLCopyQueryString (
   CFURLRef    anURL,
   CFStringRef charactersToLeaveEscaped
);
Parameters
anURL

The CFURL object to examine.

charactersToLeaveEscaped

Characters whose percent escape sequences, such as %20 for a space character, you want to leave intact. Pass NULL to specify that no percent escapes be replaced, or the empty string (CFSTR("")) to specify that all be replaced.

Return Value

The query string, or NULL if no parameter string exists. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function removes all percent escape sequences except those for characters specified in charactersToLeaveEscaped.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyResourcePropertiesForKeys

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

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

The URL.

keys

The property value keys that values are requested for. See “Common File System Resource Keys” for a list of possible keys.

error

The error that occurred if the property’s value could not be obtained. Valid only if the function call returned NULL.

Return Value

A dictionary of resource property values, or NULL if an error occurs.

Discussion

Values are fetched synchronously from the resource backing store unless they are already cached.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLCopyResourcePropertyForKey

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

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

The URL.

key

The property value key that the value is requested for. See “Common File System Resource Keys” for a list of possible keys.

propertyValueTypeRefPtr

The pointer that is populated with the result.

error

The error that occurred if the property’s value could not be obtained. Valid only if the function call returned NULL.

Return Value

true if propertyValueTypeRefPtr is successfully populated; otherwise, false.

Discussion

Values are fetched synchronously from the resource backing store unless they are already cached.

Availability
  • Available in iOS 5.0 and later. Although this symbol existed in previous iOS versions, it did not do anything.
Declared In
CFURL.h

CFURLCopyResourceSpecifier

Returns any additional resource specifiers after the path.

CFStringRef CFURLCopyResourceSpecifier (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The resource specifiers. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function leaves any percent escape sequences intact. For decomposable URLs, this function returns everything after the path. For URLs that cannot be decomposed, this function returns everything except the scheme itself.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyScheme

Returns the scheme portion of a given URL.

CFStringRef CFURLCopyScheme (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The scheme of anURL. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The URL scheme is the portion of the URL specifying the transport type. For example http, ftp, and rtsp are schemes. This function leaves any percent escape sequences intact.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyStrictPath

Returns the path portion of a given URL.

CFStringRef CFURLCopyStrictPath (
   CFURLRef anURL,
   Boolean  *isAbsolute
);
Parameters
anURL

The CFURL object to examine.

isAbsolute

On return, indicates whether the path of anURL is absolute.

Return Value

The path of anURL, or NULL if the URL cannot be decomposed (doesn't conform to RFC 1808). Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function does not resolve the URL against its base, nor does it replace percent escape sequences. This function's return value does not include a leading slash and uses isAbsolute to report whether the URL's path is absolute. If this behavior is not appropriate, use the CFURLCopyPath function whose return value includes the leading slash (giving the path the normal POSIX appearance). You may also want to use the CFURLCopyFileSystemPath function, which returns the URL's path as a file system path for the given path style. If the path is to be passed to file system calls, you may also want to use the function CFURLGetFileSystemRepresentation, which returns a C string.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCopyUserName

Returns the user name from a given URL.

CFStringRef CFURLCopyUserName (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The user name, or NULL if no user name exists. In some cases, this function may also return the empty string (CFSTR("")) if no username exists. You should consider NULL and the empty string to be equivalent. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

relativeURLBytes

The character bytes that represent a relative URL to convert into a CFURL object.

length

The number of bytes in relativeURLBytes.

encoding

The string encoding of the relativeURLBytes string. This encoding is also used to interpret percent escape sequences.

baseURL

The URL to which relativeURLBytes is relative.

useCompatibilityMode

If true, the rules historically used on the web are used to resolve the string specified by the relativeURLBytes parameter against baseURL. These rules are generally listed in the RFC as optional or alternate interpretations. Otherwise, the strict rules from the RFC are used.

Return Value

A new CFURL object, or NULL if relativeURLBytes cannot be made absolute. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The URL that bookmark data is being created for.

options

Options taken into account when creating the bookmark data.

To create a security-scoped bookmark to support App Sandbox, include (by way of bitwise OR operators with any other options in this parameter) the kCFURLBookmarkCreationWithSecurityScope option.

When you later resolve the bookmark, you can use the resulting security-scoped URL to obtain read/write access to the file-system resource pointed to by the URL.

If you instead want to create a security-scoped bookmark that, when resolved, enables you to obtain read-only access to a file-system resource, bitwise OR this parameter’s value with both the kCFURLBookmarkCreationWithSecurityScope option and the kCFURLBookmarkCreationSecurityScopeAllowOnlyReadAccess option.

resourcePropertiesToInclude

An array of names of URL resource properties. The values of these properties must be of a type that the bookmark generation code can serialize. Specifically, the values can contain any of the following primitive types:

  • NSString or CFString

  • NSData or CFData

  • NSDate or CFDate

  • NSNumber or CFNumber

  • CFBoolean

  • NSURL or CFURL

  • CFNull

  • CFUUID

In addition, the properties can contain the following collection classes:

  • NSArray or CFArray containing only the above primitive types

  • NSDictionary or CFDictionary with NSString or CFString keys, in which all values contain only the above primitive types

relativeToURL

The URL that the bookmark data is relative to.

If you are creating a security-scoped bookmark to support App Sandbox, use this parameter as follows:

  • To create an app-scoped bookmark, use a value of nil.

  • To create a document-scoped bookmark, use the absolute path (despite this parameter’s name) to the document file that is to own the new security-scoped bookmark.

error

The error that occurred in the case that the bookmark data cannot be created.

Return Value

The bookmark data for the URL.

Discussion

To use this function to create a security-scoped bookmark to support App Sandbox, you must first have enabled the appropriate entitlements for your app, as described in “Enabling Security-Scoped Bookmark and URL Access” in Entitlement Key Reference. In addition, be sure to understand the behavior of the options and relativeToURL parameters.

For an app-scoped bookmark, no sandboxed app other than the one that created the bookmark can obtain access to the file-system resource that the URL (obtained from the bookmark) points to. Specifically, a bookmark created with security scope fails to resolve if the caller does not have the same code signing identity as the caller that created the bookmark.

For a document-scoped bookmark, any sandboxed app that has access to the bookmark data itself, and has access to the document that owns the bookmark, can obtain access to the resource.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLCreateBookmarkDataFromFile

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

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

fileURL

The file URL.

errorRef

The error that occurred in the case that the bookmark data cannot be created.

Return Value

The bookmark data for the file, or NULL if an error occurs.

Availability
  • Available in iOS 5.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

bookmark

The bookmark data the URL is derived from.

options

Options taken into account when resolving the bookmark data.

To resolve a security-scoped bookmark to support App Sandbox, you must include (by way of bitwise OR operators with any other options in this parameter) the kCFURLBookmarkResolutionWithSecurityScope option.

relativeToURL

The base URL that the bookmark data is relative to. Can be NULL.

If you are resolving a security-scoped bookmark to obtain a security-scoped URL, use this parameter as follows:

  • To resolve an app-scoped bookmark, use a value of nil.

  • To resolve a document-scoped bookmark, use the absolute path (despite this parameter’s name) to the document from which you retrieved the bookmark.

resourcePropertiesToInclude

An array of resource properties to include when creating the URL. Can be NULL.

isStale

If YES, the bookmark data is stale.

error

The error that occurred in the case that the URL cannot be created.

Return Value

A new URL made by resolving bookmark, or NULL if an error occurs.

Discussion

To obtain a security-scoped URL from a security-scoped bookmark, call this method using the kCFURLBookmarkResolutionWithSecurityScope option. In addition, to use security scope, you must first have enabled the appropriate entitlements for your app, as described in “Enabling Security-Scoped Bookmark and URL Access” in Entitlement Key Reference.

To then obtain access to the file-system resource pointed to by a security-scoped URL (in other words, to bring the resource into your app’s sandbox), call the CFURLStartAccessingSecurityScopedResource function (or its Cocoa equivalent) on the URL.

For an app-scoped bookmark, no sandboxed app other than the one that created the bookmark can obtain access to the file-system resource that the URL (obtained from the bookmark) points to.

For a document-scoped bookmark, any sandboxed app that has access to the bookmark data itself, and has access to the document that owns the bookmark, can obtain access to the resource.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLCreateCopyAppendingPathComponent

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

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The CFURL object to which to append a path component.

pathComponent

The path component to append to url.

isDirectory

A Boolean value that specifies whether the string is treated as a directory path when resolving against relative path components. Pass true if the new component indicates a directory, false otherwise.

Return Value

A copy of url appended with pathComponent. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The isDirectory argument specifies whether or not the new path component points to a file or a to directory. Note that the URL syntax for a directory and for a file at otherwise the same location are slightly different—directory URLs must end in “/”. If you have the URL http://www.apple.com/foo/ and you append the path component bar, then if isDirectory is YES then the resulting URL is http://www.apple.com/foo/bar/, whereas if isDirectory is NO then the resulting URL is http://www.apple.com/foo/bar. This difference is particularly important if you resolve another URL against this new URL. file.html relative to http://www.apple.com/foo/bar is http://www.apple.com/foo/file.html, whereas file.html relative to http://www.apple.com/foo/bar/ is http://www.apple.com/foo/bar/file.html.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLCreateCopyAppendingPathExtension

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

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The CFURL object to which to append a path extension.

extension

The extension to append to url.

Return Value

A copy of url appended with extension. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateCopyDeletingLastPathComponent

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

CFURLRef CFURLCreateCopyDeletingLastPathComponent (
   CFAllocatorRef allocator,
   CFURLRef       url
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The CFURL object whose last path component you want to delete.

Return Value

A copy of url with the last path component deleted. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateCopyDeletingPathExtension

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

CFURLRef CFURLCreateCopyDeletingPathExtension (
   CFAllocatorRef allocator,
   CFURLRef       url
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The CFURL object whose path extension you want to delete.

Return Value

A copy of url with its last path extension removed. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateData

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

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

The allocator to use to allocate memory for the new CFData object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The URL to convert into a CFData object.

encoding

The string encoding to use when converting url into a CFData object.

escapeWhitespace

true if you want to escape whitespace characters in the URL, false otherwise.

Return Value

A new CFData object containing the content of url. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function escapes any character that is not 7-bit ASCII with the byte-code for the given encoding. If escapeWhitespace is true, whitespace characters (' ', '\t', '\r', '\n') will be escaped as well. This is desirable if you want to embed the URL into a larger text stream like HTML.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The path.

error

The error that occurred in the case that the URL cannot be created.

Return Value

A CFURL object initialized with url, or NULL if an error occurs.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

url

The URL.

error

The error that occurred in the case that the URL cannot be created.

Return Value

The new file reference URL, or NULL if an error occurs.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

buffer

The character bytes to convert into a CFURL object. This should be the path as you would use in POSIX function calls.

bufLen

The number of character bytes in the buffer (usually the result of a call to strlen(3) Mac OS X Developer Tools Manual Page), not including any null termination.

isDirectory

A Boolean value that specifies whether the string is treated as a directory path when resolving against relative path components—true if the pathname indicates a directory, false otherwise.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

buffer

The character bytes to convert into a CFURL object. This should be the path as you would use in POSIX function calls.

bufLen

The number of bytes in the buffer.

isDirectory

A Boolean value that specifies whether the string is treated as a directory path when resolving against relative path components. Pass true if the pathname indicates a directory, false otherwise.

baseURL

The URL against which to resolve the path.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function takes a path name in the form of a native character string, resolves it against a base URL, and returns a new CFURL object containing the result.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

resourcePropertiesToReturn

An array of names of URL resource properties. See “Common File System Resource Keys” for a list of possible keys.

bookmark

The bookmark data the resource values are derived from.

Return Value

A dictionary of the requested resource values contained in bookmarkData.

Discussion

This function does not attempt to resolve the bookmark data or perform I/O.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLCreateResourcePropertyForKeyFromBookmarkData

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

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

resourcePropertyKey

The resource property key. See “Common File System Resource Keys” for a list of possible keys.

bookmark

The bookmark data the resource value is derived from.

Return Value

The resource property value.

Discussion

This function does not attempt to resolve the bookmark data or perform I/O.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFString object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

originalString

The CFString object to copy.

charactersToLeaveUnescaped

Characters whose percent escape sequences you want to leave intact. Pass NULL to specify that all illegal characters be escaped.

legalURLCharactersToBeEscaped

Legal characters to be escaped. Pass NULL to specify that no legal characters be replaced.

encoding

The encoding to use for the translation. If you are uncertain of the correct encoding, you should use UTF-8 (kCFStringEncodingUTF8), which is the encoding designated by RFC 3986 as the correct encoding for use in URLs.

Return Value

A copy of originalString replacing certain characters. If it does not need to be modified (no percent escape sequences are missing), this function may merely return originalString with its reference count incremented. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The characters escaped are all characters that are not legal URL characters (based on RFC 3986), plus any characters in legalURLCharactersToBeEscaped, less any characters in charactersToLeaveUnescaped. To simply correct any non-URL characters in an otherwise correct URL string, pass NULL for the allocator, charactersToLeaveEscaped, and legalURLCharactersToBeEscaped parameters, and kCFStringEncodingUTF8 as the encoding parameter.

It may be difficult to use this function to "clean up" unescaped or partially escaped URL strings where sequences are unpredictable and you cannot specify charactersToLeaveUnescaped. Instead, you can "pre-process" a URL string using CFURLCreateStringByReplacingPercentEscapesUsingEncoding then add the escape characters using CFURLCreateStringByAddingPercentEscapes, as shown in the following code fragment.

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);
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLCreateStringByReplacingPercentEscapes

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

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

The allocator to use to allocate memory for the new CFString object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

originalString

The CFString object to be copied and modified.

charactersToLeaveEscaped

Characters whose percent escape sequences, such as %20 for a space character, you want to leave intact. Pass NULL to specify that no percent escapes be replaced, or the empty string (CFSTR("")) to specify that all be replaced.

Return Value

A new CFString object, or NULL if the percent escapes cannot be converted to characters, assuming UTF-8 encoding. If no characters need to be replaced, this function returns the original string with its reference count incremented. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFString object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

originalString

The CFString object to be copied and modified.

charactersToLeaveEscaped

Characters whose percent escape sequences, such as %20 for a space character, you want to leave intact. Pass NULL to specify that no percent escapes be replaced, or the empty string (CFSTR("")) to specify that all be replaced.

encoding

Specifies the encoding to use when interpreting percent escapes. If you are uncertain of the correct encoding, you should use UTF-8 (kCFStringEncodingUTF8), which is the encoding designated by RFC 3986 as the correct encoding for use in URLs.

Return Value

A new CFString object, or NULL if the percent escapes cannot be converted to characters, assuming the encoding given by encoding. If no characters need to be replaced, this function returns the original string with its reference count incremented. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateWithBytes

Creates a CFURL object using a given character bytes.

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

URLBytes

The character bytes to convert into a CFURL object.

length

The number of bytes in URLBytes.

encoding

The string encoding of the URLBytes string. This encoding is also used to interpret percent escape sequences.

baseURL

The URL to which URLBytes is relative. Pass NULL if URLBytes contains an absolute URL or if you want to create a relative URL. If URLBytes contains an absolute URL, this parameter is ignored.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

The specified string encoding will be used both to interpret URLBytes, and to interpret any percent-escapes within the string.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateWithFileSystemPath

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

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

filePath

The path string to convert to a CFURL object.

pathStyle

The operating system path style used in filePath. See “Path Style” for a list of possible values.

isDirectory

A Boolean value that specifies whether filePath is treated as a directory path when resolving against relative path components. Pass true if the pathname indicates a directory, false otherwise.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

If filePath is not absolute, the resulting URL will be considered relative to the current working directory (evaluated when this function is being invoked).

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
allocator

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

filePath

The path string to convert to a CFURL object.

pathStyle

The operating system path style used in the filePath string. See “Path Style” for a list of possible values.

isDirectory

A Boolean value that specifies whether filePath is treated as a directory path when resolving against relative path components. Pass true if the pathname indicates a directory, false otherwise.

baseURL

The base URL against which to resolve the filePath.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This function takes a path name in the form of a CFString object, resolves it against a base URL, and returns a new CFURL object containing the result.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLCreateWithString

Creates a CFURL object using a given CFString object.

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

The allocator to use to allocate memory for the new CFURL object. Pass NULL or kCFAllocatorDefault to use the current default allocator.

URLString

The CFString object containing the URL string.

baseURL

The URL to which URLString is relative. Pass NULL if URLString contains an absolute URL or if you want to create a relative URL. If URLString contains an absolute URL, baseURL is ignored.

Return Value

A new CFURL object. Ownership follows the create rule. See “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

Any escape sequences in URLString will be interpreted using UTF-8.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLGetBaseURL

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

CFURLRef CFURLGetBaseURL (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

A CFURL object representing the base URL of anURL. Ownership follows the get rule. See “The Get Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLGetByteRangeForComponent

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

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

The URL containing component.

component

The type of component in anURL whose range you want to obtain. See “Component Type” for possible values.

rangeIncludingSeparators

Specifies the range of component including the sequences that separate component from the previous and next components. If there is no previous or next components, this function will match the range of the component itself. If anURL does not contain component, rangeIncludingSeparators is set to the location where the component would be inserted.

Return Value

The range of bytes for component in the buffer returned by the CFURLGetBytes function. If anURL does not contain component, the first part of the returned range is set to kCFNotFound.

Discussion

This function is intended to be used in conjunction with the CFURLGetBytes function, since the range returned is only applicable to the bytes returned by CFURLGetBytes.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLGetBytes

Returns by reference the byte representation of a URL object.

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

The URL object to convert to a byte representation.

buffer

The buffer where you want the bytes to be placed. If the buffer is of insufficient size, returns -1 and no bytes are placed in buffer. If NULL the needed length is computed and returned. The returned bytes are the original bytes from which the URL was created (not including the base URL). If the URL was created from a string, the bytes are the bytes of the string encoded via UTF-8.

bufferLength

The number of bytes in buffer.

Return Value

Returns the number of bytes in buffer that were filled. If the buffer is of insufficient size, returns -1.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

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
);
Parameters
url

The CFURL object whose native file system representation you want to obtain.

resolveAgainstBase

Pass true to return an absolute path name.

buffer

A pointer to a character buffer. On return, the buffer holds the native file system's representation of url. The buffer is null-terminated. This parameter must be at least maxBufLen in size for the file system in question to avoid failures for insufficiently large buffers.

maxBufLen

The maximum number of characters that can be written to buffer.

Return Value

true if successful, false if an error occurred.

Discussion

No more than maxBufLen bytes are written to buffer. If url requires more than maxBufLen bytes to represent itself, including the terminating null byte, this function returns false. To avoid this possible failure, you should pass a buffer with size of at least the maximum path length for the file system in question.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLGetPortNumber

Returns the port number from a given URL.

SInt32 CFURLGetPortNumber (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

The port number of anURL, or -1 if no port number exists.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLGetString

Returns the URL as a CFString object.

CFStringRef CFURLGetString (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to convert into a CFString object.

Return Value

A string representation of anURL. Ownership follows the get rule. See “The Get Rule” in Memory Management Programming Guide for Core Foundation.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLGetTypeID

Returns the type identifier for the CFURL opaque type.

CFTypeID CFURLGetTypeID (
   void
);
Return Value

The type identifier for the CFURL opaque type.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
CFURL.h

CFURLHasDirectoryPath

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

Boolean CFURLHasDirectoryPath (
   CFURLRef anURL
);
Parameters
anURL

The CFURL object to examine.

Return Value

true if anURL represents a directory, false otherwise.

Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

CFURLResourceIsReachable

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

Boolean CFURLResourceIsReachable (
   CFURLRef   url,
   CFErrorRef *error
);
Parameters
url

The URL to check.

error

The error that occurred in the case that the resource cannot be reached.

Return Value

true if the resource is reachable; otherwise, false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

CFURLSetResourcePropertiesForKeys

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

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

The URL.

keyedPropertyValues

A dictionary of resource values to be set. See “Common File System Resource Keys” for a list of possible keys.

error

The error that occurred in the case that one or more resource values cannot be set.

Return Value

true if all resource values in keyedPropertyValues are successfully set; otherwise, false.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
url

The URL.

key

The name of one of the URL’s resource properties.

propertyValue

The value for the resource property defined by key. See “Common File System Resource Keys” for a list of possible keys.

error

The error that occurred in the case that the resource value cannot be set.

Return Value

true if the resource property named key is successfully set to value; otherwise, false.

Discussion

This function writes the new property value out to the backing store.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
url

The URL.

key

The name of one of the URL’s resource properties.

propertyValue

The value for the resource property defined by key.

Availability
  • Available in iOS 4.0 and later.
Declared In
CFURL.h

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
);
Parameters
bookmarkRef

The bookmark data containing information for the alias file.

fileURL

The desired location of the alias file.

options

Options taken into account when creating the alias file.

errorRef

The error that occurred in the case that the alias file cannot be created.

Return Value

true if the alias file is successfully created; otherwise, false.

Availability
  • Available in iOS 5.0 and later.
Declared In
CFURL.h

Data Types

Bookmark Data Types

CFURLBookmarkCreationOptions

Type for bookmark data creation options.

typedef CFOptionFlags CFURLBookmarkCreationOptions;
Discussion

See “Bookmark Data Creation Options” for possible values.

Availability
  • Available in iOS 5.0 and later.
Declared In
CFURL.h

CFURLBookmarkFileCreationOptions

Type for bookmark file creation options.

typedef CFOptionFlags CFURLBookmarkFileCreationOptions;
Availability
  • Available in iOS 5.0 and later.
Declared In
CFURL.h

CFURLBookmarkResolutionOptions

Type for bookmark data resolution options.

typedef CFOptionFlags CFURLBookmarkResolutionOptions;
Discussion

See “Bookmark Data Resolution Options” for possible values.

Availability
  • Available in iOS 5.0 and later.
Declared In
CFURL.h

Miscellaneous

CFURLRef

A reference to a CFURL object.

typedef const struct __CFURL *CFURLRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
CFURL.h

Constants

Bookmark Data Constants

Bookmark Data Creation Options

Options used when creating bookmark data.

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

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

Available in iOS 4.0 and later.

Deprecated in iOS 7.0.

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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLBookmarkCreationSuitableForBookmarkFile

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

Available in iOS 5.0 and later.

Declared in CFURL.h.

Discussion

When creating a bookmark, use bitwise OR operators to combine the options you want to specify, and provide them to the options parameter of the CFURLCreateBookmarkData method.

Version Notes

Security-scoped bookmarks are not available in versions of OS X prior to OS X v10.7.3.

Bookmark Data Resolution Options

Options used when resolving bookmark data.

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

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

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFBookmarkResolutionWithoutMountingMask

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

Available in iOS 5.0 and later.

Declared in CFURL.h.

Discussion

When resolving a bookmark to obtain a URL, use bitwise OR operators to combine the options you want to specify, and provide them to the options parameter of the CFURLCreateByResolvingBookmarkData function.

Version Notes

Security-scoped bookmarks are not available in versions of OS X prior to OS X v10.7.3.

File System Constants

Common File System Resource Keys

Keys that are applicable to file system URLs.

kCFURLNameKey kCFURLLocalizedNameKey kCFURLPathKey;
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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLLocalizedNameKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLPathKey

A CFString value containing the URL’s path as a file system path. (read-only)

Available in iOS 6.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLIsDirectoryKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLIsSymbolicLinkKey

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

Available in iOS 4.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLIsPackageKey

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

Available in iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLLinkCountKey

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

Available in iOS 4.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeURLKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLTypeIdentifierKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLLocalizedTypeDescriptionKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLLabelNumberKey

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

Available in iOS 4.0 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 iOS 4.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLEffectiveIconKey

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

Available in iOS 4.0 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 iOS 4.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileSecurityKey

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

Available in iOS 5.0 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 iOS 5.1 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeCharacterSpecial

The resource is a character special file.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeDirectory

The resource is a directory.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeNamedPipe

The resource is a named pipe.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeRegular

The resource is a regular file.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeSocket

The resource is a socket.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeSymbolicLink

The resource is a symbolic link.

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLFileResourceTypeUnknown

The resource’s type is unknown.

Available in iOS 5.0 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 iOS 4.0 and later.

Declared in CFURL.h.

kCFURLFileSizeKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLIsAliasFileKey

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

Available in iOS 4.0 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 iOS 4.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

iCloud Constants

These constants can be used to determining whether a file is stored in the cloud and to obtain information about its status.

const CFStringRef kCFURLIsUbiquitousItemKey;
   
const CFStringRef kCFURLUbiquitousItemHasUnresolvedConflictsKey;
   
const CFStringRef kCFURLUbiquitousItemIsDownloadedKey;
   
const CFStringRef kCFURLUbiquitousItemIsDownloadingKey;
   
const CFStringRef kCFURLUbiquitousItemIsUploadedKey;
   
const CFStringRef kCFURLUbiquitousItemIsUploadingKey;
   
const CFStringRef kCFURLUbiquitousItemPercentDownloadedKey;
   
const CFStringRef kCFURLUbiquitousItemPercentUploadedKey;
Constants
kCFURLIsUbiquitousItemKey

A CFBoolean value that tells whether the item is synced to the cloud. (read-only)

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLUbiquitousItemHasUnresolvedConflictsKey

A CFBoolean value that tells whether the item has conflicts outstanding. (read-only)

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLUbiquitousItemIsDownloadedKey

A CFBoolean value that tells whether there is local data present for the item. (read-only)

Available in iOS 5.0 and later.

Deprecated in iOS 7.0.

Declared in CFURL.h.

kCFURLUbiquitousItemIsDownloadingKey

A CFBoolean value that tells whether data for the item is being downloaded. (read-only)

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLUbiquitousItemIsUploadedKey

A CFBoolean value that tells whether there is data present in the cloud for this item. (read-only)

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLUbiquitousItemIsUploadingKey

A CFBoolean value that tells whether data for the item is being uploaded. (read-only)

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLUbiquitousItemPercentDownloadedKey

A CFNumber value that provides the status of the download in progress.

Deprecated. Use NSMetadataQuery and NSMetadataUbiquitousItemPercentDownloadedKey on NSMetadataItem instead.

Available in iOS 5.0 and later.

Deprecated in iOS 6.0.

Declared in CFURL.h.

kCFURLUbiquitousItemPercentUploadedKey

A CFNumber value that provides the status of the upload in progress.

Deprecated. Use NSMetadataQuery and NSMetadataUbiquitousItemPercentUploadedKey on NSMetadataItem instead.

Available in iOS 5.0 and later.

Deprecated in iOS 6.0.

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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLVolumeLocalizedNameKey

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

Available in iOS 5.0 and later.

Declared in CFURL.h.

kCFURLVolumeLocalizedFormatDescriptionKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeTotalCapacityKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeAvailableCapacityKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeResourceCountKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsPersistentIDsKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsSymbolicLinksKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsHardLinksKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsJournalingKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeIsJournalingKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsSparseFilesKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsZeroRunsKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsCaseSensitiveNamesKey

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

Available in iOS 4.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsCasePreservedNamesKey

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

Available in iOS 4.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLVolumeSupportsRenamingKey

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

Available in iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLVolumeIsAutomountedKey

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

Available in iOS 5.0 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 iOS 5.0 and later.

Declared in CFURL.h.

kCFURLVolumeIsReadOnlyKey

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

Available in iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentNetLocation

The URL’s network location.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentPath

The URL’s path component.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentResourceSpecifier

The URL’s resource specifier.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentUser

The URL’s user.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentPassword

The user’s password.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentUserInfo

The user’s information.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentHost

The URL’s host.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentPort

The URL’s port.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentParameterString

The URL’s parameter string.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentQuery

The URL’s query.

Available in iOS 2.0 and later.

Declared in CFURL.h.

kCFURLComponentFragment

The URL’s fragment.

Available in iOS 2.0 and later.

Declared in CFURL.h.

Discussion

These constants are used by the CFURLGetByteRangeForComponent function.

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 iOS 2.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 iOS 2.0 and later.

Deprecated in iOS 7.0.

Declared in CFURL.h.

kCFURLWindowsPathStyle

Indicates a Windows style path name.

Available in iOS 2.0 and later.

Declared in CFURL.h.