| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Companion guide | |
| Declared in | NSURL.h |
| Related sample code |
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 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 classes NSURLConnection and NSURLDownload define methods useful for loading URL resources in the background. See URL Loading System for more information
See also NSURL Additions Reference in the Application Kit framework, which add methods supporting pasteboards.
NSURL is “toll-free bridged” with its Core Foundation counterpart, CFURL Reference. 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.
– URLHandleResourceDidBeginLoading:
– URLHandleResourceDidCancelLoading:
– URLHandleResourceDidFinishLoading:
– URLHandle:resourceDataDidBecomeAvailable:
– URLHandle:resourceDidFailLoadingWithReason:
– initWithScheme:host:path:
+ URLWithString:
– initWithString:
+ URLWithString:relativeToURL:
– initWithString:relativeToURL:
+ fileURLWithPath:isDirectory:
– initFileURLWithPath:isDirectory:
+ fileURLWithPath:
– initFileURLWithPath:
Initializes and returns a newly created NSURL object as a file URL with a specified path.
+ (id)fileURLWithPath:(NSString *)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.
Passing nil for this parameter produces an exception.
An NSURL object initialized with path.
This method assumes that path is a directory if it ends with a slash. If path does not end with a slash, the method examines the file system to determine if path is a file or a directory. If path exists in the file system and is a directory, the method appends a trailing slash. If path does not exist in the file system, the method assumes that it represents a file and does not append a trailing slash.
As an alternative, consider using fileURLWithPath:isDirectory:, which allows you to explicitly specify whether the returned NSURL object represents a file or directory.
NSURL.hInitializes and returns a newly created NSURL object as a file URL with a specified path.
+ (id)fileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir
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.
Passing nil for this parameter produces an exception.
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.
An NSURL object initialized with path.
NSURL.hCreates and returns an NSURL object initialized with a provided string.
+ (id)URLWithString:(NSString *)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.
An NSURL object initialized with URLString. If the string was malformed, returns nil.
This method expects URLString to contain any necessary percent escape codes, which are ‘:’, ‘/’, ‘%’, ‘#’, ‘;’, and ‘@’. Note that ‘%’ escapes are translated via UTF-8.
NSURL.hCreates and returns an NSURL object initialized with a base URL and a relative string.
+ (id)URLWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL
The string with which to initialize the NSURL object. May not be nil. Must conform to RFC 2396. URLString is interpreted relative to baseURL.
The base URL for the NSURL object.
An NSURL object initialized with URLString and baseURL. If URLString was malformed, returns nil.
This method expects URLString to contain any necessary percent escape codes.
NSURL.hReturns the string for the receiver as if it were an absolute URL.
- (NSString *)absoluteString
An absolute string for the URL. Creating by resolving the receiver's string against its base according to the algorithm given in RFC 1808.
NSURL.hReturns an absolute URL that refers to the same resource as the receiver.
- (NSURL *)absoluteURL
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.
NSURL.hReturns the base URL of the receiver.
- (NSURL *)baseURL
The base URL of the receiver. If the receiver is an absolute URL, returns nil.
NSURL.hReturns the fragment of a URL conforming to RFC 1808.
- (NSString *)fragment
The fragment of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hReturns the host of a URL conforming to RFC 1808.
- (NSString *)host
The host of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hInitializes a newly created NSURL referencing the local file or directory at path.
- (id)initFileURLWithPath:(NSString *)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.
Passing nil for this parameter produces an exception.
An NSURL object initialized with path.
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.
NSURL.hInitializes a newly created NSURL referencing the local file or directory at path.
- (id)initFileURLWithPath:(NSString *)path isDirectory:(BOOL)isDir
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.
Passing nil for this parameter produces an exception.
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
An NSURL object initialized with path.
Invoking this method is equivalent to invoking initWithScheme:host:path: with scheme NSFileScheme, a nil host, and path.
NSURL.hInitializes a newly created NSURL with a specified scheme, host, and path.
- (id)initWithScheme:(NSString *)scheme host:(NSString *)host path:(NSString *)path
The scheme for the NSURL object.
The host for the NSURL object. May be the empty string.
The path for the NSURL object. If path begins with a tilde, it must first be expanded with stringByExpandingTildeInPath.
The newly initialized NSURL object.
NSURL.hInitializes an NSURL object with a provided string.
- (id)initWithString:(NSString *)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.
An NSURL object initialized with URLString. If the string was malformed, returns nil.
This method expects URLString to contain any necessary percent escape codes, which are ‘:’, ‘/’, ‘%’, ‘#’, ‘;’, and ‘@’. Note that ‘%’ escapes are translated via UTF-8.
NSURL.hInitializes an NSURL object with a base URL and a relative string.
- (id)initWithString:(NSString *)URLString relativeToURL:(NSURL *)baseURL
The string with which to initialize the NSURL object. Must conform to RFC 2396. URLString is interpreted relative to baseURL.
The base URL for the NSURL object.
An NSURL object initialized with URLString and baseURL. If URLString was malformed, returns nil.
This method expects URLString to contain any necessary percent escape codes.
initWithString:relativeToURL: is the designated initializer for NSURL.
NSURL.hReturns a Boolean value that indicates whether the receiver and a given object are equal.
- (BOOL)isEqual:(id)anObject
The object to be compared to the receiver.
YES if the receiver and anObject are equal, otherwise NO.
This method defines what it means for instances to be equal. Two NSURLs are considered equal if and only if they return identical values for both baseURL and relativeString.
Returns whether the receiver uses the file scheme.
- (BOOL)isFileURL
NSURL.hReturns the parameter string of a URL conforming to RFC 1808.
- (NSString *)parameterString
The parameter string of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hReturns the password of a URL conforming to RFC 1808.
- (NSString *)password
The password of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hReturns the path of a URL conforming to RFC 1808.
- (NSString *)path
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.
NSURL.hReturns the port number of a URL conforming to RFC 1808.
- (NSNumber *)port
The port number of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hReturns the query of a URL conforming to RFC 1808.
- (NSString *)query
The query of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hReturns the path of a URL conforming to RFC 1808, without resolving against the receiver’s base URL.
- (NSString *)relativePath
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.
NSURL.hReturns a string representation of the relative portion of the URL.
- (NSString *)relativeString
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.
NSURL.hReturns the resource specifier of the URL.
- (NSString *)resourceSpecifier
The resource specifier of the URL.
NSURL.hReturns the scheme of the URL.
- (NSString *)scheme
The scheme of the URL.
NSURL.hReturns a new NSURL object with any instances of ".." or "." removed from its path.
- (NSURL *)standardizedURL
A new NSURL object initialized with a version of the receiver’s URL that has had any instances of ".." or "." removed from its path.
NSURL.hReturns the user portion of a URL conforming to RFC 1808.
- (NSString *)user
The user portion of the URL. If the receiver does not conform to RFC 1808, returns nil.
NSURL.hThese schemes are the ones that NSURL can parse.
NSString * const NSURLFileScheme;
NSURLFileSchemeIdentifies a URL that points to a file on a mounted volume.
Available in iPhone OS 2.0 and later.
Declared in NSURL.h.
For more information, see initWithScheme:host:path:.
Last updated: 2009-10-09
