← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/inets/doc/src/http.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/inets/doc/src/http.xml
1
 
<?xml version="1.0" encoding="latin1" ?>
2
 
<!DOCTYPE erlref SYSTEM "erlref.dtd">
3
 
 
4
 
<erlref>
5
 
  <header>
6
 
    <copyright>
7
 
      <year>2004</year><year>2009</year>
8
 
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
 
    </copyright>
10
 
    <legalnotice>
11
 
      The contents of this file are subject to the Erlang Public License,
12
 
      Version 1.1, (the "License"); you may not use this file except in
13
 
      compliance with the License. You should have received a copy of the
14
 
      Erlang Public License along with this software. If not, it can be
15
 
      retrieved online at http://www.erlang.org/.
16
 
    
17
 
      Software distributed under the License is distributed on an "AS IS"
18
 
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
 
      the License for the specific language governing rights and limitations
20
 
      under the License.
21
 
    
22
 
    </legalnotice>
23
 
 
24
 
    <title>http</title>
25
 
    <prepared>Ingela Anderton Andin</prepared>
26
 
    <responsible></responsible>
27
 
    <docno></docno>
28
 
    <date></date>
29
 
    <rev></rev>
30
 
  </header>
31
 
  <module>http</module>
32
 
  <modulesummary>An HTTP/1.1 client </modulesummary>
33
 
  <description>
34
 
    <p>This module provides the API to a HTTP/1.1 client according to
35
 
      RFC 2616, caching is currently not supported.</p>
36
 
    <note>
37
 
      <p>When starting the Inets application a manager process for the
38
 
        default profile will be started. The functions in this API
39
 
        that does not explicitly use a profile will accesses the
40
 
        default profile. A profile keeps track of proxy options,
41
 
        cookies and other options that can be applied to more than one
42
 
        request. </p>
43
 
 
44
 
      <p>If the scheme
45
 
        https is used the ssl application needs to be started.</p>
46
 
 
47
 
      <p>Also note that pipelining will only be used if the pipeline
48
 
      timeout is set, otherwise persistent connections without
49
 
      pipelining will be used e.i. the  client always waits for
50
 
      the previous response before sending the next request.</p>
51
 
    </note>
52
 
    <p>There are some usage examples in the <seealso
53
 
    marker="http_client">Inets User's Guide.</seealso></p>
54
 
  </description>
55
 
  
56
 
  <section>
57
 
    <title>COMMON DATA TYPES </title>
58
 
    <p>Type definitions that are used more than once in
59
 
      this module:</p>
60
 
    <code type="none"><![CDATA[
61
 
boolean()    = true | false 
62
 
string()     = list of ASCII characters 
63
 
request_id() = ref() 
64
 
profile()    = atom()
65
 
path()       = string() representing a file path or directory path 
66
 
ip_address() = See inet(3)
67
 
    ]]></code>
68
 
 
69
 
  </section>
70
 
  
71
 
  <section>
72
 
    <title>HTTP DATA TYPES </title>
73
 
    <p>Type definitions that are related to HTTP:</p>
74
 
    <p>For more information about HTTP see rfc 2616</p>
75
 
 
76
 
    <code type="none"><![CDATA[
77
 
method()        = head | get | put | post | trace | options | delete
78
 
request()       = {url(), headers()} | 
79
 
                  {url(), headers(), content_type(), body()}
80
 
url()           = string() - Syntax according to the URI definition in rfc 2396, ex: "http://www.erlang.org"
81
 
status_line()   = {http_version(), status_code(), reason_phrase()}
82
 
http_version()  = string() ex: "HTTP/1.1"
83
 
status_code()   = integer()
84
 
reason_phrase() = string()
85
 
content_type()  = string()
86
 
headers()       = [header()]
87
 
header()        = {field(), value()}
88
 
field()         = string() 
89
 
value()         = string() 
90
 
body()          = string() | binary() 
91
 
filename()      = string() 
92
 
    ]]></code>
93
 
 
94
 
  </section>
95
 
  
96
 
  <section>
97
 
    <title>SSL DATA TYPES </title>
98
 
    <p>Some type definitions relevant when using https,
99
 
      for details <seealso marker="ssl:ssl">ssl(3)</seealso>: </p>
100
 
    <code type="none"><![CDATA[
101
 
ssl_options() = {verify,     code()}   | 
102
 
                {depth,      depth()}  | 
103
 
                {certfile,   path()}   | 
104
 
                {keyfile,    path()}   | 
105
 
                {password,   string()} | 
106
 
                {cacertfile, path()}   | 
107
 
                {ciphers,    string()} 
108
 
    ]]></code>
