1httpc(3)                   Erlang Module Definition                   httpc(3)
2
3
4

NAME

6       httpc - An HTTP/1.1 client
7

DESCRIPTION

9       This module provides the API to an HTTP/1.1 compatible client according
10       to RFC 2616. Caching is not supported.
11
12   Note:
13       When starting the Inets application, a manager process for the  default
14       profile  is  started.  The functions in this API that do not explicitly
15       use a profile accesses the default profile. A profile  keeps  track  of
16       proxy  options,  cookies, and other options that can be applied to more
17       than one request.
18
19       If the scheme https is used, the SSL application must be started.  When
20       https links need to go through a proxy, the CONNECT method extension to
21       HTTP-1.1 is used to establish a  tunnel  and  then  the  connection  is
22       upgraded  to  TLS.  However,  "TLS upgrade" according to RFC 2817is not
23       supported.
24
25       Pipelining is only used if the pipeline time-out is set, otherwise per‐
26       sistent  connections  without  pipelining are used. That is, the client
27       always waits for the previous response before sending the next request.
28
29
30       Some examples are provided in the Inets User's Guide.
31

DATA TYPES

33       Type definitions that are used more than once in this module:
34
35       boolean() = true | false
36
37       string() = list of ASCII characters
38
39       request_id() = reference()
40
41       profile() = atom()
42
43       path() = string() representing a file path or directory path
44
45       ip_address() = See the inet(3) manual page in Kernel.
46
47       socket_opt() = See the options used by gen_tcp(3) gen_tcp(3) and ssl(3)
48       connect(s)
49

HTTP DATA TYPES

51       Type definitions related to HTTP:
52
53       method() = head | get | put | post | trace | options | delete | patch
54
55         request():
56           = {url(), headers()}
57
58           | {url(), headers(), content_type(), body()}
59
60       url()  =  string()  syntax according to the URI definition in RFC 2396,
61       for example "http://www.erlang.org"
62
63       status_line() = {http_version(), status_code(), reason_phrase()}
64
65       http_version() = string(), for example, "HTTP/1.1"
66
67       status_code() = integer()
68
69       reason_phrase() = string()
70
71       content_type() = string()
72
73       headers() = [header()]
74
75       header() = {field(), value()}
76
77       field() = string()
78
79       value() = string()
80
81         body():
82           = string() | binary()
83
84           | {fun(accumulator())
85
86            -> body_processing_result(), accumulator()}
87
88           | {chunkify, fun(accumulator())
89
90            -> body_processing_result(), accumulator()}
91
92       body_processing_result() = eof | {ok, iolist(), accumulator()}
93
94       accumulator() = term()
95
96       filename() = string()
97
98       For more information about HTTP, see RFC 2616.
99

SSL DATA TYPES

101       See ssl(3) for information about SSL options (ssloptions()).
102

HTTP CLIENT SERVICE START/STOP

104       An HTTP client can be configured  to  start  when  starting  the  Inets
105       application  or  started  dynamically  in  runtime by calling the Inets
106       application API inets:start(httpc, ServiceConfig) or inets:start(httpc,
107       ServiceConfig,  How),  see  inets(3).  The configuration options are as
108       follows:
109
110         {profile, profile()}:
111           Name of the profile, see DATA TYPES. This option is mandatory.
112
113         {data_dir, path()}:
114           Directory where the profile can save persistent data.  If  omitted,
115           all cookies are treated as session cookies.
116
117       The   client   can   be   stopped   using   inets:stop(httpc,  Pid)  or
118       inets:stop(httpc, Profile).
119

EXPORTS

