← 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): Sergei Golovan
  • Date: 2009-06-11 12:18:07 UTC
  • mfrom: (1.2.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20090611121807-ks7eb4xrt7dsysgx
Tags: 1:13.b.1-dfsg-1
http://bugs.debian.org/529512
* New upstream release.
* Removed unnecessary dependency of erlang-os-mon on erlang-observer and
  erlang-tools and added missing dependency of erlang-nox on erlang-os-mon
  (closes: #529512).
* Removed a patch to eunit application because the bug was fixed upstream.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/inets/doc/src/http.xml
57
57
    <title>COMMON DATA TYPES </title>
58
58
    <p>Type definitions that are used more than once in
59
59
      this module:</p>
60
 
    <p><c>boolean() = true | false </c></p>
61
 
    <p><c>string() = list of ASCII characters</c></p>
62
 
    <p><c>request_id() = ref() </c></p>
63
 
    <p><c>profile() = atom()</c></p>
64
 
    <p><c>path()  = string() representing a file path or directory path </c></p>  
65
 
  </section>
66
 
  
 
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
 
67
111
  <section>
68
112
    <title>HTTP CLIENT SERVICE START/STOP </title>
69
113
    
86
130
    <p>The client can be stopped using inets:stop(httpc, Pid) or
87
131
    inets:stop(httpc, Profile).</p>
88
132
    
89
 
  </section>
90
 
  
91
 
  <section>
92
 
    <title>HTTP DATA TYPES </title>
93
 
    <p>Type definitions that are related to HTTP:</p>
94
 
    <p>For more information about HTTP see rfc 2616</p>
95
 
 
96
 
    <p><c>method() = head | get | put | post | trace | options | delete </c></p>
97
 
    <p><c>request() - {url(), headers()} |
98
 
      {url(), headers(), content_type(), body()}
99
 
    </c></p>
100
 
    <p><c>url() = string() - Syntax according to the URI definition in rfc 2396, ex: "http://www.erlang.org"</c></p>
101
 
    <p><c>status_line() =
102
 
        {http_version(), status_code(), reason_phrase()}</c></p>
103
 
    <p><c>http_version() = string() ex: "HTTP/1.1" </c></p>
104
 
    <p><c>status_code() = integer()</c></p>
105
 
    <p><c>reason_phrase() = string()</c></p>
106
 
    <p><c>content_type() = string()</c></p>
107
 
    <p><c>headers() = [{field(), value()}]</c></p>
108
 
    <p><c>field() = string() </c></p>
109
 
    <p><c>value() = string() </c></p> 
110
 
    <p><c>body() = string() | binary() </c></p>
111
 
    <p><c>filename = string() </c></p>
112
 
 
113
 
  </section>
114
 
  
115
 
  <section>
116
 
    <title>SSL DATA TYPES </title>
117
 
    <p>Some type definitions relevant when using https,
118
 
      for details <seealso marker="ssl:ssl">ssl(3)</seealso>: </p>
119
 
    <p><c>
120
 
      ssl_options() =
121
 
      {verify, code()} | {depth, depth()} | {certfile, path()}
122
 
      | {keyfile, path()} | {password, string()} | {cacertfile, path()}
123
 
      | {ciphers, string()}     </c></p>
124
 
  </section>
 
133
    <marker id="cancel_request"></marker>
 
134
  </section>
 
135
  
125
136
  <funcs>
126
137
    <func>
127
138
      <name>cancel_request(RequestId) -> </name>
134
145
      </type>
135
146
      <desc>
136
147
        <p>Cancels an asynchronous HTTP-request. </p>
 
148
 
 
149
        <marker id="request1"></marker>
137
150
      </desc>
138
151
    </func>
 
152
 
139
153
    <func>
140
154
      <name>request(Url) -> </name>
141
155
      <name>request(Url, Profile) -> {ok, Result} | {error, Reason}</name>
148
162
      </type>
149
163
      <desc>
150
164
        <p>Equivalent to http:request(get, {Url, []}, [], []).</p>
 
165
 
 
166
        <marker id="request2"></marker>
151
167
      </desc>
152
168
    </func>
 
169
 
153
170
    <func>
154
171
      <name>request(Method, Request, HTTPOptions, Options) -> </name>
155
172
      <name>request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}</name>
215
232
          {http, {RequestId, stream, BinBodyPart},
216
233
          {http, {RequestId, stream_end, Headers} or
217
234
          {http, {RequestId, saved_to_file}}.</p>
 
235
 
 
236
        <marker id="set_options"></marker>
218
237
      </desc>
219
238
    </func>
 
239
 
220
240
    <func>
221
241
      <name>set_options(Options) -> </name>
222
242
      <name>set_options(Options, Profile) -> ok | {error, Reason}</name>
223
243
      <fsummary>Sets options to be used for subsequent requests.</fsummary>
224
244
      <type>
225
245
        <v>Options = [Option]</v>
226
 
        <v>Option = {proxy, {Proxy, NoProxy}} | {max_sessions, MaxSessions}
227
 
        | {max_keep_alive_length, MaxKeepAlive} | {keep_alive_timeout, KeepAliveTimeout} |
228
 
        {max_pipeline_length, MaxPipeline} |  {pipeline_timeout, PipelineTimeout} | {cookies | CookieMode} | {ipv6, Ipv6Mode} | {verbose, VerboseMode}</v>
 
246
        <v>Option = {proxy, {Proxy, NoProxy}} | {max_sessions, MaxSessions} |
 
247
          {max_keep_alive_length, MaxKeepAlive} | {keep_alive_timeout, KeepAliveTimeout} |
 
248
          {max_pipeline_length, MaxPipeline} |  {pipeline_timeout, PipelineTimeout} | 
 
249
          {cookies | CookieMode} | 
 
250
          {ipfamily, IpFamily} | {ip, IpAddress} | {port, Port} | 
 
251
          {verbose, VerboseMode} </v>
229
252
        <v>Proxy = {Hostname, Port}</v>
230
253
        <v>Hostname = string() </v>
231
254
        <d>ex: "localhost" or "foo.bar.se"</d>
238
261
        <v>IpDesc = string()</v>
239
262
        <d>ex: "134.138" or "[FEDC:BA98" (all IP-adresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP-address).</d>
240
263
        <v>MaxSessions = integer() </v>
241
 
        <d>Maximum number of persistent connections to a host.Default is 2. </d>
 
264
        <d>Default is <em>2</em>. 
 
265
          Maximum number of persistent connections to a host.</d>
242
266
        <v>MaxKeepAlive = integer() </v>
243
 
        <d>Maximum number of outstanding requests on the same connection to a host. Default is 2.</d>
 
267
        <d>Default is <em>5</em>. 
 
268
          Maximum number of outstanding requests on the same connection to 
 
269
          a host.</d>
244
270
        <v>KeepAliveTimeout = integer() </v>
245
 
        <d>If a persistent connection is idle longer than the keep_alive_timeout the client will close the connection. Default is 2 min. The server may also have a such a time out but you should not count on it!</d>
246
 
 
 
271
        <d>Default is <em>120000</em> (= 2 min). 
 
272
          If a persistent connection is idle longer than the 
 
273
          keep_alive_timeout the client will close the connection. 
 
274
          The server may also have a such a time out but you should 
 
275
          not count on it!</d>
247
276
        <v>MaxPipeline = integer() </v>
248
 
        <d>Maximum number of outstanding requests on a piplined connection to a host. Default is 2.</d>
 
277
        <d>Default is <em>2</em>. 
 
278
          Maximum number of outstanding requests on a piplined connection to a host.</d>
249
279
        <v>PipelineTimeout = integer() </v>
250
 
        <d>If a persistent connection is idle longer than the pipeline_timeout the client will close the connection. Default is 0 which will result in
251
 
        that pipeling will not be used.</d>
 
280
        <d>Default is <em>0</em>, 
 
281
          which will result in pipeling not being used. 
 
282
          If a persistent connection is idle longer than the 
 
283
          pipeline_timeout the client will close the connection. </d>
252
284
        <v>CookieMode = enabled | disabled | verify </v>
253
 
        <d>Default is disabled. If Cookies are enabled all valid cookies will automatically be saved in the client manager's cookie database. If the option verify is used the function http:verify_cookie/2 has to be called for the cookie to be saved.</d>
254
 
        <v>ipv6Mode = enabled | disabled </v>
255
 
        <d>By default enabled. This should normally be what you want. When it is enabled you can use both ipv4 and ipv6. The option is here to provide a workaround for buggy ipv6 stacks to ensure that ipv4 will always work.</d>
256
 
        <v>VerboseMode = false | verbose |debug | trace </v>
257
 
        <d>By default false. This option unless it is set to false switches on different levels of erlang trace on the client. It is a debug feature.</d>
 
285
        <d>Default is <em>disabled</em>. 
 
286
          If Cookies are enabled all valid cookies will automatically be 
 
287
          saved in the client manager's cookie database. 
 
288
          If the option verify is used the function http:verify_cookie/2 
 
289
          has to be called for the cookie to be saved.</d>
 
290
        <v>IpFamily = inet | inet6 | inet6fb4 </v>
 
291
        <d>By default <em>inet</em>. 
 
292
          When it is set to <c>inet6fb4</c> you can use both ipv4 and ipv6. 
 
293
          It first tries <c>inet6</c> and if that does not works falls back to <c>inet</c>. 
 
294
          The option is here to provide a workaround for buggy ipv6 stacks to ensure that 
 
295
          ipv4 will always work.</d>
 
296
        <v>IpAddress = ip_address() </v>
 
297
        <d>If the host has several network interfaces, this option specifies which one to use. 
 
298
          See gen_tcp:connect/3,4 for more info. </d>
 
299
        <v>Port = integer() </v>
 
300
        <d>Specify which local port number to use. 
 
301
          See gen_tcp:connect/3,4 for more info. </d>
 
302
        <v>VerboseMode = false | verbose | debug | trace </v>
 
303
        <d>Default is <em>false</em>. 
 
304
          This option is used to switch on (or off) 
 
305
          different levels of erlang trace on the client. 
 
306
          It is a debug feature.</d>
258
307
        <v>Profile = profile()</v>
259
308
      </type>
260
309
      <desc>
274
323
            limit of 2 persistent connections per server, which is the
275
324
            default value of the max_sessions option. </p>
276
325
        </note>
 
326
 
 
327
        <marker id="stream_next"></marker>
277
328
      </desc>
278
329
    </func>
279
330
    
287
338
      </type>
288
339
      <desc>
289
340
        <p>Triggers the next message to be streamed, e.i.
290
 
        same behavior as active once for sockets.</p>
 
341
          same behavior as active once for sockets.</p>
 
342
 
 
343
        <marker id="verify_cookie"></marker>
291
344
      </desc>
292
345
    </func>
293
346
    
306
359
          call this function if you set the option cookies to verify.
307
360
          If no profile is specifed the default profile will be used.
308
361
        </p>
 
362
 
 
363
        <marker id="cookie_header"></marker>
309
364
      </desc>
310
365
    </func>
 
366
 
311
367
    <func>
312
368
      <name>cookie_header(Url) -> </name>
313
369
      <name>cookie_header(Url, Profile) -> header() | {error, Rason}</name>