Up

# NSURLHandle class reference

### Authors

Manuel Guesdon (`mguesdon@sbuilders.com`)
Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 37003

Date: 2013-08-22 16:44:54 +0100 (Thu, 22 Aug 2013)

Copyright: (C) 1999 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSURLHandle class
2. Software documentation for the NSURLHandleClient protocol

# Software documentation for the NSURLHandle class

## NSURLHandle : NSObject

> Declared in:
>   Foundation/NSURLHandle.h

Availability: MacOS-X 10.0.0

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 -

- `file:` (local file I/O)
- `http:` and `https:` (webserver) access.
- `ftp:` (FTP server) access.

Instance Variables
Method summary

- +URLHandleClassForURL:
- +cachedHandleForURL:
- +canInitWithURL:
- +registerURLHandleClass:
- -addClient:
- -availableResourceData
- -backgroundLoadDidFailWithReason:
- -beginLoadInBackground
- -cancelLoadInBackground
- -didLoadBytes:loadComplete:
- -endLoadInBackground
- -failureReason
- -flushCachedData
- -initWithURL:cached:
- -loadInBackground
- -loadInForeground
- -propertyForKey:
- -propertyForKeyIfAvailable:
- -removeClient:
- -resourceData
- -status
- -writeData:
- -writeProperty:forKey:

### URLHandleClassForURL:

+ (Class) URLHandleClassForURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Returns the most recently registered NSURLHandle subclass that responds to +canInitWithURL: with `YES`. If there is no such subclass, returns `nil`.

### cachedHandleForURL:

+ (NSURLHandle*) cachedHandleForURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Return a handle for the specified URL from the cache if possible. If the cache does not contain a matching handle, returns `nil`.

### canInitWithURL:

+ (BOOL) canInitWithURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Subclasses must override this 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.

### registerURLHandleClass:

+ (void) registerURLHandleClass: (Class)urlHandleSubclass;
Availability: MacOS-X 10.0.0
Used to register a subclass as being available to handle URLs.

### addClient:

- (void) addClient: (id<NSURLHandleClient>)client;
Availability: MacOS-X 10.0.0
Add a client object, making sure that it doesn't occur more than once.
The client object will receive messages notifying it of events on the handle.

### availableResourceData

- (NSData*) availableResourceData;
Availability: MacOS-X 10.0.0
Returns the resource data that is currently available for the handle. This may be a partially loaded resource or may be empty if no data has been loaded yet or the last load failed.

### backgroundLoadDidFailWithReason:

- (void) backgroundLoadDidFailWithReason: (NSString*)reason;
Availability: MacOS-X 10.0.0
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.

### beginLoadInBackground

- (void) beginLoadInBackground;
Availability: MacOS-X 10.0.0
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.

### cancelLoadInBackground

- (void) cancelLoadInBackground;
Availability: MacOS-X 10.0.0
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.

### didLoadBytes: loadComplete:

- (void) didLoadBytes: (NSData*)newData loadComplete: (BOOL)loadComplete;
Availability: MacOS-X 10.0.0
Method called by subclasses during process of loading a resource. The base class maintains a copy of the data being read in and accumulates separate parts of the data.

### endLoadInBackground

- (void) endLoadInBackground;
Availability: MacOS-X 10.0.0
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.

### failureReason

- (NSString*) failureReason;
Availability: MacOS-X 10.0.0
Returns the failure reason for the last failure to load the resource data.

### flushCachedData

- (void) flushCachedData;
Availability: MacOS-X 10.0.0
Flushes any cached resource data.

### initWithURL: cached:

- (id) initWithURL: (NSURL*)url cached: (BOOL)cached;
Availability: MacOS-X 10.0.0
This is a designated initialiser for the class.
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.

### loadInBackground

- (void) loadInBackground;
Availability: MacOS-X 10.0.0
Starts (or queues) loading of the handle's resource data in the background (asynchronously).
The default implementation uses loadInForeground - if this method is not overridden, loadInForeground MUST be.

### loadInForeground

- (NSData*) loadInForeground;
Availability: MacOS-X 10.0.0
Loads the handle's resource data in the foreground (synchronously).
The default implementation starts a background load and waits for it to complete - if this method is not overridden, loadInBackground MUST be.