121       cancel_request(RequestId) ->
122       cancel_request(RequestId, Profile) -> ok
123
124              Types:
125
126                 RequestId = request_id() - A unique identifier as returned by
127                 request/4
128                 Profile = profile() | pid()
129                   When started stand_alone only the pid can be used.
130
131              Cancels  an asynchronous HTTP request. Notice that this does not
132              guarantee that the request response is not delivered. Because it
133              is  asynchronous,  the  request  can already have been completed
134              when the cancellation arrives.
135
136       cookie_header(Url) ->
137       cookie_header(Url, Profile | Opts) -> header() | {error, Reason}
138       cookie_header(Url, Opts, Profile) -> header() | {error, Reason}
139
140              Types:
141
142                 Url = url()
143                 Opts = [cookie_header_opt()]
144                 Profile = profile() | pid()
145                   When started stand_alone.
146                 cookie_header_opt() = {ipv6_host_with_brackets, boolean()}
147
148              Returns the cookie header that would have been sent when  making
149              a  request to Url using profile Profile. If no profile is speci‐
150              fied, the default profile is used.
151
152              Option ipv6_host_with_bracket  deals  with  how  to  parse  IPv6
153              addresses. For details, see argument Options of request/[4,5].
154
155       get_options(OptionItems) -> {ok, Values} | {error, Reason}
156       get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}
157
158              Types:
159
160                 OptionItems = all | [option_item()]
161                 option_item()   =   proxy  |  https_proxy  |  max_sessions  |
162                 keep_alive_timeout | max_keep_alive_length | pipeline_timeout
163                 |  max_pipeline_length  |  cookies  |  ipfamily | ip | port |
164                 socket_opts | verbose | unix_socket
165                 Profile = profile() | pid()
166                   When started stand_alone only the pid can used.
167                 Values = [{option_item(), term()}]
168                 Reason = term()
169
170              Retrieves the options currently used by the client.
171
172       info() -> list()
173       info(Profile) -> list()
174
175              Types:
176
177                 Profile = profile() | pid()
178                   When started stand_alone only the pid can be used.
179
180              Produces a  list  of  miscellaneous  information.  Intended  for
181              debugging.  If  no  profile is specified, the default profile is
182              used.
183
184       reset_cookies() -> void()
185       reset_cookies(Profile) -> void()
186
187              Types:
188
189                 Profile = profile() | pid()
190                   When started stand_alone only the pid can be used.
191
192              Resets (clears) the cookie database for the  specified  Profile.
193              If no profile is specified the default profile is used.
194
195       request(Url) ->
196       request(Url, Profile) -> {ok, Result} | {error, Reason}
197
198              Types:
199
200                 Url = url()
201                 Result  =  {status_line(), headers(), Body} | {status_code(),
202                 Body} | request_id()
203                 Body = string() | binary()
204                 Profile = profile() | pid()
205                   When started stand_alone only the pid can be used.
206                 Reason = term()
207
208              Equivalent to httpc:request(get, {Url, []}, [], []).
209
210       request(Method, Request, HTTPOptions, Options) ->
211       request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result}
212       | {ok, saved_to_file} | {error, Reason}
213
214              Types:
215
216                 Method = method()
217                 Request = request()
218                 HTTPOptions = http_options()
219                 http_options() = [http_option()]
220                 http_option()  =  {timeout,  timeout()}  |  {connect_timeout,
221                 timeout()} | {ssl, ssloptions()}  |  {essl,  ssloptions()}  |
222                 {autoredirect, boolean()} | {proxy_auth, {userstring(), pass‐
223                 wordstring()}} | {version, http_version()} | {relaxed,  bool‐
224                 ean()}
225                 timeout() = integer() >= 0 | infinity
226                 Options = options()
227                 options() = [option()]
228                 option()  =  {sync,  boolean()}  |  {stream,  stream_to()}  |
229                 {body_format, body_format()}  |  {full_result,  boolean()}  |
230                 {headers_as_is,  boolean()  |  {socket_opts, socket_opts()} |
231                 {receiver, receiver()} | {ipv6_host_with_brackets, boolean()}
232                 stream_to() = none | self | {self, once} | filename()
233                 socket_opts() = [socket_opt()]
234                 receiver() = pid() | function()/1 | {Module, Function, Args}
235                 Module = atom()
236                 Function = atom()
237                 Args = list()
238                 body_format() = string | binary
239                 Result = {status_line(), headers(), Body}  |  {status_code(),
240                 Body} | request_id()
241                 Body = string() | binary()
242                 Profile = profile() | pid()
243                   When started stand_alone only the pid can be used.
244                 Reason = term()
245
246              Sends  an HTTP request. The function can be both synchronous and
247              asynchronous. In the latter  case,  the  function  returns  {ok,
248              RequestId} and then the information is delivered to the receiver
249              depending on that value.
250
251              HTTP option (http_option()) details:
252
253                timeout:
254                  Time-out time for the request.
255
256                  The clock starts ticking when the request is sent.
257
258                  Time is in milliseconds.
259
260                  Default is infinity.
261
262                connect_timeout:
263                  Connection time-out time, used during the  initial  request,
264                  when the client is connecting to the server.
265
266                  Time is in milliseconds.
267
268                  Default is the value of option timeout.
269
270                ssl:
271                  This is the SSL/TLS connectin configuration option.
272
273                  Defaults   to  [].  See  ssl:connect/[2,3,4]  for  available
274                  options.
275
276                autoredirect:
277                  The client automatically retrieves the information from  the
278                  new  URI  and  returns that as the result, instead of a 30X-
279                  result code.
280
281                  For  some  30X-result  codes,  automatic  redirect  is   not
282                  allowed. In these cases the 30X-result is always returned.
283
284                  Default is true.
285
286                proxy_auth:
287                  A proxy-authorization header using the provided username and
288                  password is added to the request.
289
290                version:
291                  Can be used to  make  the  client  act  as  an  HTTP/1.0  or
292                  HTTP/0.9 client. By default this is an HTTP/1.1 client. When
293                  using HTTP/1.0 persistent connections are not used.
294
295                  Default is the string "HTTP/1.1".
296
297                relaxed:
298                  If set to true, workarounds for known server deviations from
299                  the HTTP-standard are enabled.
300
301                  Default is false.
302
303              Option (option()) details:
304
305                sync:
306                  Option for the request to be synchronous or asynchronous.
307
308                  Default is true.
309
310                stream:
311                  Streams  the  body  of  a 200 or 206 response to the calling
312                  process or to a file. When streaming to the calling  process
313                  using option self, the following stream messages are sent to
314                  that process: {http,  {RequestId,  stream_start,  Headers}},
315                  {http,   {RequestId,   stream,   BinBodyPart}},  and  {http,
316                  {RequestId, stream_end, Headers}}.
317
318                  When streaming to the calling processes using option  {self,
319                  once},  the  first  message  has  an extra element, that is,
320                  {http, {RequestId, stream_start, Headers, Pid}}. This is the
321                  process  id to be used as an argument to httpc:stream_next/1
322                  to trigger the next  message  to  be  sent  to  the  calling
323                  process.
324
325                  Notice  that  chunked encoding can add headers so that there
326                  are  more  headers  in  the  stream_end  message   than   in
327                  stream_start.  When  streaming  to a file and the request is
328                  asynchronous, the message {http, {RequestId, saved_to_file}}
329                  is sent.
330
331                  Default is none.
332
333                body_format:
334                  Defines  if  the  body  is  to  be  delivered as a string or
335                  binary. This  option  is  only  valid  for  the  synchronous
336                  request.
337
338                  Default is string.
339
340                full_result:
341                  Defines  if  a "full result" is to be returned to the caller
342                  (that is, the body, the headers, and the entire status line)
343                  or not (the body and the status code).
344
345                  Default is true.
346
347                headers_as_is:
348                  Defines  if  the headers provided by the user are to be made
349                  lower case or to be regarded as case sensitive.
350
351                  The HTTP standard requires them to be case insensitive.  Use
352                  this  feature  only  if there is no other way to communicate
353                  with the server or for testing purpose. When this option  is
354                  used,  no  headers  are  automatically  added. All necessary
355                  headers must be provided by the user.
356
357                  Default is false.
358
359                socket_opts:
360                  Socket options to be used for this request.
361
362                  Overrides any value set by function set_options.
363
364                  The validity of the options  is  not  checked  by  the  HTTP
365                  client  they  are assumed to be correct and passed on to ssl
366                  application and inet driver, which may reject them  if  they
367                  are not correct.
368
369            Note:
370                Persistent  connections  are  not  supported  when setting the
371                socket_opts option. When socket_opts is not  set  the  current
372                implementation  assumes  the  requests  to the same host, port
373                combination will use the same socket options.
374
375
376                  By   default   the   socket   options   set   by    function
377                  set_options/[1,2] are used when establishing a connection.
378
379                receiver:
380                  Defines  how  the client delivers the result of an asynchro‐
381                  nous request (sync has the value false).
382
383                  pid():
384                    Messages are sent to this process  in  the  format  {http,
385                    ReplyInfo}.
386
387                  function/1:
388                    Information  is delivered to the receiver through calls to
389                    the provided fun Receiver(ReplyInfo).
390
391                  {Module, Function, Args}:
392                    Information is delivered to the receiver through calls  to
393                    the callback function apply(Module, Function, [ReplyInfo |
394                    Args]).
395
396                  In all of these cases, ReplyInfo has  the  following  struc‐
397                  ture:
398
399                {RequestId, saved_to_file}
400                {RequestId, {error, Reason}}
401                {RequestId, Result}
402                {RequestId, stream_start, Headers}
403                {RequestId, stream_start, Headers, HandlerPid}
404                {RequestId, stream, BinBodyPart}
405                {RequestId, stream_end, Headers}
406
407                  Default  is the pid of the process calling the request func‐
408                  tion (self()).
409
410                ipv6_host_with_brackets:
411                  Defines when parsing the Host-Port part of an  URI  with  an
412                  IPv6  address  with  brackets,  if  those brackets are to be
413                  retained (true) or stripped (false).
414
415                  Default is false.
416
417       set_options(Options) ->
418       set_options(Options, Profile) -> ok | {error, Reason}
419
420              Types:
421
422                 Options = [Option]
423                 Option = {proxy, {Proxy, NoProxy}}
424                 | {https_proxy, {Proxy, NoProxy}}
425                 | {max_sessions, MaxSessions}
426                 | {max_keep_alive_length, MaxKeepAlive}
427                 | {keep_alive_timeout, KeepAliveTimeout}
428                 | {max_pipeline_length, MaxPipeline}
429                 | {pipeline_timeout, PipelineTimeout}
430                 | {cookies, CookieMode}
431                 | {ipfamily, IpFamily}
432                 | {ip, IpAddress}
433                 | {port, Port}
434                 | {socket_opts, socket_opts()}
435                 | {verbose, VerboseMode}
436                 | {unix_socket, UnixSocket}
437                 Proxy = {Hostname, Port}
438                 Hostname = string()
439                   Example: "localhost" or "foo.bar.se"
440                 Port = integer()
441                   Example: 8080
442                 NoProxy = [NoProxyDesc]
443                 NoProxyDesc = DomainDesc | HostName | IPDesc
444                 DomainDesc = "*.Domain"
445                   Example: "*.ericsson.se"
446                 IpDesc = string()
447                   Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
448                   ing   with   134.138   or  FEDC:BA98),  "66.35.250.150"  or
449                   "[2010:836B:4179::836B:4179]"  (a  complete  IP   address).
450                   proxy  defaults  to  {undefined,  []}, that is, no proxy is
451                   configured and https_proxy defaults to the value of proxy.
452                 MaxSessions = integer()
453                   Maximum number of persistent connections to a host. Default
454                   is 2.
455                 MaxKeepAlive = integer()
456                   Maximum  number of outstanding requests on the same connec‐
457                   tion to a host. Default is 5.
458                 KeepAliveTimeout = integer()
459                   If  a  persistent  connection  is  idle  longer  than   the
460                   keep_alive_timeout  in  milliseconds, the client closes the
461                   connection. The server can also have such a time-out but do
462                   not take that for granted. Default is 120000 (= 2 min).
463                 MaxPipeline = integer()
464                   Maximum  number of outstanding requests on a pipelined con‐
465                   nection to a host. Default is 2.
466                 PipelineTimeout = integer()
467                   If a persistent connection is idle longer  than  the  pipe‐
468                   line_timeout in milliseconds, the client closes the connec‐
469                   tion. Default is 0, which results in pipelining  not  being
470                   used.
471                 CookieMode = enabled | disabled | verify
472                   If cookies are enabled, all valid cookies are automatically
473                   saved in the cookie database  of  the  client  manager.  If
474                   option  verify  is used, function store_cookies/2 has to be
475                   called for the cookies to be saved. Default is disabled.
476                 IpFamily = inet | inet6 | local
477                   Default is inet.
478                 IpAddress = ip_address()
479                   If the host has several  network  interfaces,  this  option
480                   specifies  which  one  to  use. See gen_tcp:connect/3,4 for
481                   details.
482                 Port = integer()
483                   Local port  number  to  use.  See  gen_tcp:connect/3,4  for
484                   details.
485                 socket_opts() = [socket_opt()]
486                   The  options are appended to the socket options used by the
487                   client. These are the default values  when  a  new  request
488                   handler  is  started  (for  the  initial connect). They are
489                   passed directly to the  underlying  transport  (gen_tcp  or
490                   SSL) without verification.
491                 VerboseMode = false | verbose | debug | trace
492                   Default is false. This option is used to switch on (or off)
493                   different levels of Erlang trace on the  client.  It  is  a
494                   debug feature.
495                 Profile = profile() | pid()
496                   When started stand_alone only the pid can be used.
497                 UnixSocket = path()
498                    Experimental  option for sending HTTP requests over a unix
499                   domain socket. The value of unix_socket shall be  the  full
500                   path  to  a unix domain socket file with read/write permis‐
501                   sions for the erlang process. Default is undefined.
502
503              Sets options to be used for subsequent requests.
504
505          Note:
506              If possible, the client keeps its  connections  alive  and  uses
507              persistent  connections  with  or  without pipeline depending on
508              configuration and current circumstances. The HTTP/1.1 specifica‐
509              tion does not provide a guideline for how many requests that are
510              ideal to be sent on a persistent connection. This  depends  much
511              on the application.
512
513              A  long  queue  of requests can cause a user-perceived delay, as
514              earlier requests can take a long time to complete. The  HTTP/1.1
515              specification suggests a limit of two persistent connections per
516              server, which is the default value of option max_sessions.
517
518              The current implementation assumes  the  requests  to  the  same
519              host, port combination will use the same socket options.
520
521
522       store_cookies(SetCookieHeaders, Url) ->
523       store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
524
525              Types:
526
527                 SetCookieHeaders = headers() - where field = "set-cookie"
528                 Url = url()
529                 Profile = profile() | pid()
530                   When started stand_alone only the pid can be used.
531
532              Saves the cookies defined in SetCookieHeaders in the client pro‐
533              file cookie database. Call this function if  option  cookies  is
534              set  to  verify. If no profile is specified, the default profile
535              is used.
536
537       stream_next(Pid) -> ok
538
539              Types:
540
541                 Pid = pid()
542                   As received in the stream_start message
543
544              Triggers the next message to be  streamed,  that  is,  the  same
545              behavior as active ones for sockets.
546
547       which_cookies() -> cookies()
548       which_cookies(Profile) -> cookies()
549
550              Types:
551
552                 Profile = profile() | pid()
553                   When started stand_alone only the pid can be used.
554                 cookies() = [cookie_stores()]
555                 cookie_stores()  =  {cookies,  cookies()} | {session_cookies,
556                 cookies()}
557                 cookies() = [cookie()]
558                 cookie() = term()
559
560              Produces a list of the  entire  cookie  database.  Intended  for
561              debugging/testing  purposes.  If  no  profile  is specified, the
562              default profile is used.
563
564       which_sessions() -> session_info()
565       which_sessions(Profile) -> session_info()
566
567              Types:
568
569                 Profile = profile() | pid()
570                   When started stand_alone only the pid can be used.
571                 session_info() = {[session()], [term()], [term()]}
572                 session() = term() - Internal representation of a session
573
574              This function is intended for  debugging  only.  It  produces  a
575              slightly  processed dump of the session database. The first list
576              of the session information tuple will contain  session  informa‐
577              tion  on  an  internal format. The last two lists of the session
578              information tuple should always be empty if the code is  working
579              as  intended. If no profile is specified, the default profile is
580              used.
581

SEE ALSO

583       RFC 2616, inets(3), gen_tcp(3), ssl(3)
584
585
586
587Ericsson AB                       inets 7.1.3                         httpc(3)
Impressum