CFURL

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 a macOS 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 CFURLStart​Accessing​Security​Scoped​Resource(_:​) function (or its Cocoa equivalent, the start​Accessing​Security​Scoped​Resource() 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 CFURLStop​Accessing​Security​Scoped​Resource(_:​) method (or its Cocoa equivalent, the stop​Accessing​Security​Scoped​Resource() 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 macOS, 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 CFURLStart​Accessing​Security​Scoped​Resource(_:​) function (or its Cocoa equivalent).

If you need a security-scoped URL’s path as a string value (as provided by the CFURLGet​String(_:​) 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 CFURLCreate​From​File​System​Representation(_:​_:​_:​_:​) and CFURLCreate​From​File​System​Representation​Relative​To​Base(_:​_:​_:​_:​_:​) 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

Symbols

Creating a CFURL

func CFURLCopy​Absolute​URL(CFURL!)

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

func CFURLCreate​Absolute​URLWith​Bytes(CFAllocator!, Unsafe​Pointer<UInt8>!, CFIndex, CFString​Encoding, CFURL!, Bool)

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

func CFURLCreate​Copy​Appending​Path​Extension(CFAllocator!, CFURL!, CFString!)

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

func CFURLCreate​Copy​Deleting​Last​Path​Component(CFAllocator!, CFURL!)

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

func CFURLCreate​Copy​Deleting​Path​Extension(CFAllocator!, CFURL!)

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

func CFURLCreate​File​Path​URL(CFAllocator!, CFURL!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

Returns a new file path URL that refers to the same resource as a specified URL.

func CFURLCreate​File​Reference​URL(CFAllocator!, CFURL!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

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

func CFURLCreate​From​File​System​Representation(CFAllocator!, Unsafe​Pointer<UInt8>!, CFIndex, Bool)

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

func CFURLCreate​With​String(CFAllocator!, CFString!, CFURL!)

Creates a CFURL object using a given CFString object.

Accessing the Parts of a URL

func CFURLCan​Be​Decomposed(CFURL!)

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

func CFURLCopy​Fragment(CFURL!, CFString!)

Returns the fragment from a given URL.

func CFURLCopy​Host​Name(CFURL!)

Returns the host name of a given URL.

func CFURLCopy​Last​Path​Component(CFURL!)

Returns the last path component of a given URL.

func CFURLCopy​Net​Location(CFURL!)

Returns the net location portion of a given URL.

func CFURLCopy​Parameter​String(CFURL!, CFString!)

Returns the parameter string from a given URL.

func CFURLCopy​Password(CFURL!)

Returns the password of a given URL.

func CFURLCopy​Path(CFURL!)

Returns the path portion of a given URL.

func CFURLCopy​Path​Extension(CFURL!)

Returns the path extension of a given URL.

func CFURLCopy​Query​String(CFURL!, CFString!)

Returns the query string of a given URL.

func CFURLCopy​Resource​Specifier(CFURL!)

Returns any additional resource specifiers after the path.

func CFURLCopy​Scheme(CFURL!)

Returns the scheme portion of a given URL.

func CFURLCopy​User​Name(CFURL!)

Returns the user name from a given URL.

func CFURLGet​Port​Number(CFURL!)

Returns the port number from a given URL.

func CFURLHas​Directory​Path(CFURL!)

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

Converting URLs to Other Representations

func CFURLCreate​Data(CFAllocator!, CFURL!, CFString​Encoding, Bool)

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

func CFURLCreate​String​By​Adding​Percent​Escapes(CFAllocator!, CFString!, CFString!, CFString!, CFString​Encoding)

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

Deprecated
func CFURLCreate​String​By​Replacing​Percent​Escapes(CFAllocator!, CFString!, CFString!)

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

func CFURLCreate​String​By​Replacing​Percent​Escapes​Using​Encoding(CFAllocator!, CFString!, CFString!, CFString​Encoding)

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

Deprecated
func CFURLGet​File​System​Representation(CFURL!, Bool, Unsafe​Mutable​Pointer<UInt8>!, CFIndex)

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

func CFURLGet​String(CFURL!)

Returns the URL as a CFString object.

Getting URL Properties

func CFURLGet​Base​URL(CFURL!)

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

func CFURLGet​Bytes(CFURL!, Unsafe​Mutable​Pointer<UInt8>!, CFIndex)

Returns by reference the byte representation of a URL object.

func CFURLGet​Type​ID()

Returns the type identifier for the CFURL opaque type.

func CFURLResource​Is​Reachable(CFURL!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

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

Getting and Setting File System Resource Properties

func CFURLClear​Resource​Property​Cache(CFURL!)

Removes all cached resource values and temporary resource values from the URL object.

func CFURLClear​Resource​Property​Cache​For​Key(CFURL!, CFString!)

Removes the cached resource value identified by a given key from the URL object.

func CFURLCopy​Resource​Properties​For​Keys(CFURL!, CFArray!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

Returns the resource values for the properties identified by specified array of keys.

func CFURLCreate​Resource​Properties​For​Keys​From​Bookmark​Data(CFAllocator!, CFArray!, CFData!)

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

func CFURLSet​Resource​Properties​For​Keys(CFURL!, CFDictionary!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

Sets the URL’s resource properties for a given set of keys to a given set of values.

Working with Bookmark Data

func CFURLCreate​Bookmark​Data​From​Alias​Record(CFAllocator!, CFData!)

Initializes and returns bookmark data derived from an alias record.

func CFURLCreate​Bookmark​Data​From​File(CFAllocator!, CFURL!, Unsafe​Mutable​Pointer<Unmanaged<CFError>?>!)

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

func CFURLStart​Accessing​Security​Scoped​Resource(CFURL!)

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

func CFURLStop​Accessing​Security​Scoped​Resource(CFURL!)

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

Bookmark Data Types

CFURLBookmark​Creation​Options

Type for bookmark data creation options.

CFURLBookmark​File​Creation​Options

Type for bookmark file creation options.

CFURLBookmark​Resolution​Options

Type for bookmark data resolution options.

Miscellaneous

CFURL

A reference to a CFURL object.

Bookmark Data Constants

Bookmark Data Creation Options

Options used when creating bookmark data.

Bookmark Data Resolution Options

Options used when resolving bookmark data.

File System Constants

Common File System Resource Keys

Keys that are applicable to file system URLs.

File Property Keys

Keys that apply to properties of files.

i​Cloud Constants

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

Volume Property Keys

Keys that apply to volumes.

CFError user​Info Dictionary Keys

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

Miscellaneous

CFURLComponent​Type

The types of components in a URL.

CFURLPath​Style

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