[Previous]
[Up]
[Next]
NSURLHandle
Authors
- Richard Frith-Macdonald
-
- Mark Allison
-
Version: $Revision$
Date: $Date$
Declared in: Foundation/NSURLHandle.h
Inherits from: NSObject
An NSURLHandle instance is used to manage the resource data
corresponding to an NSURL object. A single NSURLHandle can
be used to manage multiple NSURL objects as long as those
objects all refer to the same resource.
Different NSURLHandle subclasses are used to manage different
types of URL (usually based on the scheme of the URL), and you
can register new subclasses to extend (or replace) the
standard ones.
GNUstep comes with private subclasses to handle the common
URL schemes -
Instance Variables
Methods
Class Methods
+ (Class) URLHandleClassForURL: (NSURL*)anURL;
Returns the most recently registered NSURLHandle subclass that
responds to canInitWithURL:
with YES. If there is no such subclass, returns nil.
+ (NSURLHandle*) cachedHandleForURL: (NSURL*)anURL;
Returns a previously created object that handles the specified
URL (if any exists), otherwise returns nil.
+ (BOOL) canInitWithURL: (NSURL*)anURL;
Your subclass must override this abstract method.
Implemented by subclasses to say which URLs they can handle.
This method is used to determine which subclasses can be used
to handle a particular URL.
+ (void) registerURLHandleClass: (Class)anURLHandleSubclass;
Used to register a subclass as being available to handle URLs.
Instances Methods
- (void) addClient: (id<NSURLHandleClient>)client;
Adds an object conforming to the
NSURLHandleClient protocol
as a client of the URL handle.
- (NSData*) availableResourceData;
Returns the resource data that is currently available for the
handle. This may be a partially loaded resource or may be
empty of no data has been loaded yet.
- (void) backgroundLoadDidFailWithReason: (NSString*)reason;
This method should be called when a background load fails.
The method passes the failure notification to the clients of
the handle - so subclasses should call super's implementation
at the end of their implementation of this method.
- (void) beginLoadInBackground;
This method is called by when a background load begins.
Subclasses should call super's implementation at
the end of their implementation of this method.
- (void) cancelLoadInBackground;
This method should be called to cancel a load currently in
progress. The method calls
endLoadInBackground
Subclasses should call super's implementation at
the end of their implementation of this method.
- (void) didLoadBytes: (NSData*)newBytes loadComplete: (BOOL)yorn;
This method must be called by subclasses whenever data is
loaded.
- (void) endLoadInBackground;
This method is called to stop any background loading process.
cancelLoadInBackground
uses this method to cancel loading.
Subclasses should call super's implementation at
the end of their implementation of this method.
- (NSString*) failureReason;
Returns the failure reason for the last failure to load
the resource data.
- (void) flushCachedData;
Flushes any cached resource data.
This is the designated initialiser
- (init) initWithURL: (NSURL*)url cached: (BOOL)yesno;
Your subclass must override this abstract method.
Initialises a handle with the specified URL.
The flag determines whether the handle will cache resource data
and respond to requests from equivalent URLs for the cached data.
- (void) loadInBackground;
Your subclass must override this abstract method.
Starts (or queues) loading of the handle's resource data
in the background (asynchronously).
- (NSData*) loadInForeground;
Loads the handle's resource data in the foreground (synchronously).
This may be implemented by starting a background load and
waiting for it to complete.
- (id) propertyForKey: (NSString*)propertyKey;
Your subclass must override this abstract method.
Returns the property for the specified key, or nil if the
key does not exist.
- (id) propertyForKeyIfAvailable: (NSString*)propertyKey;
Your subclass must override this abstract method.
Returns the property for the specified key, but only if the
handle does not need to do any work to retrieve it.
- (void) removeClient: (id<NSURLHandleClient>)client;
Removes an object from them list of clients notified of
resource loading events by the URL handle.
- (NSData*) resourceData;
Returns the resource data belonging to the handler.
Calls loadInForeground if
necessary.
- (NSURLHandleStatus) status;
Returns the current status of the handle.
- (BOOL) writeData: (NSData*)data;
Your subclass must override this abstract method.
Writes resource data to the handle. Returns YES on success,
NO on failure.
- (BOOL) writeProperty: (id)propertyValue forKey: (NSString*)key;
Your subclass must override this abstract method.
Attempts to set property for handle.
Declared in: Foundation/NSURLHandle.h
- (void) URLHandleResourceDidBeginLoading: (NSURLHandle*)sender;
Sent by the NSURLHandle object when it begins loading
resource data.
- (void) URLHandleResourceDidCancelLoading: (NSURLHandle*)sender;
Sent by the NSURLHandle object when resource loading is canceled
by programmatic request (rather than by failure).
- (void) URLHandleResourceDidFinishLoading: (NSURLHandle*)sender;
Sent by the NSURLHandle object when it completes loading
resource data.
- (void) URLHandle: (NSURLHandle*)sender resourceDidBecomeAvailable: (NSData*)data;
Sent by the NSURLHandle object when some data becomes available
from the handle.
- (void) URLHandle: (NSURLHandle*)sender resourceDidFailLoadingWithReason: (NSString*)reason;
Sent by the NSURLHandle object on resource load failure.
Supplies a human readable failure reason.
Declared in: Foundation/NSURLHandle.h
typedef int NSURLHandleStatus
An NSURLHandleStatus is used to report the current state of an
NSURLHandle object, it can take the following values -
- NSURLHandleNotLoaded
- NSURLHandleLoadSucceeded
- NSURLHandleLoadInProgress
- NSURLHandleLoadFailed
Inherits from: NSURLHandle
This is a PRIVATE subclass of NSURLHandle.
It is documented here in order to give you information about the
default behavior of an NSURLHandle created to deal with a URL
that has the FILE scheme. The name and/or other
implementation details of this class may be changed at any time.
A GSFileURLHandle instance is used to manage files on the local
file-system of your machine.
Instance Variables
Methods
Instances Methods
- (id) propertyForKey: (NSString*)propertyKey;
Gets file attribute information for the file represented by
the handle, using the same dictionary keys as the
NSFileManager class.
- (BOOL) writeData: (NSData*)data;
Writes the specified data as the contents of the file
represented by the handle.
- (BOOL) writeProperty: (id)propertyValue forKey: (NSString*)key;
Changes the attributes of the file represented by this handle.
This method uses the same dictionary keys as the NSFileManger
class.
Inherits from: NSURLHandle
This is a PRIVATE subclass of NSURLHandle.
It is documented here in order to give you information about the
default behavior of an NSURLHandle created to deal with a URL
that has either the http or https scheme.
The name and/or other implementation details of this class
may be changed at any time.
A GSHTTPURLHandle instance is used to manage connections to
http and https URLs.
Secure connections are handled automatically
(using openSSL) for URLs with the scheme https.
Connection via proxy server is supported, as is proxy tunneling
for secure connections. Basic parsing of http
headers is performed to extract http status
information, cookies etc. Cookies are
retained and automatically sent during subsequent requests where
the cookie is valid.
Header information from the current page may be obtained using
-propertyForKey and -propertyForKeyIfAvailable. HTTP
status information can be retrieved as by calling either of these
methods specifying one of the following keys:
-
NSHTTPPropertyStatusCodeKey - numeric status code
-
NSHTTPPropertyStatusReasonKey - text describing status
-
NSHTTPPropertyServerHTTPVersionKey -
http
version supported by remote server
According to MacOS-X headers, the following should also
be supported, but currently are not:
- NSHTTPPropertyRedirectionHeadersKey
- NSHTTPPropertyErrorPageDataKey
The omission of these headers is not viewed as important at
present, since the MacOS-X public beta implementation doesn't
work either.
Other calls to -propertyForKey and -propertyForKeyIfAvailable may
be made specifying a http header field name.
For example specifying a key name of "Content-Length"
would return the value of the "Content-Length" header
field.
-writeProperty:forKey: can be used to specify the parameters
for the http request. The default request uses the
"GET" method when fetching a page, and the
"POST" method when using -writeData:.
This can be over-ridden by calling -writeProperty:forKey: with
the key name "GSHTTPPropertyMethodKey" and specifying an
alternative method (i.e "PUT").
A Proxy may be specified by calling -writeProperty:forKey:
with the keys "GSHTTPPropertyProxyHostKey" and
"GSHTTPPropertyProxyPortKey" to set the host and port
of the proxy server respectively. The GSHTTPPropertyProxyHostKey
property can be set to either the IP address or the hostname of
the proxy server. If an attempt is made to load a page via a
secure connection when a proxy is specified, GSHTTPURLHandle will
attempt to open an SSL Tunnel through the proxy.
Instance Variables
Methods
Instances Methods
- (id) propertyForKey: (NSString*)propertyKey;
If necessary, this method calls -loadInForeground to send a
request to the webserver, and get a page back. It then returns
the property for the specified key -
-
NSHTTPPropertyStatusCodeKey - numeric status code returned
by the last request.
-
NSHTTPPropertyStatusReasonKey - text describing status of
the last request
-
NSHTTPPropertyServerHTTPVersionKey -
http
version supported by remote server
-
Other keys are taken to be the names of
http
headers and the corresponding header value (or nil if there
is none) is returned.
- (BOOL) writeData: (NSData*)data;
Writes the specified data as the body of an http
or https request to the web server.
Returns YES on success,
NO on failure. By default, this method performs a POST operation.
On completion, the resource data for this handle is set to the
page returned by the request.
- (BOOL) writeProperty: (id)propertyValue forKey: (NSString*)key;
Sets a property to be used in the next request made by this handle.
The property is set as a header in the next request, unless it is
one of the following -
-
GSHTTPPropertyMethodKey - override the default method of
the request (eg. "PUT").
-
GSHTTPPropertyProxyHostKey - specify the name or IP address
of a host to proxy through.
-
GSHTTPPropertyProxyPortKey - specify the port number to
connect to on the proxy host. If not give, this defaults
to 8080 for
http and 4430 for https.