PATH
Documentation >
Mac OS X >
Foundation Reference: Objective-C
- 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
+ (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.
+ (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.
+ (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
- (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
- (NSString *)absoluteString
Resolves the receiver's string
against its base according to the algorithm given in RFC 1808 and returns
the resulting string.
- (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.
- (NSURL *)baseURL
Returns the base URL of the
receiver. If the receiver is an absolute URL,
returns nil
.
- (NSString *)fragment
Returns the fragment of an
URL conforming to RFC 1808. If the receiver does
not conform to RFC 1808, returns nil
.
- (NSString *)host
Returns the host portion of
an URL conforming to RFC 1808. If the receiver
does not conform to RFC 1808, returns nil
.
- (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.
- (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.
- (id)initWithString:(NSString
*)URLString
Initializes a newly created
NSURL with the string URLString. This
method expects URLString to contain
any necessary percent escape codes.
-(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
- (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.
- (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.
- (NSString *)parameterString
Returns the parameter string
of an URL conforming to RFC 1808. If the receiver
does not conform to RFC 1808, returns nil
.
- (NSString *)password
Returns the password of an
URL conforming to RFC 1808. If the receiver does
not conform to RFC 1808, returns nil
.
- (NSString *)path
Returns the path of an URL
conforming to RFC 1808. If the receiver does not
conform to RFC 1808, returns nil
.
- (NSNumber *)port
Returns the port number of
an URL conforming to RFC 1808. If the receiver
does not conform to RFC 1808, returns nil
.
- (id)propertyForKey:(NSString
*)propertyKey
Description forthcoming.
- (NSString *)query
Returns the query portion of
an URL conforming to RFC 1808. If the receiver
does not conform to RFC 1808, returns nil
.
- (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
.
- (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.
- (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.
- (NSString *)resourceSpecifier
Returns the resource specifier
portion of the receiver.
- (NSString *)scheme
Returns the scheme portion
of the receiver.
- (BOOL)setProperty:(id)property
forKey:(NSString *)propertyKey
Description forthcoming.
- (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.
- (NSURL *)standardizedURL
Description forthcoming.
- (NSString *)user
Returns the user portion of
a URL conforming to RFC 1808. If the receiver
does not conform to RFC 1808, returns nil
.