NSURL Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSURLHandleClient
NSSecureCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Declared in
NSURL.h
NSURLHandle.h
Companion guides
File System Programming Guide
URL Loading System Programming Guide
Related sample code

Overview

An NSURL object lets you manipulate URLs and the resources they reference. The URLs employed by the NSURL class are described in RFCs 1808, 1738, and 2732. The litmus test for conformance to RFC 1808 is as recommended in RFC 1808—specifically, whether the first two characters of resourceSpecifier are slashes (//).

You can use an NSURL object to refer to a file, which is the preferred way to do so. AppKit objects that can read data from or write data to a file generally have methods that accept an NSURL object instead of a pathname as the file reference. In OS X, the NSWorkspace class provides openURL: to open a location specified by a URL. Similarly, in iOS, UIApplication provides openURL:. To get the contents of a URL, NSString provides stringWithContentsOfURL: and NSData provides dataWithContentsOfURL:.

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 whose string is fully resolved without a base is considered absolute; all others are considered relative.

The classes NSURLConnection and NSURLDownload define methods useful for loading URL resources in the background. See URL Loading System Programming Guide for more information

See also NSURL Additions Reference in the AppKit framework, which describes methods supporting pasteboards.

The NSURL class is toll-free bridged with its Core Foundation counterpart, CFURLRef. For more information on toll-free bridging, see “Toll-Free Bridging”.

Bookmarks, Security Scope, and Start/Stop Semantics

Starting in OS X v10.6, 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 call the stopAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStopAccessingSecurityScopedResource function) on the resource’s URL.

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 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

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.
See Also
Related Sample Code
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.
See Also
Related Sample Code
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.

bookmarkData

The bookmark data the resource values are derived from.

Return Value

A dictionary of the requested resource values contained in bookmarkData.

Availability
  • Available in OS X v10.6 and later.
See Also
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

If YES, the bookmark data is stale.

error

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

Return Value

A new URL made by resolving bookmarkData.

Discussion

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.
See Also
Related Sample Code
Declared In
NSURL.h

URLWithString:

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

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

The 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. (To create NSURL objects for file system paths, use fileURLWithPath:isDirectory: instead.)

Return Value

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

Discussion

This method expects URLString to contain any necessary percent escape codes, which are ‘:’, ‘/’, ‘%’, ‘#’, ‘;’, and ‘@’. Note that ‘%’ escapes are translated via UTF-8.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 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, returns nil.

Discussion

This method expects URLString to contain any necessary percent escape codes.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 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.
Related Sample Code
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.

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

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

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

keys

An array of names of URL resource properties.

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

To use this method to create a security-scoped bookmark to support App Sandbox, you must first have enabled the appropriate entitlements for your app, as described in “Enabling Security-Scoped Bookmark and URL Access” in Entitlement Key Reference. In addition, be sure to understand the behavior of the options and 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.
See Also
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 in the case that the resource cannot be reached.

Return Value

YES if the resource is reachable; otherwise, NO.

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 file path URL. If the original URL is a file path URL, the returned URL is identical. If the original URL is not a file URL, 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

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.

Availability
  • Available in OS X v10.6 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.

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

getResourceValue:forKey:error:

Returns the resource value for the property identified by a given key.

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

The value for the property identified 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 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.

Availability
  • Available in OS X v10.6 and later.
See Also
Related Sample Code
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.

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

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 examines path in the file system to determine if it is a directory. If path is a directory, then a trailing slash is appended. If the file does not exist, it is assumed that path represents a directory and a trailing slash is appended. As an alternative, consider using initFileURLWithPath:isDirectory: which allows you to explicitly specify whether the returned NSURL represents a file or directory.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
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.
See Also
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.

host

The host for the NSURL object. May be the empty string.

path

The path for the NSURL object. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.

Return Value

The newly initialized NSURL object.

Discussion

This method automatically escapes path with the stringByAddingPercentEscapesUsingEncoding: method.

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

initWithString:

Initializes an NSURL object with a provided string.

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

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

Return Value

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

Discussion

