← Back to branch summary

~ubuntu-branches/ubuntu/karmic/gnustep-base/karmic

« back to all changes in this revision

Viewing changes to Documentation/gsdoc/NSURLHandle.gsdoc

  • Committer: Bazaar Package Importer
  • Author(s): Eric Heintzmann
  • Date: 2005-04-17 00:14:38 UTC
  • mfrom: (1.2.1 upstream) (2.1.2 hoary)
  • Revision ID: james.westby@ubuntu.com-20050417001438-enf0y07c9tku85z1
Tags: 1.10.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/gsdoc/NSURLHandle.gsdoc
1
 
<?xml version="1.0"?>
2
 
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
3
 
<gsdoc base="NSURLHandle" prev="NSURL" next="NSUnarchiver" up="Base">
4
 
  <head>
5
 
    <title>NSURLHandle</title>
6
 
    <author name="Richard Frith-Macdonald">
7
 
      <email address="rfm@gnu.org"/>
8
 
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
9
 
    </author>
10
 
    <author name="Mark Allison">
11
 
      <email address="mark@brainstorm.co.uk"/>
12
 
      <url url="http://www.brainstorm.co.uk"/>
13
 
    </author>
14
 
    <version>$Revision: 1.13 $</version>
15
 
    <date>$Date: 2001/12/12 14:10:13 $</date>
16
 
  </head>
17
 
  <body>
18
 
    <chapter>
19
 
      <heading>NSURLHandle</heading>
20
 
      <class name="NSURLHandle" super="NSObject">
21
 
        <declared>Foundation/NSURLHandle.h</declared>
22
 
          <desc>
23
 
            <p>
24
 
              An NSURLHandle instance is used to manage the resource data
25
 
              corresponding to an NSURL object. A single NSURLHandle can
26
 
              be used to manage multiple NSURL objects as long as those
27
 
              objects all refer to the same resource.
28
 
            </p>
29
 
            <p>
30
 
              Different NSURLHandle subclasses are used to manage different
31
 
              types of URL (usually based on the scheme of the URL), and you
32
 
              can register new subclasses to extend (or replace) the
33
 
              standard ones.
34
 
            </p>
35
 
            <p>
36
 
              GNUstep comes with private subclasses to handle the common
37
 
              URL schemes -
38
 
            </p>
39
 
            <list>
40
 
              <item>
41
 
                <ref id="GSFileURLHandle">GSFileURLHandle</ref> for
42
 
                <code>file:</code> (local file I/O)
43
 
              </item>
44
 
              <item>
45
 
                <ref id="GSHTTPURLHandle">GSHTTPURLHandle</ref> for
46
 
                <code>http</code> and <code>shttp</code> (webserver) access.
47
 
              </item>
48
 
            </list>
49
 
          </desc>
50
 
 
51
 
        <method type="Class" factory="yes">
52
 
          <sel>URLHandleClassForURL:</sel>
53
 
          <arg type="NSURL*">anURL</arg>
54
 
          <desc>
55
 
            Returns the most recently registered NSURLHandle subclass that
56
 
            responds to <ref id="canInitWithURL:">canInitWithURL:</ref>
57
 
            with <code>YES</code>.  If there is no such subclass, returns nil.
58
 
          </desc>
59
 
        </method>
60
 
 
61
 
        <method type="NSURLHandle*" factory="yes">
62
 
          <sel>cachedHandleForURL:</sel>
63
 
          <arg type="NSURL*">anURL</arg>
64
 
          <desc>
65
 
            Returns a previously created object that handles the specified
66
 
            URL (if any exists), otherwise returns nil.
67
 
          </desc>
68
 
        </method>
69
 
 
70
 
        <method type="BOOL" factory="yes" id="canInitWithURL:"
71
 
          override="subclass">
72
 
          <sel>canInitWithURL:</sel>
73
 
          <arg type="NSURL*">anURL</arg>
74
 
          <desc>
75
 
            Implemented by subclasses to say which URLs they can handle.
76
 
            This method is used to determine which subclasses can be used
77
 
            to handle a particular URL.
78
 
          </desc>
