PATH
Documentation >
Mac OS X >
Foundation Reference: Objective-C
- Inherits
from:
- NSObject
- Conforms to:
- none
Declared in: - Foundation/NSURLHandle.h
Class Description
NSURLHandle is the class responsible for accessing and managing
resource data indicated by an NSURL object. A single NSURLHandle
can service multiple equivalent NSURL objects, but only if these
URLs map to the same resource. If you want to implement support
for additional URL schemes, you would do so by creating a subclass
of NSURLHandle.
Method Types
- TBD_Heading (Class Methods)
- + URLHandleClassForURL:
- + cachedHandleForURL:
- + canInitWithURL:
- + registerURLHandleClass:
- TBD_Heading (Instance
Methods)
- - addClient:
- - availableResourceData
- - backgroundLoadDidFailWithReason:
- - beginLoadInBackground
- - cancelLoadInBackground
- - didLoadBytes:loadComplete:
- - endLoadInBackground
- - failureReason
- - flushCachedData
- - initWithURL:cached:
- - loadInBackground
- - loadInForeground
- - propertyForKey:
- - propertyForKeyIfAvailable:
- - removeClient:
- - resourceData
- - status
- - writeData:
- - writeProperty:forKey:
Class Methods
+ (Class)URLHandleClassForURL:(NSURL
*)anURL
Returns the class of the URL
handle used for anURL. Subclasses
of NSURLHandle must be registered via the registerURLHandleClass: method. The
subclass is determined by asking the list of registered subclasses
if it canInitWithURL:;
the first class to respond YES is selected.
+ (NSURLHandle *)cachedHandleForURL:(NSURL
*)anURL
Returns the URL handle from
the cache that has serviced anURL or
another identical URL. Subclasses of NSURLHandle
must override this method. Returns nil if there is no such handle.
+ (BOOL)canInitWithURL:(NSURL
*)anURL
Returns whether an URL handle
can be initialized with anURL. If anURL uses
an unsupported scheme, this method returns NO
.
Subclasses of NSURLHandle must override this method. to identify which
URLs they can service.
+ (void)registerURLHandleClass:(Class)anURLHandleSubclass
Registers anURLHandleSubclass as
an available subclass of NSURLHandle.
Instance Methods
- (void)addClient:(id
<NSURLHandleClient>)client
Adds client (an
object conforming to the NSURLHandleClient protocol) as a client
of the URL handle.
- (NSData *)availableResourceData
Immediately returns the currently
available resource data managed by the URL handle.
- (void)backgroundLoadDidFailWithReason:(NSString
*)reason
Called when a background load
fails. This method is provided mainly for subclasses
that wish to take some action before passing along the failure notification
to the URL client. You should call super
's implementation
at the end of your implementation of this method.
- (void)beginLoadInBackground
Called when a background load
begins. This method is provided mainly for subclasses
that wish to take advantage of the superclass' failure reporting
mechanism.See Also: - endLoadInBackground, - loadInBackground
- (void)cancelLoadInBackground
Called to cancel a load currently
in progress. You should call super
's
implementation at the end of your implementation of this method.See
Also: - endLoadInBackground
- (void)didLoadBytes:(NSData
*)newBytes
loadComplete:(BOOL)yorn
Description forthcoming.
- (void)endLoadInBackground
Called by cancelLoadInBackground to halt any
background loading. You should call super
's implementation
at the end of your implementation of this method.See
Also: - beginLoadInBackground, - cancelLoadInBackground, - loadInBackground
- (NSString *)failureReason
Returns a string describing
the reason a load failed. Should status not be NSURLHandleLoadFailed
, returns nil.
- (void)flushCachedData
Flushes any cached data for
the URL served by this URL handle.
- (id)initWithURL:(NSURL
*)anURL
cached:(BOOL)willCache
Initializes a newly created
URL handle with the URL anURL. willCache controls
whether the URL handle will cache its data and respond to requests
from equivalent URLs for the cached data. Subclasses of NSURLHandle
must override this method.
- (void)loadInBackground
Loads the URL handle's data
in the background. Each subclass determines the
loading policy. For example, and subclass may have it that only
one thread is maintained for background loading, so only one background
loading operation can be in progress at a time. If multiple background
loads are requested, the later requests will wait in a queue until
earlier requests are handled.See Also: - beginLoadInBackground
- (NSData *)loadInForeground
Loads the URL handle's data
in the synchronously. Called by resourceData. Subclasses
of NSURLHandle must override this method.
- (id)propertyForKey:(NSString
*)propertyKey
Returns the property for key propertyKey;
returns nil if there is no such key. Subclasses
of NSURLHandle must override this method.
- (id)propertyForKeyIfAvailable:(NSString
*)propertyKey
Returns the property for key propertyKey only
if the value is already available, i.e., the client doesn't need
to do any work.
- (void)removeClient:(id
<NSURLHandleClient>)client
Removes client as
an NSURLHandleClient of the URL handle.
- (NSData *)resourceData
Returns the resource data managed
by the URL handle, loading it if necessary. Blocks
until all data is available.
- (NSURLHandleStatus)status
Returns the status of the URL
handle. Possible return statuses are:
NSURLHandleNotLoaded
NSURLHandleLoadSucceeded
NSURLHandleLoadInProgress
NSURLHandleLoadFailed
- (BOOL)writeData:(NSData
*)data
Attempts to write data to
the location specified by the receiver's URL.
Returns YES if successful; NO otherwise. Must be overridden by subclasses.
- (BOOL)writeProperty:(id)propertyValue
forKey:(NSString *)propertyKey
Description forthcoming.