This method expects URLString to contain any necessary percent escape codes, which are ‘:’, ‘/’, ‘%’, ‘#’, ‘;’, and ‘@’. Note that ‘%’ escapes are translated via UTF-8.

Availability
  • Available in OS X v10.0 and later.
See Also
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 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 expects URLString to contain any necessary percent escape codes.

initWithString:relativeToURL: is the designated initializer for NSURL.

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

isEqual:

Returns a Boolean value that indicates whether the receiver and a given object are equal.

- (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.

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.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
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.

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.

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 this URL object contains a file 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.

Per RFC 3986, the leading slash after the authority (host name and port) portion is treated as part of the path.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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.

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.

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.

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

query

Returns the query of a URL conforming to RFC 1808.

- (NSString *)query
Return Value

The query of the URL. If the receiver does not conform to RFC 1808, returns nil.

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 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

resourceSpecifier

Returns the resource specifier of the URL.

- (NSString *)resourceSpecifier
Return Value

The resource specifier of the URL.

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

If an error occurs, this method returns nil.

A key is left out of the returned dictionary if its corresponding resource value is not defined for the URL.

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

scheme

Returns the scheme of the URL.

- (NSString *)scheme
Return Value

The scheme of the URL.

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

The resource is modified synchronously.

Availability
  • Available in OS X v10.6 and later.
See Also
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

If an error occurs during the execution of this method, error will contain an array of the resource values that were not successfully set in its userInfo dictionary.

Availability
  • Available in OS X v10.6 and later.
See Also
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.

Calls to the startAccessingSecurityScopedResource method (or its Core Foundation equivalent) are nestable on a per-process basis. This means that if your app calls the start method on a URL twice, to fully relinquish access to the referenced resource you must call the corresponding stop method twice.

Availability
  • Available in OS X v10.7 and later.
See Also
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. 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.
See Also
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.

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.
Related Sample Code
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 :(BOOL)isDirectory
Parameters
pathComponent

The path component to add to the URL.

isDirectory

If TRUE, 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.

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.

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.

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 through OS X v10.7.

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

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.

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.

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.

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.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLFileResourceIdentifierKey

The resource’s unique identifier, returned as an id.

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

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.

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.

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 access.

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.

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.

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. 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. A true value means that the resource is a file package.

Value is read/write. In versions of OS X prior to 10.8, value is read-only.

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.

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.

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.

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.

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.

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.

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.

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.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLabelNumberKey

The resource’s label number, returned as an NSNumber object.

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.

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.

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.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLLocalizedTypeDescriptionKey

The resource’s localized type description, returned as an NSString object.

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.

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.

Available in OS X v10.6 and later.

Declared in NSURL.h.

NSURLPathKey

The file system path for the URL, returned a read-only NSString object.

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.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLTypeIdentifierKey

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

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLVolumeNameKey

The name of the volume, returned as an NSString object. Settable 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.

Available in OS X v10.7 and later.

Declared in NSURL.h.

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 an alias 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.

Declared in NSURL.h.

NSURLBookmarkCreationMinimalBookmark

Specifies that an alias 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.

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.

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 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 propertyForKeyIfAvailable: 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 propertyForKeyIfAvailable: 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 NSURLUbiquitousItemHasUnresolvedConflictsKey;
NSString * const NSURLUbiquitousItemIsDownloadedKey;
NSString * const NSURLUbiquitousItemIsDownloadingKey;
NSString * const NSURLUbiquitousItemIsUploadedKey;
NSString * const NSURLUbiquitousItemIsUploadingKey;
NSString * const NSURLUbiquitousItemPercentDownloadedKey;
NSString * const NSURLUbiquitousItemPercentUploadedKey;
Constants
NSURLIsUbiquitousItemKey

A boolean NSNumber that contains true if this item is in iCloud storage, false if it is a local item.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemHasUnresolvedConflictsKey

A boolean NSNumber that contains true if this item has conflicts outstanding, false otherwise.

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.

Available in OS X v10.7 and later.

Declared in NSURL.h.

NSURLUbiquitousItemIsDownloadingKey

A boolean NSNumber that contains true if this item is being downloaded from iCloud, false otherwise.

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.

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.

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.

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.

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.

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.



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...