NSURL class reference

This class permits manipulation of URLs and the resources to which they refer. They can be used to represent absolute URLs or relative URLs which are based upon an absolute URL. The relevant RFCs describing how a URL is formatted, and what is legal in a URL are - 1808, 1738, and 2396.
Handling of the underlying resources is carried out by NSURLHandle objects, but NSURL provides a simplified API wrapping these objects.

URLByResolvingAliasFileAtURL: options: error:

+ (instancetype) URLByResolvingAliasFileAtURL: (NSURL*)url options: (NSURLBookmarkResolutionOptions)options error: (NSError**)error;

Availability: MacOS-X 10.10.0

Description forthcoming.

URLWithString:

+ (instancetype) URLWithString: (NSString*)aUrlString;

Availability: MacOS-X 10.0.0

Create and return a URL with the supplied string, which should be a string (containing percent escape codes where necessary) conforming to the description (in RFC2396) of an absolute URL.
Calls -initWithString:

URLWithString: relativeToURL:

+ (instancetype) URLWithString: (NSString*)aUrlString relativeToURL: (NSURL*)aBaseUrl;

Availability: MacOS-X 10.0.0

Create and return a URL with the supplied string, which should be a string (containing percent escape codes where necessary) conforming to the description (in RFC2396) of a relative URL.
Calls -initWithString:relativeToURL:

fileURLWithPath:

+ (instancetype) fileURLWithPath: (NSString*)aPath;

Availability: MacOS-X 10.0.0

Create and return a file URL with the supplied path.
The value of aPath must be a valid filesystem path.
Calls -initFileURLWithPath: which escapes characters in the path where necessary.

fileURLWithPath: isDirectory:

+ (instancetype) fileURLWithPath: (NSString*)aPath isDirectory: (BOOL)isDir;

Availability: MacOS-X 10.5.0

Description forthcoming.

fileURLWithPath: isDirectory: relativeToURL:

+ (instancetype) fileURLWithPath: (NSString*)aPath isDirectory: (BOOL)isDir relativeToURL: (NSURL*)baseURL;

Availability: MacOS-X 10.11.0

Description forthcoming.

fileURLWithPath: relativeToURL:

+ (instancetype) fileURLWithPath: (NSString*)aPath relativeToURL: (NSURL*)baseURL;

Availability: MacOS-X 10.11.0

Create and return a file URL with the supplied path, relative to a base URL.

fileURLWithPathComponents:

+ (instancetype) fileURLWithPathComponents: (NSArray*)components;

Availability: MacOS-X 10.6.0

Creates a file URL using a path built from components.

URLByAppendingPathComponent:

- (NSURL*) URLByAppendingPathComponent: (NSString*)pathComponent;

Availability: MacOS-X 10.6.0

Returns a URL formed by adding a path component to the path of the receiver.
See [NSString -stringByAppendingPathComponent:] .

URLByAppendingPathComponent: isDirectory:

- (NSURL*) URLByAppendingPathComponent: (NSString*)pathComponent isDirectory: (BOOL)isDirectory;

Availability: MacOS-X 10.7.0

Returns a URL formed by adding a path component to the path of the receiver, along with a trailing slash if the component is designated a directory.
See [NSString -stringByAppendingPathComponent:] .

URLByAppendingPathExtension:

- (NSURL*) URLByAppendingPathExtension: (NSString*)pathExtension;

Availability: MacOS-X 10.6.0

Returns a URL formed by adding a path extension to the path of the receiver.
See [NSString -stringByAppendingPathExtension:] .

URLByDeletingLastPathComponent

- (NSURL*) URLByDeletingLastPathComponent;

Availability: MacOS-X 10.6.0

Returns a URL formed by removing a path component from the path of the receiver.
See [NSString -stringByDeletingLastPathComponent] .

URLByDeletingPathExtension

- (NSURL*) URLByDeletingPathExtension;

Availability: MacOS-X 10.6.0

Returns a URL formed by removing an extension from the path of the receiver.
See [NSString -stringByDeletingPathExtension] .

URLByResolvingSymlinksInPath

- (NSURL*) URLByResolvingSymlinksInPath;

Availability: MacOS-X 10.6.0

