1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="next" href="Http_client.key.html">
<link rel="Up" href="Http_client.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Http_client_mt" rel="Chapter" href="Http_client_mt.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html"><link title="Call State" rel="Section" href="#2_CallState">
<link title="Accessing the request message (new style) " rel="Section" href="#2_Accessingtherequestmessagenewstyle">
<link title="Accessing the response message (new style) " rel="Section" href="#2_Accessingtheresponsemessagenewstyle">
<link title="Options" rel="Section" href="#2_Options">
<link title="Method characteristics" rel="Section" href="#2_Methodcharacteristics">
<link title="Repeating calls" rel="Section" href="#2_Repeatingcalls">
<link title="Old style access methods" rel="Section" href="#2_Oldstyleaccessmethods">
<link title="Private" rel="Section" href="#2_Private">
<title>The Netclient Manual : Http_client.http_call</title>
</head>
<body>
<div class="navbar"> <a href="Http_client.html">Up</a>
<a href="Http_client.key.html">Next</a>
</div>
<center><h1>Class type <a href="type_Http_client.http_call.html">Http_client.http_call</a></h1></center>
<br>
<pre><span class="keyword">class type</span> <a name="TYPEhttp_call"></a>http_call = <code class="code">object</code> <a href="Http_client.http_call.html">..</a> <code class="code">end</code></pre>The container for HTTP calls<br>
<hr width="100%">
<code class="code">http_call</code> is the runtime container for HTTP method calls. It contains
the request message, the response message, and the current transmission
status.
<p>
In previous versions of netclient, this class type was called
<code class="code">message</code>. This was quite inexact because this class embraces both
messages that are part of a call.
<p>
<b>Incompatible changes</b>:<ul>
<li><code class="code">using_proxy</code> has been removed. This simply isn't a property of
an individual call.</li>
<li><code class="code">get_req_uri</code> has been removed from the public interface for similar
reasons.</li>
<li>The request and response messages are now primarily stored as
<code class="code">Netmime.mime_header</code> and <code class="code">Netmime.mime_body</code> objects. The old
style access methods remain in the API for now. The advantage is
that it is possible to use external files as body containers.</li>
<li>There are two request headers, <code class="code">`Base</code> and <code class="code">`Effective</code>.</li>
</ul>
<a name="2_CallState"></a>
<h2>Call State</h2><pre><span class="keyword">method</span> <a name="METHODis_served"></a>is_served : <code class="type">bool</code></pre><div class="info">
<code class="code">true</code> if request/response cycle(s) have been finished, i.e. the
call was successful, or a final error state has been reached.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODstatus"></a>status : <code class="type"><a href="Http_client.html#TYPEstatus">status</a></code></pre><div class="info">
The condensed status<br>
</div>
<a name="2_Accessingtherequestmessagenewstyle"></a>
<h2>Accessing the request message (new style) </h2><pre><span class="keyword">method</span> <a name="METHODrequest_method"></a>request_method : <code class="type">string</code></pre><div class="info">
The HTTP method as string<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODrequest_uri"></a>request_uri : <code class="type">string</code></pre><div class="info">
The request URI as string. This is always an absolute URI in the
form "http://server/path".<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_request_uri"></a>set_request_uri : <code class="type">string -> unit</code></pre><div class="info">
Sets the request URI<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODrequest_header"></a>request_header : <code class="type"><a href="Http_client.html#TYPEheader_kind">header_kind</a> -> Netmime.mime_header</code></pre><div class="info">
The whole header of the request. Users of this class should only
modify the <code class="code">`Base</code> header. After the call has been processed,
the <code class="code">`Effective</code> header contains the version of the header that has
actually been transmitted.
<p>
The user should set the following headers:<ul>
<li><code class="code">Content-length</code>: Set this to the length of the request body
if known. (The client falls back to HTTP 1.0 if not set!)</li>
<li><code class="code">Content-type</code>: Set this to the media type of the request body</li>
<li><code class="code">Expect</code>: Set this to "100-continue" to enable a handshake before
the body is sent. Recommended for large bodies.</li>
</ul>
The following headers may be set, but there are reasonable defaults:<ul>
<li><code class="code">Date</code></li>
<li><code class="code">User-agent</code></li>
</ul>
The following headers must not be set:<ul>
<li><code class="code">Connection</code></li>
</ul>
<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_request_header"></a>set_request_header : <code class="type">Netmime.mime_header -> unit</code></pre><div class="info">
Replaces the whole <code class="code">`Base</code> header object<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODeffective_request_uri"></a>effective_request_uri : <code class="type">string</code></pre><div class="info">
The URI actually sent to the server in the request line of the
protocol.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODrequest_body"></a>request_body : <code class="type">Netmime.mime_body</code></pre><div class="info">
The whole body of the request<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_request_body"></a>set_request_body : <code class="type">Netmime.mime_body -> unit</code></pre><div class="info">
Replaces the whole body object<br>
</div>
<a name="2_Accessingtheresponsemessagenewstyle"></a>
<h2>Accessing the response message (new style) </h2>
<p>
These method will fail if the call has not yet been served!
If the call has been finished, but was not successful, the
exception <code class="code">Http_protocol</code> is raised.<pre><span class="keyword">method</span> <a name="METHODresponse_status_code"></a>response_status_code : <code class="type">int</code></pre><div class="info">
The three-digit status code<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODresponse_status_text"></a>response_status_text : <code class="type">string</code></pre><div class="info">
The text transmitted along with the code<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODresponse_protocol"></a>response_protocol : <code class="type">string</code></pre><div class="info">
The HTTP version indicated in the response<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODresponse_header"></a>response_header : <code class="type">Netmime.mime_header</code></pre><div class="info">
The whole header of the response. If the call has not succeeded,
<code class="code">Http_protocol</code> will be raised.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODresponse_body"></a>response_body : <code class="type">Netmime.mime_body</code></pre><div class="info">
The whole body of the response. If the call has not succeeded,
<code class="code">Http_protocol</code> will be raised. If the call has succeeded,
but no body has been transmitted, the empty body is substituted.<br>
</div>
<a name="2_Options"></a>
<h2>Options</h2><pre><span class="keyword">method</span> <a name="METHODresponse_body_storage"></a>response_body_storage : <code class="type"><a href="Http_client.html#TYPEresponse_body_storage">response_body_storage</a></code></pre><div class="info">
How to create the response body. Defaults to <code class="code">`Memory</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_response_body_storage"></a>set_response_body_storage : <code class="type"><a href="Http_client.html#TYPEresponse_body_storage">response_body_storage</a> -> unit</code></pre><div class="info">
Sets how to create the response body<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_reconnect_mode"></a>get_reconnect_mode : <code class="type"><a href="Http_client.http_call.html">http_call</a> <a href="Http_client.html#TYPEhow_to_reconnect">how_to_reconnect</a></code></pre><div class="info">
Get what to do if the server needs to be reconnected, i.e.
if the request must be sent repeatedly.
By default, this is <code class="code">Send_again_if_idem</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_reconnect_mode"></a>set_reconnect_mode : <code class="type"><a href="Http_client.http_call.html">http_call</a> <a href="Http_client.html#TYPEhow_to_reconnect">how_to_reconnect</a> -> unit</code></pre><div class="info">
Sets the reconnect mode<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_redirect_mode"></a>get_redirect_mode : <code class="type"><a href="Http_client.http_call.html">http_call</a> <a href="Http_client.html#TYPEhow_to_redirect">how_to_redirect</a></code></pre><div class="info">
By default, the redirect mode is <code class="code">Redirect_if_idem</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_redirect_mode"></a>set_redirect_mode : <code class="type"><a href="Http_client.http_call.html">http_call</a> <a href="Http_client.html#TYPEhow_to_redirect">how_to_redirect</a> -> unit</code></pre><div class="info">
Sets the redirect mode<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODproxy_enabled"></a>proxy_enabled : <code class="type">bool</code></pre><div class="info">
Returns the proxy mode<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_proxy_enabled"></a>set_proxy_enabled : <code class="type">bool -> unit</code></pre><div class="info">
Sets the proxy mode<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODno_proxy"></a>no_proxy : <code class="type">unit -> unit</code></pre><div class="info">
Same as <code class="code">set_proxy_enabled false</code><br>
</div>
<pre><span class="keyword">method</span> <a name="METHODis_proxy_allowed"></a>is_proxy_allowed : <code class="type">unit -> bool</code></pre><div class="info">
<b>Deprecated.</b> Same as <code class="code">proxy_enabled</code><br>
</div>
<a name="2_Methodcharacteristics"></a>
<h2>Method characteristics</h2>
<p>
These properties describe the HTTP method<pre><span class="keyword">method</span> <a name="METHODempty_path_replacement"></a>empty_path_replacement : <code class="type">string</code></pre><div class="info">
The string to substitute in the request line for the empty
path. This is usually "/", and for OPTIONS it is "*".<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODis_idempotent"></a>is_idempotent : <code class="type">bool</code></pre><div class="info">
Whether the method is to be considered as idempotent ( = repeated
invocations have the same result and no side effect). This is
true for GET and HEAD.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODhas_req_body"></a>has_req_body : <code class="type">bool</code></pre><div class="info">
Whether the method allows to send a request body<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODhas_resp_body"></a>has_resp_body : <code class="type">bool</code></pre><div class="info">
Whether the method allows to reply with a body. This is true
except for HEAD.<br>
</div>
<a name="2_Repeatingcalls"></a>
<h2>Repeating calls</h2><pre><span class="keyword">method</span> <a name="METHODsame_call"></a>same_call : <code class="type">unit -> <a href="Http_client.http_call.html">http_call</a></code></pre><div class="info">
This method returns a new object that will perform the same call
as this object (this function is called "reload" in browsers).
The new object is initialized as follows:<ul>
<li>The state is set to <code class="code">`Unserved</code></li>
<li>The request method remains the same (the class of the returned
object remains the same)</li>
<li>The request URI is the same string as the original URI</li>
<li>The base request header is the same object</li>
<li>The request body is the same object</li>
<li>Options like reconnect, redirect mode, and proxy mode are
copied.</li>
</ul>
<br>
</div>
<a name="2_Oldstyleaccessmethods"></a>
<h2>Old style access methods</h2>
<p>
These method were introduced in previous versions of netclient,
but are quite limited. Some questionable methods are now deprecated
and will be removed in future versions of netclient.<pre><span class="keyword">method</span> <a name="METHODget_req_method"></a>get_req_method : <code class="type">unit -> string</code></pre><div class="info">
Get the name of the request method. Same as <code class="code">request_method</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_host"></a>get_host : <code class="type">unit -> string</code></pre><div class="info">
The host name of the content server, extracted from the URI<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_port"></a>get_port : <code class="type">unit -> int</code></pre><div class="info">
The port number of the content server, extracted from the URI<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_path"></a>get_path : <code class="type">unit -> string</code></pre><div class="info">
The path extracted from the URI<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_uri"></a>get_uri : <code class="type">unit -> string</code></pre><div class="info">
the full URI of this message: http://server:port/path. If the
path is empty, it is omitted. - Same as <code class="code">request_uri</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_req_body"></a>get_req_body : <code class="type">unit -> string</code></pre><div class="info">
What has been sent as body in the (last) request. Same as
<code class="code">request_body # value</code>.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_req_header"></a>get_req_header : <code class="type">unit -> (string * string) list</code></pre><div class="info">
<b>Deprecated.</b>
What has been sent as header in the (last) request. Returns
(key, value) pairs, where the keys are all in lowercase.
<p>
In new code, the <code class="code">request_header</code> object should be accessed instead.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODassoc_req_header"></a>assoc_req_header : <code class="type">string -> string</code></pre><div class="info">
Query a specific header entry, or raise <code class="code">Not_found</code><br>
</div>
<pre><span class="keyword">method</span> <a name="METHODassoc_multi_req_header"></a>assoc_multi_req_header : <code class="type">string -> string list</code></pre><div class="info">
Return all header values for a given field name (header entries
which allow several values separated by commas can also be
transmitted by several header lines with the same name).<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODset_req_header"></a>set_req_header : <code class="type">string -> string -> unit</code></pre><pre><span class="keyword">method</span> <a name="METHODget_resp_header"></a>get_resp_header : <code class="type">unit -> (string * string) list</code></pre><div class="info">
<b>Deprecated.</b>
Get the header of the last response. The keys are in lowercase
characters again.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODassoc_resp_header"></a>assoc_resp_header : <code class="type">string -> string</code></pre><div class="info">
Query a specific header entry of the response.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODassoc_multi_resp_header"></a>assoc_multi_resp_header : <code class="type">string -> string list</code></pre><div class="info">
Return all response header values for a given field name (header
entries which allow several values separated by commas can also be
transmitted by several header lines with the same name).<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODget_resp_body"></a>get_resp_body : <code class="type">unit -> string</code></pre><div class="info">
<b>Deprecated.</b>
Returns the body of the last response if the response status
is OK (i.e. the code is in the range 200 to 299).
<p>
Otherwise, Http_error (code, body) is raised where 'code' is
the response code and 'body' is the body of the (errorneous)
response.<br>
</div>
<pre><span class="keyword">method</span> <a name="METHODdest_status"></a>dest_status : <code class="type">unit -> string * int * string</code></pre><div class="info">
Returns the status line of the last response (but status lines
with code 100 are ignored).
The returned triple is (http_string, code, text)<br>
</div>
<a name="2_Private"></a>
<h2>Private</h2><pre><span class="keyword">method</span> <a name="METHODprivate_api"></a>private_api : <code class="type"><a href="Http_client.html#TYPEprivate_api">private_api</a></code></pre></body></html>
|