79
 
        </method>
80
 
 
81
 
        <method type="void" factory="yes">
82
 
          <sel>registerURLHandleClass:</sel>
83
 
          <arg type="Class">anURLHandleSubclass</arg>
84
 
          <desc>
85
 
            Used to register a subclass as being available to handle URLs.
86
 
          </desc>
87
 
        </method>
88
 
 
89
 
        <method type="void">
90
 
          <sel>addClient:</sel>
91
 
          <arg type="id&lt;NSURLHandleClient&gt;">client</arg>
92
 
          <desc>
93
 
            Adds an object conforming to the
94
 
            <ref id="NSURLHandleClient">NSURLHandleClient protocol</ref>
95
 
            as a client of the URL handle.
96
 
          </desc>
97
 
        </method>
98
 
 
99
 
        <method type="NSData*">
100
 
          <sel>availableResourceData</sel>
101
 
          <desc>
102
 
            Returns the resource data that is currently available for the
103
 
            handle.  This may be a partially loaded resource or may be
104
 
            empty of no data has been loaded yet.
105
 
          </desc>
106
 
        </method>
107
 
 
108
 
        <method type="void">
109
 
          <sel>backgroundLoadDidFailWithReason:</sel>
110
 
          <arg type="NSString*">reason</arg>
111
 
          <desc>
112
 
            This method should be called when a background load fails.
113
 
            The method passes the failure notification to the clients of
114
 
            the handle - so subclasses should call super's implementation
115
 
            at the end of their implementation of this method.
116
 
          </desc>
117
 
        </method>
118
 
 
119
 
        <method type="void">
120
 
          <sel>beginLoadInBackground</sel>
121
 
          <desc>
122
 
            This method is called by when a background load begins.
123
 
            Subclasses should call super's implementation at
124
 
            the end of their implementation of this method.
125
 
          </desc>
126
 
        </method>
127
 
 
128
 
        <method type="void" id="cancelLoadInBackground">
129
 
          <sel>cancelLoadInBackground</sel>
130
 
          <desc>
131
 
            This method should be called to cancel a load currently in
132
 
            progress.  The method calls
133
 
            <ref id="endLoadInBackground">endLoadInBackground</ref>
134
 
            Subclasses should call super's implementation at
135
 
            the end of their implementation of this method.
136
 
          </desc>
137
 
        </method>
138
 
 
139
 
        <method type="void">
140
 
          <sel>didLoadBytes:</sel>
141
 
          <arg type="NSData*">newBytes</arg>
142
 
          <sel>loadComplete:</sel>
143
 
          <arg type="BOOL">yorn</arg>
144
 
          <desc>
145
 
            This method must be called by subclasses whenever data is
146
 
            loaded.
147
 
          </desc>
148
 
        </method>
149
 
 
150
 
        <method type="void" id="endLoadInBackground">
151
 
          <sel>endLoadInBackground</sel>
152
 
          <desc>
153
 
            This method is called to stop any background loading process.
154
 
            <ref id="cancelLoadInBackground">cancelLoadInBackground</ref>
155
 
            uses this method to cancel loading.
156
 
            Subclasses should call super's implementation at
157
 
            the end of their implementation of this method.
158
 
          </desc>
159
 
        </method>
160
 
 
161
 
        <method type="NSString*">
162
 
          <sel>failureReason</sel>
163
 
          <desc>
164
 
            Returns the failure reason for the last failure to load
165
 
            the resource data.
166
 
          </desc>
167
 
        </method>
168
 
 
169
 
        <method type="void">
170
 
          <sel>flushCachedData</sel>
171
 
          <desc>
172
 
            Flushes any cached resource data.
173
 
          </desc>
174
 
        </method>
175
 
 
176
 
        <method type="init" init="yes" override="subclass">
177
 
          <sel>initWithURL:</sel>
178
 
          <arg type="NSURL*">url</arg>
179
 
          <sel>cached:</sel>
180
 
          <arg type="BOOL">yesno</arg>
181
 
          <desc>
182
 
            Initialises a handle with the specified URL.