Returns self unless the receiver is a file URL, in which case it returns a URL formed by calling [NSString -stringByResolvingSymlinksInPath] .

URLByStandardizingPath

- (NSURL*) URLByStandardizingPath;

Availability: MacOS-X 10.6.0

Returns self unless the receiver is a file URL, in which case it returns a URL formed by calling [NSString -stringByStandardizingPath] .

URLHandleUsingCache:

- (NSURLHandle*) URLHandleUsingCache: (BOOL)shouldUseCache;

Availability: MacOS-X 10.0.0

Returns an NSURLHandle instance which may be used to write data to the resource represented by the receiver URL, or read data from it.
The shouldUseCache flag indicates whether a cached handle may be returned or a new one should be created.

absoluteString

- (NSString*) absoluteString;

Availability: MacOS-X 10.0.0

Returns the full string describing the receiver resolved against its base.

absoluteURL

- (NSURL*) absoluteURL;

Availability: MacOS-X 10.0.0

If the receiver is an absolute URL, returns self. Otherwise returns an absolute URL referring to the same resource as the receiver.

baseURL

- (NSURL*) baseURL;

Availability: MacOS-X 10.0.0

If the receiver is a relative URL, returns its base URL.
Otherwise, returns nil.

checkResourceIsReachableAndReturnError:

- (BOOL) checkResourceIsReachableAndReturnError: (NSError**)error;

Availability: MacOS-X 10.6.0

Attempts to load from the specified URL and provides an error response if the data is unrachable.
Returns YES on success, NO on failure.

filePathURL

- (NSURL*) filePathURL;

Availability: MacOS-X 10.6.0

Description forthcoming.

fileReferenceURL

- (NSURL*) fileReferenceURL;

Availability: MacOS-X 10.6.0

Description forthcoming.

fragment

- (NSString*) fragment;

Availability: MacOS-X 10.0.0

Returns the fragment portion of the receiver or nil if there is no fragment supplied in the URL.
The fragment is everything in the original URL string after a '#'
File URLs do not have fragments.

getResourceValue: forKey: error:

- (BOOL) getResourceValue: (id*)value forKey: (NSString*)key error: (NSError**)error;

Availability: MacOS-X 10.6.0

Description forthcoming.

host

- (NSString*) host;

Availability: MacOS-X 10.0.0

Returns the host portion of the receiver or nil if there is no host supplied in the URL.
Percent escape sequences in the user string are translated and the string treated as UTF8.
Returns IPv6 addresses without the enclosing square brackets required (by RFC2732) in URL strings.

initFileURLWithPath:

- (instancetype) initFileURLWithPath: (NSString*)aPath;

Availability: MacOS-X 10.0.0

Initialise as a file URL with the specified path (which must be a valid path on the local filesystem).
Raises NSInvalidArgumentException if aPath is nil.
Converts relative paths to absolute ones.
Appends a trailing slash to the path when necessary if it specifies a directory.
Calls -initWithScheme:host:path:

initFileURLWithPath: isDirectory:

- (instancetype) initFileURLWithPath: (NSString*)aPath isDirectory: (BOOL)isDir;

Availability: MacOS-X 10.5.0

initFileURLWithPath: isDirectory: relativeToURL:

- (instancetype) initFileURLWithPath: (NSString*)aPath isDirectory: (BOOL)isDir relativeToURL: (NSURL*)baseURL;

Availability: MacOS-X 10.11.0

Initialise as a file URL with the specified path (which must be a valid path on the local filesystem) relative to the base URL.
Raises NSInvalidArgumentException if aPath is nil.
Converts relative paths to absolute ones.
Appends a trailing slash to the path when necessary if it specifies a directory.
Calls -initWithScheme:host:path:

initFileURLWithPath: relativeToURL:

- (instancetype) initFileURLWithPath: (NSString*)aPath relativeToURL: (NSURL*)baseURL;

Availability: MacOS-X 10.11.0

initWithScheme: host: path:

- (instancetype) initWithScheme: (NSString*)aScheme host: (NSString*)aHost path: (NSString*)aPath;

Availability: MacOS-X 10.0.0

