NSURL Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSURL.h
NSURLHandle.h
Companion guides
Related sample code

Overview

An NSURL object represents a URL that can potentially contain the location of a resource on a remote server, the path of a local file on disk, or even an arbitrary piece of encoded data.

You can use URL objects to construct URLs and access their parts. For URLs that represent local files, you can also manipulate properties of those files directly, such as changing the file’s last modification date. Finally, you can pass URL objects to other APIs to retrieve the contents of those URLs. For example, you can use the NSURLSession, NSURLConnection, and NSURLDownload classes to access the contents of remote resources, as described in URL Loading System Programming Guide.

URL objects are the preferred way to refer to local files. Most AppKit objects that read data from or write data to a file have methods that accept an NSURL object instead of a pathname as the file reference. For example, you can get the contents of a local file URL as an NSString object by calling the stringWithContentsOfURL:encoding:error: method, or as an NSData object by calling the dataWithContentsOfURL:options:error: method.

You can also use URLs for interapplication communication. In OS X, the NSWorkspace class provides the openURL: method to open a location specified by a URL. Similarly, in iOS, the UIApplication class provides the openURL: method.

Additionally, you can use URLs when working with pasteboards, as described in NSURL Additions Reference (part of the AppKit framework).

Structure of a URL

An NSURL object is composed of two parts—a potentially nil base URL and a string that is resolved relative to the base URL. An NSURL object is considered absolute if its string part is fully resolved without a base; all other URLs are considered relative.

For example, when constructing an NSURL object, you might specify file:///path/to/web_root/ as the base URL and folder/file.html as the string part, as follows:

    NSURL *baseURL = [NSURL URLWithString:@"file:///path/to/web_root/"];
    NSURL *url = [NSURL URLWithString:@"folder/file.html" relativeToURL:baseURL];
    NSURL *absURL = [url absoluteURL];
    NSLog(@"absURL = %@", absURL);

When fully resolved, the absolute URL is file:///path/to/web_root/folder/file.html.

The URL as a whole can also be divided into pieces based on its structure. For example, the URL https://www.example.com/script?name=value contains a URL scheme (https), a host (www.example.com), a path (/script), and a query string (name=value). The NSURL class provides accessor methods that let you examine those pieces.

Bookmarks, Security Scope, and Start/Stop Semantics

In OS X v10.6 and later, the NSURL class provides a facility for creating and using bookmark objects. 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 startAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStartAccessingSecurityScopedResource function) 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 relinquish your access by calling the stopAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStopAccessingSecurityScopedResource function) on the resource’s URL. When you call these methods, you immediately lose access to the resource in question.

The methods 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.

Security-Scoped URLs and String Paths

In an OS X app, 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 startAccessingSecurityScopedResource method (or its Core Foundation equivalent).

If you need a security-scoped URL’s path as a string value (as provided by the path method), 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 to a security-scoped resource.

Handling Object Creation Failure

The NSURL class fails to create a new NSURL object if the path being passed is not well-formed; the path must comply with RFC 2396. Examples of cases that will not succeed are strings containing space characters and high-bit characters. Should creating an NSURL object fail, the creation methods return nil, which you must be prepared to handle. If you are creating NSURL objects using file system paths, you should use fileURLWithPath: or initFileURLWithPath:, which handle the subtle differences between URL paths and file system paths. If you wish to be tolerant of malformed path strings, you’ll need to use functions provided by the Core Foundation framework to clean up the strings.

Adopted Protocols

NSCoding
NSCopying
NSURLHandleClient

Tasks

Creating an NSURL

Identifying and Comparing Objects

Querying an NSURL

Loading the Resource of an NSURL Object

Accessing the Parts of the URL

Modifying and Converting a File URL

Working with Bookmark Data

Getting and Setting File System Resource Properties

Class Methods

bookmarkDataWithContentsOfURL:error:

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

+ (NSData *)bookmarkDataWithContentsOfURL:(NSURL *)bookmarkFileURL error:(NSError **)error
Parameters
bookmarkFileURL

The URL that points to the alias file.

error

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

Return Value

The bookmark data for the alias file.

Discussion

If bookmarkFileURL points to an alias file created prior to OS X v10.6 that contains Alias Manager information but no bookmark data, this method synthesizes bookmark data for the file.

This method returns nil if bookmark data cannot be created.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

fileURLWithFileSystemRepresentation:isDirectory:relativeToURL:

Returns a new URL object initialized with a C string representing a local file system path.

+ (id)fileURLWithFileSystemRepresentation:(const char *)path isDirectory:(BOOL)isDir relativeToURL:(NSURL *)baseURL
Parameters
path

A null-terminated C string in file system representation containing the path to represent as a URL. If this path is a relative path, it is treated as being relative to the current working directory.

isDir

YES if the last path part is a directory, otherwise NO.

baseURL

The base URL for the new URL object. This must be a file URL. If path is absolute, this URL is ignored.

Return Value

Returns the new object or nil if an error occurred.

Discussion

The file system representation format is described in “File Encodings and Fonts”.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

fileURLWithPath:

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

+ (id)fileURLWithPath:(NSString *)path
Parameters
path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath. If path is a relative path, it is treated as being relative to the current working directory.

Passing nil for this parameter produces an exception.

Return Value

An NSURL object initialized with path.

Discussion

This method assumes that path is a directory if it ends with a slash. If path does not end with a slash, the method examines the file system to determine if path is a file or a directory. If path exists in the file system and is a directory, the method appends a trailing slash. If path does not exist in the file system, the method assumes that it represents a file and does not append a trailing slash.

As an alternative, consider using fileURLWithPath:isDirectory:, which allows you to explicitly specify whether the returned NSURL object represents a file or directory.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

fileURLWithPath:isDirectory:

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

+ (id)fileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir
Parameters
path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath. If path is a relative path, it is treated as being relative to the current working directory.

Passing nil for this parameter produces an exception.

isDir

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

Return Value

An NSURL object initialized with path.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURL.h

fileURLWithPathComponents:

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

+ (NSURL *)fileURLWithPathComponents:(NSArray *)components
Parameters
components

An array of path components.

Passing nil for this parameter produces an exception.

Return Value

An NSURL object initialized with components.

Discussion

The path components are separated by a forward slash in the returned URL.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

resourceValuesForKeys:fromBookmarkData:

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

+ (NSDictionary *)resourceValuesForKeys:(NSArray *)keys fromBookmarkData:(NSData *)bookmarkData
Parameters
keys

An array of names of URL resource properties. In addition to the standard, system-defined resource properties, you can also request any custom properties that you provided when you created the bookmark. See the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method for details.

bookmarkData

The bookmark data from which you want to retrieve resource values.

Return Value

A dictionary of the requested resource values contained in bookmarkData.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:

Returns a new URL made by resolving bookmark data.

+ (id)URLByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError **)error
Parameters
bookmarkData

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 NSURLBookmarkResolutionWithSecurityScope option.

relativeURL

The base URL that the bookmark data is relative to.

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.

isStale

On return, if YES, the bookmark data is stale. Your app should create a new bookmark using the returned URL and use it in place of any stored copies of the existing bookmark.

error

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

Return Value

A new URL made by resolving bookmarkData.

Discussion

This method fails if the original file or directory could not be located or is on a volume that could not be mounted. If this method fails, you can use the resourceValuesForKeys:fromBookmarkData: method to obtain information about the bookmark, such as the last known path (NSURLPathKey) to help the user decide how to proceed.

