An object that represents the location of a resource, such as an item on a remote server or the path to a local file.
SDKs
- iOS 2.0+
- macOS 10.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
@interface NSURL : NSObject
Overview
You can use URL objects to construct URLs and access their parts. For URLs that represent local files, you can also manipulate properties of those files directly, such as changing the file’s last modification date. Finally, you can pass URL objects to other APIs to retrieve the contents of those URLs. For example, you can use the NSURLSession
, NSURLConnection
, and NSURLDownload
classes to access the contents of remote resources, as described in URL Loading System.
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 using the init
initializer, or as an NSData
object using the init
initializer.
You can also use URLs for interapplication communication. In macOS, the NSWorkspace
class provides the open
method to open a location specified by a URL. Similarly, in iOS, the UIApplication
class provides the open
method.
Additionally, you can use URLs when working with pasteboards, as described in NSURL Additions Reference (part of the AppKit framework).
The NSURL
class is “toll-free bridged” with its Core Foundation counterpart, CFURLRef
. See Toll-Free Bridging for more information on toll-free bridging.
Important
The Swift overlay to the Foundation framework provides the URL
structure, which bridges to the NSURL
class. For more information about value types, see Classes and Structures in The Swift Programming Language (Swift 4.1) and Working with Cocoa Frameworks in Using Swift with Cocoa and Objective-C (Swift 4.1).
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
as the string part, as follows:
NSURL *baseURL = [NSURL fileURLWithPath:@"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
.
A URL can be also be divided into pieces based on its structure. For example, the URL https://johnny:
contains the following URL components:
Component | Value |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
|
The NSURL
class provides properties that let you examine each of these components.
Note
The URLs employed by the NSURL
class are described in RFC 1808, RFC 1738, and RFC 2732.
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 a macOS 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 macOS, you get access to security-scoped URLs when you resolve a security-scoped bookmark. In iOS, apps that open or move documents using a UIDocument
also receive security-scoped URLs.
To gain access to a security-scoped URL, you must call the start
method (or its Core Foundation equivalent, the CFURLStart
function). For iOS apps, if you use a UIDocument
to access the URL, it automatically manages the security-scoped URL for you.
If start
(or CFUr
) returns YES
, you must relinquish your access by calling the stop
method (or its Core Foundation equivalent, the CFURLStop
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.
Warning
If you fail to relinquish your access when you no longer need a file-system resource, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, using Powerbox, security-scoped bookmarks, or similar APIs, until relaunched.
Security-Scoped URLs and String Paths
In a macOS 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 start
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 macOS or UIImage
objects in iOS using the get
or get
methods.
NSURL *URL = [self URLForDocument];
NSDictionary *thumbnails = nil;
NSError *error = nil;
BOOL success = [URL getPromisedItemResourceValue:&thumbnails
forKey:NSURLThumbnailDictionaryKey
error:&error];
if (success) {
NSImage *image = thumbnails[NSThumbnail1024x1024SizeKey];
} else {
// handle the error
}
In macOS, you can set a dictionary of thumbnails using the set
method. You can also get or set all the thumbnails as an NSImage
object with multiple representations by using the NSURLThumbnail
.
NSURL *URL = [self URLForDocument];
NSImage *thumbnail = [self createDocumentThumbnail];
NSError *error = nil;
BOOL success = [URL setResourceValue:@{NSThumbnail1024x1024SizeKey : thumbnail}
forKey:NSURLThumbnailDictionaryKey
error:&error];
if (!success) {
// handle the error
}
Note
Do not set the NSURLThumbnail
key directly. Modifying this key interferes with document tracking and can create duplicates of your document, as well as other possible problems.
In iOS, use a UIDocument
subclass to manage your file. Set the thumbnail by overriding the document’s file
method and returning a dictionary that contains the proper thumbnail keys (along with any other file attributes).
In macOS, follow the instructions for creating thumbnails given in Quick Look Programming Guide.
Note
Although the thumbnail API is designed to support multiple image resolutions, currently it only supports 1024 x 1024 pixel thumbnails.