# NSURLHandle class reference

mguesdon@sbuilders.com
rfm@gnu.org
Generated at 2025-02-13 06:02:40 +0000
1999 Free Software Foundation, Inc.
Software documentation for the NSURLHandle class
Foundation/NSURLHandle.h

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.
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.
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.
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.
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.
URLHandleClassForURL:
url
Returns the most recently registered NSURLHandle subclass that responds to +canInitWithURL: with `YES`. If there is no such subclass, returns `nil`.
cachedHandleForURL:
url
Return a handle for the specified URL from the cache if possible. If the cache does not contain a matching handle, returns `nil`.
canInitWithURL:
url
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:
urlHandleSubclass
Used to register a subclass as being available to handle URLs.
addClient:
client
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
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:
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.
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.
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.
didLoadBytes:
newData
loadComplete:
loadComplete
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
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
Returns the failure reason for the last failure to load the resource data.
flushCachedData
Flushes any cached resource data.
initWithURL:
url
cached:
cached
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
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
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:
propertyKey
Returns the property for the specified key, or `nil` if the key does not exist.
propertyForKeyIfAvailable:
propertyKey
Returns the property for the specified key, but only if the handle does not need to do any work to retrieve it.
removeClient:
client
Removes an object from them list of clients notified of resource loading events by the URL handle.
resourceData
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.

setDebug:
flag
GNUstep extension to turn on debug logging for a handle. Returns the previous debug setting for the handle. Implemented for http/https only.
setReturnAll:
flag
GNUstep extension to turn on returning of complete http/https response even when the status code is not in the 200 to 299 success range.
setURL:
newUrl
GNUstep extension to change the URL that the handle sends requests to. Implemented for http/https only.
status
Returns the current status of the handle.
writeData:
data

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:
propertyValue
forKey:
propertyKey

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.

Software documentation for the NSURLHandleClient protocol
Foundation/NSURLHandle.h
A protocol to which clients of a handle must conform in order to receive notification of events on the handle.
URLHandle:
sender
resourceDataDidBecomeAvailable:
newData
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:
sender
resourceDidFailLoadingWithReason:
reason
Sent by the NSURLHandle object on resource load failure. Supplies a human readable failure reason.
URLHandleResourceDidBeginLoading:
sender
Sent by the NSURLHandle object when it begins loading resource data.
URLHandleResourceDidCancelLoading:
sender
Sent by the NSURLHandle object when resource loading is cancelled by programmatic request (rather than by failure).
URLHandleResourceDidFinishLoading:
sender
Sent by the NSURLHandle object when it completes loading resource data.