mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-26 18:21:04 +00:00
8f6392e943
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9280 72102866-910b-0410-8b05-ffd578937521
553 lines
18 KiB
XML
553 lines
18 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
<gsdoc base="NSURLHandle" prev="NSURL" next="NSUnarchiver" up="Base">
|
|
<head>
|
|
<title>NSURLHandle</title>
|
|
<author name="Richard Frith-Macdonald">
|
|
<email address="rfm@gnu.org"/>
|
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
|
</author>
|
|
<author name="Mark Allison">
|
|
<email address="mark@brainstorm.co.uk"/>
|
|
<url url="http://www.brainstorm.co.uk"/>
|
|
</author>
|
|
<version>$Revision$</version>
|
|
<date>$Date$</date>
|
|
</head>
|
|
<body>
|
|
<chapter>
|
|
<heading>NSURLHandle</heading>
|
|
<class name="NSURLHandle" super="NSObject">
|
|
<declared>Foundation/NSURLHandle.h</declared>
|
|
<desc>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
GNUstep comes with private subclasses to handle the common
|
|
URL schemes -
|
|
</p>
|
|
<list>
|
|
<item>
|
|
<ref id="GSFileURLHandle">GSFileURLHandle</ref> for
|
|
<code>file:</code> (local file I/O)
|
|
</item>
|
|
<item>
|
|
<ref id="GSHTTPURLHandle">GSHTTPURLHandle</ref> for
|
|
<code>http</code> and <code>shttp</code> (webserver) access.
|
|
</item>
|
|
</list>
|
|
</desc>
|
|
|
|
<method type="Class" factory="yes">
|
|
<sel>URLHandleClassForURL:</sel>
|
|
<arg type="NSURL*">anURL</arg>
|
|
<desc>
|
|
Returns the most recently registered NSURLHandle subclass that
|
|
responds to <ref id="canInitWithURL:">canInitWithURL:</ref>
|
|
with <code>YES</code>. If there is no such subclass, returns nil.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSURLHandle*" factory="yes">
|
|
<sel>cachedHandleForURL:</sel>
|
|
<arg type="NSURL*">anURL</arg>
|
|
<desc>
|
|
Returns a previously created object that handles the specified
|
|
URL (if any exists), otherwise returns nil.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL" factory="yes" id="canInitWithURL:"
|
|
override="subclass">
|
|
<sel>canInitWithURL:</sel>
|
|
<arg type="NSURL*">anURL</arg>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void" factory="yes">
|
|
<sel>registerURLHandleClass:</sel>
|
|
<arg type="Class">anURLHandleSubclass</arg>
|
|
<desc>
|
|
Used to register a subclass as being available to handle URLs.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>addClient:</sel>
|
|
<arg type="id<NSURLHandleClient>">client</arg>
|
|
<desc>
|
|
Adds an object conforming to the
|
|
<ref id="NSURLHandleClient">NSURLHandleClient protocol</ref>
|
|
as a client of the URL handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSData*">
|
|
<sel>availableResourceData</sel>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>backgroundLoadDidFailWithReason:</sel>
|
|
<arg type="NSString*">reason</arg>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>beginLoadInBackground</sel>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void" id="cancelLoadInBackground">
|
|
<sel>cancelLoadInBackground</sel>
|
|
<desc>
|
|
This method should be called to cancel a load currently in
|
|
progress. The method calls
|
|
<ref id="endLoadInBackground">endLoadInBackground</ref>
|
|
Subclasses should call super's implementation at
|
|
the end of their implementation of this method.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>didLoadBytes:</sel>
|
|
<arg type="NSData*">newBytes</arg>
|
|
<sel>loadComplete:</sel>
|
|
<arg type="BOOL">yorn</arg>
|
|
<desc>
|
|
This method must be called by subclasses whenever data is
|
|
loaded.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void" id="endLoadInBackground">
|
|
<sel>endLoadInBackground</sel>
|
|
<desc>
|
|
This method is called to stop any background loading process.
|
|
<ref id="cancelLoadInBackground">cancelLoadInBackground</ref>
|
|
uses this method to cancel loading.
|
|
Subclasses should call super's implementation at
|
|
the end of their implementation of this method.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSString*">
|
|
<sel>failureReason</sel>
|
|
<desc>
|
|
Returns the failure reason for the last failure to load
|
|
the resource data.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>flushCachedData</sel>
|
|
<desc>
|
|
Flushes any cached resource data.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="init" init="yes" override="subclass">
|
|
<sel>initWithURL:</sel>
|
|
<arg type="NSURL*">url</arg>
|
|
<sel>cached:</sel>
|
|
<arg type="BOOL">yesno</arg>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void" override="subclass">
|
|
<sel>loadInBackground</sel>
|
|
<desc>
|
|
Starts (or queues) loading of the handle's resource data
|
|
in the background (asynchronously).
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSData*" id ="loadInForeground">
|
|
<sel>loadInForeground</sel>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id" override="subclass">
|
|
<sel>propertyForKey:</sel>
|
|
<arg type="NSString*">propertyKey</arg>
|
|
<desc>
|
|
Returns the property for the specified key, or nil if the
|
|
key does not exist.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="id" override="subclass">
|
|
<sel>propertyForKeyIfAvailable:</sel>
|
|
<arg type="NSString*">propertyKey</arg>
|
|
<desc>
|
|
Returns the property for the specified key, but only if the
|
|
handle does not need to do any work to retrieve it.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>removeClient:</sel>
|
|
<arg type="id<NSURLHandleClient>">client</arg>
|
|
<desc>
|
|
Removes an object from them list of clients notified of
|
|
resource loading events by the URL handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSData*">
|
|
<sel>resourceData</sel>
|
|
<desc>
|
|
Returns the resource data belonging to the handler.
|
|
Calls <ref id="loadInForeground">loadInForeground</ref> if
|
|
necessary.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="NSURLHandleStatus">
|
|
<sel>status</sel>
|
|
<desc>
|
|
Returns the current status of the handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL" override="subclass">
|
|
<sel>writeData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
Writes resource data to the handle. Returns YES on success,
|
|
NO on failure.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL" override="subclass">
|
|
<sel>writeProperty:</sel>
|
|
<arg type="id">propertyValue</arg>
|
|
<sel>forKey:</sel>
|
|
<arg type="NSString*">key</arg>
|
|
<desc>
|
|
Attempts to set property for handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<standards><MacOS-X/><NotOpenStep/></standards>
|
|
</class>
|
|
|
|
<protocol name="NSURLHandleClient">
|
|
<declared>Foundation/NSURLHandle.h</declared>
|
|
<desc>
|
|
</desc>
|
|
|
|
<method type="void">
|
|
<sel>URLHandleResourceDidBeginLoading:</sel>
|
|
<arg type="NSURLHandle*">sender</arg>
|
|
<desc>
|
|
Sent by the NSURLHandle object when it begins loading
|
|
resource data.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>URLHandleResourceDidCancelLoading:</sel>
|
|
<arg type="NSURLHandle*">sender</arg>
|
|
<desc>
|
|
Sent by the NSURLHandle object when resource loading is canceled
|
|
by programmatic request (rather than by failure).
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>URLHandleResourceDidFinishLoading:</sel>
|
|
<arg type="NSURLHandle*">sender</arg>
|
|
<desc>
|
|
Sent by the NSURLHandle object when it completes loading
|
|
resource data.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>URLHandle:</sel>
|
|
<arg type="NSURLHandle*">sender</arg>
|
|
<sel>resourceDidBecomeAvailable:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
Sent by the NSURLHandle object when some data becomes available
|
|
from the handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="void">
|
|
<sel>URLHandle:</sel>
|
|
<arg type="NSURLHandle*">sender</arg>
|
|
<sel>resourceDidFailLoadingWithReason:</sel>
|
|
<arg type="NSString*">reason</arg>
|
|
<desc>
|
|
Sent by the NSURLHandle object on resource load failure.
|
|
Supplies a human readable failure reason.
|
|
</desc>
|
|
</method>
|
|
|
|
<standards><MacOS-X/><NotOpenStep/></standards>
|
|
</protocol>
|
|
|
|
<type name="NSURLHandleStatus">
|
|
<typespec>int</typespec>
|
|
<declared>Foundation/NSURLHandle.h</declared>
|
|
<desc>
|
|
An NSURLHandleStatus is used to report the current state of an
|
|
NSURLHandle object, it can take the following values -
|
|
<list>
|
|
<item>NSURLHandleNotLoaded</item>
|
|
<item>NSURLHandleLoadSucceeded</item>
|
|
<item>NSURLHandleLoadInProgress</item>
|
|
<item>NSURLHandleLoadFailed</item>
|
|
</list>
|
|
</desc>
|
|
<standards><MacOS-X/><NotOpenStep/></standards>
|
|
</type>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<heading>GSFileURLHandle</heading>
|
|
<class name="GSFileURLHandle" super="NSURLHandle" id = "GSFileURLHandle">
|
|
<desc>
|
|
<p>
|
|
This is a <em>PRIVATE</em> 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.
|
|
</p>
|
|
<p>
|
|
A GSFileURLHandle instance is used to manage files on the local
|
|
file-system of your machine.
|
|
</p>
|
|
</desc>
|
|
|
|
<method type="id">
|
|
<sel>propertyForKey:</sel>
|
|
<arg type="NSString*">propertyKey</arg>
|
|
<desc>
|
|
Gets file attribute information for the file represented by
|
|
the handle, using the same dictionary keys as the
|
|
NSFileManager class.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>writeData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
Writes the specified data as the contents of the file
|
|
represented by the handle.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>writeProperty:</sel>
|
|
<arg type="id">propertyValue</arg>
|
|
<sel>forKey:</sel>
|
|
<arg type="NSString*">key</arg>
|
|
<desc>
|
|
Changes the attributes of the file represented by this handle.
|
|
This method uses the same dictionary keys as the NSFileManger
|
|
class.
|
|
</desc>
|
|
</method>
|
|
|
|
<standards><NotMacOS-X/><NotOpenStep/></standards>
|
|
</class>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<heading>GSHTTPURLHandle</heading>
|
|
<class name="GSHTTPURLHandle" super="NSURLHandle" id = "GSHTTPURLHandle">
|
|
<desc>
|
|
<p>
|
|
This is a <em>PRIVATE</em> 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 <code>http</code> or <code>https</code> scheme.
|
|
The name and/or other implementation details of this class
|
|
may be changed at any time.
|
|
</p>
|
|
<p>
|
|
A GSHTTPURLHandle instance is used to manage connections to
|
|
<code>http</code> and <code>https</code> URLs.
|
|
Secure connections are handled automatically
|
|
(using openSSL) for URLs with the scheme <code>https</code>.
|
|
Connection via proxy server is supported, as is proxy tunneling
|
|
for secure connections. Basic parsing of <code>http</code>
|
|
headers is performed to extract <code>http</code> status
|
|
information, cookies etc. Cookies are
|
|
retained and automatically sent during subsequent requests where
|
|
the cookie is valid.
|
|
</p>
|
|
<p>
|
|
Header information from the current page may be obtained using
|
|
-propertyForKey and -propertyForKeyIfAvailable. <code>HTTP</code>
|
|
status information can be retrieved as by calling either of these
|
|
methods specifying one of the following keys:
|
|
</p>
|
|
<list>
|
|
<item>
|
|
NSHTTPPropertyStatusCodeKey - numeric status code
|
|
</item>
|
|
<item>
|
|
NSHTTPPropertyStatusReasonKey - text describing status
|
|
</item>
|
|
<item>
|
|
NSHTTPPropertyServerHTTPVersionKey - <code>http</code>
|
|
version supported by remote server
|
|
</item>
|
|
</list>
|
|
<p>
|
|
According to MacOS-X headers, the following should also
|
|
be supported, but currently are not:
|
|
</p>
|
|
<list>
|
|
<item>NSHTTPPropertyRedirectionHeadersKey</item>
|
|
<item>NSHTTPPropertyErrorPageDataKey</item>
|
|
</list>
|
|
<p>
|
|
The omission of these headers is not viewed as important at
|
|
present, since the MacOS-X public beta implementation doesn't
|
|
work either.
|
|
</p>
|
|
<p>
|
|
Other calls to -propertyForKey and -propertyForKeyIfAvailable may
|
|
be made specifying a <code>http</code> header field name.
|
|
For example specifying a key name of "Content-Length"
|
|
would return the value of the "Content-Length" header
|
|
field.
|
|
</p>
|
|
<p>
|
|
<ref id="GSHTTPURLHandle-writeProperty:forKey:">
|
|
-writeProperty:forKey:</ref> can be used to specify the parameters
|
|
for the <code>http</code> 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").
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</desc>
|
|
|
|
<method type="id">
|
|
<sel>propertyForKey:</sel>
|
|
<arg type="NSString*">propertyKey</arg>
|
|
<desc>
|
|
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 -
|
|
<list>
|
|
<item>
|
|
NSHTTPPropertyStatusCodeKey - numeric status code returned
|
|
by the last request.
|
|
</item>
|
|
<item>
|
|
NSHTTPPropertyStatusReasonKey - text describing status of
|
|
the last request
|
|
</item>
|
|
<item>
|
|
NSHTTPPropertyServerHTTPVersionKey - <code>http</code>
|
|
version supported by remote server
|
|
</item>
|
|
<item>
|
|
Other keys are taken to be the names of <code>http</code>
|
|
headers and the corresponding header value (or nil if there
|
|
is none) is returned.
|
|
</item>
|
|
</list>
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL">
|
|
<sel>writeData:</sel>
|
|
<arg type="NSData*">data</arg>
|
|
<desc>
|
|
Writes the specified data as the body of an <code>http</code>
|
|
or <code>https</code> 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.
|
|
</desc>
|
|
</method>
|
|
|
|
<method type="BOOL" id="GSHTTPURLHandle-writeProperty:forKey:">
|
|
<sel>writeProperty:</sel>
|
|
<arg type="id">propertyValue</arg>
|
|
<sel>forKey:</sel>
|
|
<arg type="NSString*">key</arg>
|
|
<desc>
|
|
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 -
|
|
<list>
|
|
<item>
|
|
GSHTTPPropertyMethodKey - override the default method of
|
|
the request (eg. "PUT").
|
|
</item>
|
|
<item>
|
|
GSHTTPPropertyProxyHostKey - specify the name or IP address
|
|
of a host to proxy through.
|
|
</item>
|
|
<item>
|
|
GSHTTPPropertyProxyPortKey - specify the port number to
|
|
connect to on the proxy host. If not give, this defaults
|
|
to 8080 for <code>http</code> and 4430 for <code>https</code>.
|
|
</item>
|
|
</list>
|
|
</desc>
|
|
</method>
|
|
|
|
<standards><NotMacOS-X/><NotOpenStep/></standards>
|
|
</class>
|
|
</chapter>
|
|
</body>
|
|
</gsdoc>
|