NSURL
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 Session Programming Guide.
URL objects are the preferred way to refer to local files. Most 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/user/ as the base URL and folder/file.html as the string part, as follows:
NSURL *baseURL = [NSURL fileURLWithString:@"file:///path/to/user/"];NSURL *URL = [NSURL URLWithString:@"folder/file.html" relativeToURL:baseURL];NSLog(@"absoluteURL = %@", [URL absoluteURL]);
When fully resolved, the absolute URL is file:///path/to/user/folder/file.html.
A URL can be also be divided into pieces based on its structure. For example, the URL https://johnny:p4ssw0rd@www.example.com:443/script.ext;param=value?query=value#ref contains the following URL components:
Component |
Value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The NSURL class provides properties that let you examine each of these components.
Bookmarks and Security Scope
Starting with OS X v10.6 and iOS 4.0, 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.
For a general introduction to using bookmarks, read Locating Files Using Bookmarks in File System Programming Guide.
In an OS X app that adopts App Sandbox, you can use security-scoped bookmarks to gain access to file-system resources outside your app’s sandbox. These bookmarks preserve the user’s intent to give your app access to a resource across app launches. 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. The methods for using security-scoped bookmarks are described in this document in Working with Bookmark Data.
When you resolve a security-scoped bookmark, you get a security-scoped URL.
Security-Scoped URLs
Security-scoped URLs provide access to resources outside an app’s sandbox. In OS X, you get access to security-scoped URLs when you resolve a security-scoped bookmark. In iOS, apps that open or move documents using a UIDocumentPickerViewController also receive security-scoped URLs.
To gain access to a security-scoped URL, you must call the startAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStartAccessingSecurityScopedResource function). For iOS apps, if you use a UIDocument to access the URL, it automatically manages the security-scoped URL for you.
If startAccessingSecurityScopedResource (or CFUrLStartAccessingSecurityScopedResource) returns YEStrue, you must relinquish your access by calling the stopAccessingSecurityScopedResource method (or its Core Foundation equivalent, the CFURLStopAccessingSecurityScopedResource function). You should relinquish your access as soon as you have finished using the file. After you call these methods, you immediately lose access to the resource in question.
Security-Scoped URLs and String Paths
In an OS X app, when you copy a security-scoped URL, 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.
iCloud Document Thumbnails
With OS X v10.10 and iOS 8.0, the NSURL class includes the ability to get and set document thumbnails as a resource property for iCloud documents. You can get a dictionary of NSImage objects in OS X or UIImage objects in iOS using the getResourceValue:forKey:error: or getPromisedItemResourceValue:forKey:error: methods.
Objective-C
NSURL *URL = [self URLForDocument];NSDictionary *thumbnails = nil;NSError *error = nil;BOOL success = [URL getPromisedItemResourceValue:&thumbnailsforKey:NSURLThumbnailDictionaryKeyerror:nil];if (success) {NSImage *image = thumbnails[NSThumbnail1024x1024SizeKey];} else {// handle the error}
Swift
let URL = self.URLForDocument()var thumbnails: AnyObject?do {try URL.getResourceValue(&thumbnails, forKey: NSURLThumbnailDictionaryKey)if let thumbnails = thumbnails as? [NSString: NSImage] {let image = thumbnails[NSThumbnail1024x1024SizeKey]}} catch {// handle the error}
On OS X, you can set a dictionary of thumbnails using the setResourceValue:forKey:error: method. You can also get or set all the thumbnails as an NSImage object with multiple representations by using the NSURLThumbnailKey.
Objective-C
NSURL *URL = [self URLForDocument];NSImage *thumbnail = [self createDocumentThumbnail];NSError *error = nil;BOOL success = [URL setResourceValue:@{NSThumbnail1024x1024SizeKey : thumbnail}forKey:NSURLThumbnailDictionaryKeyerror:&error];if (!success) {// handle the error}
Swift
let URL = self.URLForDocument()let thumbnail = self.createDocumentThumbnail()do {try URL.setResourceValue([NSThumbnail1024x1024SizeKey: thumbnail], forKey: NSURLThumbnailDictionaryKey)} catch {// handle the error}
-
init(scheme:host:path:) - initWithScheme:host:path:(OS X v10.11)Initializes a newly created NSURL with a specified scheme, host, and path.
Declaration
Parameters
schemeThe scheme for the NSURL object. For example, in the URL
http://www.example.com/index.html, the scheme ishttp.hostThe host for the NSURL object (for example,
www.example.com). May be the empty string.pathThe path for the NSURL object (for example,
/index.html). If the path begins with a tilde, you must first expand it by callingstringByExpandingTildeInPath.Return Value
The newly initialized NSURL object.
Discussion
This method automatically uses percent encoding to escape the
pathandhostparameters.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.11.
-
Creates and returns an NSURL object initialized with a provided URL string.
Declaration
Objective-C
+ (instancetype)URLWithString:(NSString *)URLStringParameters
URLStringThe URL string with which to initialize the NSURL object. Must be a URL that conforms to RFC 2396. This method parses
URLStringaccording to RFCs 1738 and 1808.Return Value
An NSURL object initialized with
URLString. If the URL string was malformed ornil, returnsnil.Discussion
This method expects
URLStringto 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.
-
Initializes an NSURL object with a provided URL string.
Declaration
Swift
convenience init?(stringURLString: String)Objective-C
- (instancetype)initWithString:(NSString *)URLStringParameters
URLStringThe 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 parsesURLStringaccording to RFCs 1738 and 1808.Return Value
An NSURL object initialized with
URLString. If the URL string was malformed, returnsnil.Discussion
This method expects
URLStringto 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.
See Also
-
Creates and returns an NSURL object initialized with a base URL and a relative string.
Declaration
Objective-C
+ (instancetype)URLWithString:(NSString *)URLStringrelativeToURL:(NSURL *)baseURLParameters
URLStringThe URL string with which to initialize the NSURL object. May not be
nil. Must conform to RFC 2396.URLStringis interpreted relative tobaseURL.baseURLThe base URL for the NSURL object.
Return Value
An NSURL object initialized with
URLStringandbaseURL. IfURLStringwas malformed ornil, returnsnil.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
URLStringto 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.
-
init(string:relativeTo:) - initWithString:relativeToURL:Designated InitializerInitializes an NSURL object with a base URL and a relative string.
Declaration
Swift
init?(stringURLString: String, relativeToURLbaseURL: NSURL?)Objective-C
- (instancetype)initWithString:(NSString *)URLStringrelativeToURL:(NSURL *)baseURLParameters
URLStringThe URL string with which to initialize the NSURL object. Must conform to RFC 2396.
URLStringis interpreted relative tobaseURL.baseURLThe base URL for the NSURL object.
Return Value
An NSURL object initialized with
URLStringandbaseURL. IfURLStringwas malformed, returnsnil.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
URLStringto 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.
-
Initializes and returns a newly created NSURL object as a file URL with a specified path.
Declaration
Objective-C
+ (NSURL *)fileURLWithPath:(NSString *)pathisDirectory:(BOOL)isDirParameters
pathThe path that the NSURL object will represent.
pathshould be a valid system path. Ifpathbegins with a tilde, it must first be expanded withstringByExpandingTildeInPath. Ifpathis a relative path, it is treated as being relative to the current working directory.isDirA Boolean value that specifies whether
pathis treated as a directory path when resolving against relative path components. PassYEStrueif thepathindicates a directory,NOfalseotherwise.Return Value
An NSURL object initialized with
path, ornilifpathis zero-length.Availability
Available in OS X v10.5 and later.
See Also
-
init(fileURLWithPath:isDirectory:) - initFileURLWithPath:isDirectory:Designated InitializerInitializes a newly created NSURL referencing the local file or directory at
path.Declaration
Objective-C
- (instancetype)initFileURLWithPath:(NSString *)pathisDirectory:(BOOL)isDirParameters
pathThe path that the NSURL object will represent.
pathshould be a valid system path. Ifpathbegins with a tilde, it must first be expanded withstringByExpandingTildeInPath. Ifpathis a relative path, it is treated as being relative to the current working directory.isDirA Boolean value that specifies whether
pathis treated as a directory path when resolving against relative path components. PassYEStrueif thepathindicates a directory,NOfalseotherwiseReturn Value
An NSURL object initialized with
path, ornilifpathis zero-length.Discussion
Invoking this method is equivalent to invoking
initWithScheme:host:path:with schemeNSURLFileScheme, anilhost, andpath.Availability
Available in OS X v10.5 and later.
See Also
-
Initializes and returns a newly created NSURL object as a file URL with a specified path.
Declaration
Swift
class func fileURLWithPath(_path: String) -> NSURLObjective-C
+ (NSURL *)fileURLWithPath:(NSString *)pathParameters
pathThe path that the NSURL object will represent.
pathshould be a valid system path. Ifpathbegins with a tilde, it must first be expanded withstringByExpandingTildeInPath. Ifpathis a relative path, it is treated as being relative to the current working directory.Return Value
An NSURL object initialized with
path, ornilifpathis zero-length.Discussion
This method assumes that
pathis a directory if it ends with a slash. Ifpathdoes not end with a slash, the method examines the file system to determine ifpathis a file or a directory. Ifpathexists in the file system and is a directory, the method appends a trailing slash. Ifpathdoes 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 returnedNSURLobject represents a file or directory.Availability
Available in OS X v10.0 and later.
See Also
-
init(fileURLWithPath:) - initFileURLWithPath:Designated InitializerInitializes a newly created NSURL referencing the local file or directory at
path.Declaration
Swift
init(fileURLWithPathpath: String)Objective-C
- (instancetype)initFileURLWithPath:(NSString *)pathParameters
pathThe path that the NSURL object will represent.
pathshould be a valid system path. Ifpathbegins with a tilde, it must first be expanded withstringByExpandingTildeInPath. Ifpathis a relative path, it is treated as being relative to the current working directory.Return Value
An NSURL object initialized with
path, ornilifpathis zero-length.Discussion
Invoking this method is equivalent to invoking
initWithScheme:host:path:with schemeNSURLFileScheme, anilhost, andpath.This method assumes that
pathis a directory if it ends with a slash. Ifpathdoes not end with a slash, the method examines the file system to determine ifpathis a file or a directory. Ifpathexists in the file system and is a directory, the method appends a trailing slash. Ifpathdoes 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 returnedNSURLobject represents a file or directory.Availability
Available in OS X v10.0 and later.
See Also
-
Initializes and returns a newly created NSURL object as a file URL with specified path components.
Declaration
Swift
class func fileURLWithPathComponents(_components: [String]) -> NSURL?Parameters
componentsAn array of path components.
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.
-
Returns a new URL made by resolving the alias file at
url.Declaration
Swift
convenience init(byResolvingAliasFileAtURLurl: NSURL, optionsoptions: NSURLBookmarkResolutionOptions) throwsObjective-C
+ (instancetype)URLByResolvingAliasFileAtURL:(NSURL *)urloptions:(NSURLBookmarkResolutionOptions)optionserror:(NSError * _Nullable *)errorParameters
urlThe URL pointing to the alias file.
optionsOptions taken into account when resolving the bookmark data. The
NSURLBookmarkResolutionWithSecurityScopeoption is not supported by this method.errorThe error that occurred while trying to resolve the provided URL.
Return Value
A new URL created by resolving the bookmark data derived from the provided alias file. If an error occurs, this method returns
nil.Discussion
Creates and initializes a new URL based on the alias file at
url. Use this method to resolve bookmark data that was saved usingwriteBookmarkData:toURL:options:error:and resolves that data in one step.If the
urlargument does not refer to an alias file as defined by theNSURLIsAliasFileKeyproperty, this method returns theurlargument.If the
urlargument is unreachable, this method returnsniland the optional error argument is populated.Availability
Available in OS X v10.10 and later.
-
Returns a new URL made by resolving bookmark data.
Declaration
Objective-C
+ (instancetype)URLByResolvingBookmarkData:(NSData *)bookmarkDataoptions:(NSURLBookmarkResolutionOptions)optionsrelativeToURL:(NSURL *)relativeURLbookmarkDataIsStale:(BOOL *)isStaleerror:(NSError * _Nullable *)errorParameters
bookmarkDataThe bookmark data the URL is derived from.
optionsOptions 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
ORoperators with any other options in this parameter) theNSURLBookmarkResolutionWithSecurityScopeoption.relativeURLThe 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.
App Sandbox does not restrict which URL values may be passed to this parameter.
isStaleOn return, if
YEStrue, 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.errorThe 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
NSURLBookmarkResolutionWithSecurityScopeoption. 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.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
startAccessingSecurityScopedResourcemethod (or its Core Foundation equivalent, theCFURLStartAccessingSecurityScopedResourcefunction) 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.
-
init(resolvingBookmarkData:options:relativeTo:bookmarkDataIsStale:) - initByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:Initializes a newly created NSURL that points to a location specified by resolving bookmark data.
Declaration
Swift
convenience init(byResolvingBookmarkDatabookmarkData: NSData, optionsoptions: NSURLBookmarkResolutionOptions, relativeToURLrelativeURL: NSURL?, bookmarkDataIsStaleisStale: UnsafeMutablePointer<ObjCBool>) throwsObjective-C
- (instancetype)initByResolvingBookmarkData:(NSData *)bookmarkDataoptions:(NSURLBookmarkResolutionOptions)optionsrelativeToURL:(NSURL *)relativeURLbookmarkDataIsStale:(BOOL *)isStaleerror:(NSError * _Nullable *)errorParameters
bookmarkDataThe bookmark data the URL is derived from.
optionsOptions taken into account when resolving the bookmark data.
relativeURLThe base URL that the bookmark data is relative to.
isStaleIf
YEStrue, the bookmark data is stale.errorThe error that occurred in the case that the URL cannot be created.
Return Value
An NSURL initialized by resolving
bookmarkData.Discussion
Availability
Available in OS X v10.6 and later.
-
fileURL(withFileSystemRepresentation:isDirectory:relativeTo:) + fileURLWithFileSystemRepresentation:isDirectory:relativeToURL:Returns a new URL object initialized with a C string representing a local file system path.
Declaration
Swift
class func fileURLWithFileSystemRepresentation(_path: UnsafePointer<Int8>, isDirectoryisDir: Bool, relativeToURLbaseURL: NSURL?) -> NSURLObjective-C
+ (NSURL *)fileURLWithFileSystemRepresentation:(const char *)pathisDirectory:(BOOL)isDirrelativeToURL:(NSURL *)baseURLParameters
pathA 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.
isDirYEStrueif the last path part is a directory, otherwiseNOfalse.baseURLThe base URL for the new URL object. This must be a file URL. If
pathis absolute, this URL is ignored.Return Value
Returns the new object or
nilif an error occurred.Discussion
The file system representation format is described in File System Programming Guide.
Availability
Available in OS X v10.9 and later.
-
Fills the provided buffer with a C string representing a local file system path.
Declaration
Swift
func getFileSystemRepresentation(_buffer: UnsafeMutablePointer<Int8>, maxLengthmaxBufferLength: Int) -> BoolObjective-C
- (BOOL)getFileSystemRepresentation:(char *)buffermaxLength:(NSUInteger)maxBufferLengthParameters
bufferA buffer large enough to hold the path. On return, contains a null-terminated C string in file system representation.
maxBufferLengthThe size of
bufferin bytes (typicallyMAXPATHLENorPATH_MAX).Return Value
Returns
YEStrueif the URL could be converted into a file system representation, otherwiseNOfalse.Discussion
The file system representation format is described in File Encodings and Fonts.
Availability
Available in OS X v10.9 and later.
-
init(fileURLWithFileSystemRepresentation:isDirectory:relativeTo:) - initFileURLWithFileSystemRepresentation:isDirectory:relativeToURL:Designated InitializerInitializes a URL object with a C string representing a local file system path.
Declaration
Swift
init(fileURLWithFileSystemRepresentationpath: UnsafePointer<Int8>, isDirectoryisDir: Bool, relativeToURLbaseURL: NSURL?)Objective-C
- (instancetype)initFileURLWithFileSystemRepresentation:(const char *)pathisDirectory:(BOOL)isDirrelativeToURL:(NSURL *)baseURLParameters
pathA 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.
isDirYEStrueif the last path part is a directory, otherwiseNOfalse.baseURLThe base URL for the new URL object. This must be a file URL. If
pathis absolute, this URL is ignored.Return Value
Returns the initialized object or
nilif 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.
-
Returns a Boolean value that indicates whether the receiver and a given object have identical URL strings and base URLs.
Declaration
Objective-C
- (BOOL)isEqual:(id)anObjectParameters
anObjectThe object to be compared to the receiver.
Return Value
YEStrueif the receiver andanObjectare equal, otherwiseNOfalse.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
baseURLandrelativeString.
-
Returns whether the resource pointed to by a file URL can be reached.
Declaration
Swift
func checkResourceIsReachableAndReturnError(_error: NSErrorPointer) -> BoolObjective-C
- (BOOL)checkResourceIsReachableAndReturnError:(NSError * _Nullable *)errorParameters
errorThe error that occurred when the resource could not be reached.
Return Value
YEStrueif the resource is reachable; otherwise,NOfalse.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.
If this method returns
NOfalse, the object pointer referenced byerroris populated with additional information.Availability
Available in OS X v10.6 and later.
-
Returns whether the URL is a file reference URL.
Return Value
YEStrueif the URL is a file reference URL; otherwise,NOfalse.Availability
Available in OS X v10.6 and later.
-
A boolean value that determines whether the receiver is a file URL. (read-only)
Declaration
Swift
var fileURL: Bool { get }Objective-C
@property(readonly, getter=isFileURL) BOOL fileURLDiscussion
The property’s value is
YEStrueif the receiver uses the file scheme,NOfalseotherwise. Both file path and file reference URLs are considered to be file URLs.If this property’s value is
YEStrue, then the receiver’spathproperty contains a suitable value for input intoNSFileManagerorNSPathUtilities.Availability
Available in OS X v10.0 and later.
-
- URLHandleUsingCache:(OS X v10.4)Returns a URL handle to service the receiver.
Declaration
Objective-C
- (NSURLHandle *)URLHandleUsingCache:(BOOL)shouldUseCacheParameters
shouldUseCacheWhether to use a cached URL handle. If
shouldUseCacheisYEStrue, the cache is searched for a URL handle that has serviced the receiver or another identical URL. IfshouldUseCacheisNOfalse, a newly instantiated handle is returned, even if an equivalent URL has been loaded.Return Value
A URL handle to service the receiver.
Discussion
Sophisticated clients use the URL handle directly for additional control.
Special Considerations
Use the
NSURLSessionorNSURLConnectionclasses for loading content from remote URLs.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
See Also
cachedHandleForURL:(NSURLHandle) -
- loadResourceDataNotifyingClient:usingCache:(OS X v10.4)Loads the receiver’s resource data in the background.
Declaration
Objective-C
- (void)loadResourceDataNotifyingClient:(id)clientusingCache:(BOOL)shouldUseCacheParameters
clientThe client of the loading operation.
clientis notified of the receiver’s progress loading the resource data using the NSURLClient informal protocol. The NSURLClient messages are delivered on the current thread and require the run loop to be running.shouldUseCacheWhether the URL should use cached resource data from an already loaded URL that refers to the same resource. If
YES, the cache is consulted when loading data. IfNO, the data is always loaded directly, without consulting the cache.Discussion
A given NSURL object can perform only one background load at a time.
Special Considerations
Use the
NSURLSessionorNSURLConnectionclasses for loading content from remote URLs.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
- resourceDataUsingCache:(OS X v10.4)Returns the receiver’s resource data, loading it if necessary.
Declaration
Objective-C
- (NSData *)resourceDataUsingCache:(BOOL)shouldUseCacheParameters
shouldUseCacheWhether the URL should use cached resource data from an already loaded URL that refers to the same resource. If
YES, the cache is consulted when loading data. IfNO, the data is always loaded directly, without consulting the cache.Return Value
The receiver's resource data.
Discussion
If the receiver has not already loaded its resource data, it will attempt to load it as a blocking operation.
In OS X v10.4, this method requests that the data be sent with gzip compression, however it does not automatically decompress the data if the server complies with this request. Data is automatically decompressed in OS X v10.5 and later.
Special Considerations
Use the
NSURLSessionorNSURLConnectionclasses for loading content from remote URLs.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
- setResourceData:(OS X v10.4)Attempts to set the resource data for the receiver.
Declaration
Objective-C
- (BOOL)setResourceData:(NSData *)dataParameters
dataThe data to set for the URL.
Return Value
Returns
YEStrueif successful,NOfalseotherwise.Discussion
In the case of a file URL, setting the data involves writing
datato the specified file.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
- propertyForKey:(OS X v10.4)Returns the specified property of the receiver’s resource.
Declaration
Objective-C
- (id)propertyForKey:(NSString *)propertyKeyParameters
propertyKeyThe key of the desired property.
Return Value
The value of the property of the receiver's resource for the provided key. Returns
nilif there is no such key.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
See Also
-
- setProperty:forKey:(OS X v10.4)Changes the specified property of the receiver’s resource.
Declaration
Objective-C
- (BOOL)setProperty:(id)propertyValueforKey:(NSString *)propertyKeyParameters
propertyValueThe new value of the property of the receiver's resource.
propertyKeyThe key of the desired property.
Return Value
Returns
YEStrueif the modification was successful,NOfalseotherwise.Availability
Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
absoluteString absoluteStringPropertyThe URL string for the receiver as an absolute URL. (read-only)
Declaration
Swift
var absoluteString: String { get }Objective-C
@property(readonly, copy) NSString *absoluteStringDiscussion
This property’s value is calculated 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.
-
absoluteURL absoluteURLPropertyAn absolute URL that refers to the same resource as the receiver. (read-only)
Declaration
Swift
@NSCopying var absoluteURL: NSURL { get }Objective-C
@property(readonly, copy) NSURL *absoluteURLDiscussion
If the URL is already absolute, this property contains a copy of the receiver. Resolution is performed per RFC 1808.
Availability
Available in OS X v10.0 and later.
-
The base URL. (read-only)
Declaration
Swift
@NSCopying var baseURL: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *baseURLDiscussion
This property contains the base URL. If the receiver is an absolute URL, this property contains
nil.Availability
Available in OS X v10.0 and later.
-
A C string containing the URL’s file system path. (read-only)
Declaration
Swift
var fileSystemRepresentation: UnsafePointer<Int8> { get }Objective-C
@property(readonly) const char *fileSystemRepresentationDiscussion
This returns a null-terminated C string in file system representation.
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.
-
The fragment identifier, conforming to RFC 1808. (read-only)
Declaration
Swift
var fragment: String? { get }Objective-C
@property(readonly, copy) NSString *fragmentDiscussion
This property contains the URL’s fragment. Any percent-encoded characters are not unescaped. If the receiver does not conform to RFC 1808, this property contains
nil. For example, in the URLhttp://www.example.com/index.html#jumpLocation, the fragment identifier isjumpLocation.Availability
Available in OS X v10.0 and later.
-
The host, conforming to RFC 1808. (read-only)
Discussion
This property contains the host, unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. If the receiver does not conform to RFC 1808, this property containsnil. For example, in the URLhttp://www.example.com/index.html, the host iswww.example.com.Availability
Available in OS X v10.0 and later.
-
lastPathComponent lastPathComponentPropertyThe last path component. (read-only)
Declaration
Swift
var lastPathComponent: String? { get }Objective-C
@property(readonly, copy) NSString *lastPathComponentDiscussion
This property contains the last path component, unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. For example, in the URLfile:///path/to/file, the last path component isfile.Availability
Available in OS X v10.6 and later.
-
parameterString parameterStringPropertyThe parameter string conforming to RFC 1808. (read-only)
Declaration
Swift
var parameterString: String? { get }Objective-C
@property(readonly, copy) NSString *parameterStringDiscussion
This property contains the parameter string. Any percent-encoded characters are not unescaped. If the receiver does not conform to RFC 1808, this property contains
nil. For example, in the URLfile:///path/to/file;foo, the parameter string isfoo.This property should not be confused with the
queryproperty, which also often contains a string of parameters.Availability
Available in OS X v10.0 and later.
-
The password conforming to RFC 1808. (read-only)
Declaration
Swift
var password: String? { get }Objective-C
@property(readonly, copy) NSString *passwordDiscussion
This property contains the password. Any percent-encoded characters are not unescaped. If the receiver does not conform to RFC 1808, it contains
nil. For example, in the URLhttp://username:password@www.example.com/index.html, the password ispassword.Availability
Available in OS X v10.0 and later.
-
The path, conforming to RFC 1808. (read-only)
Discussion
This property contains the path, unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. If the receiver does not conform to RFC 1808, this property containsnil.If the receiver contains a file or file reference URL (as determined with
isFileURL), this property’s value is suitable for input into methods ofNSFileManagerorNSPathUtilities. If the path has a trailing slash, it is stripped.If the receiver contains a file reference URL, this property’s value provides the current path for the referenced resource, which may be
nilif the resource no longer exists.If the
parameterStringproperty contains a non-nilvalue, the path may be incomplete. If the receiver contains an unencoded semicolon, the path property ends at the character before the semicolon. The remainder of the URL is provided in theparameterStringproperty.To obtain the complete path, if
parameterStringcontains a non-nilvalue, append a semicolon, followed by the parameter string.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.Availability
Available in OS X v10.0 and later.
-
pathComponents pathComponentsPropertyAn array containing the path components. (read-only)
Declaration
Swift
var pathComponents: [String]? { get }Objective-C
@property(readonly, copy) NSArray <NSString *> *pathComponentsDiscussion
This property contains an array containing the individual path components of the URL, each unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. For example, in the URLfile:///directory/directory%202/file, the path components array would be@[@"/", @"directory", @"directory 2", @"file"].Availability
Available in OS X v10.6 and later.
-
pathExtension pathExtensionPropertyThe path extension. (read-only)
Declaration
Swift
var pathExtension: String? { get }Objective-C
@property(readonly, copy) NSString *pathExtensionReturn Value
The path extension of the receiver, or
nilifpathisnil.Discussion
This property contains the path extension, unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. For example, in the URLfile:///path/to/file.txt, the path extension istxt.Availability
Available in OS X v10.6 and later.
-
The port, conforming to RFC 1808. (read-only)
Declaration
Swift
@NSCopying var port: NSNumber? { get }Objective-C
@property(readonly, copy) NSNumber *portDiscussion
This property contains the port number. If the receiver does not conform to RFC 1808, this property contains
nil. For example, in the URLhttp://www.example.com:8080/index.php, the port number is8080.Availability
Available in OS X v10.0 and later.
-
The query string, conforming to RFC 1808. (read-only)
Discussion
This property contains the query string. Any percent-encoded characters are not unescaped. If the receiver does not conform to RFC 1808, this property contains
nil. For example, in the URLhttp://www.example.com/index.php?key1=value1&key2=value2, the query string iskey1=value1&key2=value2.Availability
Available in OS X v10.0 and later.
-
relativePath relativePathPropertyThe relative path, conforming to RFC 1808. (read-only)
Declaration
Swift
var relativePath: String? { get }Objective-C
@property(readonly, copy) NSString *relativePathDiscussion
This property contains the relative path of the receiver’s URL without resolving against its base URL. Any percent-encoded characters are not unescaped. If the path has a trailing slash it is stripped. If the receiver is an absolute URL, this property contains the same value as
path. If the receiver does not conform to RFC 1808, it containsnil.Availability
Available in OS X v10.0 and later.
-
relativeString relativeStringPropertyA string representation of the relative portion of the URL. (read-only)
Declaration
Swift
var relativeString: String? { get }Objective-C
@property(readonly, copy) NSString *relativeStringDiscussion
This property contains a string representation of the relative portion of the URL. Any percent-encoded characters are not unescaped. If the receiver is an absolute URL this method returns the same value as
absoluteString.Availability
Available in OS X v10.0 and later.
-
resourceSpecifier resourceSpecifierPropertyThe resource specifier. (read-only)
Declaration
Swift
var resourceSpecifier: String { get }Objective-C
@property(readonly, copy) NSString *resourceSpecifierDiscussion
This property contains the resource specifier. Any percent-encoded characters are not unescaped. 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).Availability
Available in OS X v10.0 and later.
-
The scheme. (read-only)
Discussion
This property contains the scheme. Any percent-encoded characters are not unescaped. For example, in the URL
http://www.example.com/index.html, the scheme ishttp.The full URL is the concatenation of the scheme, a colon (
:), and the value ofresourceSpecifier.Availability
Available in OS X v10.0 and later.
-
standardized standardizedURLPropertyA copy of the URL with any instances of
".."or"."removed from its path. (read-only)Declaration
Swift
@NSCopying var standardizedURL: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *standardizedURLDiscussion
This property contains a new
NSURLobject, initialized using the receiver’s path with any instances of".."or"."removed. If the receiver does not conform to RFC 1808, this property containsnil.Availability
Available in OS X v10.0 and later.
-
The user name, conforming to RFC 1808. (read-only)
Discussion
This property contains the user name, unescaped using the
stringByReplacingPercentEscapesUsingEncoding:method. If the receiver’s URL does not conform to RFC 1808, this property returnsnil. For example, in the URLftp://username@www.example.com/, the user name isusername.Availability
Available in OS X v10.0 and later.
-
filePathURL filePathURLPropertyA file path URL that points to the same resource as the URL object. (read-only)
Declaration
Swift
@NSCopying var filePathURL: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *filePathURLDiscussion
If the receiver is a file reference URL, this property contains a copy of the URL converted to a file path URL. If the receiver’s URL is a file path URL, this property contains the original URL. If the original URL is not a file URL, or if the resource is not reachable or no longer exists, this property contains
nil.Availability
Available in OS X v10.6 and later.
-
Returns a new file reference URL that points to the same resource as the receiver.
Declaration
Swift
func fileReferenceURL() -> NSURL?Objective-C
- (NSURL *)fileReferenceURLReturn 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 property contains a copy of the URL converted into a file reference URL. If the original URL is a file reference URL, this property contains the original. If the original URL is not a file URL, this property contains
nil.File reference URLs cannot be created to file system objects which do not exist or are not reachable. This property contains
nilinstead.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.
-
Returns a new URL made by appending a path component to the original URL.
Declaration
Swift
func URLByAppendingPathComponent(_pathComponent: String) -> NSURLObjective-C
- (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponentParameters
pathComponentThe path component to add to the URL, in its original form (not URL encoded).
Return Value
A new URL with
pathComponentappended.Discussion
If the original URL does not end with a forward slash and
pathComponentdoes 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.If the receiver is a file URL and
pathComponentdoes not end with a trailing slash, this method may read file metadata to determine whether the resulting path is a directory. This is done synchronously, and may have significant performance costs if the receiver is a location on a network mounted filesystem. You can instead call theURLByAppendingPathComponent:isDirectory:method if you know whether the resulting path is a directory to avoid this file metadata operation.Availability
Available in OS X v10.6 and later.
-
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.
Declaration
Swift
func URLByAppendingPathComponent(_pathComponent: String, isDirectoryisDirectory: Bool) -> NSURLObjective-C
- (NSURL *)URLByAppendingPathComponent:(NSString *)pathComponentisDirectory:(BOOL)isDirectoryParameters
pathComponentThe path component to add to the URL.
isDirectoryIf
YEStrue, a trailing slash is appended afterpathComponent.Return Value
A new URL with
pathComponentappended.Discussion
If the original URL does not end with a forward slash and
pathComponentdoes 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.
-
Returns a new URL made by appending a path extension to the original URL.
Declaration
Swift
func URLByAppendingPathExtension(_pathExtension: String) -> NSURLObjective-C
- (NSURL *)URLByAppendingPathExtension:(NSString *)pathExtensionParameters
pathExtensionThe path extension to add to the URL.
Return Value
A new URL with
pathExtensionappended.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.
-
A URL created by taking the receiver and removing the last path component. (read-only)
Declaration
Swift
@NSCopying var URLByDeletingLastPathComponent: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *URLByDeletingLastPathComponentDiscussion
If the receiver’s URL represents the root path, this property contains a copy of the original URL. Otherwise, if the original URL has only one path component, this property contains the empty string.
Availability
Available in OS X v10.6 and later.
-
A URL created by taking the receiver and removing the path extension, if any. (read-only)
Declaration
Swift
@NSCopying var URLByDeletingPathExtension: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *URLByDeletingPathExtensionDiscussion
If the receiver represents the root path, this property contains a copy of the original URL. If the URL has multiple path extensions, only the last one is removed.
Availability
Available in OS X v10.6 and later.
-
A URL that points to the same resource as the receiver and includes no symbolic links. (read-only)
Declaration
Swift
@NSCopying var URLByResolvingSymlinksInPath: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *URLByResolvingSymlinksInPathDiscussion
If the receiver has no symbolic links, this property contains a copy of the original URL.
If some symbolic links cannot be resolved, this property contains those broken symbolic links.
If the name of the receiving path begins with
/private, this property strips off the/privatedesignator, provided the result is the name of an existing file.This property only works on URLs with the
file:path scheme. For all other URLs, it contains a copy of the receiver.Availability
Available in OS X v10.6 and later.
-
standardizingPath URLByStandardizingPathPropertyA URL that points to the same resource as the original URL using an absolute path. (read-only)
Declaration
Swift
@NSCopying var URLByStandardizingPath: NSURL? { get }Objective-C
@property(readonly, copy) NSURL *URLByStandardizingPathDiscussion
This property only works on URLs with the
file:path scheme. For all other URLs, it returns a copy of the original URL.Like
stringByStandardizingPath, this property 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 contained by this property may still have symbolic link components in it. Note also that this property only works with file paths (not, for example, string representations of URLs).
Availability
Available in OS X v10.6 and later.
-
Initializes and returns bookmark data derived from an alias file pointed to by a specified URL.
Declaration
Swift
class func bookmarkDataWithContentsOfURL(_bookmarkFileURL: NSURL) throws -> NSDataParameters
bookmarkFileURLThe URL that points to the alias file.
errorThe error that occurred in the case that the bookmark data cannot be derived.
Return Value
The bookmark data for the alias file.
Discussion
If
bookmarkFileURLpoints 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
nilif bookmark data cannot be created.Availability
Available in OS X v10.6 and later.
-
bookmarkData(options:includingResourceValuesForKeys:relativeTo:) - bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:Returns a bookmark for the URL, created with specified options and resource values.
Declaration
Swift
func bookmarkDataWithOptions(_options: NSURLBookmarkCreationOptions, includingResourceValuesForKeyskeys: [String]?, relativeToURLrelativeURL: NSURL?) throws -> NSDataObjective-C
- (NSData *)bookmarkDataWithOptions:(NSURLBookmarkCreationOptions)optionsincludingResourceValuesForKeys:(NSArray<NSString *> *)keysrelativeToURL:(NSURL *)relativeURLerror:(NSError * _Nullable *)errorParameters
optionsOptions taken into account when creating the bookmark for the URL. The possible flags (which can be combined with bitwise
ORoperations) are described in Bookmark Data Creation Options.To create a security-scoped bookmark to support App Sandbox, include the
NSURLBookmarkCreationWithSecurityScopeflag. 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
ORthis parameter’s value with both theNSURLBookmarkCreationWithSecurityScopeoption and theNSURLBookmarkCreationSecurityScopeAllowOnlyReadAccessoption.keysAn 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:
NSStringorCFStringNSDataorCFDataNSDateorCFDateNSNumberorCFNumberCFBooleanNSURLorCFURLkCFNullorNSNullCFUUID
In addition, the properties can contain the following collection classes:
NSArrayorCFArraycontaining only the above primitive typesNSDictionaryorCFDictionarywithNSStringorCFStringkeys, in which all values contain only the above primitive types
relativeURLThe 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.
App Sandbox does not restrict which URL values may be passed to this parameter.
errorThe 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 addition, be sure to understand the behavior of the
optionsandrelativeURLparameters.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.
-
Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data.
Declaration
Swift
class func resourceValuesForKeys(_keys: [String], fromBookmarkDatabookmarkData: NSData) -> [String : AnyObject]?Objective-C
+ (NSDictionary<NSString *,id> *)resourceValuesForKeys:(NSArray<NSString *> *)keysfromBookmarkData:(NSData *)bookmarkDataParameters
keysAn 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.bookmarkDataThe 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.
-
Creates an alias file on disk at a specified location with specified bookmark data.
Declaration
Swift
class func writeBookmarkData(_bookmarkData: NSData, toURLbookmarkFileURL: NSURL, optionsoptions: NSURLBookmarkFileCreationOptions) throwsObjective-C
+ (BOOL)writeBookmarkData:(NSData *)bookmarkDatatoURL:(NSURL *)bookmarkFileURLoptions:(NSURLBookmarkFileCreationOptions)optionserror:(NSError * _Nullable *)errorParameters
bookmarkDataThe bookmark data containing information for the alias file.
bookmarkFileURLThe desired location of the alias file.
optionsOptions taken into account when creating the alias file.
errorThe error that occurred in the case that the alias file cannot be created.
Return Value
YEStrueif the alias file is successfully created; otherwise,NOfalse.Discussion
This method will produce an error if
bookmarkDatawas not created with theNSURLBookmarkCreationSuitableForBookmarkFileoption.If
bookmarkFileURLpoints to a directory, the alias file will be created in that directory with its name derived from the information inbookmarkData. IfbookmarkFileURLpoints to a file, the alias file will be created with the location and name indicated bybookmarkFileURL, and its extension will be changed to.aliasif it is not already.Availability
Available in OS X v10.6 and later.
-
In an app that has adopted App Sandbox, makes the resource pointed to by a security-scoped URL available to the app.
Declaration
Swift
func startAccessingSecurityScopedResource() -> BoolObjective-C
- (BOOL)startAccessingSecurityScopedResourceReturn Value
YEStrueif the request to access the resource succeeded; otherwise,NOfalse.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, the
CFURLStartAccessingSecurityScopedResourcefunction) on the security-scoped URL.If this method returns
YEStrue, then you must relinquish access as soon as you finish using the resource. Call thestopAccessingSecurityScopedResourcemethod to relinquish access. When you call thestopAccessingSecurityScopedResourcemethod, you immediately lose access to the resource in question.Availability
Available in OS X v10.7 and later.
-
In an app that adopts App Sandbox, revokes access to the resource pointed to by a security-scoped URL.
Declaration
Swift
func stopAccessingSecurityScopedResource()Objective-C
- (void)stopAccessingSecurityScopedResourceDiscussion
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, the
CFURLStopAccessingSecurityScopedResourcefunction) on the URL to relinquish access. When you call this method, you immediately lose access to the resource in question.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.
-
Returns the value of the resource property for the specified key.
Declaration
Swift
func getResourceValue(_value: AutoreleasingUnsafeMutablePointer<AnyObject?>, forKeykey: String) throwsParameters
valueThe location where the value for the resource property identified by
keyshould be stored.keyThe name of one of the URL’s resource properties.
errorThe error that occurred if the resource value could not be retrieved. This parameter is optional. If you are not interested in receiving error information, you can pass
nil.Return Value
YEStrueifvalueis successfully populated; otherwise,NOfalse.Discussion
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
YEStrueand the value is populated withnil, 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
NOfalse, an error occurred. The object pointer referenced byerroris populated with additional information.Availability
Available in OS X v10.6 and later.
-
Returns the resource values for the properties identified by specified array of keys.
Declaration
Objective-C
- (NSDictionary<NSString *,id> *)resourceValuesForKeys:(NSArray<NSString *> *)keyserror:(NSError * _Nullable *)errorParameters
keysAn array of property keys for the desired resource properties.
errorThe error that occurred if one or more resource values could not be retrieved. This parameter is optional. If you are not interested in receiving error information, you can pass
nil.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 URL, and no errors occurred when determining those resource properties were not available.
If an error occurs, this method returns
niland populates the object pointer referenced byerrorwith additional information.Availability
Available in OS X v10.6 and later.
-
Sets the URL’s resource property for a given key to a given value.
Declaration
Parameters
valueThe value for the resource property defined by
key.keyThe name of one of the URL’s resource properties.
errorThe error that occurred if the resource value could not be set.
Return Value
YEStrueif the resource property namedkeyis successfully set tovalue; otherwise,NOfalse.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.
If an error occurs, this method returns
NOfalseand populates the object pointer referenced byerrorwith additional information.Availability
Available in OS X v10.6 and later.
-
Sets the URL’s resource properties for a given set of keys to a given set of values.
Declaration
Objective-C
- (BOOL)setResourceValues:(NSDictionary<NSString *,id> *)keyedValueserror:(NSError * _Nullable *)errorParameters
keyedValuesA dictionary of resource values to be set.
errorThe error that occurred if one or more resource values could not be set.
Return Value
YEStrueif all resource values inkeyedValuesare successfully set; otherwise,NOfalse.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
userInfodictionary in the returned error object contains akCFURLKeysOfUnsetValuesKeykey 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.
-
Removes all cached resource values and temporary resource values from the URL object.
Declaration
Swift
func removeAllCachedResourceValues()Objective-C
- (void)removeAllCachedResourceValuesAvailability
Available in OS X v10.9 and later.
-
Removes the cached resource value identified by a given key from the URL object.
Declaration
Swift
func removeCachedResourceValueForKey(_key: String)Objective-C
- (void)removeCachedResourceValueForKey:(NSString *)keyParameters
keyThe resource value key whose cached values you want 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.
-
Sets a temporary resource value on the URL object.
Declaration
Objective-C
- (void)setTemporaryResourceValue:(id)valueforKey:(NSString *)keyParameters
valueThe value to store.
keyThe 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:orresourceValuesForKeys:error:.Your app can remove a temporary resource value from the URL object by calling
removeCachedResourceValueForKey:orremoveAllCachedResourceValues(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.
-
Returns whether the promised item can be reached.
Declaration
Swift
func checkPromisedItemIsReachableAndReturnError(_error: NSErrorPointer) -> BoolObjective-C
- (BOOL)checkPromisedItemIsReachableAndReturnError:(NSError * _Nullable *)errorParameters
errorThe error that occurred when the promised item could not be reached.
Return Value
YEStrueif the promised item is reachable; otherwise,NOfalse.Discussion
This method behaves identically to
checkResourceIsReachableAndReturnError:, but works on promised items. A promised item is not guaranteed to have its contents in the file system until you use a file coordinator to perform a coordinated read on its URL, which causes the contents to be downloaded or otherwise generated. Promised item URLs are returned by various APIs, including:A metadata query using either the
NSMetadataQueryUbiquitousDataScopeorNSMetadataQueryUbiquitousDocumentsScopescopesThe contents of the directory returned by the file manager’s
URLForUbiquitousContainerIdentifier:The URL inside the accessor block of a coordinated read or write operation that used the
NSFileCoordinatorReadingImmediatelyAvailableMetadataOnly,NSFileCoordinatorWritingForDeleting,NSFileCoordinatorWritingForMoving, orNSFileCoordinatorWritingContentIndependentMetadataOnlyoptions
You must use this method instead of
checkResourceIsReachableAndReturnErrorfor any URLs returned by these methods.Availability
Available in OS X v10.10 and later.
-
Returns the value of the resource property for the specified key.
Declaration
Swift
func getPromisedItemResourceValue(_value: AutoreleasingUnsafeMutablePointer<AnyObject?>, forKeykey: String) throwsParameters
valueThe location where the value for the resource property identified by
keyshould be stored.keyThe name of one of the URL’s resource properties.
errorThe error that occurred in the case that the resource value cannot be retrieved.
Return Value
YEStrueifvalueis successfully populated; otherwise,NOfalse.Discussion
This method behaves identically to
getResourceValue:forKey:error:, but works on promised items. A promised item is not guaranteed to have its contents in the file system until you use a file coordinator to perform a coordinated read on its URL, which causes the contents to be downloaded or otherwise generated. Promised item URLs are returned by various APIs, including:A metadata query using either the
NSMetadataQueryUbiquitousDataScopeorNSMetadataQueryUbiquitousDocumentsScopescopesThe contents of the directory returned by the file manager’s
URLForUbiquitousContainerIdentifier:The URL inside the accessor block of a coordinated read or write operation that used the
NSFileCoordinatorReadingImmediatelyAvailableMetadataOnly,NSFileCoordinatorWritingForDeleting,NSFileCoordinatorWritingForMoving, orNSFileCoordinatorWritingContentIndependentMetadataOnlyoptions
You must use this method instead of
getResourceValue:forKey:error:for any URLs returned by these methods.This method works for any resource value that is not tied to the item’s contents. Some keys, like
NSURLContentAccessDateKeyorNSURLGenerationIdentifierKey, do not return valid values. If you use one of these keys, the method returnsYEStrue, but the value returnsnil.Availability
Available in OS X v10.10 and later.
-
Returns the resource values for the properties identified by specified array of keys.
Declaration
Objective-C
- (NSDictionary<NSString *,id> *)promisedItemResourceValuesForKeys:(NSArray<NSString *> *)keyserror:(NSError * _Nullable *)errorParameters
keysAn array of names of URL resource properties.
errorThe 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 behaves identically to
resourceValuesForKeys:error:, but works on promised items. A promised item is not guaranteed to have its contents in the file system until you use a file coordinator to perform a coordinated read on its URL, which causes the contents to be downloaded or otherwise generated. Promised item URLs are returned by various APIs, including:A metadata query using either the
NSMetadataQueryUbiquitousDataScopeorNSMetadataQueryUbiquitousDocumentsScopescopesThe contents of the directory returned by the file manager’s
URLForUbiquitousContainerIdentifier:The URL inside the accessor block of a coordinated read or write operation that used the
NSFileCoordinatorReadingImmediatelyAvailableMetadataOnly,NSFileCoordinatorWritingForDeleting,NSFileCoordinatorWritingForMoving, orNSFileCoordinatorWritingContentIndependentMetadataOnlyoptions
You must use this method instead of
resourceValuesForKeys:error:for any URLs returned by these methods.This method works for any resource value that is not tied to the item’s contents. Some keys, like
NSURLContentAccessDateKeyorNSURLGenerationIdentifierKey, do not return valid values. If you use one of these keys, the method returnsYEStrue, but the value returnsnil.Availability
Available in OS X v10.10 and later.
-
Reads an NSURL object off of the specified pasteboard.
Declaration
Swift
init?(fromPasteboardpasteBoard: NSPasteboard)Objective-C
+ (NSURL *)URLFromPasteboard:(NSPasteboard *)pasteBoardParameters
pasteBoardThe target pasteboard.
Return Value
a
NSURLobject, ornilif the pasteboard does not containNSURLPboardTypedata.Import Statement
Objective-C
@import AppKit;Swift
import AppKitAvailability
Available in OS X v10.0 and later.
See Also
-
Writes the URL to the specified pasteboard.
Declaration
Swift
func writeToPasteboard(_pasteBoard: NSPasteboard)Objective-C
- (void)writeToPasteboard:(NSPasteboard *)pasteboardParameters
pasteboardThe target pasteboard.
Discussion
You must declare an
NSURLPboardTypedata type for the pasteboard before invoking this method. Otherwise, the method returns without doing anything.Import Statement
Objective-C
@import AppKit;Swift
import AppKitAvailability
Available in OS X v10.0 and later.
See Also
+ URLFromPasteboard:declareTypes:owner:(NSPasteboard)
Data Types
-
Options used when creating file bookmark data
Declaration
Swift
typealias NSURLBookmarkFileCreationOptions = IntObjective-C
typedef NSUInteger NSURLBookmarkFileCreationOptions;Discussion
See Bookmark Data Creation Options for more information.
Import Statement
Objective-C
@import Foundation;Swift
import FoundationAvailability
Available in OS X v10.6 and later.
-
These schemes are the ones that
NSURLcan parse.Constants
-
NSURLFileSchemeNSURLFileSchemeIdentifies a URL that points to a file on a mounted volume.
Available in OS X v10.0 and later.
Discussion
For more information, see initWithScheme:host:path:.
-
-
Keys that apply to file system URLs.
Declaration
Swift
let NSURLAddedToDirectoryDateKey: String let NSURLAttributeModificationDateKey: String let NSURLContentAccessDateKey: String let NSURLContentModificationDateKey: String let NSURLCreationDateKey: String let NSURLCustomIconKey: String let NSURLDocumentIdentifierKey: String let NSURLEffectiveIconKey: String let NSURLFileResourceIdentifierKey: String let NSURLFileResourceTypeKey: String let NSURLFileSecurityKey: String let NSURLGenerationIdentifierKey: String let NSURLHasHiddenExtensionKey: String let NSURLIsDirectoryKey: String let NSURLIsExcludedFromBackupKey: String let NSURLIsExecutableKey: String let NSURLIsHiddenKey: String let NSURLIsMountTriggerKey: String let NSURLIsPackageKey: String let NSURLIsReadableKey: String let NSURLIsRegularFileKey: String let NSURLIsSymbolicLinkKey: String let NSURLIsSystemImmutableKey: String let NSURLIsUserImmutableKey: String let NSURLIsVolumeKey: String let NSURLIsWritableKey: String let NSURLLabelColorKey: String let NSURLLabelNumberKey: String let NSURLLinkCountKey: String let NSURLLocalizedLabelKey: String let NSURLLocalizedNameKey: String let NSURLLocalizedTypeDescriptionKey: String let NSURLNameKey: String let NSURLParentDirectoryURLKey: String let NSURLPathKey: String let NSURLPreferredIOBlockSizeKey: String let NSURLTagNamesKey: String let NSURLThumbnailDictionaryKey: String let NSURLThumbnailKey: String let NSURLTypeIdentifierKey: String let NSURLVolumeIdentifierKey: String let NSURLVolumeURLKey: StringObjective-C
NSString * const NSURLAddedToDirectoryDateKey NSString * const NSURLAttributeModificationDateKey; NSString * const NSURLContentAccessDateKey; NSString * const NSURLContentModificationDateKey; NSString * const NSURLCreationDateKey; NSString * const NSURLCustomIconKey; NSString * const NSURLDocumentIdentifierKey NSString * const NSURLEffectiveIconKey; NSString * const NSURLFileResourceIdentifierKey; NSString * const NSURLFileResourceTypeKey; NSString * const NSURLFileSecurityKey; NSString * const NSURLGenerationIdentifierKey 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 NSURLThumbnailDictionaryKey NSString * const NSURLThumbnailKey NSString * const NSURLTypeIdentifierKey; NSString * const NSURLVolumeIdentifierKey; NSString * const NSURLVolumeURLKey;Constants
-
NSURLAddedToDirectoryDateKeyNSURLAddedToDirectoryDateKeyThe time at which the resource’s was created or renamed into or within its parent directory, returned as an
NSDate. Inconsistent behavior may be observed when this attribute is requested on hard-linked items. This property is not supported by all volumes. (read-only)Available in OS X v10.10 and iOS 8.0.
-
NSURLAttributeModificationDateKeyNSURLAttributeModificationDateKeyThe time at which the resource’s attributes were most recently modified, returned as an
NSDateobject if the volume supports attribute modification dates, ornilif attribute modification dates are unsupported (read-write).Available in OS X v10.6 and later.
-
NSURLContentAccessDateKeyNSURLContentAccessDateKeyThe time at which the resource was most recently accessed, returned as an
NSDateobject if the volume supports access dates, ornilif access dates are unsupported (read-only).Available in OS X v10.6 and later.
-
NSURLContentModificationDateKeyNSURLContentModificationDateKeyThe time at which the resource was most recently modified, returned as an
NSDateobject if the volume supports modification dates, ornilif modification dates are unsupported (read-write).Available in OS X v10.6 and later.
-
NSURLCreationDateKeyNSURLCreationDateKeyThe resource’s creation date, returned as an
NSDateobject if the volume supports creation dates, ornilif creation dates are unsupported (read-write).Available in OS X v10.6 and later.
-
NSURLCustomIconKeyNSURLCustomIconKeyThe icon stored with the resource, returned as an
NSImageobject, ornilif the resource has no custom icon.Available in OS X v10.6 and later.
-
NSURLDocumentIdentifierKeyNSURLDocumentIdentifierKeyThe document identifier returned as an
NSNumber(read-only).The document identifier is a value assigned by the kernel to a file or directory. This value is used to identify the document regardless of where it is moved on a volume. The identifier persists across system restarts. It is not transferred when the file is copied, but it survives "safe save” operations. For example, it remains on the path to which it was assigned, even after calling the
replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error:method. Document identifiers are only unique within a single volume. This property is not supported by all volumes.Available in OS X v10.10 and iOS 8.0.
-
NSURLEffectiveIconKeyNSURLEffectiveIconKeyThe resource’s normal icon, returned as an
NSImageobject (read-only).Available in OS X v10.6 and later.
-
NSURLFileResourceIdentifierKeyNSURLFileResourceIdentifierKeyThe 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.
-
NSURLFileResourceTypeKeyNSURLFileResourceTypeKeyThe resource’s object type, returned as an
NSStringobject (read-only). See File Resource Types for possible values.Available in OS X v10.7 and later.
-
NSURLFileSecurityKeyNSURLFileSecurityKeyThe resource’s security information, returned as an
NSFileSecurityobject (read-write).Available in OS X v10.7 and later.
-
NSURLGenerationIdentifierKeyNSURLGenerationIdentifierKeyAn opaque generation identifier, returned as an
id <NSCopying, NSCoding, NSObject>(read-only)The generation identifier can be compared using isEqual: to determine if the data in a document has been modified. For URLs which refer to the same file inode, the generation identifier changes when the data in the file's data fork is changed. Changes to extended attributes or other file system metadata do not change the identifier. For URLs which refer to the same directory inode, the generation identifier changes when direct children of that directory are added, removed or renamed. Changes to the data of the direct children of that directory does not change the generation identifier. The identifier persists across system restarts. It is tied to a specific document on a specific volume and is not transferred when the document is copied to another volume. This property is not supported by all volumes.
Available in OS X v10.10 and iOS 8.0.
-
NSURLHasHiddenExtensionKeyNSURLHasHiddenExtensionKeyKey for determining whether the resource’s extension is normally removed from its localized name, returned as a Boolean
NSNumberobject (read-write).Available in OS X v10.6 and later.
-
NSURLIsDirectoryKeyNSURLIsDirectoryKeyKey for determining whether the resource is a directory, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLIsExcludedFromBackupKeyNSURLIsExcludedFromBackupKeyKey for determining whether the resource is excluded from all backups of app data, returned as a Boolean
NSNumberobject (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.
-
NSURLIsExecutableKeyNSURLIsExecutableKeyKey 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
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLIsHiddenKeyNSURLIsHiddenKeyKey for determining whether the resource is normally not displayed to users, returned as a Boolean
NSNumberobject (read-write).Available in OS X v10.6 and later.
-
NSURLIsMountTriggerKeyNSURLIsMountTriggerKeyKey for determining whether the URL is a file system trigger directory, returned as a Boolean
NSNumberobject (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.
-
NSURLIsPackageKeyNSURLIsPackageKeyKey for determining whether the resource is a file package, returned as a Boolean
NSNumberobject (read-write in OS X v10.8 and later, read-only in previous versions). Atruevalue 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
falsehas no effect.Available in OS X v10.6 and later.
-
NSURLIsReadableKeyNSURLIsReadableKeyKey for determining whether the current process (as determined by the EUID) can read the resource, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLIsRegularFileKeyNSURLIsRegularFileKeyKey for determining whether the resource is a regular file, as opposed to a directory or a symbolic link. Returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLIsSymbolicLinkKeyNSURLIsSymbolicLinkKeyKey for determining whether the resource is a symbolic link, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLIsSystemImmutableKeyNSURLIsSystemImmutableKeyKey for determining whether the resource's system immutable bit is set, returned as a Boolean
NSNumberobject (read-write).Available in OS X v10.6 and later.
-
NSURLIsUserImmutableKeyNSURLIsUserImmutableKeyKey for determining whether the resource's user immutable bit is set, returned as a Boolean
NSNumberobject (read-write).Available in OS X v10.6 and later.
-
NSURLIsVolumeKeyNSURLIsVolumeKeyKey for determining whether the resource is the root directory of a volume, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLIsWritableKeyNSURLIsWritableKeyKey for determining whether the current process (as determined by the EUID) can write to the resource, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLLabelColorKeyNSURLLabelColorKeyThe resource’s label color, returned as an
NSColorobject, ornilif the resource has no label color (read-only).Available in OS X v10.6 and later.
-
NSURLLabelNumberKeyNSURLLabelNumberKeyThe resource’s label number, returned as an
NSNumberobject (read-write).Available in OS X v10.6 and later.
-
NSURLLinkCountKeyNSURLLinkCountKeyThe number of hard links to the resource, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLLocalizedLabelKeyNSURLLocalizedLabelKeyThe resource’s localized label text, returned as an
NSStringobject, ornilif the resource has no localized label text (read-only).Available in OS X v10.6 and later.
-
NSURLLocalizedNameKeyNSURLLocalizedNameKeyThe resource’s localized or extension-hidden name, returned as an
NSStringobject (read-only).Available in OS X v10.6 and later.
-
NSURLLocalizedTypeDescriptionKeyNSURLLocalizedTypeDescriptionKeyThe resource’s localized type description, returned as an
NSStringobject (read-only).Available in OS X v10.6 and later.
-
NSURLNameKeyNSURLNameKeyThe resource’s name in the file system, returned as an
NSStringobject (read-write).Available in OS X v10.6 and later.
-
NSURLParentDirectoryURLKeyNSURLParentDirectoryURLKeyThe parent directory of the resource, returned as an
NSURLobject, ornilif the resource is the root directory of its volume (read-only).Available in OS X v10.6 and later.
-
NSURLPathKeyNSURLPathKeyThe file system path for the URL, returned as an
NSStringobject (read-only).Available in OS X v10.8 and later.
-
NSURLPreferredIOBlockSizeKeyNSURLPreferredIOBlockSizeKeyThe optimal block size to use when reading or writing this file's data, returned as an
NSNumberobject, ornilif the preferred size is not available (read-only).Available in OS X v10.7 and later.
-
NSURLTagNamesKeyNSURLTagNamesKeyThe names of tags attached to the resource, returned as an array of
NSStringvalues (read-write).Available in OS X v10.9 and later.
-
NSURLThumbnailDictionaryKeyNSURLThumbnailDictionaryKeyA dictionary of NSImage/UIImage objects keyed by size (read-write). See Thumbnail Property Keys for a list of possible keys.
Available in OS X v10.10 and iOS 8.0.
-
NSURLThumbnailKeyNSURLThumbnailKeyAll thumbnails as a single NSImage (read-write).
Available in OS X v10.10.
-
NSURLTypeIdentifierKeyNSURLTypeIdentifierKeyThe resource’s uniform type identifier (UTI), returned as an
NSStringobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeIdentifierKeyNSURLVolumeIdentifierKeyThe 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.
-
NSURLVolumeURLKeyNSURLVolumeURLKeyThe root directory of the resource’s volume, returned as an
NSURLobject (read-only).Available in OS X v10.6 and later.
Discussion
To request information using one of these keys, pass it to the
forKey:parameter of thegetResourceValue:forKey:error:instance method. -
-
Possible values for the
NSURLFileResourceTypeKeykey.Declaration
Swift
let NSURLFileResourceTypeNamedPipe: String let NSURLFileResourceTypeCharacterSpecial: String let NSURLFileResourceTypeDirectory: String let NSURLFileResourceTypeBlockSpecial: String let NSURLFileResourceTypeRegular: String let NSURLFileResourceTypeSymbolicLink: String let NSURLFileResourceTypeSocket: String let NSURLFileResourceTypeUnknown: StringObjective-C
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
-
NSURLFileResourceTypeNamedPipeNSURLFileResourceTypeNamedPipeThe resource is a named pipe.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeCharacterSpecialNSURLFileResourceTypeCharacterSpecialThe resource is a character special file.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeDirectoryNSURLFileResourceTypeDirectoryThe resource is a directory.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeBlockSpecialNSURLFileResourceTypeBlockSpecialThe resource is a block special file.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeRegularNSURLFileResourceTypeRegularThe resource is a regular file.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeSymbolicLinkNSURLFileResourceTypeSymbolicLinkThe resource is a symbolic link.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeSocketNSURLFileResourceTypeSocketThe resource is a socket.
Available in OS X v10.7 and later.
-
NSURLFileResourceTypeUnknownNSURLFileResourceTypeUnknownThe resource’s type is unknown.
Available in OS X v10.7 and later.
-
-
Possible keys for the
NSURLThumbnailDictionaryKeydictionary.Declaration
Swift
let NSThumbnail1024x1024SizeKey: StringObjective-C
NSString * const NSThumbnail1024x1024SizeKeyConstants
-
Keys that apply to properties of files.
Declaration
Swift
let NSURLFileSizeKey: String let NSURLFileAllocatedSizeKey: String let NSURLTotalFileSizeKey: String let NSURLTotalFileAllocatedSizeKey: String let NSURLIsAliasFileKey: StringObjective-C
NSString * const NSURLFileSizeKey; NSString * const NSURLFileAllocatedSizeKey; NSString * const NSURLIsAliasFileKey; NSString * const NSURLTotalFileAllocatedSizeKey; NSString * const NSURLTotalFileSizeKey;Constants
-
NSURLFileSizeKeyNSURLFileSizeKeyKey for the file’s size in bytes, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLFileAllocatedSizeKeyNSURLFileAllocatedSizeKeyKey for the total size allocated on disk for the file, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLTotalFileSizeKeyNSURLTotalFileSizeKeyKey for the total displayable size of the file in bytes, returned as an
NSNumberobject (read-only). This includes the size of any file metadata.Available in OS X v10.7 and later.
-
NSURLTotalFileAllocatedSizeKeyNSURLTotalFileAllocatedSizeKeyKey for the total allocated size of the file in bytes, returned as an
NSNumberobject (read-only). This includes the size of any file metadata.Available in OS X v10.7 and later.
-
NSURLIsAliasFileKeyNSURLIsAliasFileKeyKey for determining whether the file is an alias, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
-
Keys that apply to volumes.
Declaration
Swift
let NSURLVolumeLocalizedFormatDescriptionKey: String let NSURLVolumeTotalCapacityKey: String let NSURLVolumeAvailableCapacityKey: String let NSURLVolumeResourceCountKey: String let NSURLVolumeSupportsPersistentIDsKey: String let NSURLVolumeSupportsSymbolicLinksKey: String let NSURLVolumeSupportsHardLinksKey: String let NSURLVolumeSupportsJournalingKey: String let NSURLVolumeIsJournalingKey: String let NSURLVolumeSupportsSparseFilesKey: String let NSURLVolumeSupportsZeroRunsKey: String let NSURLVolumeSupportsCaseSensitiveNamesKey: String let NSURLVolumeSupportsCasePreservedNamesKey: String let NSURLVolumeSupportsRootDirectoryDatesKey: String let NSURLVolumeSupportsVolumeSizesKey: String let NSURLVolumeSupportsRenamingKey: String let NSURLVolumeSupportsAdvisoryFileLockingKey: String let NSURLVolumeSupportsExtendedSecurityKey: String let NSURLVolumeIsBrowsableKey: String let NSURLVolumeMaximumFileSizeKey: String let NSURLVolumeIsEjectableKey: String let NSURLVolumeIsRemovableKey: String let NSURLVolumeIsInternalKey: String let NSURLVolumeIsAutomountedKey: String let NSURLVolumeIsLocalKey: String let NSURLVolumeIsReadOnlyKey: String let NSURLVolumeCreationDateKey: String let NSURLVolumeURLForRemountingKey: String let NSURLVolumeUUIDStringKey: String let NSURLVolumeNameKey: String let NSURLVolumeLocalizedNameKey: StringObjective-C
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
-
NSURLVolumeLocalizedFormatDescriptionKeyNSURLVolumeLocalizedFormatDescriptionKeyKey for the volume’s descriptive format name, returned as an
NSStringobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeTotalCapacityKeyNSURLVolumeTotalCapacityKeyKey for the volume’s capacity in bytes, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeAvailableCapacityKeyNSURLVolumeAvailableCapacityKeyKey for the volume’s available capacity in bytes, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeResourceCountKeyNSURLVolumeResourceCountKeyKey for the total number of resources on the volume, returned as an
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsPersistentIDsKeyNSURLVolumeSupportsPersistentIDsKeyKey for determining whether the volume supports persistent IDs, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsSymbolicLinksKeyNSURLVolumeSupportsSymbolicLinksKeyKey for determining whether the volume supports symbolic links, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsHardLinksKeyNSURLVolumeSupportsHardLinksKeyKey for determining whether the volume supports hard links, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsJournalingKeyNSURLVolumeSupportsJournalingKeyKey for determining whether the volume supports journaling, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeIsJournalingKeyNSURLVolumeIsJournalingKeyKey for determining whether the volume is currently journaling, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsSparseFilesKeyNSURLVolumeSupportsSparseFilesKeyKey for determining whether the volume supports sparse files, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsZeroRunsKeyNSURLVolumeSupportsZeroRunsKeyKey for determining whether the volume supports zero runs, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsCaseSensitiveNamesKeyNSURLVolumeSupportsCaseSensitiveNamesKeyKey for determining whether the volume supports case-sensitive names, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsCasePreservedNamesKeyNSURLVolumeSupportsCasePreservedNamesKeyKey for determining whether the volume supports case-preserved names, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.6 and later.
-
NSURLVolumeSupportsRootDirectoryDatesKeyNSURLVolumeSupportsRootDirectoryDatesKeyKey for determining whether the volume supports reliable storage of times for the root directory, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeSupportsVolumeSizesKeyNSURLVolumeSupportsVolumeSizesKeyKey for determining whether the volume supports returning volume size information, returned as a Boolean
NSNumberobject (read-only). Iftrue, volume size information is available as values of theNSURLVolumeTotalCapacityKeyandNSURLVolumeAvailableCapacityKeykeys.Available in OS X v10.7 and later.
-
NSURLVolumeSupportsRenamingKeyNSURLVolumeSupportsRenamingKeyKey for determining whether the volume can be renamed, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeSupportsAdvisoryFileLockingKeyNSURLVolumeSupportsAdvisoryFileLockingKeyKey for determining whether the volume implements whole-file advisory locks in the style of
flock, along with theO_EXLOCKandO_SHLOCKflags of theopenfunction, returned as a BooleanNSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeSupportsExtendedSecurityKeyNSURLVolumeSupportsExtendedSecurityKeyKey for determining whether the volume supports extended security (access control lists), returned as a Boolean
NSNumberobject (read-only) (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsBrowsableKeyNSURLVolumeIsBrowsableKeyKey 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
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeMaximumFileSizeKeyNSURLVolumeMaximumFileSizeKeyKey for the largest file size supported by the volume in bytes, returned as a Boolean
NSNumberobject, ornilif it cannot be determined (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsEjectableKeyNSURLVolumeIsEjectableKeyKey for determining whether the volume is ejectable from the drive mechanism under software control, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsRemovableKeyNSURLVolumeIsRemovableKeyKey for determining whether the volume is removable from the drive mechanism, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsInternalKeyNSURLVolumeIsInternalKeyKey for determining whether the volume is connected to an internal bus, returned as a Boolean
NSNumberobject, ornilif it cannot be determined (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsAutomountedKeyNSURLVolumeIsAutomountedKeyKey for determining whether the volume is automounted, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsLocalKeyNSURLVolumeIsLocalKeyKey for determining whether the volume is stored on a local device, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeIsReadOnlyKeyNSURLVolumeIsReadOnlyKeyKey for determining whether the volume is read-only, returned as a Boolean
NSNumberobject (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeCreationDateKeyNSURLVolumeCreationDateKeyKey for the volume’s creation date, returned as an
NSDateobject, orNULLif it cannot be determined (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeURLForRemountingKeyNSURLVolumeURLForRemountingKeyKey for the URL needed to remount the network volume, returned as an
NSURLobject, ornilif a URL is not available (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeUUIDStringKeyNSURLVolumeUUIDStringKeyKey for the volume’s persistent UUID, returned as an
NSStringobject, ornilif a persistent UUID is not available (read-only).Available in OS X v10.7 and later.
-
NSURLVolumeNameKeyNSURLVolumeNameKeyThe name of the volume, returned as an
NSStringobject (read-write). Settable only ifNSURLVolumeSupportsRenamingKeyisYEStrue.Available in OS X v10.7 and later.
-
NSURLVolumeLocalizedNameKeyNSURLVolumeLocalizedNameKeyThe name of the volume as it should be displayed in the user interface, returned as an
NSStringobject (read-only).Available in OS X v10.7 and later.
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.
-
-
Options used when creating bookmark data.
Declaration
Swift
struct NSURLBookmarkCreationOptions : OptionSetType { init(rawValuerawValue: UInt) static var PreferFileIDResolution: NSURLBookmarkCreationOptions { get } static var MinimalBookmark: NSURLBookmarkCreationOptions { get } static var SuitableForBookmarkFile: NSURLBookmarkCreationOptions { get } static var WithSecurityScope: NSURLBookmarkCreationOptions { get } static var SecurityScopeAllowOnlyReadAccess: NSURLBookmarkCreationOptions { get } }Objective-C
enum { NSURLBookmarkCreationMinimalBookmark = ( 1UL << 9 ), NSURLBookmarkCreationSuitableForBookmarkFile = ( 1UL << 10 ), NSURLBookmarkCreationWithSecurityScope = ( 1UL << 11 ), NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess = ( 1UL << 12 ), // Deprecated NSURLBookmarkCreationPreferFileIDResolution = ( 1UL << 8 ), }; typedef NSUInteger NSURLBookmarkCreationOptions;Constants
-
NSURLBookmarkCreationPreferFileIDResolutionSpecifies 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.
This option does nothing and has no effect on bookmark resolution.
Available in OS X v10.6 and later.
Deprecated in OS X v10.9.
-
MinimalBookmarkNSURLBookmarkCreationMinimalBookmarkSpecifies 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.
-
SuitableForBookmarkFileNSURLBookmarkCreationSuitableForBookmarkFileSpecifies that the bookmark data should include properties required to create Finder alias files.
Available in OS X v10.6 and later.
-
WithSecurityScopeNSURLBookmarkCreationWithSecurityScopeSpecifies 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
NSURLBookmarkCreationMinimalBookmarkorNSURLBookmarkCreationSuitableForBookmarkFile.Available in OS X v10.7 and later.
-
SecurityScopeAllowOnlyReadAccessNSURLBookmarkCreationSecurityScopeAllowOnlyReadAccessWhen combined with the
NSURLBookmarkCreationWithSecurityScopeoption, 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.
Discussion
When creating a bookmark, use bitwise
ORoperators to combine the options you want to specify, and provide them to theoptionsparameter of thebookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error:method.Import Statement
Objective-C
@import Foundation;Swift
import FoundationAvailability
Available in OS X v10.6 and later.
-
-
Options used when resolving bookmark data.
Declaration
Swift
struct NSURLBookmarkResolutionOptions : OptionSetType { init(rawValuerawValue: UInt) static var WithoutUI: NSURLBookmarkResolutionOptions { get } static var WithoutMounting: NSURLBookmarkResolutionOptions { get } static var WithSecurityScope: NSURLBookmarkResolutionOptions { get } }Objective-C
enum { NSURLBookmarkResolutionWithoutUI = ( 1UL << 8 ), NSURLBookmarkResolutionWithoutMounting = ( 1UL << 9 ), NSURLBookmarkResolutionWithSecurityScope = ( 1UL << 10 ) }; typedef NSUInteger NSURLBookmarkResolutionOptions;Constants
-
WithoutUINSURLBookmarkResolutionWithoutUISpecifies that no UI feedback should accompany resolution of the bookmark data.
Available in OS X v10.6 and later.
-
WithoutMountingNSURLBookmarkResolutionWithoutMountingSpecifies that no volume should be mounted during resolution of the bookmark data.
Available in OS X v10.6 and later.
-
WithSecurityScopeNSURLBookmarkResolutionWithSecurityScopeSpecifies 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.
Discussion
When resolving a bookmark, use bitwise
ORoperators to combine the options you want to specify, and provide them to theoptionsparameter of theURLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error:method.Import Statement
Objective-C
@import Foundation;Swift
import FoundationAvailability
Available in OS X v10.6 and later.
-
-
FTP-specific property keys.
Declaration
Objective-C
NSString *NSFTPPropertyUserLoginKey; NSString *NSFTPPropertyUserPasswordKey; NSString *NSFTPPropertyActiveTransferModeKey; NSString *NSFTPPropertyFileOffsetKey; NSString *NSFTPPropertyFTPProxy;Constants
-
NSFTPPropertyUserLoginKeyKey for the user login, returned as an
NSStringobject.The default value for this key is “anonymous”.
Available in OS X v10.2 and later.
Deprecated in OS X v10.4.
-
NSFTPPropertyUserPasswordKeyKey for the user password, returned as an
NSStringobject.The default value for this key is "
NSURLHandle@apple.com".Available in OS X v10.2 and later.
Deprecated in OS X v10.4.
-
NSFTPPropertyActiveTransferModeKeyKey for retrieving whether in active transfer mode, returned as a boolean wrapped in an
NSNumberobject.The default value for this key is
NOfalse(passive mode).Available in OS X v10.2 and later.
Deprecated in OS X v10.4.
-
NSFTPPropertyFileOffsetKeyKey for retrieving the file offset, returned as an
NSNumberobject. The default value for this key is zero.Available in OS X v10.2 and later.
Deprecated in OS X v10.4.
-
NSFTPPropertyFTPProxyNSDictionarycontaining proxy information to use in place of proxy identified inSystemConfiguration.framework.To avoid any proxy use, pass an empty dictionary.
Available in OS X v10.3 and later.
Deprecated in OS X v10.4.
Discussion
Pass these keys to
NSURLHandle’sgetResourceValue:forKey:error:orresourceValuesForKeys: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. -
-
HTTP-specific property keys.
Declaration
Objective-C
NSString * const NSHTTPPropertyStatusCodeKey; NSString * const NSHTTPPropertyStatusReasonKey; NSString * const NSHTTPPropertyServerHTTPVersionKey; NSString * const NSHTTPPropertyRedirectionHeadersKey; NSString * const NSHTTPPropertyErrorPageDataKey; NSString * const NSHTTPPropertyHTTPProxy;Constants
-
NSHTTPPropertyStatusCodeKeyKey for the status code, returned as an integer wrapped in an
NSNumberobject.Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
NSHTTPPropertyStatusReasonKeyKey for the remainder of the HTTP status line following the status code, returned as an
NSStringobject.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.
-
NSHTTPPropertyServerHTTPVersionKeyKey for retrieving the HTTP version as an
NSStringobject 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.
-
NSHTTPPropertyRedirectionHeadersKeyKey for retrieving the redirection headers as an
NSDictionaryobject with each header value keyed to the header name.Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
NSHTTPPropertyErrorPageDataKeyKey for retrieving an error page as an
NSDataobject.Available in OS X v10.0 and later.
Deprecated in OS X v10.4.
-
NSHTTPPropertyHTTPProxyKey for retrieving the
NSDictionaryobject containing proxy information to use in place of proxy identified inSystemConfiguration.framework.To avoid any proxy use, pass an empty dictionary.
Available in OS X v10.2 and later.
Deprecated in OS X v10.4.
Discussion
Pass these keys to
NSURLHandle'sgetResourceValue:forKey:error:orresourceValuesForKeys:error:method to request specific data. -
-
Keys in the userInfo dictionary of an
NSErrorobject when certain NSURL methods return an error.Declaration
Swift
let NSURLKeysOfUnsetValuesKey: StringObjective-C
NSString * const NSURLKeysOfUnsetValuesKey;Constants
-
NSURLKeysOfUnsetValuesKeyNSURLKeysOfUnsetValuesKeyKey for the resource properties that have not been set after the
setResourceValues:error:method returns an error, returned as an array of ofNSStringobjects.Available in OS X v10.7 and later.
-
-
Keys that describe the iCloud storage state of a file.
Declaration
Swift
let NSURLIsUbiquitousItemKey: String let NSURLUbiquitousItemDownloadingErrorKey: String let NSURLUbiquitousItemDownloadingStatusKey: String let NSURLUbiquitousItemHasUnresolvedConflictsKey: String let NSURLUbiquitousItemIsDownloadingKey: String let NSURLUbiquitousItemIsUploadedKey: String let NSURLUbiquitousItemIsUploadingKey: String let NSURLUbiquitousItemUploadingErrorKey: String let NSURLUbiquitousItemDownloadRequestedKey: String let NSURLUbiquitousItemContainerDisplayNameKey: StringObjective-C
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 NSURLUbiquitousItemUploadingErrorKey; NSString * const NSURLUbiquitousItemDownloadRequestedKey; NSString * const NSURLUbiquitousItemContainerDisplayNameKey; // Deprecated NSString * const NSURLUbiquitousItemPercentDownloadedKey; NSString * const NSURLUbiquitousItemPercentUploadedKey;Constants
-
NSURLIsUbiquitousItemKeyNSURLIsUbiquitousItemKeyA boolean
NSNumberthat containstrueif this item is in iCloud storage,falseif it is a local item (read-only).Available in OS X v10.7 and later.
-
NSURLUbiquitousItemDownloadingErrorKeyNSURLUbiquitousItemDownloadingErrorKeyAn 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.
-
NSURLUbiquitousItemDownloadingStatusKeyNSURLUbiquitousItemDownloadingStatusKeyThe 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.
-
NSURLUbiquitousItemHasUnresolvedConflictsKeyNSURLUbiquitousItemHasUnresolvedConflictsKeyA boolean
NSNumberthat containstrueif this item has conflicts outstanding,falseotherwise (read-only).Available in OS X v10.7 and later.
-
NSURLUbiquitousItemIsDownloadedKeyA boolean
NSNumberthat containstrueif this item’s data has been downloaded to a ubiquity container,falseotherwise (read-only).Available in OS X v10.7 and later.
Deprecated in OS X v10.9.
-
NSURLUbiquitousItemIsDownloadingKeyNSURLUbiquitousItemIsDownloadingKeyA boolean
NSNumberthat containstrueif this item is being downloaded from iCloud,falseotherwise (read-only).Available in OS X v10.7 and later.
-
NSURLUbiquitousItemIsUploadedKeyNSURLUbiquitousItemIsUploadedKeyA boolean
NSNumberthat containstrueif this item’s data has been uploaded to iCloud storage,falseotherwise (read-only).Available in OS X v10.7 and later.
-
NSURLUbiquitousItemIsUploadingKeyNSURLUbiquitousItemIsUploadingKeyA boolean
NSNumberthat containstrueif this item is being uploaded to iCloud,falseotherwise (read-only).Available in OS X v10.7 and later.
-
NSURLUbiquitousItemPercentDownloadedKeyAn
NSNumberin the range0–100that indicates the percentage of the data that has been downloaded (read-only).Use the
NSMetadataQueryclass to search forNSMetadataItemobjects that have theNSMetadataUbiquitousItemPercentDownloadedKeyattribute instead.Available in OS X v10.7 and later.
Deprecated in OS X v10.8.
-
NSURLUbiquitousItemPercentUploadedKeyAn
NSNumberin the range0–100that indicates the percentage of the data that has been uploaded (read-only).Use the
NSMetadataQueryclass to search forNSMetadataItemobjects that have theNSMetadataUbiquitousItemPercentUploadedKeyattribute instead.Available in OS X v10.7 and later.
Deprecated in OS X v10.8.
-
NSURLUbiquitousItemUploadingErrorKeyNSURLUbiquitousItemUploadingErrorKeyAn 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.
-
NSURLUbiquitousItemDownloadRequestedKeyNSURLUbiquitousItemDownloadRequestedKeyA Boolean indicating whether a call to
startDownloadingUbiquitousItemAtURL:error:has already been made to download the item. The value of this key is read-only.Available in OS X v10.10 and later.
-
NSURLUbiquitousItemContainerDisplayNameKeyNSURLUbiquitousItemContainerDisplayNameKeyA string containing the name of the item’s container, as it is displayed to the user.
Available in OS X v10.10 and later.
Discussion
To request information about the iCloud storage state of an item, pass one of these keys to the
forKey:parameter of thegetResourceValue:forKey:error:instance method. -
-
Values that describe the iCloud storage state of a file.
Declaration
Swift
let NSURLUbiquitousItemDownloadingStatusCurrent: String let NSURLUbiquitousItemDownloadingStatusDownloaded: String let NSURLUbiquitousItemDownloadingStatusNotDownloaded: StringObjective-C
NSString * const NSURLUbiquitousItemDownloadingStatusCurrent; NSString * const NSURLUbiquitousItemDownloadingStatusDownloaded; NSString * const NSURLUbiquitousItemDownloadingStatusNotDownloaded;Constants
-
NSURLUbiquitousItemDownloadingStatusCurrentNSURLUbiquitousItemDownloadingStatusCurrentA 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.
-
NSURLUbiquitousItemDownloadingStatusDownloadedNSURLUbiquitousItemDownloadingStatusDownloadedA 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.
-
NSURLUbiquitousItemDownloadingStatusNotDownloadedNSURLUbiquitousItemDownloadingStatusNotDownloadedThis item has not been downloaded yet. Use
startDownloadingUbiquitousItemAtURL:error:to download it.Available in OS X v10.9 and later.
Discussion
These constants are possible values for the
NSURLUbiquitousItemDownloadingStatusKeykey. -
Copyright © 2016 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2015-04-08