### propertyForKey:

- (id) propertyForKey: (NSString*)propertyKey;
Availability: MacOS-X 10.0.0
Subclasses must override this method.
Returns the property for the specified key, or `nil` if the key does not exist.

### propertyForKeyIfAvailable:

- (id) propertyForKeyIfAvailable: (NSString*)propertyKey;
Availability: MacOS-X 10.0.0
Subclasses must override this method.
Returns the property for the specified key, but only if the handle does not need to do any work to retrieve it.

### removeClient:

- (void) removeClient: (id<NSURLHandleClient>)client;
Availability: MacOS-X 10.0.0
Removes an object from them list of clients notified of resource loading events by the URL handle.

### resourceData

- (NSData*) resourceData;
Availability: MacOS-X 10.0.0
Returns the resource data belonging to the handle. Calls -loadInForeground if necessary.

The GNUstep implementation treats an ftp: request for a directory as a request to list the names of the directory contents.

### status

- (NSURLHandleStatus) status;
Availability: MacOS-X 10.0.0
Returns the current status of the handle.

### writeData:

- (BOOL) writeData: (NSData*)data;
Availability: MacOS-X 10.0.0

Writes resource data to the handle. Returns `YES` on success, `NO` on failure.

The GNUstep implementation for file: writes the data directly to the local filesystem, and the return status reflects the result of that write operation.

The GNUstep implementation for http: and https: sets the specified data as information to be POSTed to the URL next time it is loaded - so the method always returns `YES`.

The GNUstep implementation for ftp: sets the specified data as information to be written to the URL next time it is loaded - so the method always returns `YES`.

### writeProperty: forKey:

- (BOOL) writeProperty: (id)propertyValue forKey: (NSString*)propertyKey;
Availability: MacOS-X 10.0.0

Sets a property for handle. Returns `YES` on success, `NO` on failure.

The GNUstep implementation sets the property as a header to be sent the next time the URL is loaded, and recognizes some special property keys which control the behavior of the next load.

## Instance Variables for NSURLHandle Class

### _clients

@protected NSMutableArray* _clients;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _data

@protected id _data;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _failure

@protected NSString* _failure;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _status

@protected NSURLHandleStatus _status;
Availability: MacOS-X 10.0.0
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSURLHandleClient protocol

## NSURLHandleClient

> Declared in:
>   Foundation/NSURLHandle.h

Availability: MacOS-X 10.0.0
A protocol to which clients of a handle must conform in order to receive notification of events on the handle.
Method summary

- -URLHandle:resourceDataDidBecomeAvailable:
- -URLHandle:resourceDidFailLoadingWithReason:
- -URLHandleResourceDidBeginLoading:
- -URLHandleResourceDidCancelLoading:
- -URLHandleResourceDidFinishLoading:

### URLHandle: resourceDataDidBecomeAvailable:

- (void) URLHandle: (NSURLHandle*)sender resourceDataDidBecomeAvailable: (NSData*)newData;
Availability: MacOS-X 10.0.0
Sent by the NSURLHandle object when some data becomes available from the handle. Note that this does not mean that all data has become available, only that a chunk of data has arrived.

### URLHandle: resourceDidFailLoadingWithReason:

- (void) URLHandle: (NSURLHandle*)sender resourceDidFailLoadingWithReason: (NSString*)reason;
Availability: MacOS-X 10.0.0
Sent by the NSURLHandle object on resource load failure. Supplies a human readable failure reason.

### URLHandleResourceDidBeginLoading:

- (void) URLHandleResourceDidBeginLoading: (NSURLHandle*)sender;
Availability: MacOS-X 10.0.0
Sent by the NSURLHandle object when it begins loading resource data.

### URLHandleResourceDidCancelLoading:

- (void) URLHandleResourceDidCancelLoading: (NSURLHandle*)sender;
Availability: MacOS-X 10.0.0
Sent by the NSURLHandle object when resource loading is cancelled by programmatic request (rather than by failure).

### URLHandleResourceDidFinishLoading:

- (void) URLHandleResourceDidFinishLoading: (NSURLHandle*)sender;
Availability: MacOS-X 10.0.0
Sent by the NSURLHandle object when it completes loading resource data.

Up