PATH  Documentation > Mac OS X > Foundation Reference: Objective-C



Table of Contents

NSURLHandle


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



URLHandleClassForURL:

+ (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.

cachedHandleForURL:

+ (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.

canInitWithURL:

+ (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.

registerURLHandleClass:

+ (void)registerURLHandleClass:(Class)anURLHandleSubclass

Registers anURLHandleSubclass as an available subclass of NSURLHandle.


Instance Methods



addClient:

- (void)addClient:(id <NSURLHandleClient>)client

Adds client (an object conforming to the NSURLHandleClient protocol) as a client of the URL handle.

availableResourceData

- (NSData *)availableResourceData

Immediately returns the currently available resource data managed by the URL handle.

backgroundLoadDidFailWithReason:

- (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.

beginLoadInBackground

- (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



cancelLoadInBackground

- (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



didLoadBytes:loadComplete:

- (void)didLoadBytes:(NSData *)newBytes loadComplete:(BOOL)yorn

Description forthcoming.

endLoadInBackground

- (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



failureReason

- (NSString *)failureReason

Returns a string describing the reason a load failed. Should status not be NSURLHandleLoadFailed, returns nil.

flushCachedData

- (void)flushCachedData

Flushes any cached data for the URL served by this URL handle.

initWithURL:cached:

- (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.

loadInBackground

- (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



loadInForeground

- (NSData *)loadInForeground

Loads the URL handle's data in the synchronously. Called by resourceData. Subclasses of NSURLHandle must override this method.

propertyForKey:

- (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.

propertyForKeyIfAvailable:

- (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.

removeClient:

- (void)removeClient:(id <NSURLHandleClient>)client

Removes client as an NSURLHandleClient of the URL handle.

resourceData

- (NSData *)resourceData

Returns the resource data managed by the URL handle, loading it if necessary. Blocks until all data is available.

status

- (NSURLHandleStatus)status

Returns the status of the URL handle. Possible return statuses are:

writeData:

- (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.

writeProperty:forKey:

- (BOOL)writeProperty:(id)propertyValue forKey:(NSString *)propertyKey

Description forthcoming.


Table of Contents