[Previous]
[Up]
[Next]
NSURLHandle
Authors
- Richard Frith-Macdonald
-
Version: 0.1
Date: 28 February, 2000
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.
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;
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 cancelled
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