source: project/wiki/eggref/4/http-client @ 15029

Last change on this file since 15029 was 15029, checked in by sjamaan, 11 years ago

Document some parameters

File size: 6.0 KB
Line 
1[[tags: egg]]
2
3== http-client
4
5[[toc:]]
6
7=== Description
8
9Http-client is a highlevel HTTP client library.
10
11=== Author
12
13[[Peter Bex]]
14
15=== Requirements
16
17Requires the [[intarweb]] and [[openssl]] extensions.
18
19=== Documentation
20
21This egg is still very much under development; the API should be
22considered to be unstable and can change heavily from version to
23version.
24
25==== Main request procedures
26
27All these procedures accept [[intarweb]] {{request}} objects,
28[[uri-common]] {{uri}} objects or strings.  In case of an
29{{uri-common}} object, {{(make-request uri: uri-common)}} is used to
30convert the URI object to a request object.  In case of a string, the
31string is first converted to a URI-common object and then converted to
32a request object.  The upshot of all this is that it becomes extremely
33easy to perform basic {{GET}} requests.
34
35<procedure>(call-with-response uri-or-request [writer] reader)</procedure>
36
37This is the core http-client procedure.  It is only necessary to use
38this when you want the most control over the request/response cycle.
39{{uri-or-request}} is the request object, uri or string that contains
40information about the request to perform.  {{reader}} is a procedure
41that receives the response object and should read the request body,
42{{writer}} is an optional procedure that receives the request object
43and should write the request body.
44
45The {{writer}} should be prepared to be called several times; if the
46response is a redirect or some other status that indicates the server
47wants the client to perform a new request, the writer should be ready
48to write a request body for this new request.
49
50Returns three values: The result of the call to {{reader}}, the
51request-uri of the last request and the response object. The
52request-uri is useful because this is to be used as the base uri of
53the document. This can differ from the initial request in the presence
54of redirects.
55
56<procedure>(call-with-input-request uri-or-request reader)</procedure>
57
58This procedure simply calls the {{reader}} with one argument: an input
59port from which the response body can be read.
60
61Returns three values: The result of the call to {{reader}}, the
62request-uri of the last request and the response object.  If the
63response code is not in the 200 class, it will throw an exception of
64type {{client-error}}, {{server-error}} or
65{{unexpected-server-response}}, depending on the response code.  This
66includes {{404 not found}} (which is a {{client-error}}).
67
68<procedure>(with-input-request uri-or-request thunk)</procedure>
69
70Same as {{call-with-input-request}}, except this accepts a thunk
71(lambda of no arguments) which will be executed with
72{{current-input-port}} bound to the response port.
73
74<example>
75<init>(use http-client)</init>
76<expr>(with-input-from-request "http://chicken.wiki.br/" read-string)</expr>
77<result>"[the chicken wiki page HTML contents]"</result>
78</example>
79
80==== Parameters
81
82<parameter>(max-retry-attempts [number])</parameter>
83
84When a request fails because of an I/O or network problem (or simply
85because the remote end closed a persistent connection while we were
86doing something else), the library will try to establish a new
87connection and perform the request again.  This parameter controls how
88many times this is allowed to be done.  If {{#f}}, it will never give up.
89
90Defaults to 1.
91
92<parameter>(retry-request? [predicate])</procedure>
93
94This procedure is invoked when a retry should take place, to determine
95if it should take place at all.  It should be a procedure accepting a
96request object and returning {{#f}} or a true value.  If the value is
97true, the new request will be sent.  Otherwise, the error that caused
98the retry attempt will be re-raised.
99
100Defaults to {{idempotent?}}, from [[intarweb]].  This is because
101non-idempotent requests cannot be safely retried when it is unknown
102whether the previous request reached the server or not.
103
104<parameter>(max-redirect-depth [number])</procedure>
105
106The maximum number of allowed redirects, or {{#f}} if there is no
107limit.  Currently there's no automatic redirect loop detection
108algorithm implemented.
109
110Defaults to 5.
111
112<parameter>(client-software [software-spec])</procedure>
113
114This is the names, versions and comments of the software packages that
115the client is using, for use in the {{user-agent}} header which is
116automatically added to each request.
117
118Defaults to {{(("Chicken Scheme HTTP-client" VERSION #f))}}, where
119{{VERSION}} is the version of this egg.
120
121==== Connection management
122
123TODO
124
125=== Changelog
126
127* 0.1 Initial version
128
129=== License
130
131  Copyright (c) 2008-2009, Peter Bex
132  Parts copyright (c) 2000-2004, Felix L. Winkelmann
133  All rights reserved.
134 
135  Redistribution and use in source and binary forms, with or without
136  modification, are permitted provided that the following conditions are
137  met:
138 
139  Redistributions of source code must retain the above copyright
140  notice, this list of conditions and the following disclaimer.
141 
142  Redistributions in binary form must reproduce the above copyright
143  notice, this list of conditions and the following disclaimer in the
144  documentation and/or other materials provided with the distribution.
145 
146  Neither the name of the author nor the names of its contributors may
147  be used to endorse or promote products derived from this software
148  without specific prior written permission.
149 
150  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
151  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
152  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
153  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
154  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
155  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
156  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
157  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
158  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
159  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
160  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
161  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.