109
 
  </section>
110
 
 
111
 
  <section>
112
 
    <title>HTTP CLIENT SERVICE START/STOP </title>
113
 
    
114
 
    <p>A HTTP client can be configured to start when starting the inets
115
 
      application or started dynamically in runtime by calling the
116
 
      inets application API <c>inets:start(httpc, ServiceConfig)</c>, or
117
 
      <c>inets:start(httpc,  ServiceConfig, How)</c>
118
 
      see <seealso marker="inets">inets(3)</seealso> Below follows a
119
 
      description of the available configuration options.</p>
120
 
    <taglist>
121
 
      <tag>{profile, profile()}</tag>
122
 
      <item>Name of the profile, see
123
 
        common data types below, this option is mandatory.</item>
124
 
      <tag>{data_dir, path()}</tag>
125
 
      <item>Directory where the profile
126
 
        may save persistent data, if omitted all cookies will be treated
127
 
        as session cookies.</item>
128
 
    </taglist>
129
 
 
130
 
    <p>The client can be stopped using inets:stop(httpc, Pid) or
131
 
    inets:stop(httpc, Profile).</p>
132
 
    
133
 
    <marker id="cancel_request"></marker>
134
 
  </section>
135
 
  
136
 
  <funcs>
137
 
    <func>
138
 
      <name>cancel_request(RequestId) -> </name>
139
 
      <name>cancel_request(RequestId, Profile) -> ok</name>
140
 
      <fsummary>Cancels an asynchronous HTTP-request.</fsummary>
141
 
      <type>
142
 
        <v>RequestId = request_id() - A unique identifier as returned
143
 
        by request/4</v>
144
 
        <v>Profile = profile()</v>
145
 
      </type>
146
 
      <desc>
147
 
        <p>Cancels an asynchronous HTTP-request. </p>
148
 
 
149
 
        <marker id="request1"></marker>
150
 
      </desc>
151
 
    </func>
152
 
 
153
 
    <func>
154
 
      <name>request(Url) -> </name>
155
 
      <name>request(Url, Profile) -> {ok, Result} | {error, Reason}</name>
156
 
      <fsummary>Sends a get HTTP-request</fsummary>
157
 
      <type>
158
 
        <v>Url = url() </v> <v>Result = {status_line(), headers(),
159
 
        body()} | {status_code(), body()} | request_id() </v>
160
 
        <v>Profile = profile()</v>
161
 
        <v>Reason = term() </v>
162
 
      </type>
163
 
      <desc>
164
 
        <p>Equivalent to http:request(get, {Url, []}, [], []).</p>
165
 
 
166
 
        <marker id="request2"></marker>
167
 
      </desc>
168
 
    </func>
169
 
 
170
 
    <func>
171
 
      <name>request(Method, Request, HTTPOptions, Options) -> </name>
172
 
      <name>request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}</name>
173
 
      
174
 
      <fsummary>Sends a HTTP-request</fsummary>
175
 
      <type>
176
 
        <v>Method = method() </v>
177
 
        <v>Request = request()</v>
178
 
        <v>HTTPOptions = http_options()</v>
179
 
        <v>http_options() = [http_option()]</v>
180
 
        <v>http_option() = {timeout, timeout()} | 
181
 
                           {connect_timeout, timeout()} | 
182
 
                           {ssl, ssl_options()} | 
183
 
                           {autoredirect, boolean()} | 
184
 
                           {proxy_auth, {userstring(), passwordstring()}} | 
185
 
                           {version, http_version()} | 
186
 
                           {relaxed, boolean()}</v>
187
 
        <v>timeout() = integer() >= 0 | infinity</v>
188
 
        <v>Options = options()</v>
189
 
        <v>options() = [option()]</v>
190
 
        <v>option() = {sync, boolean()} | 
191
 
                      {stream, stream_to()} | 
192
 
                      {body_format, body_format()} | 
193
 
                      {full_result, boolean()} | 
194
 
                      {headers_as_is, boolean()}</v>
195
 
        <v>stream_to() = self | {self, once} | filename() </v>
196
 
        <v>body_format() = string() | binary() </v>
197
 
        <v>Result = {status_line(), headers(), body()} | 
198
 
                    {status_code(), body()} | request_id() </v>
199
 
        <v>Profile = profile() </v>
200
 
        <v>Reason = term() </v>
201
 
      </type>
202
 
 
203
 
      <desc>
204
 
        <p>Sends a HTTP-request. The function can be both synchronous
205
 
          and asynchronous. In the later case the function will return
206
 
          {ok, RequestId} and later on message(s) will be sent to the
207
 
          calling process on the format: </p>
208
 