183
 
            The flag determines whether the handle will cache resource data
184
 
            and respond to requests from equivalent URLs for the cached data.
185
 
          </desc>
186
 
        </method>
187
 
 
188
 
        <method type="void" override="subclass">
189
 
          <sel>loadInBackground</sel>
190
 
          <desc>
191
 
            Starts (or queues) loading of the handle's resource data
192
 
            in the background (asynchronously).
193
 
          </desc>
194
 
        </method>
195
 
 
196
 
        <method type="NSData*" id ="loadInForeground">
197
 
          <sel>loadInForeground</sel>
198
 
          <desc>
199
 
            Loads the handle's resource data in the foreground (synchronously).
200
 
            This may be implemented by starting a background load and
201
 
            waiting for it to complete.
202
 
          </desc>
203
 
        </method>
204
 
 
205
 
        <method type="id" override="subclass">
206
 
          <sel>propertyForKey:</sel>
207
 
          <arg type="NSString*">propertyKey</arg>
208
 
          <desc>
209
 
            Returns the property for the specified key, or nil if the
210
 
            key does not exist.
211
 
          </desc>
212
 
        </method>
213
 
 
214
 
        <method type="id" override="subclass">
215
 
          <sel>propertyForKeyIfAvailable:</sel>
216
 
          <arg type="NSString*">propertyKey</arg>
217
 
          <desc>
218
 
            Returns the property for the specified key, but only if the
219
 
            handle does not need to do any work to retrieve it.
220
 
          </desc>
221
 
        </method>
222
 
 
223
 
        <method type="void">
224
 
          <sel>removeClient:</sel>
225
 
          <arg type="id&lt;NSURLHandleClient&gt;">client</arg>
226
 
          <desc>
227
 
            Removes an object from them list of clients notified of
228
 
            resource loading events by the URL handle.
229
 
          </desc>
230
 
        </method>
231
 
 
232
 
        <method type="NSData*">
233
 
          <sel>resourceData</sel>
234
 
          <desc>
235
 
            Returns the resource data belonging to the handler.
236
 
            Calls <ref id="loadInForeground">loadInForeground</ref> if
237
 
            necessary.
238
 
          </desc>
239
 
        </method>
240
 
 
241
 
        <method type="NSURLHandleStatus">
242
 
          <sel>status</sel>
243
 
          <desc>
244
 
            Returns the current status of the handle.
245
 
          </desc>
246
 
        </method>
247
 
 
248
 
        <method type="BOOL" override="subclass">
249
 
          <sel>writeData:</sel>
250
 
          <arg type="NSData*">data</arg>
251
 
          <desc>
252
 
            <p>
253
 
              Writes resource data to the handle.  Returns YES on success,
254
 
              NO on failure.
255
 
            </p>
256
 
            <p>
257
 
              The GNUstep implementation sets the specified data as
258
 
              information to be POSTed to the URL next time it is loaded.
259
 
            </p>
260
 
          </desc>
261
 
        </method>
262
 
 
263
 
        <method type="BOOL" override="subclass">
264
 
          <sel>writeProperty:</sel>
265
 
          <arg type="id">propertyValue</arg>
266
 
          <sel>forKey:</sel>
267
 
          <arg type="NSString*">key</arg>
268
 
          <desc>
269
 
            <p>
270
 
              Sets a property for handle.
271
 
              Returns YES on success, NO on failure.
272
 
            </p>
273
 
            <p>
274
 
              The GNUstep implementation sets the property as a header
275
 
              to be sent the next time the URL is loaded, and recognizes
276
 
              some special property keys which control the behavior of
277
 
              the next load.
278
 
            </p>
279
 
          </desc>
280
 
        </method>
281
 
 
282
 
        <standards><MacOS-X/><NotOpenStep/></standards>
283
 
      </class>
284
 
 
285
 
      <protocol name="NSURLHandleClient">
286
 
        <declared>Foundation/NSURLHandle.h</declared>
287
 
        <desc>
288
 
        </desc>
289
 
 
290
 
        <method type="void">
291
 
          <sel>URLHandleResourceDidBeginLoading:</sel>
