---

NSURL Class Reference

Overview

The NSURL class provides a way to manipulate URLs and the resources they reference. NSURL objects understand URLs as specified in RFCs 1808, 1738, and 2732. The litmus test for conformance to RFC 1808 is as recommended in RFC 1808—whether the first two characters of resourceSpecifier are @"//".

NSURL objects can be used to refer to files, and are the preferred way to do so. ApplicationKit objects that can read data from or write data to a file generally have methods that accept an NSURL object instead of a pathname as the file reference. NSWorkspace provides openURL: to open a location specified by a URL. To get the contents of a URL, NSString provides stringWithContentsOfURL: and NSData provides dataWithContentsOfURL:.

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

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

The informal protocol NSURLClient defines a set of methods useful for managing the loading of a URL resource in the background.

See also NSURL Additions in the Application Kit framework, which add methods supporting pasteboards.

NSURL is “toll-free bridged” with its Core Foundation counterpart, CFURL. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object, providing you cast one type to the other. In an API where you see an NSURL * parameter, you can pass in a CFURLRef, and in an API where you see a CFURLRef parameter, you can pass in a pointer to an NSURL instance. This approach also applies to your concrete subclasses of NSURL. See Interchangeable Data Types for more information on toll-free bridging.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

• – URLHandleResourceDidBeginLoading:

• – URLHandleResourceDidCancelLoading:

• – URLHandleResourceDidFinishLoading:

• – URLHandle:resourceDataDidBecomeAvailable:

• – URLHandle:resourceDidFailLoadingWithReason:

Tasks

Creating an NSURL

• – initWithScheme:host:path:
• + URLWithString:
• – initWithString:
• + URLWithString:relativeToURL:
• – initWithString:relativeToURL:
• + fileURLWithPath:isDirectory:
• + fileURLWithPath:
• – initFileURLWithPath:isDirectory:
• – initFileURLWithPath:

Identifying and Comparing Objects

• – isEqual:

Querying an NSURL

• – isFileURL

Loading the Resource of an NSURL Object

• – loadResourceDataNotifyingClient:usingCache: Deprecated in Mac OS X v10.4
• – propertyForKey: Deprecated in Mac OS X v10.4
• – resourceDataUsingCache: Deprecated in Mac OS X v10.4
• – setProperty:forKey: Deprecated in Mac OS X v10.4
• – setResourceData: Deprecated in Mac OS X v10.4
• – URLHandleUsingCache: Deprecated in Mac OS X v10.4

Accessing the Parts of the URL

• – absoluteString
• – absoluteURL
• – baseURL
• – fragment
• – host
• – parameterString
• – password
• – path
• – port
• – query
• – relativePath
• – relativeString
• – resourceSpecifier
• – scheme
• – standardizedURL
• – user

Class Methods

fileURLWithPath:

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

+ (id)fileURLWithPath:(NSString *)path

Parameters

path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.

Return Value

An NSURL object initialized with path.

Discussion

This method examines path in the file system to determine if it is a directory. If path is a directory, then a trailing slash is appended. If the file does not exist, it is assumed that path represents a directory and a trailing slash is appended. As an alternative, consider using fileURLWithPath:isDirectory: which allows you to explicitly specify whether the returned NSURL object represents a file or directory.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• initFileURLWithPath:

Related Sample Code

• CoreRecipes
• iSpend
• Quartz Composer WWDC 2005 TextEdit
• StickiesExample
• TextEditPlus

Declared In

NSURL.h

fileURLWithPath:isDirectory:

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

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

Parameters

path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.

isDir

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

Return Value

An NSURL object initialized with path.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• initFileURLWithPath:

Related Sample Code

• AutoSample
• IKSlideshowDemo

Declared In

NSURL.h

URLWithString:

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

+ (id)URLWithString:(NSString *)URLString

Parameters

URLString

The string with which to initialize the NSURL object. Must conform to RFC 2396. This method parses URLString according to RFCs 1738 and 1808.

Return Value

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• Core Data HTML Store
• LSMSmartCategorizer
• NewsReader
• ObjectPath
• VertexPerformanceTest

Declared In

NSURL.h

URLWithString:relativeToURL:

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

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

Parameters

URLString

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

baseURL

The base URL for the NSURL object.

Return Value

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CocoaHTTPServer
• CocoaSOAP
• Quartz Composer WWDC 2005 TextEdit
• Reducer
• TextEditPlus

Declared In

NSURL.h

Instance Methods

absoluteString

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

- (NSString *)absoluteString

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CocoaDragAndDrop
• CoreRecipes
• NewsReader
• Reducer

Declared In

NSURL.h

absoluteURL

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

- (NSURL *)absoluteURL

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

baseURL

Returns the base URL of the receiver.

- (NSURL *)baseURL

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

fragment

Returns the fragment of a URL conforming to RFC 1808.

- (NSString *)fragment

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

host

Returns the host of a URL conforming to RFC 1808.

- (NSString *)host

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CoreRecipes

Declared In

NSURL.h

initFileURLWithPath:

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

- (id)initFileURLWithPath:(NSString *)path

Parameters

path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.

Return Value

An NSURL object initialized with path.

Discussion

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

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• fileURLWithPath:

Related Sample Code

