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


[Previous] [Class List] [Next]

NSURL


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




Class Description


The NSURL class provides a way to manipulate URL's and the resources they reference. NSURL understands URL's as specified in RFC's 1808 and 1738.

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

An NSURL can be composed of two parts-a base URL, and a string that is resolved relative to the base URL. An NSURL with a base URL and a relative string is referred to as a relative URL. An NSURL with no base URL, is called an absolute URL

NSURL uses NSURLHandle to actually manage data. NSURLHandle and its registered subclasses control which URL schemes are supported. See the NSURLHandle class description for more information.


Method Types


Creating an NSURL
+ URLWithString:
+ URLWithString:relativeToURL:
+ fileURLWithPath:
Accessing an NSURL's resource data
- loadResourceDataNotifyingClient:usingCache:
- resourceDataUsingCache:
Accessing the parts of the URL
- scheme
- resourceSpecifier
- host
- port
- user
- password
- path
- fragment
- parameterString
- query
- relativePath

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.

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.


Instance Methods



URLHandleUsingCache:

- (NSURLHandle *)URLHandleUsingCache:(BOOL)shouldUseCache

Description forthcoming.

absoluteString

- (NSString *)absoluteString

Returns a string representation of the receiver's base URL and any relative 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.

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 a URL conforming to RFC 1808. If the receiver does not conform to RFC 1808, returns nil.

host

- (NSString *)host

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

initFileURLWithPath:

- initFileURLWithPath:(NSString *)path

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

initWithScheme:host:path:

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

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

initWithString:

- initWithString:(NSString *)URLString

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

initWithString:relativeToURL:

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

Initializes a new URL with a base URL of baseURL and a relative string portion of URLString. This method expects URLString to contain any necessary percent escape codes.

See Also: baseURL, relativeString



isFileURL

- (BOOL)isFileURL

Returns YES if the reciver is a file URL, NO otherwise.

loadResourceDataNotifyingClient:usingCache:

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

Loads the URL's resource data in the background. client is notified of the NSURL'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 equivalent URL.

parameterString

- (NSString *)parameterString

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

password

- (NSString *)password

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

path

- (NSString *)path

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

port

- (NSNumber *)port

Returns the port number of a 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 a URL conforming to RFC 1808. If the receiver does not conform to RFC 1808, returns nil.

relativePath

- (NSString *)relativePath

Returns the relative path of a URL conforming to RFC 1808. 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 URL's resource data, loading it if necessary. If the URL has already loaded its resource data through an invocation of loadResourceDataNotifyingClient:usingCache:, this returns the resource data. If the URL 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 URL.

scheme

- (NSString *)scheme

Returns the scheme portion of the URL.

setProperty:forKey:

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

<<Description forthcoming.>>

setResourceData:

- (BOOL)setResourceData:(NSData *)data

Attemps to write the resource data for the URL. 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.


[Previous] [Next]