<pre>
209
 
          {http, {RequestId, Result}}
210
 
          {http, {RequestId, {error, Reason}}}
211
 
          {http, {RequestId, stream_start, Headers}
212
 
          {http, {RequestId, stream, BinBodyPart}
213
 
          {http, {RequestId, stream_end, Headers}
214
 
          {http, {RequestId, saved_to_file}}.
215
 
</pre>
216
 
 
217
 
        <p>Http option (<c>http_option()</c>) details: </p>
218
 
        <taglist>
219
 
          <tag><c><![CDATA[timeout]]></c></tag>
220
 
          <item>
221
 
            <p>Timeout time for the request. </p>
222
 
            <p>Defaults to <c>infinity</c>. </p>
223
 
          </item>
224
 
 
225
 
          <tag><c><![CDATA[connect_timeout]]></c></tag>
226
 
          <item>
227
 
            <p>Connection timeout time, used during the initial request, 
228
 
              when the client is connecting to the server. </p>
229
 
            <p>Defaults to the value of the <c>timeout</c> option. </p>
230
 
          </item>
231
 
 
232
 
          <tag><c><![CDATA[ssl]]></c></tag>
233
 
          <item>
234
 
            <p>If using SSL, these SSL-specific options are used. </p>
235
 
            <p>Defaults to <c>[]</c>. </p>
236
 
          </item>
237
 
 
238
 
          <tag><c><![CDATA[autoredirect]]></c></tag>
239
 
          <item>
240
 
            <p>Should the client automatically retreive the information 
241
 
              from the new URI and return that as the result instead 
242
 
              of a 30X-result code. </p>
243
 
            <p>Note that for some 30X-result codes automatic redirect 
244
 
              is not allowed in these cases the 30X-result will always 
245
 
              be returned. </p>
246
 
            <p>Defaults to <c>true</c>. </p>
247
 
          </item>
248
 
 
249
 
          <tag><c><![CDATA[proxy_auth]]></c></tag>
250
 
          <item>
251
 
            <p>A proxy-authorization header using the provided user name and 
252
 
              password will be added to the request. </p>
253
 
          </item>
254
 
 
255
 
          <tag><c><![CDATA[version]]></c></tag>
256
 
          <item>
257
 
            <p>Can be used to make the client act as an <c>HTTP/1.0</c> or
258
 
              <c>HTTP/0.9</c> client. By default this is an <c>HTTP/1.1</c> 
259
 
              client. When using <c>HTTP/1.0</c> persistent connections will 
260
 
              not be used. </p>
261
 
            <p>Defaults to the trsing <c>"HTTP/1.1"</c>. </p>
262
 
          </item>
263
 
 
264
 
          <tag><c><![CDATA[relaxed]]></c></tag>
265
 
          <item>
266
 
            <p>If set to true workarounds for known server deviations from
267
 
              the HTTP-standard are enabled. </p>
268
 
            <p>Defaults to <c>false</c>. </p>
269
 
          </item>
270
 
 
271
 
        </taglist>
272
 
 
273
 
        <p>Option (<c>option()</c>) details: </p>
274
 
        <taglist>
275
 
          <tag><c><![CDATA[sync]]></c></tag>
276
 
          <item>
277
 
            <p>Shall the request be synchronous or asynchronous. </p>
278
 
            <p>Defaults to <c>true</c>. </p>
279
 
          </item>
280
 
 
281
 
          <tag><c><![CDATA[stream]]></c></tag>
282
 
          <item>
283
 
            <p>Streams the body of a 200 or 206 response to the calling 
284
 
              process or to a file. When streaming to the calling process 
285
 
              using the option <c>self</c> the the following stream messages
286
 
              will be sent to that process: {http, {RequestId,
287
 
              stream_start, Headers}, {http, {RequestId, stream,
288
 
              BinBodyPart}, {http, {RequestId, stream_end, Headers}. When
289
 
              streaming to to the calling processes using the option
290
 
              <c>{self once}</c> the first message will have an additional
291
 
              element e.i. {http, {RequestId, stream_start, Headers, Pid},
292
 
              this is the process id that should be used as an argument to
293
 
              http:stream_next/1 to trigger the next message to be sent to
294
 
              the calling process. </p>
295
 
            <p>Note that it is possible that chunked encoding will add
296
 
              headers so that there are more headers in the stream_end
297
 
              message than in the stream_start.
298
 
              When streaming to a file and the request is asynchronous the
299
 
              message {http, {RequestId, saved_to_file}} will be sent. </p>
300
 
            <p>Defaults to <c>none</c>. </p>
301
 
          </item>
302
 
 
303
 
          <tag><c><![CDATA[body_format]]></c></tag>
304
 
          <item>
305
 
            <p>Defines if the body shall be delivered as a string or as a 
306
 
              binary. This option is only valid for the synchronous 
307
 
              request. </p>
308
 
            <p>Defaults to <c>string</c>. </p>
309
 
          </item>
310
 
 
311
 
          <tag><c><![CDATA[full_result]]></c></tag>
312
 
          <item>
313
 
            <p>Should a "full result" be returned to the caller (that is,
314
 
              the body, the headers and the entire status-line) or not 
315
 
              (the body and the status code). </p>
316
 
            <p>Defaults to <c>true</c>. </p>
317
 
          </item>
318
 
 
319
 
          <tag><c><![CDATA[header_as_is]]></c></tag>
320
 
          <item>
321
 
            <p>Shall the headers provided by the user be made 
322
 
              lower case or be regarded as case sensitive. </p>
323
 
            <p>Note that the http standard requires them to be 
324
 
              case insenstive. This feature should only be used if there is 
325
 
              no other way to communicate with the server or for testing 
326
 
              purpose. Also note that when this option is used no headers 
327
 
              will be automatically added, all necessary headers has to be 
328
 
              provided by the user. </p>
329
 
            <p>Defaults to <c>false</c>. </p>
330
 
          </item>
331
 
 
332
 
        </taglist>
333
 
 
334
 
        <marker id="set_options"></marker>
335
 
      </desc>
336
 
    </func>
337
 
 
338
 
    <func>
339
 
      <name>set_options(Options) -> </name>
340
 
      <name>set_options(Options, Profile) -> ok | {error, Reason}</name>
341
 
      <fsummary>Sets options to be used for subsequent requests.</fsummary>
342
 
      <type>
343
 
        <v>Options = [Option]</v>
344
 
        <v>Option = {proxy, {Proxy, NoProxy}} | {max_sessions, MaxSessions} |
345
 
          {max_keep_alive_length, MaxKeepAlive} | {keep_alive_timeout, KeepAliveTimeout} |
346
 
          {max_pipeline_length, MaxPipeline} |  {pipeline_timeout, PipelineTimeout} | 
347
 
          {cookies | CookieMode} | 
348
 
          {ipfamily, IpFamily} | {ip, IpAddress} | {port, Port} | 
349
 
          {verbose, VerboseMode} </v>
350
 
        <v>Proxy = {Hostname, Port}</v>
351
 
        <v>Hostname = string() </v>
352
 
        <d>ex: "localhost" or "foo.bar.se"</d>
353
 
        <v>Port = integer()</v>
354
 
        <d>ex: 8080 </d>
355
 
        <v>NoProxy = [NoProxyDesc]</v>
356
 
        <v>NoProxyDesc = DomainDesc | HostName | IPDesc</v>
357
 
        <v>DomainDesc = "*.Domain"</v>
358
 
        <d>ex: "*.ericsson.se"</d>
359
 
        <v>IpDesc = string()</v>
360
 
        <d>ex: "134.138" or "[FEDC:BA98" (all IP-addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP-address).</d>
361
 
        <v>MaxSessions = integer() </v>
362
 
        <d>Default is <em>2</em>. 
363
 
          Maximum number of persistent connections to a host.</d>
364
 
        <v>MaxKeepAlive = integer() </v>
365
 
        <d>Default is <em>5</em>. 
366
 
          Maximum number of outstanding requests on the same connection to 
367
 
          a host.</d>
368
 
        <v>KeepAliveTimeout = integer() </v>
369
 
        <d>Default is <em>120000</em> (= 2 min). 
370
 
          If a persistent connection is idle longer than the 
371
 
          keep_alive_timeout the client will close the connection. 
372
 
          The server may also have a such a time out but you should 
373
 
          not count on it!</d>
374
 
        <v>MaxPipeline = integer() </v>
375
 
        <d>Default is <em>2</em>. 
376
 
          Maximum number of outstanding requests on a pipelined connection to a host.</d>
377
 
        <v>PipelineTimeout = integer() </v>
378
 
        <d>Default is <em>0</em>, 
379
 
          which will result in pipelining not being used. 
380
 
          If a persistent connection is idle longer than the 
381
 
          pipeline_timeout the client will close the connection. </d>
382
 
        <v>CookieMode = enabled | disabled | verify </v>
383
 
        <d>Default is <em>disabled</em>. 
384
 
          If Cookies are enabled all valid cookies will automatically be 
385
 
          saved in the client manager's cookie database. 
386
 
          If the option verify is used the function http:verify_cookie/2 
387
 
          has to be called for the cookie to be saved.</d>
388
 
        <v>IpFamily = inet | inet6 | inet6fb4 </v>
389
 
        <d>By default <em>inet</em>. 
390
 
          When it is set to <c>inet6fb4</c> you can use both ipv4 and ipv6. 
391
 
          It first tries <c>inet6</c> and if that does not works falls back to <c>inet</c>. 
392
 
          The option is here to provide a workaround for buggy ipv6 stacks to ensure that 
393
 
          ipv4 will always work.</d>
394
 
        <v>IpAddress = ip_address() </v>
395
 
        <d>If the host has several network interfaces, this option specifies which one to use. 
396
 
          See gen_tcp:connect/3,4 for more info. </d>
397
 
        <v>Port = integer() </v>
398
 
        <d>Specify which local port number to use. 
399
 
          See gen_tcp:connect/3,4 for more info. </d>
400
 
        <v>VerboseMode = false | verbose | debug | trace </v>
401
 
        <d>Default is <em>false</em>. 
402
 
          This option is used to switch on (or off) 
403
 
          different levels of erlang trace on the client. 
404
 
          It is a debug feature.</d>
405
 
        <v>Profile = profile()</v>
406
 
      </type>
407
 
      <desc>
408
 
        <p>Sets options to be used for subsequent
409
 
          requests.</p>
410
 
        <note>
411
 
          <p>If possible the client will keep its connections
412
 
            alive and use persistent connections
413
 
            with  or without pipeline depending on configuration
414
 
            and current circumstances. The HTTP/1.1 specification does not
415
 
            provide a guideline for how many requests that would be
416
 
            ideal to be sent on a persistent connection,
417
 
            this very much depends on the
418
 
            application. Note that a very long queue of requests may cause a
419
 
            user perceived delays as earlier request may take a long time
420
 
            to complete. The HTTP/1.1 specification does suggest a
421
 
            limit of 2 persistent connections per server, which is the
422
 
            default value of the max_sessions option. </p>
423
 
        </note>
424
 
 
425
 
        <marker id="stream_next"></marker>
426
 
      </desc>
427
 
    </func>
428
 
    
429
 
     <func>
430
 
      <name>stream_next(Pid) -> ok</name>
431
 
      <fsummary> Triggers the next message to be streamed, e.i.
432
 
        same behavior as active once for sockets.
433
 
      </fsummary>
434
 
      <type>
435
 
        <v>Pid = pid() - as received in the stream_start message</v>
436
 
      </type>
437
 
      <desc>
438
 
        <p>Triggers the next message to be streamed, e.i.
439
 
          same behavior as active once for sockets.</p>
440
 
 
441
 
        <marker id="verify_cookie"></marker>
442
 
      </desc>
443
 
    </func>
444
 
    
445
 
    <func>
446
 
      <name>verify_cookie(SetCookieHeaders, Url) -> </name>
447
 
      <name>verify_cookie(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name>
448
 
      <fsummary>Saves the cookies defined in SetCookieHeaders in the client profile's cookie database.</fsummary>
449
 
      <type>
450
 
        <v>SetCookieHeaders = headers() - where field = "set-cookie"</v>
451
 
        <v>Url = url()</v>
452
 
        <v>Profile = profile()</v>
453
 
      </type>
454
 
      <desc>
455
 
        <p>Saves the cookies defined in SetCookieHeaders
456
 
          in the client profile's cookie database. You need to
457
 
          call this function if you set the option cookies to verify.
458
 
          If no profile is specified the default profile will be used.
459
 
        </p>
460
 
 
461
 
        <marker id="cookie_header"></marker>
462
 
      </desc>
463
 
    </func>
464
 
 
465
 
    <func>
466
 
      <name>cookie_header(Url) -> </name>
467
 
      <name>cookie_header(Url, Profile) -> header() | {error, Rason}</name>
468
 
      <fsummary>Returns the cookie header that would be sent when
469
 
      making a request to Url using the profile Profile.</fsummary>
470
 
      <type>
471
 
        <v>Url = url()</v>
472
 
        <v>Profile = profile()</v>
473
 
      </type>
474
 
      <desc>
475
 
        <p>Returns the cookie header that would be sent
476
 
          when making a request to Url using the profile Profile.
477
 
          If no profile is specified the default profile will be used.
478
 
        </p>
479
 
      </desc>
480
 
    </func>
481
 
  </funcs>
482
 
 
483
 
  <section>
484
 
    <title>SEE ALSO</title>
485
 
    <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>,
486
 
      <seealso marker="ssl:ssl">ssl(3)</seealso>
487
 
    </p>
488
 
  </section>
489
 
  
490
 
</erlref>
491