NSURLHandle $Revision$ $Date$ NSURLHandle 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 -

GSFileURLHandle for file: (local file I/O) GSHTTPURLHandle for http and shttp (webserver) access. URLHandleClassForURL: anURL Returns the most recently registered NSURLHandle subclass that responds to canInitWithURL: with YES. If there is no such subclass, returns nil. cachedHandleForURL: anURL Returns a previously created object that handles the specified URL (if any exists), otherwise returns nil. canInitWithURL: anURL 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: anURLHandleSubclass Used to register a subclass as being available to handle URLs. addClient: client Adds an object conforming to the NSURLHandleClient protocol as a client of the URL handle. 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. 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: newBytes loadComplete: yorn This method must be called by subclasses whenever data is loaded. 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: yesno 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). 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. 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 handler. Calls loadInForeground if necessary. status Returns the current status of the handle. writeData: data Writes resource data to the handle. Returns YES on success, NO on failure. writeProperty: propertyValue forKey: key Attempts to set property for handle. Foundation/NSURLHandle.h URLHandleResourceDidBeginLoading: sender Sent by the NSURLHandle object when it begins loading resource data. URLHandleResourceDidCancelLoading: sender Sent by the NSURLHandle object when resource loading is canceled by programmatic request (rather than by failure). URLHandleResourceDidFinishLoading: sender Sent by the NSURLHandle object when it completes loading resource data. URLHandle: sender resourceDidBecomeAvailable: data Sent by the NSURLHandle object when some data becomes available from the handle. URLHandle: sender resourceDidFailLoadingWithReason: reason Sent by the NSURLHandle object on resource load failure. Supplies a human readable failure reason. int Foundation/NSURLHandle.h An NSURLHandleStatus is used to report the current state of an NSURLHandle object, it can take the following values - NSURLHandleNotLoaded NSURLHandleLoadSucceeded NSURLHandleLoadInProgress NSURLHandleLoadFailed GSFileURLHandle

This is a PRIVATE subclass of NSURLHandle. It is documented here in order to give you information about the default behavior of an NSURLHandle created to deal with a URL that has the FILE scheme. The name and/or other implementation details of this class may be changed at any time.

A GSFileURLHandle instance is used to manage files on the local file-system of your machine.

propertyForKey: propertyKey Gets file attribute information for the file represented by the handle, using the same dictionary keys as the NSFileManager class. writeData: data Writes the specified data as the contents of the file represented by the handle. writeProperty: propertyValue forKey: key Changes the attributes of the file represented by this handle. This method uses the same dictionary keys as the NSFileManger class. GSHTTPURLHandle

This is a PRIVATE subclass of NSURLHandle. It is documented here in order to give you information about the default behavior of an NSURLHandle created to deal with a URL that has either the http or https scheme. The name and/or other implementation details of this class may be changed at any time.

A GSHTTPURLHandle instance is used to manage connections to http and https URLs. Secure connections are handled automatically (using openSSL) for URLs with the scheme https. Connection via proxy server is supported, as is proxy tunneling for secure connections. Basic parsing of http headers is performed to extract http status information, cookies etc. Cookies are retained and automatically sent during subsequent requests where the cookie is valid.

Header information from the current page may be obtained using -propertyForKey and -propertyForKeyIfAvailable. HTTP status information can be retrieved as by calling either of these methods specifying one of the following keys:

NSHTTPPropertyStatusCodeKey - numeric status code NSHTTPPropertyStatusReasonKey - text describing status NSHTTPPropertyServerHTTPVersionKey - http version supported by remote server

According to MacOS-X headers, the following should also be supported, but currently are not:

NSHTTPPropertyRedirectionHeadersKey NSHTTPPropertyErrorPageDataKey

The omission of these headers is not viewed as important at present, since the MacOS-X public beta implementation doesn't work either.

Other calls to -propertyForKey and -propertyForKeyIfAvailable may be made specifying a http header field name. For example specifying a key name of "Content-Length" would return the value of the "Content-Length" header field.

-writeProperty:forKey: can be used to specify the parameters for the http request. The default request uses the "GET" method when fetching a page, and the "POST" method when using -writeData:. This can be over-ridden by calling -writeProperty:forKey: with the key name "GSHTTPPropertyMethodKey" and specifying an alternative method (i.e "PUT").

A Proxy may be specified by calling -writeProperty:forKey: with the keys "GSHTTPPropertyProxyHostKey" and "GSHTTPPropertyProxyPortKey" to set the host and port of the proxy server respectively. The GSHTTPPropertyProxyHostKey property can be set to either the IP address or the hostname of the proxy server. If an attempt is made to load a page via a secure connection when a proxy is specified, GSHTTPURLHandle will attempt to open an SSL Tunnel through the proxy.

propertyForKey: propertyKey If necessary, this method calls -loadInForeground to send a request to the webserver, and get a page back. It then returns the property for the specified key - NSHTTPPropertyStatusCodeKey - numeric status code returned by the last request. NSHTTPPropertyStatusReasonKey - text describing status of the last request NSHTTPPropertyServerHTTPVersionKey - http version supported by remote server Other keys are taken to be the names of http headers and the corresponding header value (or nil if there is none) is returned. writeData: data Writes the specified data as the body of an http or https request to the web server. Returns YES on success, NO on failure. By default, this method performs a POST operation. On completion, the resource data for this handle is set to the page returned by the request. writeProperty: propertyValue forKey: key Sets a property to be used in the next request made by this handle. The property is set as a header in the next request, unless it is one of the following - GSHTTPPropertyMethodKey - override the default method of the request (eg. "PUT"). GSHTTPPropertyProxyHostKey - specify the name or IP address of a host to proxy through. GSHTTPPropertyProxyPortKey - specify the port number to connect to on the proxy host. If not give, this defaults to 8080 for http and 4430 for https.