PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSURL


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSURLHandleClient
NSObject (NSObject)
Declared in:
Foundation/NSURL.h




Class Description


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

NSURLs can be used to refer to files, and are in fact the preferred way to do so. ApplicationKit objects that can read or write data from or to a file generally have methods that accept an NSURL instead of a pathname as the file reference.

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




Method Types


Creating an NSURL
+ URLWithString:
+ URLWithString:relativeToURL:
+ fileURLWithPath:
- initFileURLWithPath:
- initWithScheme:host:path:
- initWithString:
- initWithString:relativeToURL:
Querying an NSURL
- isFileURL
Accessing an NSURL's resource data
- URLHandleUsingCache:
- loadResourceDataNotifyingClient:usingCache:
- resourceDataUsingCache:
- setResourceData:
Accessing the parts of the URL
- absoluteString
- absoluteURL
- baseURL
- fragment
- host
- parameterString
- password
- path
- port
- propertyForKey:
- query
- relativePath
- relativeString
- resourceSpecifier
- scheme
- setProperty:forKey:
- standardizedURL
- user


Class Methods



URLWithString:

+ (id)URLWithString:(NSString *)URLString

Initializes and returns a newly created NSURL with URLString. This method expects URLString to contain any necessary percent escape codes, which are ':', '/', '%', '#', ';', and '@'. Note that '%' escapes are translated via UTF-8. URLWithString: parses URLString according to RFCs 1738 and 1808.

URLWithString:relativeToURL:

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

Initializes and returns a newly created NSURL with URLString, interpreted relative to baseURL. This method expects URLString to contain any necessary percent escape codes.

fileURLWithPath:

+ (id)fileURLWithPath:(NSString *)path

Initializes and returns a newly created NSURL as a file URL that refers to the file or directory at path. path should be a valid system path.


Instance Methods



URLHandleUsingCache:

- (NSURLHandle *)URLHandleUsingCache:(BOOL)shouldUseCache

Description forthcoming. Sophisticated clients will want to ask for this, then message the handle directly. If shouldUseCache is NO, a newly instantiated handle is returned, even if an equivalent URL has been loaded

absoluteString

- (NSString *)absoluteString

Resolves the receiver's string against its base according to the algorithm given in RFC 1808 and returns the resulting string.

absoluteURL

- (NSURL *)absoluteURL

Returns an NSURL that refers to the same resource as the receiver, but has no relative portion. If the receiver is already absolute, returns self. Resolution is performed per RFC 1808.

baseURL

- (NSURL *)baseURL

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

fragment

- (NSString *)fragment

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

host

- (NSString *)host

Returns the host portion of an URL conforming to RFC 1808. If the receiver does not conform to RFC 1808, returns nil.

initFileURLWithPath:

- (id)initFileURLWithPath:(NSString *)path

Initializes a newly created NSURL referencing the local file or directory at path. This is equivalent to initWithScheme:host:path:, with scheme NSFileScheme , a nil host and path.

initWithScheme:host:path:

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

Initializes a newly created NSURL as an URL with scheme scheme, host host, and path path.

initWithString:

- (id)initWithString:(NSString *)URLString

Initializes a newly created NSURL with the string URLString. This method expects URLString to contain any necessary percent escape codes.

initWithString:relativeToURL:

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

Initializes a new URL with a base URL of baseURL and a relative string portion of URLString. It is an error for URLString to be nil. This method expects URLString to contain any necessary percent escape codes. URLWithString:relativeToURL: is the designated initializer for NSURL.

See Also: - baseURL, - relativeString



isFileURL

- (BOOL)isFileURL

Returns YES if the receiver uses the file scheme, NO otherwise. If YES, then the result of sending path to the receiver is suitable for input into NSFileManager or NSPathUtilities.

loadResourceDataNotifyingClient:usingCache:

- (void)loadResourceDataNotifyingClient:(id)client usingCache:(BOOL)shouldUseCache

Loads the receiver's resource data in the background. client is notified of the receiver's progress loading the resource data using the NSURLClient informal protocol. shouldUseCache controls whether the URL should use cached resource data from an already loaded URL that refers to the same resource. Only one background load can proceed at a time.

parameterString

- (NSString *)parameterString

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

password

- (NSString *)password

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

path

- (NSString *)path

Returns the path of an URL conforming to RFC 1808. If the receiver does not conform to RFC 1808, returns nil.

port

- (NSNumber *)port

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

propertyForKey:

- (id)propertyForKey:(NSString *)propertyKey

Description forthcoming.

query

- (NSString *)query

Returns the query portion of an URL conforming to RFC 1808. If the receiver does not conform to RFC 1808, returns nil.

relativePath

- (NSString *)relativePath

Returns the path of an URL conforming to RFC 1808, without resolving against the receiver's 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.

relativeString

- (NSString *)relativeString

Returns a string representation of the relative portion of the URL. If the receiver is an absolute URL, or if baseURL is nil, this method returns the same value as absoluteString.

resourceDataUsingCache:

- (NSData *)resourceDataUsingCache:(BOOL)shouldUseCache

Returns the receiver's resource data, loading it if necessary. If the receiver has already loaded its resource data through an invocation of loadResourceDataNotifyingClient:usingCache: and shouldUseCache is YES, this returns the resource data. If shouldUseCache is NO, a fresh load is always performed. If the receiver has not already loaded its resource data, it will attempt to load it as a blocking operation. shouldUseCache controls whether the URL returns cached resource data for an already loaded, equivalent URL.

resourceSpecifier

- (NSString *)resourceSpecifier

Returns the resource specifier portion of the receiver.

scheme

- (NSString *)scheme

Returns the scheme portion of the receiver.

setProperty:forKey:

- (BOOL)setProperty:(id)property forKey:(NSString *)propertyKey

Description forthcoming.

setResourceData:

- (BOOL)setResourceData:(NSData *)data

Attempts to write the resource data for the receiver. In the case of a file URL, this involves writing data to the specified file. Returns YES if successful, NO otherwise.

standardizedURL

- (NSURL *)standardizedURL

Description forthcoming.

user

- (NSString *)user

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


Table of Contents