Initialise by building a URL string from the supplied parameters and calling -initWithString:relativeToURL:
This method adds percent escapes to aPath if it contains characters which need escaping.
Accepts RFC2732 style IPv6 host addresses either with or without the enclosing square brackets (MacOS-X at least up to version 10.5 does not handle these correctly, but GNUstep does).
Permits the 'aHost' part to contain 'username:password@host:port' or 'host:port' in addition to a simple host name or address.

initWithString:

- (instancetype) initWithString: (NSString*)aUrlString;

Availability: MacOS-X 10.0.0

Initialise as an absolute URL.
Calls -initWithString:relativeToURL:

initWithString: relativeToURL:

- (instancetype) initWithString: (NSString*)aUrlString relativeToURL: (NSURL*)aBaseUrl;

Availability: MacOS-X 10.0.0

This is a designated initialiser for the class.

Initialised using aUrlString and aBaseUrl. The value of aBaseUrl may be nil, but aUrlString must be non-nil.
Accepts RFC2732 style IPv6 host addresses.
Parses a string wihthout a scheme as a simple path.
Parses an empty string as an empty path.
If the string cannot be parsed the method returns nil.

isFileReferenceURL

- (BOOL) isFileReferenceURL;

Availability: MacOS-X 10.6.0

Description forthcoming.

isFileURL

- (BOOL) isFileURL;

Availability: MacOS-X 10.0.0

Description forthcoming.

lastPathComponent

- (NSString*) lastPathComponent;

Availability: MacOS-X 10.6.0

Returns the last (rightmost) path component of the receiver.

loadResourceDataNotifyingClient: usingCache:

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

Availability: MacOS-X 10.0.0

Loads resource data for the specified client.

If shouldUseCache is YES then an attempt will be made to locate a cached NSURLHandle to provide the resource data, otherwise a new handle will be created and cached.

If the handle does not have the data available, it will be asked to load the data in the background by calling its loadInBackground method.

The specified client (if non-nil) will be set up to receive notifications of the progress of the background load process.

The processes current run loop must be run in order for the background load operation to operate!

parameterString

- (NSString*) parameterString;

Availability: MacOS-X 10.0.0

Returns the parameter portion of the receiver or nil if there is no parameter supplied in the URL.
The parameters are everything in the original URL string after a ';' but before the query.
File URLs do not have parameters.

password

- (NSString*) password;

Availability: MacOS-X 10.0.0

Returns the password portion of the receiver or nil if there is no password supplied in the URL.
Percent escape sequences in the user string are translated and the string treated as UTF8 in GNUstep but this appears to be broken in MacOS-X.
NB. because of its security implications it is recommended that you do not use URLs with users and passwords unless necessary.

path

- (NSString*) path;

Availability: MacOS-X 10.0.0

Returns the path portion of the receiver.
Replaces percent escapes with unescaped values, interpreting non-ascii character sequences as UTF8.
NB. This does not conform strictly to the RFCs, in that it includes a leading slash ('/') character (whereas the path part of a URL strictly should not) and the interpretation of non-ascii character is (strictly speaking) undefined.
Also, this breaks strict conformance in that a URL of file scheme is treated as having a path (contrary to RFCs)

pathComponents

- (NSArray*) pathComponents;

Availability: MacOS-X 10.6.0

Returns thepath components of the receiver.
See [NSString -pathComponents] .

pathExtension

- (NSString*) pathExtension;

Availability: MacOS-X 10.6.0

Returns the file extension (text after the rightmost dot in the path) of the receiver.
see [NSString -pathExtension] .

port

- (NSNumber*) port;

Availability: MacOS-X 10.0.0

Returns the port portion of the receiver or nil if there is no port supplied in the URL.
Percent escape sequences in the user string are translated in GNUstep but this appears to be broken in MacOS-X.

propertyForKey:

- (id) propertyForKey: (NSString*)propertyKey;

Availability: MacOS-X 10.0.0

Asks a URL handle to return the property for the specified key and returns the result.

query

- (NSString*) query;

Availability: MacOS-X 10.0.0

Returns the query portion of the receiver or nil if there is no query supplied in the URL.
The query is everything in the original URL string after a '?' but before the fragment.
File URLs do not have queries.

relativePath

- (NSString*) relativePath;

Availability: MacOS-X 10.0.0