• AttachAScript
• CoreRecipes
• LSMSmartCategorizer
• Quartz Composer WWDC 2005 TextEdit
• TextEditPlus

Declared In

NSURL.h

initFileURLWithPath:isDirectory:

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

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

Parameters

path

The path that the NSURL object will represent. path should be a valid system path. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.

isDir

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

Return Value

An NSURL object initialized with path.

Discussion

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

Availability

• Available in Mac OS X v10.5 and later.

See Also

• fileURLWithPath:

Declared In

NSURL.h

initWithScheme:host:path:

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

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

Parameters

scheme

The scheme for the NSURL object.

host

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

path

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

Return Value

The newly initialized NSURL object.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CoreRecipes

Declared In

NSURL.h

initWithString:

Initializes an NSURL object with a provided string.

- (id)initWithString:(NSString *)URLString

Parameters

URLString

The string with which to initialize the NSURL object. Must conform to RFC 2396. This method parses URLString according to RFCs 1738 and 1808.

Return Value

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• URLWithString:

Declared In

NSURL.h

initWithString:relativeToURL:

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

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

Parameters

URLString

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

baseURL

The base URL for the NSURL object.

Return Value

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

Discussion

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

initWithString:relativeToURL: is the designated initializer for NSURL.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – baseURL
• – relativeString
• URLWithString:relativeToURL:

Declared In

NSURL.h

isEqual:

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

- (BOOL)isEqual:(id)anObject

Parameters

anObject

The object to be compared to the receiver.

Return Value

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

Discussion

This method defines what it means for instances to be equal. For example, two NSURLs are considered equal if they both have the same base baseURL and relativeString.

isFileURL

Returns whether the receiver uses the file scheme.

- (BOOL)isFileURL

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

parameterString

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

- (NSString *)parameterString

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

password

Returns the password of a URL conforming to RFC 1808.

- (NSString *)password

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

path

Returns the path of a URL conforming to RFC 1808.

- (NSString *)path

Return Value

The path of the URL. If the receiver does not conform to RFC 1808, returns nil. If isFileURL returnsYES, the return value is suitable for input into NSFileManager or NSPathUtilities. If the path has a trailing slash it is stripped.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• CoreRecipes
• File Wrappers with Core Data Documents
• iSpend
• QTKitCreateMovie
• Quartz Composer WWDC 2005 TextEdit

Declared In

NSURL.h

port

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

- (NSNumber *)port

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

query

Returns the query of a URL conforming to RFC 1808.

- (NSString *)query

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

relativePath

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

- (NSString *)relativePath

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• IdentitySample

Declared In

NSURL.h

relativeString

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

- (NSString *)relativeString

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

resourceSpecifier

Returns the resource specifier of the URL.

- (NSString *)resourceSpecifier

Return Value

The resource specifier of the URL.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

scheme

Returns the scheme of the URL.

- (NSString *)scheme

Return Value

The scheme of the URL.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• NewsReader

Declared In

NSURL.h

standardizedURL

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

- (NSURL *)standardizedURL

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

user

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

- (NSString *)user

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSURL.h

Constants

NSURL Schemes

These schemes are the ones that NSURL can parse.

extern NSString *NSURLFileScheme;

Constants

NSURLFileScheme

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

Available in Mac OS X v10.0 and later.

Declared in NSURL.h.

Discussion

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

Declared In

NSURL.h

NSURLHandle FTP Property Keys

FTP-specific property keys.

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

Constants

NSFTPPropertyUserLoginKey

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

The default value for this key is “anonymous”.

Available in Mac OS X v10.2 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyUserPasswordKey

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

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

Available in Mac OS X v10.2 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyActiveTransferModeKey

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

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

Available in Mac OS X v10.2 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyFileOffsetKey

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

Available in Mac OS X v10.2 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSFTPPropertyFTPProxy

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

To avoid any proxy use, pass an empty dictionary.

Available in Mac OS X v10.3 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

Discussion

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

Declared In

NSURL.h

NSURLHandle HTTP Property Keys

HTTP-specific property keys.

extern NSString *NSHTTPPropertyStatusCodeKey;
extern NSString *NSHTTPPropertyStatusReasonKey;
extern NSString *NSHTTPPropertyServerHTTPVersionKey;
extern NSString *NSHTTPPropertyRedirectionHeadersKey;
extern NSString *NSHTTPPropertyErrorPageDataKey;
extern NSString *NSHTTPPropertyHTTPProxy;

Constants

NSHTTPPropertyStatusCodeKey

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

Available in Mac OS X v10.0 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyStatusReasonKey

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

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

Available in Mac OS X v10.0 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyServerHTTPVersionKey

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

Available in Mac OS X v10.0 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyRedirectionHeadersKey

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

Available in Mac OS X v10.0 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyErrorPageDataKey

Key for retrieving an error page as an NSData object.

Available in Mac OS X v10.0 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

NSHTTPPropertyHTTPProxy

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

To avoid any proxy use, pass an empty dictionary.

Available in Mac OS X v10.2 and later.

Deprecated in Mac OS X v10.4.

Declared in NSURLHandle.h.

Discussion

Pass these keys to NSURLHandle's propertyForKeyIfAvailable: to request specific data.

Declared In

NSURL.h

---