292
 
          <arg type="NSURLHandle*">sender</arg>
293
 
          <desc>
294
 
            Sent by the NSURLHandle object when it begins loading
295
 
            resource data.
296
 
          </desc>
297
 
        </method>
298
 
 
299
 
        <method type="void">
300
 
          <sel>URLHandleResourceDidCancelLoading:</sel>
301
 
          <arg type="NSURLHandle*">sender</arg>
302
 
          <desc>
303
 
            Sent by the NSURLHandle object when resource loading is canceled
304
 
            by programmatic request (rather than by failure).
305
 
          </desc>
306
 
        </method>
307
 
 
308
 
        <method type="void">
309
 
          <sel>URLHandleResourceDidFinishLoading:</sel>
310
 
          <arg type="NSURLHandle*">sender</arg>
311
 
          <desc>
312
 
            Sent by the NSURLHandle object when it completes loading
313
 
            resource data.
314
 
          </desc>
315
 
        </method>
316
 
 
317
 
        <method type="void">
318
 
          <sel>URLHandle:</sel>
319
 
          <arg type="NSURLHandle*">sender</arg>
320
 
          <sel>resourceDidBecomeAvailable:</sel>
321
 
          <arg type="NSData*">data</arg>
322
 
          <desc>
323
 
            Sent by the NSURLHandle object when some data becomes available
324
 
            from the handle.
325
 
          </desc>
326
 
        </method>
327
 
 
328
 
        <method type="void">
329
 
          <sel>URLHandle:</sel>
330
 
          <arg type="NSURLHandle*">sender</arg>
331
 
          <sel>resourceDidFailLoadingWithReason:</sel>
332
 
          <arg type="NSString*">reason</arg>
333
 
          <desc>
334
 
            Sent by the NSURLHandle object on resource load failure.
335
 
            Supplies a human readable failure reason.
336
 
          </desc>
337
 
        </method>
338
 
 
339
 
        <standards><MacOS-X/><NotOpenStep/></standards>
340
 
      </protocol>
341
 
 
342
 
      <type name="NSURLHandleStatus">
343
 
        <typespec>int</typespec>
344
 
        <declared>Foundation/NSURLHandle.h</declared>
345
 
        <desc>
346
 
          An NSURLHandleStatus is used to report the current state of an
347
 
          NSURLHandle object, it can take the following values -
348
 
          <list>
349
 
            <item>NSURLHandleNotLoaded</item>
350
 
            <item>NSURLHandleLoadSucceeded</item>
351
 
            <item>NSURLHandleLoadInProgress</item>
352
 
            <item>NSURLHandleLoadFailed</item>
353
 
          </list>
354
 
        </desc>
355
 
        <standards><MacOS-X/><NotOpenStep/></standards>
356
 
      </type>
357
 
    </chapter>
358
 
 
359
 
    <chapter>
360
 
      <heading>GSFileURLHandle</heading>
361
 
      <class name="GSFileURLHandle" super="NSURLHandle" id = "GSFileURLHandle">
362
 
        <desc>
363
 
          <p>
364
 
            This is a <em>PRIVATE</em> subclass of NSURLHandle.
365
 
            It is documented here in order to give you information about the
366
 
            default behavior of an NSURLHandle created to deal with a URL
367
 
            that has the FILE scheme.  The name and/or other
368
 
            implementation details of this class may be changed at any time.
369
 
          </p>
370
 
          <p>
371
 
            A GSFileURLHandle instance is used to manage files on the local
372
 
            file-system of your machine.
373
 
          </p>
374
 
        </desc>
375
 
 
376
 
        <method type="id">
377
 
          <sel>propertyForKey:</sel>
378
 
          <arg type="NSString*">propertyKey</arg>
379
 
          <desc>
380
 
            Gets file attribute information for the file represented by
381
 
            the handle, using the same dictionary keys as the
382
 
            NSFileManager class.
383
 
          </desc>
384
 
        </method>
385
 
 
386
 
        <method type="BOOL">
387
 
          <sel>writeData:</sel>
388
 
          <arg type="NSData*">data</arg>