Returns the path of the receiver, without taking any base URL into account. If the receiver is an absolute URL, -relativePath is the same as -path .
Returns nil if there is no path specified for the URL.

relativeString

- (NSString*) relativeString;

Availability: MacOS-X 10.0.0

Returns the relative portion of the URL string. If the receiver is not a relative URL, this returns the same as absoluteString.

resourceDataUsingCache:

- (NSData*) resourceDataUsingCache: (BOOL)shouldUseCache;

Availability: MacOS-X 10.0.0

Loads the resource data for the represented URL and returns the result. The shouldUseCache flag determines whether data previously retrieved by an existing NSURLHandle can be used to provide the data, or if it should be refetched.

resourceSpecifier

- (NSString*) resourceSpecifier;

Availability: MacOS-X 10.0.0

Returns the resource specifier of the URL... the part which lies after the scheme.

scheme

- (NSString*) scheme;

Availability: MacOS-X 10.0.0

Returns the scheme of the receiver.

setProperty: forKey:

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

Availability: MacOS-X 10.0.0

Calls [NSURLHandle -writeProperty:forKey:] to set the named property.

setResourceData:

- (BOOL) setResourceData: (NSData*)data;

Availability: MacOS-X 10.0.0

Calls [NSURLHandle -writeData:] to write the specified data object to the resource identified by the receiver URL.
Returns the result.

standardizedURL

- (NSURL*) standardizedURL;

Availability: MacOS-X 10.0.0

Returns a URL with '/./' and '/../' sequences resolved etc.

user

- (NSString*) user;

Availability: MacOS-X 10.0.0

Returns the user portion of the receiver or nil if there is no user supplied in the URL.
Percent escape sequences in the user string are translated and the whole is treated as UTF8 data.
NB. because of its security implications it is recommended that you do not use URLs with users and passwords unless necessary.

Software documentation for the NSURLComponents class

NSURLComponents : NSObject

componentsWithString:

+ (instancetype) componentsWithString: (NSString*)URLString;

Availability: MacOS-X 10.9.0

Description forthcoming.

componentsWithURL: resolvingAgainstBaseURL:

+ (instancetype) componentsWithURL: (NSURL*)url resolvingAgainstBaseURL: (BOOL)resolve;

Availability: MacOS-X 10.9.0

Description forthcoming.

URL

- (NSURL*) URL;

Availability: MacOS-X 10.9.0

Description forthcoming.

URLRelativeToURL:

- (NSURL*) URLRelativeToURL: (NSURL*)baseURL;

Availability: MacOS-X 10.9.0

Description forthcoming.

fragment

- (NSString*) fragment;

Availability: MacOS-X 10.9.0

Description forthcoming.

host

- (NSString*) host;

Availability: MacOS-X 10.9.0

Description forthcoming.

init

- (instancetype) init;

Availability: MacOS-X 10.9.0

Description forthcoming.

initWithString:

- (instancetype) initWithString: (NSString*)URLString;

Availability: MacOS-X 10.9.0

Description forthcoming.

initWithURL: resolvingAgainstBaseURL:

- (instancetype) initWithURL: (NSURL*)url resolvingAgainstBaseURL: (BOOL)resolve;

Availability: MacOS-X 10.9.0

Description forthcoming.

password

- (NSString*) password;

Availability: MacOS-X 10.9.0

Description forthcoming.

path

- (NSString*) path;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedFragment

- (NSString*) percentEncodedFragment;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedHost

- (NSString*) percentEncodedHost;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedPassword

- (NSString*) percentEncodedPassword;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedPath

- (NSString*) percentEncodedPath;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedQuery

- (NSString*) percentEncodedQuery;

Availability: MacOS-X 10.9.0

Description forthcoming.

percentEncodedQueryItems

- (NSArray*) percentEncodedQueryItems;

Availability: MacOS-X 10.10.0

Description forthcoming.

percentEncodedUser

- (NSString*) percentEncodedUser;

Availability: MacOS-X 10.9.0

Description forthcoming.

port

- (NSNumber*) port;

Availability: MacOS-X 10.9.0

Description forthcoming.

query

- (NSString*) query;

Availability: MacOS-X 10.9.0

Description forthcoming.

queryItems

- (NSArray*) queryItems;

Availability: MacOS-X 10.10.0

