Class

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.

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 URLSession, 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 using the init(contentsOf:encoding:) initializer, or as an NSData object using the init(contentsOf:options:) 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 openURL(_:) 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, CFURL. See Toll-Free Bridging for more information on toll-free bridging.

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

scheme

https

user

johnny

password

p4ssw0rd

host

www.example.com

port

443

path

/script.ext

pathExtension

ext

pathComponents

["/", "script.ext"]

parameterString

param=value

query

query=value

fragment

ref

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 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 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 true, 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 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 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 macOS or UIImage objects in iOS using the getResourceValue(_:forKey:) or getPromisedItemResourceValue(_:forKey:) methods.

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
}

In macOS, you can set a dictionary of thumbnails using the setResourceValue(_:forKey:) method. You can also get or set all the thumbnails as an NSImage object with multiple representations by using the thumbnailKey.

let URL = self.URLForDocument()
let thumbnail = self.createDocumentThumbnail()
 
do {
    try URL.setResourceValue([NSThumbnail1024x1024SizeKey: thumbnail], forKey: NSURLThumbnailDictionaryKey)
} catch {
    // handle the error
}

Nested Types

NSURL.BookmarkResolutionOptions

Options used when resolving bookmark data.

NSURL.BookmarkCreationOptions

Options used when creating bookmark data.

Symbols

Creating an NSURL Object

init?(scheme: String, host: String?, path: String)

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

Deprecated
init?(string: String)

Initializes an NSURL object with a provided URL string.

init?(string: String, relativeTo: URL?)

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

class func fileURL(withPath: String, isDirectory: Bool)

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

init(fileURLWithPath: String, isDirectory: Bool)

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

class func fileURL(withPath: String)

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

init(fileURLWithPath: String)

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

class func fileURL(withPathComponents: [String])

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

init(resolvingAliasFileAt: URL, options: NSURL.BookmarkResolutionOptions = [])

Returns a new URL made by resolving the alias file at url.

class func fileURL(withFileSystemRepresentation: UnsafePointer<Int8>, isDirectory: Bool, relativeTo: URL?)

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

func getFileSystemRepresentation(UnsafeMutablePointer<Int8>, maxLength: Int)

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

init(fileURLWithFileSystemRepresentation: UnsafePointer<Int8>, isDirectory: Bool, relativeTo: URL?)

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

Querying an NSURL

func checkResourceIsReachableAndReturnError(NSErrorPointer)

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

func isFileReferenceURL()

Returns whether the URL is a file reference URL.

var isFileURL: Bool

A boolean value that determines whether the receiver is a file URL.

Accessing the Parts of the URL

var absoluteString: String?

The URL string for the receiver as an absolute URL. (read-only)

var absoluteURL: URL?

An absolute URL that refers to the same resource as the receiver. (read-only)

var baseURL: URL?

The base URL. (read-only)

var fileSystemRepresentation: UnsafePointer<Int8>

A C string containing the URL’s file system path. (read-only)

var fragment: String?

The fragment identifier, conforming to RFC 1808. (read-only)

var host: String?

The host, conforming to RFC 1808. (read-only)

var lastPathComponent: String?

The last path component. (read-only)

var parameterString: String?

The parameter string conforming to RFC 1808. (read-only)

var password: String?

The password conforming to RFC 1808. (read-only)

var path: String?

The path, conforming to RFC 1808. (read-only)

var pathComponents: [String]?

An array containing the path components. (read-only)

var pathExtension: String?

The path extension. (read-only)

var port: NSNumber?

The port, conforming to RFC 1808.

var query: String?

The query string, conforming to RFC 1808.

var relativePath: String?

The relative path, conforming to RFC 1808. (read-only)

var relativeString: String

A string representation of the relative portion of the URL. (read-only)

var resourceSpecifier: String?

The resource specifier. (read-only)

var scheme: String?

The scheme. (read-only)

var standardized: URL?

A copy of the URL with any instances of ".." or "." removed from its path. (read-only)

var user: String?

The user name, conforming to RFC 1808.

Modifying and Converting a File URL

var filePathURL: URL?

A file path URL that points to the same resource as the URL object. (read-only)

func fileReferenceURL()

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

func appendingPathComponent(String)

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

func appendingPathComponent(String, isDirectory: Bool)

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.

func appendingPathExtension(String)

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

var deletingLastPathComponent: URL?

A URL created by taking the receiver and removing the last path component. (read-only)

var deletingPathExtension: URL?

A URL created by taking the receiver and removing the path extension, if any. (read-only)

var resolvingSymlinksInPath: URL?

A URL that points to the same resource as the receiver and includes no symbolic links. (read-only)

var standardizingPath: URL?

A URL that points to the same resource as the original URL using an absolute path. (read-only)

Working with Bookmark Data

class func bookmarkData(withContentsOf: URL)

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

class func resourceValues(forKeys: [URLResourceKey], fromBookmarkData: Data)

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

class func writeBookmarkData(Data, to: URL, options: NSURL.BookmarkFileCreationOptions)

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

func startAccessingSecurityScopedResource()

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

func stopAccessingSecurityScopedResource()

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

Getting and Setting File System Resource Properties

func getResourceValue(AutoreleasingUnsafeMutablePointer<AnyObject?>, forKey: URLResourceKey)

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

func resourceValues(forKeys: [URLResourceKey])

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

func setResourceValue(Any?, forKey: URLResourceKey)

Sets the URL’s resource property for a given key to a given value.

func setResourceValues([URLResourceKey : Any])

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

func removeAllCachedResourceValues()

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

func removeCachedResourceValue(forKey: URLResourceKey)

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

func setTemporaryResourceValue(Any?, forKey: URLResourceKey)

Sets a temporary resource value on the URL object.

Working with Promised Items

func checkPromisedItemIsReachableAndReturnError(NSErrorPointer)

Returns whether the promised item can be reached.

func promisedItemResourceValues(forKeys: [URLResourceKey])

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

Working with pasteboards

init?(from: NSPasteboard)

Reads an NSURL object off of the specified pasteboard.

func write(to: NSPasteboard)

Writes the URL to the specified pasteboard.

Constants

NSURL Schemes

The schemes that the NSURL class is able to parse.

URLResourceKey

Keys that apply to file system URLs.

URLFileResourceType

Possible values for the fileResourceTypeKey key.

URLThumbnailDictionaryItem

Possible keys for the thumbnailDictionaryKey dictionary.

File Property Keys

Keys that apply to properties of files.

Volume Resource Keys

Resource keys that apply to volumes.

BookmarkFileCreationOptions

Options used when creating file bookmark data

NSURL.BookmarkCreationOptions

Options used when creating bookmark data.

NSURL.BookmarkResolutionOptions

Options used when resolving bookmark data.

NSError userInfo Dictionary Keys

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

Ubiquitous Item Resource Keys

Keys that describe the iCloud storage state of a file.

URLUbiquitousItemDownloadingStatus

Values that describe the iCloud storage state of a file.