389
 
          <desc>
390
 
            Writes the specified data as the contents of the file
391
 
            represented by the handle.
392
 
          </desc>
393
 
        </method>
394
 
 
395
 
        <method type="BOOL">
396
 
          <sel>writeProperty:</sel>
397
 
          <arg type="id">propertyValue</arg>
398
 
          <sel>forKey:</sel>
399
 
          <arg type="NSString*">key</arg>
400
 
          <desc>
401
 
            Changes the attributes of the file represented by this handle.
402
 
            This method uses the same dictionary keys as the NSFileManger
403
 
            class.
404
 
          </desc>
405
 
        </method>
406
 
 
407
 
        <standards><NotMacOS-X/><NotOpenStep/></standards>
408
 
      </class>
409
 
    </chapter>
410
 
 
411
 
    <chapter>
412
 
      <heading>GSHTTPURLHandle</heading>
413
 
      <class name="GSHTTPURLHandle" super="NSURLHandle" id = "GSHTTPURLHandle">
414
 
        <desc>
415
 
          <p>
416
 
            This is a <em>PRIVATE</em> subclass of NSURLHandle.
417
 
            It is documented here in order to give you information about the
418
 
            default behavior of an NSURLHandle created to deal with a URL
419
 
            that has either the <code>http</code> or <code>https</code> scheme.
420
 
            The name and/or other implementation details of this class
421
 
            may be changed at any time.
422
 
          </p>
423
 
          <p>
424
 
            A GSHTTPURLHandle instance is used to manage connections to
425
 
            <code>http</code> and <code>https</code> URLs.
426
 
             Secure connections are handled automatically
427
 
            (using openSSL) for URLs with the scheme <code>https</code>.
428
 
            Connection via proxy server is supported, as is proxy tunneling
429
 
            for secure connections.  Basic parsing of <code>http</code>
430
 
            headers is performed to extract <code>http</code> status
431
 
            information, cookies etc.  Cookies are
432
 
            retained and automatically sent during subsequent requests where
433
 
            the cookie is valid.
434
 
          </p>
435
 
          <p>
436
 
            Header information from the current page may be obtained using
437
 
            -propertyForKey and -propertyForKeyIfAvailable.  <code>HTTP</code>
438
 
            status information can be retrieved as by calling either of these 
439
 
            methods specifying one of the following keys:
440
 
          </p>
441
 
          <list>
442
 
            <item>
443
 
              NSHTTPPropertyStatusCodeKey - numeric status code
444
 
            </item>
445
 
            <item>
446
 
              NSHTTPPropertyStatusReasonKey - text describing status
447
 
            </item>
448
 
            <item>
449
 
              NSHTTPPropertyServerHTTPVersionKey - <code>http</code>
450
 
              version supported by remote server
451
 
            </item>
452
 
          </list>
453
 
          <p>
454
 
            According to MacOS-X headers, the following should also
455
 
            be supported, but currently are not:
456
 
          </p>
457
 
          <list>
458
 
            <item>NSHTTPPropertyRedirectionHeadersKey</item>
459
 
            <item>NSHTTPPropertyErrorPageDataKey</item>
460
 
          </list>
461
 
          <p>
462
 
            The omission of these headers is not viewed as important at
463
 
            present, since the MacOS-X public beta implementation doesn't
464
 
            work either.
465
 
          </p>
466
 
          <p>
467
 
            Other calls to -propertyForKey and -propertyForKeyIfAvailable may
468
 
            be made specifying a <code>http</code> header field name.
469
 
            For example specifying a key name of &quot;Content-Length&quot;
470
 
            would return the value of the &quot;Content-Length&quot; header
471
 
            field.
472
 
          </p>
473
 
          <p>
474
 
            <ref id="GSHTTPURLHandle-writeProperty:forKey:">
475
 
            -writeProperty:forKey:</ref> can be used to specify the parameters
476
 
            for the <code>http</code> request.  The default request uses the
477
 
            &quot;GET&quot; method when fetching a page, and the
478
 
            &quot;POST&quot; method when using -writeData:.