Description forthcoming.

rangeOfFragment

- (NSRange) rangeOfFragment;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfHost

- (NSRange) rangeOfHost;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfPassword

- (NSRange) rangeOfPassword;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfPath

- (NSRange) rangeOfPath;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfPort

- (NSRange) rangeOfPort;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfQuery

- (NSRange) rangeOfQuery;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfScheme

- (NSRange) rangeOfScheme;

Availability: MacOS-X 10.9.0

Description forthcoming.

rangeOfUser

- (NSRange) rangeOfUser;

Availability: MacOS-X 10.9.0

Description forthcoming.

scheme

- (NSString*) scheme;

Availability: MacOS-X 10.9.0

Description forthcoming.

setFragment:

- (void) setFragment: (NSString*)fragment;

Availability: MacOS-X 10.9.0

Description forthcoming.

setHost:

- (void) setHost: (NSString*)host;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPassword:

- (void) setPassword: (NSString*)password;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPath:

- (void) setPath: (NSString*)path;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedFragment:

- (void) setPercentEncodedFragment: (NSString*)fragment;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedHost:

- (void) setPercentEncodedHost: (NSString*)host;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedPassword:

- (void) setPercentEncodedPassword: (NSString*)password;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedPath:

- (void) setPercentEncodedPath: (NSString*)path;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedQuery:

- (void) setPercentEncodedQuery: (NSString*)query;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPercentEncodedQueryItems:

- (void) setPercentEncodedQueryItems: (NSArray*)queryItems;

Availability: MacOS-X 10.10.0

Description forthcoming.

setPercentEncodedUser:

- (void) setPercentEncodedUser: (NSString*)user;

Availability: MacOS-X 10.9.0

Description forthcoming.

setPort:

- (void) setPort: (NSNumber*)port;

Availability: MacOS-X 10.9.0

Description forthcoming.

setQuery:

- (void) setQuery: (NSString*)query;

Availability: MacOS-X 10.9.0

Description forthcoming.

setQueryItems:

- (void) setQueryItems: (NSArray*)queryItems;

Availability: MacOS-X 10.10.0

Description forthcoming.

setScheme:

- (void) setScheme: (NSString*)scheme;

Availability: MacOS-X 10.9.0

Description forthcoming.

setString:

- (void) setString: (NSString*)urlString;

Availability: MacOS-X 10.9.0

Description forthcoming.

setURL:

- (void) setURL: (NSURL*)url;

Availability: MacOS-X 10.9.0

Description forthcoming.

setUser:

- (void) setUser: (NSString*)user;

Availability: MacOS-X 10.9.0

Description forthcoming.

string

- (NSString*) string;

Availability: MacOS-X 10.9.0

Description forthcoming.

user

- (NSString*) user;

Availability: MacOS-X 10.9.0

Description forthcoming.

Software documentation for the NSURLQueryItem class

NSURLQueryItem : NSObject

queryItemWithName: value:

+ (instancetype) queryItemWithName: (NSString*)name value: (NSString*)value;

Availability: MacOS-X 10.10.0

Description forthcoming.

initWithName: value:

- (instancetype) initWithName: (NSString*)name value: (NSString*)value;

Availability: MacOS-X 10.10.0

Description forthcoming.

name

- (NSString*) name;

Availability: MacOS-X 10.10.0

Description forthcoming.

value

- (NSString*) value;

Availability: MacOS-X 10.10.0

Description forthcoming.

Software documentation for the NSObject(NSURLClient) category

NSObject(NSURLClient)

URL: resourceDataDidBecomeAvailable:

- (void) URL: (NSURL*)sender resourceDataDidBecomeAvailable: (NSData*)newBytes;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Some data has become available. Note that this does not mean that all data has become available, only that a chunk of data has arrived.

URL: resourceDidFailLoadingWithReason:

- (void) URL: (NSURL*)sender resourceDidFailLoadingWithReason: (NSString*)reason;

Availability: MacOS-X 10.0.0

An empty method provided for subclasses to override.

Loading of resource data has failed, for given human-readable reason.

Authors

Contents -

NSURL : NSObject

NSURLComponents : NSObject

NSURLQueryItem : NSObject

NSObject(NSURLClient)