To obtain a security-scoped URL from a security-scoped bookmark, call this method using the NSURLBookmarkResolutionWithSecurityScope 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 startAccessingSecurityScopedResource method (or its Core Foundation 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 OS X v10.6 and later.
Declared In
NSURL.h

URLWithString:

Creates and returns an NSURL object initialized with a provided URL string.

+ (id)URLWithString:(NSString *)URLString
Parameters
URLString

The URL string with which to initialize the NSURL object. Must be a URL that conforms to RFC 2396. This method parses URLString according to RFCs 1738 and 1808.

Return Value

An NSURL object initialized with URLString. If the URL string was malformed or nil, returns nil.

Discussion

This method expects URLString to contain only characters that are allowed in a properly formed URL. All other characters must be properly percent escaped. Any percent-escaped characters are interpreted using UTF-8 encoding.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

URLWithString:relativeToURL:

Creates and returns an NSURL object initialized with a base URL and a relative string.

+ (id)URLWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL
Parameters
URLString

The URL string with which to initialize the NSURL object. May not be nil. Must conform to RFC 2396. URLString is interpreted relative to baseURL.

baseURL

The base URL for the NSURL object.

Return Value

An NSURL object initialized with URLString and baseURL. If URLString was malformed or nil, returns nil.

Discussion

This method allows you to create a URL relative to a base path or URL. For example, if you have the URL for a folder on disk and the name of a file within that folder, you can construct a URL for the file by providing the folder’s URL as the base path (with a trailing slash) and the filename as the string part.

This method expects URLString to contain only characters that are allowed in a properly formed URL. All other characters must be properly percent escaped. Any percent-escaped characters are interpreted using UTF-8 encoding.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

writeBookmarkData:toURL:options:error:

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

+ (BOOL)writeBookmarkData:(NSData *)bookmarkData toURL:(NSURL *)bookmarkFileURL options:(NSURLBookmarkFileCreationOptions)options error:(NSError **)error
Parameters
bookmarkData

The bookmark data containing information for the alias file.

bookmarkFileURL

The desired location of the alias file.

options

Options taken into account when creating the alias file.

error

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

Return Value

YES if the alias file is successfully created; otherwise, NO.

Discussion

This method will produce an error if bookmarkData was not created with the NSURLBookmarkCreationSuitableForBookmarkFile option.

If bookmarkFileURL points to a directory, the alias file will be created in that directory with its name derived from the information in bookmarkData. If bookmarkFileURL points to a file, the alias file will be created with the location and name indicated by bookmarkFileURL, and its extension will be changed to .alias if it is not already.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

Instance Methods

absoluteString

Returns the URL string for the receiver as if it were an absolute URL.

- (NSString *)absoluteString
Return Value

An absolute string for the URL. Creating by resolving the receiver's string against its base according to the algorithm given in RFC 1808.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

absoluteURL

Returns an absolute URL that refers to the same resource as the receiver.

- (NSURL *)absoluteURL
Return Value

An absolute URL that refers to the same resource as the receiver. If the receiver is already absolute, returns self. Resolution is performed per RFC 1808.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSURL.h

baseURL

Returns the base URL of the receiver.

- (NSURL *)baseURL
Return Value

The base URL of the receiver. If the receiver is an absolute URL, returns nil.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:

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

- (NSData *)bookmarkDataWithOptions:(NSURLBookmarkCreationOptions)options includingResourceValuesForKeys:(NSArray *)keys relativeToURL:(NSURL *)relativeURL error:(NSError **)error
Parameters
options

Options taken into account when creating the bookmark for the URL. The possible flags (which can be combined with bitwise OR operations) are described in “Bookmark Data Creation Options.”

To create a security-scoped bookmark to support App Sandbox, include the NSURLBookmarkCreationWithSecurityScope flag. 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 NSURLBookmarkCreationWithSecurityScope option and the NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess option.

keys

An array of names of URL resource properties to store as part of the bookmark. You can later access these values (without resolving the bookmark) by calling the resourceValuesForKeys:fromBookmarkData: method.

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

  • kCFNull or NSNull

  • 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

relativeURL

The URL that the bookmark data will be 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

A bookmark for the URL.

Discussion

This method returns bookmark data that can later be resolved into a URL object for a file even if the user moves or renames it (if the volume format on which the file resides supports doing so).

You can also use this method to create a security-scoped bookmark to support App Sandbox. Before you do so, you must first enable 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 relativeURL 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 OS X v10.6 and later.
Declared In
NSURL.h

checkResourceIsReachableAndReturnError:

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

- (BOOL)checkResourceIsReachableAndReturnError:(NSError **)error
Parameters
error

The error that occurred when the resource could not be reached.

Return Value

YES if the resource is reachable; otherwise, NO.

Discussion

This method synchronously checks if the file at the provided URL is reachable. Checking reachability is appropriate when making decisions that do not require other immediate operations on the resource, such as periodic maintenance of user interface state that depends on the existence of a specific document. For example, you might remove an item from a download list if the user deletes the file.

If your app must perform operations on the file, such as opening it or copying resource properties, it is more efficient to attempt the operation and handle any failure that may occur.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

filePathURL

Returns a new file path URL that points to the same resource as the original URL.

- (NSURL *)filePathURL
Return Value

The new file path URL.

Discussion

If the original URL is a file reference URL, this method converts it to a URL that contains a file system path. If the original URL is a file path URL, the returned URL is identical. If the original URL is not a file URL, or if the resource is not reachable or no longer exists, this method returns nil.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

fileReferenceURL

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

- (NSURL *)fileReferenceURL
Return Value

The new file reference URL.

Discussion

File reference URLs use a URL path syntax that identifies a file system object by reference, not by path. This form of file URL remains valid when the file system path of the URL’s underlying resource changes.

If the original URL is a file path URL, this method converts it to a file reference URL. If the original URL is a file reference URL, the returned URL is identical. If the original URL is not a file URL, this method returns nil.

File reference URLs cannot be created to file system objects which do not exist or are not reachable. If you try, this method returns nil.

In some areas of the file system hierarchy, file reference URLs cannot be generated to the leaf node of the URL path.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

fileSystemRepresentation

Returns a C string containing the file system path for a file URL.

- (const char *)fileSystemRepresentation
Return Value

A null-terminated C string in file system representation.

Discussion

This string is automatically freed in the same way that a returned object would be released. The caller must either copy the string or use getFileSystemRepresentation:maxLength: if it needs to store the representation outside of the autorelease context in which the value was obtained.

The file system representation format is described in “File Encodings and Fonts”.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

fragment

Returns the fragment of a URL conforming to RFC 1808.

- (NSString *)fragment
Return Value

The fragment of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://www.example.com/index.html#jumpLocation, the fragment identifier is jumpLocation.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

getFileSystemRepresentation:maxLength:

Fills the provided buffer with a C string representing a local file system path.

- (BOOL)getFileSystemRepresentation:(char *)buffer maxLength:(NSUInteger)maxBufferLength
Parameters
buffer

A buffer large enough to hold the path. On return, contains a null-terminated C string in file system representation.

maxBufferLength

The size of buffer in bytes (typically MAXPATHLEN or PATH_MAX).

Return Value

Returns YES if the URL could be converted into a file system representation, otherwise NO.

Discussion

The file system representation format is described in “File Encodings and Fonts”.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

getResourceValue:forKey:error:

Returns the value of the resource property for the specified key.

- (BOOL)getResourceValue:(out id *)value forKey:(NSString *)key error:(out NSError **)error
Parameters
value

The location where the value for the resource property identified by key should be stored.

key

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

error

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

Return Value

YES if value is successfully populated; otherwise, NO.

Discussion

value is set to nil if the requested resource value is not defined for the URL. In this case, the method still returns YES.

This method first checks if the URL object already caches the resource value. If so, it returns the cached resource value to the caller. If not, then this method synchronously obtains the resource value from the backing store, adds the resource value to the URL object's cache, and returns the resource value to the caller.

The type of the returned resource value varies by resource property; for details, see the documentation for the key you want to access.

If this method returns YES and the value is populated with nil, it means that the resource property is not available for the specified resource, and that no errors occurred when determining that the resource property was unavailable.

If this method returns NO, the object pointer referenced by error is populated with additional information.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

host

Returns the host of a URL conforming to RFC 1808.

- (NSString *)host
Return Value

The host of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://www.example.com/index.html, the host is www.example.com.

Discussion

If the URL conforms to RFC 1808 (the most common form of URL), this accessor returns the specified URL component; otherwise it returns nil. The litmus test for conformance to RFC 1808 is as recommended in RFC 1808—specifically, whether the first two characters of resourceSpecifier are slashes (//).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

initByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:

Initializes a newly created NSURL that points to a location specified by resolving bookmark data.

- (id)initByResolvingBookmarkData:(NSData *)bookmarkData options:(NSURLBookmarkResolutionOptions)options relativeToURL:(NSURL *)relativeURL bookmarkDataIsStale:(BOOL *)isStale error:(NSError **)error
Parameters
bookmarkData

The bookmark data the URL is derived from.

options

Options taken into account when resolving the bookmark data.

relativeURL

The base URL that the bookmark data is relative to.

isStale

If YES, the bookmark data is stale.

error

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

Return Value

An NSURL initialized by resolving bookmarkData.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

initFileURLWithFileSystemRepresentation:isDirectory:relativeToURL:

Initializes a URL object with a C string representing a local file system path.

- (id)initFileURLWithFileSystemRepresentation:(const char *)path isDirectory:(BOOL)isDir relativeToURL:(NSURL *)baseURL
Parameters
path

A null-terminated C string in file system representation containing the path to represent as a URL. If this path is a relative path, it is treated as being relative to the current working directory.

isDir

YES if the last path part is a directory, otherwise NO.

baseURL

The base URL for the new URL object. This must be a file URL. If path is absolute, this URL is ignored.

Return Value

Returns the initialized object or nil if an error occurred.

Discussion

The file system representation format is described in “File Encodings and Fonts”.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

initFileURLWithPath:

Initializes a newly created NSURL referencing the local file or directory at path.

- (id)initFileURLWithPath:(NSString *)path
Parameters
path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath. If path is a relative path, it is treated as being relative to the current working directory.

Passing nil for this parameter produces an exception.

Return Value

An NSURL object initialized with path.

Discussion

Invoking this method is equivalent to invoking initWithScheme:host:path: with scheme NSURLFileScheme, a nil host, and path.

This method assumes that path is a directory if it ends with a slash. If path does not end with a slash, the method examines the file system to determine if path is a file or a directory. If path exists in the file system and is a directory, the method appends a trailing slash. If path does not exist in the file system, the method assumes that it represents a file and does not append a trailing slash.

As an alternative, consider using initFileURLWithPath:isDirectory:, which allows you to explicitly specify whether the returned NSURL object represents a file or directory.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

initFileURLWithPath:isDirectory:

Initializes a newly created NSURL referencing the local file or directory at path.

- (id)initFileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir
Parameters
path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath. If path is a relative path, it is treated as being relative to the current working directory.

Passing nil for this parameter produces an exception.

isDir

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

Return Value

An NSURL object initialized with path.

Discussion

Invoking this method is equivalent to invoking initWithScheme:host:path: with scheme NSURLFileScheme, a nil host, and path.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURL.h

initWithScheme:host:path:

Initializes a newly created NSURL with a specified scheme, host, and path.

- (id)initWithScheme:(NSString *)scheme host:(NSString *)host path:(NSString *)path
Parameters
scheme

The scheme for the NSURL object. For example, in the URL http://www.example.com/index.html, the scheme is http.

host

The host for the NSURL object (for example, www.example.com). May be the empty string.

path

The path for the NSURL object (for example, /index.html). If the path begins with a tilde, you must first expand it by calling stringByExpandingTildeInPath.

Return Value

The newly initialized NSURL object.

Discussion

This method automatically uses percent encoding to escape the path and host parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

initWithString:

Initializes an NSURL object with a provided URL string.

- (id)initWithString:(NSString *)URLString
Parameters
URLString

The URL string with which to initialize the NSURL object. This URL string must conform to URL format as described in RFC 2396, and must not be nil. This method parses URLString according to RFCs 1738 and 1808.

Return Value

An NSURL object initialized with URLString. If the URL string was malformed, returns nil.

Discussion

This method expects URLString to contain only characters that are allowed in a properly formed URL. All other characters must be properly percent escaped. Any percent-escaped characters are interpreted using UTF-8 encoding.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

initWithString:relativeToURL:

Initializes an NSURL object with a base URL and a relative string.

- (id)initWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL
Parameters
URLString

The URL string with which to initialize the NSURL object. Must conform to RFC 2396. URLString is interpreted relative to baseURL.

baseURL

The base URL for the NSURL object.

Return Value

An NSURL object initialized with URLString and baseURL. If URLString was malformed, returns nil.

Discussion

This method allows you to create a URL relative to a base path or URL. For example, if you have the URL for a folder on disk and the name of a file within that folder, you can construct a URL for the file by providing the folder’s URL as the base path (with a trailing slash) and the filename as the string part.

This method expects URLString to contain only characters that are allowed in a properly formed URL. All other characters must be properly percent escaped. Any percent-escaped characters are interpreted using UTF-8 encoding.

initWithString:relativeToURL: is the designated initializer for NSURL.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

isEqual:

Returns a Boolean value that indicates whether the receiver and a given object have identical URL strings and base URLs.

- (BOOL)isEqual:(id)anObject
Parameters
anObject

The object to be compared to the receiver.

Return Value

YES if the receiver and anObject are equal, otherwise NO.

Discussion

This method defines what it means for instances to be equal. Two NSURLs are considered equal if and only if they return identical values for both baseURL and relativeString.

isFileReferenceURL

Returns whether the URL is a file reference URL.

- (BOOL)isFileReferenceURL
Return Value

YES if the URL is a file reference URL; otherwise, NO.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

isFileURL

Returns whether the receiver uses the file scheme.

- (BOOL)isFileURL
Return Value

Returns YES if the receiver uses the file scheme, NO otherwise.

Discussion

Both file path and file reference URLs are considered to be file URLs.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSURL.h

lastPathComponent

Returns the last path component of a file URL.

- (NSString *)lastPathComponent
Return Value

The last path component of the URL. For example, in the URL file:///path/to/file, the last path component is file.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

parameterString

Returns the parameter string of a URL conforming to RFC 1808.

- (NSString *)parameterString
Return Value

The parameter string of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL file:///path/to/file;foo, the parameter string is foo.

Discussion

This method should not be confused with the query method, which also often contains a string of parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

password

Returns the password of a URL conforming to RFC 1808.

- (NSString *)password
Return Value

The password of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://username:password@www.example.com/index.html, the password is password.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

path

Returns the path of a URL conforming to RFC 1808.

- (NSString *)path
Return Value

The path of the URL, unescaped with the stringByReplacingPercentEscapesUsingEncoding: method. If the receiver does not conform to RFC 1808, returns nil.

If the URL object contains a file or file reference URL (as determined with isFileURL), the return value of this method is suitable for input into methods of NSFileManager or NSPathUtilities. If the path has a trailing slash, it is stripped.

If the URL object contains a file reference URL, the return value provides the current path for the referenced resource, which may be nil if it no longer exists.

Per RFC 3986, the leading slash after the authority (host name and port) portion is treated as part of the path. For example, in the URL http://www.example.com/index.html, the path is /index.html.

Discussion

If the parameterString method returns a non-nil value, the returned path may be incomplete. In a URL whose path contains an unencoded semicolon, the returned path ends at the character before the semicolon. The remainder of the URL is provided in the parameterString method.

To obtain the complete path, if parameterString returns a non-nil value, append a semicolon, followed by the parameter string.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

pathComponents

Returns the individual path components of a file URL in an array.

- (NSArray *)pathComponents
Return Value

An array containing the individual path components of the URL. For example, in the URL file:///directory/directory2/file, the path components array contains directory, directory2, and file.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

pathExtension

Returns the path extension of a file URL.

- (NSString *)pathExtension
Return Value

The path extension of the URL. For example, in the URL file:///path/to/file.txt, the path extension is txt.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSURL.h

port

Returns the port number of a URL conforming to RFC 1808.

- (NSNumber *)port
Return Value

The port number of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://www.example.com:8080/index.php, the port number is 8080.

Discussion

If the URL conforms to RFC 1808 (the most common form of URL), this accessor returns the specified URL component; otherwise it returns nil. The litmus test for conformance to RFC 1808 is as recommended in RFC 1808—specifically, whether the first two characters of resourceSpecifier are slashes (//).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

query

Returns the query string from a URL conforming to RFC 1808.

- (NSString *)query
Return Value

The query string from the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://www.example.com/index.php?key1=value1&key2=value2, the query string is key1=value1&key2=value2.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

relativePath

Returns the path of a URL conforming to RFC 1808, without resolving against the receiver’s base URL.

- (NSString *)relativePath
Return Value

The relative path of the URL without resolving against the base URL. If the path has a trailing slash it is stripped. If the receiver is an absolute URL, this method returns the same value as path. If the receiver does not conform to RFC 1808, returns nil.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSURL.h

relativeString

Returns a string representation of the relative portion of the URL.

- (NSString *)relativeString
Return Value

A string representation of the relative portion of the URL. If the receiver is an absolute URL this method returns the same value as absoluteString.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

removeAllCachedResourceValues

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

- (void)removeAllCachedResourceValues
Discussion

This method is applicable only to URLs that represent file system resources.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

removeCachedResourceValueForKey:

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

- (void)removeCachedResourceValueForKey:(NSString *)key
Parameters
key

The resource value key whose cached values you wish to remove.

Discussion

Removing a cached resource value may remove other cached resource values because some resource values are cached as a set of values, and because some resource values depend on other resource values. (Temporary resource values have no dependencies.)

This method is currently applicable only to URLs for file system resources.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

resourceSpecifier

Returns the resource specifier of the URL.

- (NSString *)resourceSpecifier
Return Value

The resource specifier of the URL. For example, in the URL http://www.example.com/index.html?key1=value1#jumplink, the resource specifier is //www.example.com/index.html?key1=value1#jumplink (everything after the colon).

Discussion

The full URL is the concatenation of the value of scheme, a colon (:), and this resource specifier value.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

resourceValuesForKeys:error:

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

- (NSDictionary *)resourceValuesForKeys:(NSArray *)keys error:(NSError **)error
Parameters
keys

An array of names of URL resource properties.

error

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

Return Value

A dictionary of resource values indexed by key.

Discussion

This method first checks if the URL object already caches the specified resource values. If so, it returns the cached resource values to the caller. If not, then this method synchronously obtains the resource values from the backing store, adds the resource values to the URL object's cache, and returns the resource values to the caller.

The type of the returned resource value varies by resource property; for details, see the documentation for the key you want to access.

If the result dictionary does not contain a resource value for one or more of the requested resource keys, it means those resource properties are not available for the specified resource and no errors occurred when determining those resource properties were not available.

If an error occurs, this method returns nil and populates the object pointer referenced by error with additional information.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSURL.h

scheme

Returns the scheme of the URL.

- (NSString *)scheme
Return Value

The scheme of the URL. For example, in the URL http://www.example.com/index.html, the scheme is http.

Discussion

The full URL is the concatenation of the scheme, a colon (:), and the value of resourceSpecifier.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSURL.h

setResourceValue:forKey:error:

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

- (BOOL)setResourceValue:(id)value forKey:(NSString *)key error:(NSError **)error
Parameters
value

The value for the resource property defined by key.

key

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

error

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

Return Value

YES if the resource property named key is successfully set to value; otherwise, NO.

Discussion

This method synchronously writes the new resource value out to disk. Attempts to set a read-only resource property or to set a resource property that is not supported by the resource are ignored and are not considered errors.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

setResourceValues:error:

Sets resource properties of the URL specified by a given set of keys to a given set of values.

- (BOOL)setResourceValues:(NSDictionary *)keyedValues error:(NSError **)error
Parameters
keyedValues

A dictionary of resource values to be set.

error

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

Return Value

YES if all resource values in keyedValues are successfully set; otherwise, NO.

Discussion

This method synchronously writes the new resource value out to disk. If an error occurs after some resource properties have been successfully changed, the userInfo dictionary in the returned error object contains a kCFURLKeysOfUnsetValuesKey key whose value is an array of the resource values that were not successfully set.

Attempts to set a read-only resource property or to set a resource property that is not supported by the resource are ignored and are not considered errors.

The order in which the resource values are set is not defined. If you need to guarantee the order in which resource values are set, you should make multiple requests to this method or setResourceValue:forKey:error:.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

setTemporaryResourceValue:forKey:

Sets a temporary resource value on the URL object.

- (void)setTemporaryResourceValue:(id)value forKey:(NSString *)key
Parameters
value

The value to store.

key

The key where the value should be stored. This key must be unique and must not conflict with any system-defined keys. Reverse-domain-name notation is recommended.

Discussion

Your app can use a temporary resource value to temporarily store a value for an app-defined resource value key in memory without modifying the actual resource that the URL represents. Once set, you can copy the temporary resource value from the URL object just as you would copy system-defined keys—by calling getResourceValue:forKey:error: or resourceValuesForKeys:error:.

Your app can remove a temporary resource value from the URL object by calling removeCachedResourceValueForKey: or removeAllCachedResourceValues (to remove all temporary values).

This method is applicable only to URLs for file system resources.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSURL.h

standardizedURL

Returns a new NSURL object with any instances of ".." or "." removed from its path.

- (NSURL *)standardizedURL
Return Value

A new NSURL object initialized with a version of the receiver’s URL that has had any instances of ".." or "." removed from its path.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

startAccessingSecurityScopedResource

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

- (BOOL)startAccessingSecurityScopedResource
Return Value

YES if the request to access the resource succeeded; otherwise, NO.

Discussion

When you obtain a security-scoped URL, such as by resolving a security-scoped bookmark, you cannot immediately use the resource it points to. To make the resource available to your app, by way of adding its location to your app’s sandbox, call this method (or its Core Foundation equivalent) on the security-scoped URL.

When you finish using the resource, call the stopAccessingSecurityScopedResource method to relinquish access. When you call the stopAccessingSecurityScopedResource method, you immediately lose access to the resource in question (even if you have previously called startAccessingSecurityScopedResource more than once).

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSURL.h

stopAccessingSecurityScopedResource

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

- (void)stopAccessingSecurityScopedResource
Discussion

When you no longer need access to a file or directory pointed to by a security-scoped URL, such as one returned by resolving a security-scoped bookmark, call this method (or its Core Foundation equivalent) on the URL to relinquish access. When you call this method, you immediately lose access to the resource in question (even if you have previously called startAccessingSecurityScopedResource more than once).

If you call this method on a URL whose referenced resource you do not have access to, nothing happens.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSURL.h

URLByAppendingPathComponent:

Returns a new URL made by appending a path component to the original URL.

- (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponent
Parameters
pathComponent

The path component to add to the URL, in its original form (not URL encoded).

Return Value

A new URL with pathComponent appended.

Discussion

If the original URL does not end with a forward slash and pathComponent does not begin with a forward slash, a forward slash is inserted between the two parts of the returned URL, unless the original URL is the empty string.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

URLByAppendingPathComponent:isDirectory:

Returns a new URL made by appending a path component to the original URL, along with a trailing slash if the component is designated a directory.

- (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponentisDirectory isDirectory:(BOOL)isDirectory
Parameters
pathComponent

The path component to add to the URL.

isDirectory

If YES, a trailing slash is appended after pathComponent.

Return Value

A new URL with pathComponent appended.

Discussion

If the original URL does not end with a forward slash and pathComponent does not begin with a forward slash, a forward slash is inserted between the two parts of the returned URL, unless the original URL is the empty string.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSURL.h

URLByAppendingPathExtension:

Returns a new URL made by appending a path extension to the original URL.

- (NSURL *)URLByAppendingPathExtension:(NSString *)pathExtension
Parameters
pathExtension

The path extension to add to the URL.

Return Value

A new URL with pathExtension appended.

Discussion

If the original URL ends with one or more forward slashes, these are removed from the returned URL. A period is inserted between the two parts of the new URL.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

URLByDeletingLastPathComponent

Returns a new URL made by deleting the last path component from the original URL.

- (NSURL *)URLByDeletingLastPathComponent
Return Value

A new URL with the last path component of the original URL removed.

Discussion

If the original URL represents the root path, the returned URL is identical. Otherwise, if the original URL has only one path component, the new URL is the empty string.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

URLByDeletingPathExtension

Returns a new URL made by deleting the path extension, if any, from the original URL.

- (NSURL *)URLByDeletingPathExtension
Return Value

A new URL with the path extension of the original URL removed.

Discussion

If the original URL represents the root path, the returned URL is identical. If the URL has multiple path extensions, only the last one is removed.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
NSURL.h

URLByResolvingSymlinksInPath

Returns a new URL that points to the same resource as the original URL and includes no symbolic links.

- (NSURL *)URLByResolvingSymlinksInPath
Return Value

A new URL that points to the same resource as the original URL and includes no symbolic links.

Discussion

If the original URL has no symbolic links, the returned URL is identical to the original URL.

If some symbolic links cannot be resolved, the returned URL contains those broken symbolic links.

If the name of the receiving path begins with /private, this method strips off the /private designator, provided the result is the name of an existing file.

This method only works on URLs with the file: path scheme. This method will return an identical URL for all other URLs.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

URLByStandardizingPath

Returns a new URL that points to the same resource as the original URL and is an absolute path.

- (NSURL *)URLByStandardizingPath
Return Value

A new URL that points to the same resource as the original URL and is an absolute path.

Discussion

This method only works on URLs with the file: path scheme. This method will return an identical URL for all other URLs.

Like stringByStandardizingPath, this method can make the following changes in the provided URL:

  • Expand an initial tilde expression using stringByExpandingTildeInPath.

  • Reduce empty components and references to the current directory (that is, the sequences “//” and “/./”) to single path separators.

  • In absolute paths only, resolve references to the parent directory (that is, the component “..”) to the real parent directory if possible using stringByResolvingSymlinksInPath, which consults the file system to resolve each potential symbolic link.

    In relative paths, because symbolic links can’t be resolved, references to the parent directory are left in place.

  • Remove an initial component of “/private” from the path if the result still indicates an existing file or directory (checked by consulting the file system).

Note that the path returned by this method may still have symbolic link components in it. Note also that this method only works with file paths (not, for example, string representations of URLs).

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

user

Returns the user portion of a URL conforming to RFC 1808.

- (NSString *)user
Return Value

The user portion of the URL. If the receiver does not conform to RFC 1808, returns nil. For example, in the URL http://username:password@www.example.com/index.html, the user is username.

Discussion

If the URL conforms to RFC 1808 (the most common form of URL), this accessor returns the specified URL component; otherwise it returns nil. The litmus test for conformance to RFC 1808 is as recommended in RFC 1808—specifically, whether the first two characters of resourceSpecifier are slashes (//).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSURL.h

Constants

NSURL Schemes

These schemes are the ones that NSURL can parse.

NSString * const NSURLFileScheme;
Constants
NSURLFileScheme

Identifies a URL that points to a file on a mounted volume.

Available in OS X v10.0 and later.

Declared in NSURL.h.

Discussion

For more information, see initWithScheme:host:path:.

Common File System Resource Keys

Keys that apply to file system URLs.

NSString * const NSURLAttributeModificationDateKey;
NSString * const NSURLContentAccessDateKey;
NSString * const NSURLContentModificationDateKey;
NSString * const NSURLCreationDateKey;
NSString * const NSURLCustomIconKey;
NSString * const NSURLEffectiveIconKey;
NSString * const NSURLFileResourceIdentifierKey;
NSString * const NSURLFileResourceTypeKey;
NSString * const NSURLFileSecurityKey;
NSString * const NSURLHasHiddenExtensionKey;
NSString * const NSURLIsDirectoryKey;
NSString * const NSURLIsExcludedFromBackupKey;
NSString * const NSURLIsExecutableKey;
NSString * const NSURLIsHiddenKey;
NSString * const NSURLIsMountTriggerKey;
NSString * const NSURLIsPackageKey;
NSString * const NSURLIsReadableKey;
NSString * const NSURLIsRegularFileKey;
NSString * const NSURLIsSymbolicLinkKey;
NSString * const NSURLIsSystemImmutableKey;
NSString * const NSURLIsUserImmutableKey;
NSString * const NSURLIsVolumeKey;
NSString * const NSURLIsWritableKey;
NSString * const NSURLLabelColorKey;
NSString * const NSURLLabelNumberKey;
NSString * const NSURLLinkCountKey;
NSString * const NSURLLocalizedLabelKey;
NSString * const NSURLLocalizedNameKey;
NSString * const NSURLLocalizedTypeDescriptionKey;
NSString * const NSURLNameKey;
NSString * const NSURLParentDirectoryURLKey;
NSString * const NSURLPathKey
NSString * const NSURLPreferredIOBlockSizeKey;
NSString * const NSURLTagNamesKey;
NSString * const NSURLTypeIdentifierKey;
NSString * const NSURLVolumeIdentifierKey;
NSString * const NSURLVolumeURLKey;
Constants
NSURLAttributeModificationDateKey

The time at which the resource’s attributes were most recently modified, returned as an NSDate object if the volume supports attribute modification dates, or nil if attribute modification dates are unsupported (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLContentAccessDateKey

The time at which the resource was most recently accessed, returned as an NSDate object if the volume supports access dates, or nil if access dates are unsupported (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLContentModificationDateKey

The time at which the resource was most recently modified, returned as an NSDate object if the volume supports modification dates, or nil if modification dates are unsupported (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLCreationDateKey

The resource’s creation date, returned as an NSDate object if the volume supports creation dates, or nil if creation dates are unsupported (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLCustomIconKey

The icon stored with the resource, returned as an NSImage object, or nil if the resource has no custom icon.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLEffectiveIconKey

The resource’s normal icon, returned as an NSImage object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLFileResourceIdentifierKey

The resource’s unique identifier, returned as an id (read-only).

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

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

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeKey

The resource’s object type, returned as an NSString object (read-only). See “File Resource Types” for possible values.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileSecurityKey

The resource’s security information, returned as an NSFileSecurity object (read-write).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLHasHiddenExtensionKey

Key for determining whether the resource’s extension is normally removed from its localized name, returned as a Boolean NSNumber object (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsDirectoryKey

Key for determining whether the resource is a directory, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsExcludedFromBackupKey

Key for determining whether the resource is excluded from all backups of app data, returned as a Boolean NSNumber object (read-write).

You can use this property to exclude cache and other app support files which are not needed in a backup. Some operations commonly made to user documents cause this property to be reset to false; consequently, do not use this property on user documents.

Available in OS X v10.8 and later.

Declared in NSURL.h.

NSURLIsExecutableKey

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 Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLIsHiddenKey

Key for determining whether the resource is normally not displayed to users, returned as a Boolean NSNumber object (read-write).

Note: If the resource is hidden because its name begins with a period, setting this value has no effect.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsMountTriggerKey

Key for determining whether the URL is a file system trigger directory, returned as a Boolean NSNumber object (read-only). Traversing or opening a file system trigger directory causes an attempt to mount a file system on the directory.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLIsPackageKey

Key for determining whether the resource is a file package, returned as a Boolean NSNumber object (read-write in OS X v10.8 and later, read-only in previous versions). A true value means that the resource is a file package.

If you attempt to set or clear this key’s value on a file instead of a directory, the system ignores your attempt. If the directory is defined as a package by way of its filename extension or other reason apart from this key, setting this key’s value to false has no effect.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsReadableKey

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

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLIsRegularFileKey

Key for determining whether the resource is a regular file, as opposed to a directory or a symbolic link. Returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsSymbolicLinkKey

Key for determining whether the resource is a symbolic link, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsSystemImmutableKey

Key for determining whether the resource's system immutable bit is set, returned as a Boolean NSNumber object (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsUserImmutableKey

Key for determining whether the resource's user immutable bit is set, returned as a Boolean NSNumber object (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsVolumeKey

Key for determining whether the resource is the root directory of a volume, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLIsWritableKey

Key for determining whether the current process (as determined by the EUID) can write to the resource, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLLabelColorKey

The resource’s label color, returned as an NSColor object, or nil if the resource has no label color (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLabelNumberKey

The resource’s label number, returned as an NSNumber object (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLinkCountKey

The number of hard links to the resource, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLocalizedLabelKey

The resource’s localized label text, returned as an NSString object, or nil if the resource has no localized label text (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLocalizedNameKey

The resource’s localized or extension-hidden name, returned as an NSString object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLocalizedTypeDescriptionKey

The resource’s localized type description, returned as an NSString object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLNameKey

The resource’s name in the file system, returned as an NSString object (read-write).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLParentDirectoryURLKey

The parent directory of the resource, returned as an NSURL object, or nil if the resource is the root directory of its volume (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLPathKey

The file system path for the URL, returned as an NSString object (read-only).

Available in OS X v10.8 and later.

Declared in NSURL.h.

NSURLPreferredIOBlockSizeKey

The optimal block size to use when reading or writing this file's data, returned as an NSNumber object, or nil if the preferred size is not available (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLTagNamesKey

The names of tags attached to the resource, returned as an array of NSString values (read-write).

Available in OS X v10.9 and later.

Declared in NSURL.h.

NSURLTypeIdentifierKey

The resource’s uniform type identifier (UTI), returned as an NSString object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeIdentifierKey

The unique identifier of the resource’s volume, returned as an id (read-only).

This identifier can be used with the isEqual: method to determine whether two file system resources are on the same volume.

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

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeURLKey

The root directory of the resource’s volume, returned as an NSURL object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

Discussion

To request information using one of these keys, pass it to the forKey: parameter of the getResourceValue:forKey:error: instance method.

File Resource Types

Possible values for the NSURLFileResourceTypeKey key.

NSString * const NSURLFileResourceTypeNamedPipe;
NSString * const NSURLFileResourceTypeCharacterSpecial;
NSString * const NSURLFileResourceTypeDirectory;
NSString * const NSURLFileResourceTypeBlockSpecial;
NSString * const NSURLFileResourceTypeRegular;
NSString * const NSURLFileResourceTypeSymbolicLink;
NSString * const NSURLFileResourceTypeSocket;
NSString * const NSURLFileResourceTypeUnknown;
Constants
NSURLFileResourceTypeNamedPipe

The resource is a named pipe.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeCharacterSpecial

The resource is a character special file.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeDirectory

The resource is a directory.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeBlockSpecial

The resource is a block special file.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeRegular

The resource is a regular file.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeSymbolicLink

The resource is a symbolic link.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeSocket

The resource is a socket.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLFileResourceTypeUnknown

The resource’s type is unknown.

Available in OS X v10.7 and later.

Declared in NSURL.h.

File Property Keys

Keys that apply to properties of files.

NSString * const NSURLFileSizeKey;
NSString * const NSURLFileAllocatedSizeKey;
NSString * const NSURLIsAliasFileKey;
NSString * const NSURLTotalFileAllocatedSizeKey;
NSString * const NSURLTotalFileSizeKey;
Constants
NSURLFileSizeKey

Key for the file’s size in bytes, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLFileAllocatedSizeKey

Key for the total size allocated on disk for the file, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLTotalFileSizeKey

Key for the total displayable size of the file in bytes, returned as an NSNumber object (read-only). This includes the size of any file metadata.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLTotalFileAllocatedSizeKey

Key for the total allocated size of the file in bytes, returned as an NSNumber object (read-only). This includes the size of any file metadata.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLIsAliasFileKey

Key for determining whether the file is an alias, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

Volume Property Keys

Keys that apply to volumes.

NSString * const NSURLVolumeLocalizedFormatDescriptionKey;
NSString * const NSURLVolumeTotalCapacityKey;
NSString * const NSURLVolumeAvailableCapacityKey;
NSString * const NSURLVolumeResourceCountKey;
NSString * const NSURLVolumeSupportsPersistentIDsKey;
NSString * const NSURLVolumeSupportsSymbolicLinksKey;
NSString * const NSURLVolumeSupportsHardLinksKey;
NSString * const NSURLVolumeSupportsJournalingKey;
NSString * const NSURLVolumeIsJournalingKey;
NSString * const NSURLVolumeSupportsSparseFilesKey;
NSString * const NSURLVolumeSupportsZeroRunsKey;
NSString * const NSURLVolumeSupportsCaseSensitiveNamesKey;
NSString * const NSURLVolumeSupportsCasePreservedNamesKey;
NSString * const NSURLVolumeSupportsRootDirectoryDatesKey;
NSString * const NSURLVolumeSupportsVolumeSizesKey;
NSString * const NSURLVolumeSupportsRenamingKey;
NSString * const NSURLVolumeSupportsAdvisoryFileLockingKey;
NSString * const NSURLVolumeSupportsExtendedSecurityKey;
NSString * const NSURLVolumeIsBrowsableKey;
NSString * const NSURLVolumeMaximumFileSizeKey;
NSString * const NSURLVolumeIsEjectableKey;
NSString * const NSURLVolumeIsRemovableKey;
NSString * const NSURLVolumeIsInternalKey;
NSString * const NSURLVolumeIsAutomountedKey;
NSString * const NSURLVolumeIsLocalKey;
NSString * const NSURLVolumeIsReadOnlyKey;
NSString * const NSURLVolumeCreationDateKey;
NSString * const NSURLVolumeURLForRemountingKey;
NSString * const NSURLVolumeUUIDStringKey;
NSString * const NSURLVolumeNameKey;
NSString * const NSURLVolumeLocalizedNameKey;
Constants
NSURLVolumeLocalizedFormatDescriptionKey

Key for the volume’s descriptive format name, returned as an NSString object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeTotalCapacityKey

Key for the volume’s capacity in bytes, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeAvailableCapacityKey

Key for the volume’s available capacity in bytes, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeResourceCountKey

Key for the total number of resources on the volume, returned as an NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsPersistentIDsKey

Key for determining whether the volume supports persistent IDs, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsSymbolicLinksKey

Key for determining whether the volume supports symbolic links, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsHardLinksKey

Key for determining whether the volume supports hard links, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsJournalingKey

Key for determining whether the volume supports journaling, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeIsJournalingKey

Key for determining whether the volume is currently journaling, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsSparseFilesKey

Key for determining whether the volume supports sparse files, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsZeroRunsKey

Key for determining whether the volume supports zero runs, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsCaseSensitiveNamesKey

Key for determining whether the volume supports case-sensitive names, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsCasePreservedNamesKey

Key for determining whether the volume supports case-preserved names, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLVolumeSupportsRootDirectoryDatesKey

Key for determining whether the volume supports reliable storage of times for the root directory, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeSupportsVolumeSizesKey

Key for determining whether the volume supports returning volume size information, returned as a Boolean NSNumber object (read-only). If true, volume size information is available as values of the NSURLVolumeTotalCapacityKey andNSURLVolumeAvailableCapacityKey keys.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeSupportsRenamingKey

Key for determining whether the volume can be renamed, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeSupportsAdvisoryFileLockingKey

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 Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeSupportsExtendedSecurityKey

Key for determining whether the volume supports extended security (access control lists), returned as a Boolean NSNumber object (read-only) (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsBrowsableKey

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 Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeMaximumFileSizeKey

Key for the largest file size supported by the volume in bytes, returned as a Boolean NSNumber object, or nil if it cannot be determined (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsEjectableKey

Key for determining whether the volume is ejectable from the drive mechanism under software control, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsRemovableKey

Key for determining whether the volume is removable from the drive mechanism, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsInternalKey

Key for determining whether the volume is connected to an internal bus, returned as a Boolean NSNumber object, or nil if it cannot be determined (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsAutomountedKey

Key for determining whether the volume is automounted, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsLocalKey

Key for determining whether the volume is stored on a local device, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeIsReadOnlyKey

Key for determining whether the volume is read-only, returned as a Boolean NSNumber object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeCreationDateKey

Key for the volume’s creation date, returned as an NSDate object, or NULL if it cannot be determined (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeURLForRemountingKey

Key for the URL needed to remount the network volume, returned as an NSURL object, or nil if a URL is not available (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeUUIDStringKey

Key for the volume’s persistent UUID, returned as an NSString object, or nil if a persistent UUID is not available (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeNameKey

The name of the volume, returned as an NSString object (read-write). Settable only if NSURLVolumeSupportsRenamingKey is YES.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeLocalizedNameKey

The name of the volume as it should be displayed in the user interface, returned as an NSString object (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

Discussion

As a convenience, volume resource property values can be requested from any file system URL. The value returned reflects the property value for the volume on which the resource is located.

NSURLBookmarkFileCreationOptions

Options used when creating file bookmark data

typedef NSUInteger NSURLBookmarkFileCreationOptions;
Discussion

See “Bookmark Data Creation Options” for more information.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSURL.h

Bookmark Data Creation Options

Options used when creating bookmark data.

enum {
   NSURLBookmarkCreationPreferFileIDResolution            = ( 1UL << 8 ),
   NSURLBookmarkCreationMinimalBookmark                   = ( 1UL << 9 ),
   NSURLBookmarkCreationSuitableForBookmarkFile           = ( 1UL << 10 ),
   NSURLBookmarkCreationWithSecurityScope                 = ( 1UL << 11 ),
   NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess  = ( 1UL << 12 )
};
typedef NSUInteger NSURLBookmarkCreationOptions;
Constants
NSURLBookmarkCreationPreferFileIDResolution

Specifies that when a bookmark created with this option is resolved, its embedded file ID should take precedence over other sources of information (file system path, for example) in the event of a conflict.

Available in OS X v10.6 and later.

Deprecated in OS X v10.9.

Declared in NSURL.h.

NSURLBookmarkCreationMinimalBookmark

Specifies that a bookmark created with this option should be created with minimal information. This produces a smaller bookmark that can be resolved in fewer ways.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLBookmarkCreationSuitableForBookmarkFile

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

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLBookmarkCreationWithSecurityScope

Specifies that you want to create a security-scoped bookmark that, when resolved, provides a security-scoped URL allowing read/write access to a file-system resource; for use in an app that adopts App Sandbox. For more information, see App Sandbox Design Guide. Note that this flag cannot be used in conjunction with either NSURLBookmarkCreationMinimalBookmark or NSURLBookmarkCreationSuitableForBookmarkFile.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess

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

Available in OS X v10.7 and later.

Declared in NSURL.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 bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: 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 {
   NSURLBookmarkResolutionWithoutUI          = ( 1UL << 8 ),
   NSURLBookmarkResolutionWithoutMounting    = ( 1UL << 9 ),
   NSURLBookmarkResolutionWithSecurityScope  = ( 1UL << 10 )
};
typedef NSUInteger NSURLBookmarkResolutionOptions;
Constants
NSURLBookmarkResolutionWithoutUI

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

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLBookmarkResolutionWithoutMounting

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

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLBookmarkResolutionWithSecurityScope

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

Available in OS X v10.7 and later.

Declared in NSURL.h.

Discussion

When resolving a bookmark, use bitwise OR operators to combine the options you want to specify, and provide them to the options parameter of the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: method.

Version Notes

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

NSURLHandle FTP Property Keys

FTP-specific property keys.

NSString *NSFTPPropertyUserLoginKey;
NSString *NSFTPPropertyUserPasswordKey;
NSString *NSFTPPropertyActiveTransferModeKey;
NSString *NSFTPPropertyFileOffsetKey;
NSString *NSFTPPropertyFTPProxy;
Constants
NSFTPPropertyUserLoginKey

Key for the user login, returned as an NSString object.

The default value for this key is “anonymous”.

Available in OS X v10.2 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyUserPasswordKey

Key for the user password, returned as an NSString object.

The default value for this key is "NSURLHandle@apple.com".

Available in OS X v10.2 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyActiveTransferModeKey

Key for retrieving whether in active transfer mode, returned as a boolean wrapped in an NSNumber object.

The default value for this key is NO (passive mode).

Available in OS X v10.2 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyFileOffsetKey

Key for retrieving the file offset, returned as an NSNumber object. The default value for this key is zero.

Available in OS X v10.2 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyFTPProxy

NSDictionary containing proxy information to use in place of proxy identified in SystemConfiguration.framework.

To avoid any proxy use, pass an empty dictionary.

Available in OS X v10.3 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

Discussion

Pass these keys to NSURLHandle’s getResourceValue:forKey:error: or resourceValuesForKeys:error: method to request specific data. All keys are optional. The default configuration allows an anonymous, passive-mode, one-off transfer of the specified URL.

NSURLHandle HTTP Property Keys

HTTP-specific property keys.

NSString * const NSHTTPPropertyStatusCodeKey;
NSString * const NSHTTPPropertyStatusReasonKey;
NSString * const NSHTTPPropertyServerHTTPVersionKey;
NSString * const NSHTTPPropertyRedirectionHeadersKey;
NSString * const NSHTTPPropertyErrorPageDataKey;
NSString * const NSHTTPPropertyHTTPProxy;
Constants
NSHTTPPropertyStatusCodeKey

Key for the status code, returned as an integer wrapped in an NSNumber object.

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyStatusReasonKey

Key for the remainder of the HTTP status line following the status code, returned as an NSString object.

This string usually contains an explanation of the error in English. Because this string is taken straight from the server response, it’s not localized.

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyServerHTTPVersionKey

Key for retrieving the HTTP version as an NSString object containing the initial server status line up to the first space.

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyRedirectionHeadersKey

Key for retrieving the redirection headers as an NSDictionary object with each header value keyed to the header name.

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyErrorPageDataKey

Key for retrieving an error page as an NSData object.

Available in OS X v10.0 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyHTTPProxy

Key for retrieving the NSDictionary object containing proxy information to use in place of proxy identified in SystemConfiguration.framework.

To avoid any proxy use, pass an empty dictionary.

Available in OS X v10.2 and later.

Deprecated in OS X v10.4.

Declared in NSURLHandle.h.

Discussion

Pass these keys to NSURLHandle's getResourceValue:forKey:error: or resourceValuesForKeys:error: method to request specific data.

NSError userInfo Dictionary Keys

Keys in the userInfo dictionary of an NSError object when certain NSURL methods return an error.

NSString * const NSURLKeysOfUnsetValuesKey;
Constants
NSURLKeysOfUnsetValuesKey

Key for the resource properties that have not been set after the setResourceValues:error: method returns an error, returned as an array of of NSString objects.

Available in OS X v10.7 and later.

Declared in NSURL.h.

Ubiquitous Item Property Keys

Keys that describe the iCloud storage state of a file.

NSString * const NSURLIsUbiquitousItemKey;
NSString * const NSURLUbiquitousItemDownloadingErrorKey;
NSString * const NSURLUbiquitousItemDownloadingStatusKey;
NSString * const NSURLUbiquitousItemHasUnresolvedConflictsKey;
NSString * const NSURLUbiquitousItemIsDownloadedKey;
NSString * const NSURLUbiquitousItemIsDownloadingKey;
NSString * const NSURLUbiquitousItemIsUploadedKey;
NSString * const NSURLUbiquitousItemIsUploadingKey;
NSString * const NSURLUbiquitousItemPercentDownloadedKey;
NSString * const NSURLUbiquitousItemPercentUploadedKey;
NSString * const NSURLUbiquitousItemUploadingErrorKey;
Constants
NSURLIsUbiquitousItemKey

A boolean NSNumber that contains true if this item is in iCloud storage, false if it is a local item (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemDownloadingErrorKey

An error object that indicates why downloading the item from iCloud failed. See Foundation Constants Reference for possible error codes.

Available in OS X v10.9 and later.

Declared in NSURL.h.

NSURLUbiquitousItemDownloadingStatusKey

The current download state for the item, indicating whether a local copy exists and whether that copy is the most current version of the item. The possible values for this key are described in “Ubiquitous Item Downloading Status Constants.”

Available in OS X v10.9 and later.

Declared in NSURL.h.

NSURLUbiquitousItemHasUnresolvedConflictsKey

A boolean NSNumber that contains true if this item has conflicts outstanding, false otherwise (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemIsDownloadedKey

A boolean NSNumber that contains true if this item’s data has been downloaded to a ubiquity container, false otherwise (read-only).

Available in OS X v10.7 and later.

Deprecated in OS X v10.9.

Declared in NSURL.h.

NSURLUbiquitousItemIsDownloadingKey

A boolean NSNumber that contains true if this item is being downloaded from iCloud, false otherwise (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemIsUploadedKey

A boolean NSNumber that contains true if this item’s data has been uploaded to iCloud storage, false otherwise (read-only).

Note: When waiting for an upload to complete, do not poll this key from within a block passed to coordinateReadingItemAtURL:options:error:byAccessor:, because the coordinated read required to obtain this value cannot be performed until that block completes and returns. Instead, use NSMetadataQuery or an NSFilePresenter delegate to asynchronously notify your app when the status changes.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemIsUploadingKey

A boolean NSNumber that contains true if this item is being uploaded to iCloud, false otherwise (read-only).

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemPercentDownloadedKey

An NSNumber in the range 0–100 that indicates the percentage of the data that has been downloaded (read-only).

Deprecated. Instead, use the property key NSMetadataUbiquitousItemPercentDownloadedKey of the NSMetadataQuery class to obtain information on an NSMetadataItem object.

Available in OS X v10.7 and later.

Deprecated in OS X v10.8.

Declared in NSURL.h.

NSURLUbiquitousItemPercentUploadedKey

An NSNumber in the range 0–100 that indicates the percentage of the data that has been uploaded (read-only).

Deprecated. Instead, use the property key NSMetadataUbiquitousItemPercentUploadedKey of the NSMetadataQuery class to obtain information on an NSMetadataItem object.

Available in OS X v10.7 and later.

Deprecated in OS X v10.8.

Declared in NSURL.h.

NSURLUbiquitousItemUploadingErrorKey

An error object that indicates why uploading the item to iCloud failed. See Foundation Constants Reference for possible error codes.

Available in OS X v10.9 and later.

Declared in NSURL.h.

Discussion

To request information about the iCloud storage state of an item, pass one of these keys to the forKey: parameter of the getResourceValue:forKey:error: instance method.

Ubiquitous Item Downloading Status Constants

Values that describe the iCloud storage state of a file.

NSString * const NSURLUbiquitousItemDownloadingStatusCurrent;
NSString * const NSURLUbiquitousItemDownloadingStatusDownloaded;
NSString * const NSURLUbiquitousItemDownloadingStatusNotDownloaded;
Constants
NSURLUbiquitousItemDownloadingStatusCurrent

A local copy of this item exists and is the most up-to-date version known to the device.

Available in OS X v10.9 and later.

Declared in NSURL.h.

NSURLUbiquitousItemDownloadingStatusDownloaded

A local copy of this item exists, but it is stale. The most recent version will be downloaded as soon as possible.

Available in OS X v10.9 and later.

Declared in NSURL.h.

NSURLUbiquitousItemDownloadingStatusNotDownloaded

This item has not been downloaded yet. Use startDownloadingUbiquitousItemAtURL:error: to download it.

Available in OS X v10.9 and later.

Declared in NSURL.h.

Discussion

These constants are possible values for the NSURLUbiquitousItemDownloadingStatusKey key.