479
 
            This can be over-ridden by calling -writeProperty:forKey: with
480
 
            the key name &quot;GSHTTPPropertyMethodKey&quot; and specifying an 
481
 
            alternative method (i.e &quot;PUT&quot;).
482
 
          </p>
483
 
          <p>
484
 
            A Proxy may be specified by calling -writeProperty:forKey:
485
 
            with the keys &quot;GSHTTPPropertyProxyHostKey&quot; and
486
 
            &quot;GSHTTPPropertyProxyPortKey&quot; to set the host and port
487
 
            of the proxy server respectively.  The GSHTTPPropertyProxyHostKey
488
 
            property can be set to either the IP address or the hostname of
489
 
            the proxy server.  If an attempt is made to load a page via a
490
 
            secure connection when a proxy is specified, GSHTTPURLHandle will
491
 
            attempt to open an SSL Tunnel through the proxy.
492
 
          </p>
493
 
        </desc>
494
 
 
495
 
        <method type="id">
496
 
          <sel>propertyForKey:</sel>
497
 
          <arg type="NSString*">propertyKey</arg>
498
 
          <desc>
499
 
            If necessary, this method calls -loadInForeground to send a
500
 
            request to the webserver, and get a page back.  It then returns
501
 
            the property for the specified key -
502
 
            <list>
503
 
              <item>
504
 
                NSHTTPPropertyStatusCodeKey - numeric status code returned
505
 
                by the last request.
506
 
              </item>
507
 
              <item>
508
 
                NSHTTPPropertyStatusReasonKey - text describing status of
509
 
                the last request
510
 
              </item>
511
 
              <item>
512
 
                NSHTTPPropertyServerHTTPVersionKey - <code>http</code>
513
 
                version supported by remote server
514
 
              </item>
515
 
              <item>
516
 
                Other keys are taken to be the names of <code>http</code>
517
 
                headers and the corresponding header value (or nil if there
518
 
                is none) is returned.
519
 
              </item>
520
 
            </list>
521
 
          </desc>
522
 
        </method>
523
 
 
524
 
        <method type="BOOL">
525
 
          <sel>writeData:</sel>
526
 
          <arg type="NSData*">data</arg>
527
 
          <desc>
528
 
            Writes the specified data as the body of an <code>http</code>
529
 
            or <code>https</code> request to the web server.
530
 
            Returns YES on success,
531
 
            NO on failure.  By default, this method performs a POST operation.
532
 
            On completion, the resource data for this handle is set to the
533
 
            page returned by the request.
534
 
          </desc>
535
 
        </method>
536
 
 
537
 
        <method type="BOOL" id="GSHTTPURLHandle-writeProperty:forKey:">
538
 
          <sel>writeProperty:</sel>
539
 
          <arg type="id">propertyValue</arg>
540
 
          <sel>forKey:</sel>
541
 
          <arg type="NSString*">key</arg>
542
 
          <desc>
543
 
            Sets a property to be used in the next request made by this handle.
544
 
            The property is set as a header in the next request, unless it is
545
 
            one of the following -
546
 
            <list>
547
 
              <item>
548
 
                GSHTTPPropertyBodyKey - set an NSData item to be sent to
549
 
                the server as the body of the request.
550
 
              </item>
551
 
              <item>
552
 
                GSHTTPPropertyMethodKey - override the default method of
553
 
                the request (eg. &quot;PUT&quot;).
554
 
              </item>
555
 
              <item>
556
 
                GSHTTPPropertyProxyHostKey - specify the name or IP address
557
 
                of a host to proxy through.
558
 
              </item>
559
 
              <item>
560
 
                GSHTTPPropertyProxyPortKey - specify the port number to 
561
 
                connect to on the proxy host.  If not give, this defaults
562
 
                to 8080 for <code>http</code> and 4430 for <code>https</code>.
563
 
              </item>
564
 
            </list>
565
 
          </desc>
566
 
        </method>
567
 
 
568
 
        <standards><NotMacOS-X/><NotOpenStep/></standards>
569
 
      </class>
570
 
    </chapter>
571
 
  </body>
572
 
</gsdoc>