1httpc(3) Erlang Module Definition httpc(3)
2
6 httpc - An HTTP/1.1 client
7
9 This module provides the API to an HTTP/1.1 compatible client according
10 to RFC 2616. Caching is not supported.
11 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 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 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 Some examples are provided in the Inets User's Guide.
31
33 Type definitions that are used more than once in this module:
34 boolean() = true | false
36 string() = list of ASCII characters
38 request_id() = reference()
40 profile() = atom()
42 path() = string() representing a file path or directory path
44 ip_address() = See the inet(3) manual page in Kernel.
46 socket_opt() = See the options used by gen_tcp(3) [22mgen_tcp(3) and ssl(3)
48 connect(s)
49
51 Type definitions related to HTTP:
52 method() = head | get | put | post | trace | options | delete | patch
54 request():
56 = {url(), headers()}
57 | {url(), headers(), content_type(), body()}
59 url() = string() syntax according to the URI definition in RFC 2396,
61 for example "http://www.erlang.org"
62 status_line() = {http_version(), status_code(), reason_phrase()}
64 http_version() = string(), for example, "HTTP/1.1"
66 status_code() = integer()
68 reason_phrase() = string()
70 content_type() = string()
72 headers() = [header()]
74 header() = {field(), value()}
76 field() = string()
78 value() = string()
80 body():
82 = string() | binary()
83 | {fun(accumulator())
85 -> body_processing_result(), accumulator()}
87 | {chunkify, fun(accumulator())
89 -> body_processing_result(), accumulator()}
91 body_processing_result() = eof | {ok, iolist(), accumulator()}
93 accumulator() = term()
95 filename() = string()
97 For more information about HTTP, see RFC 2616.
99
101 See ssl(3) for information about SSL options (ssloptions()).
102
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 {profile, profile()}:
111 Name of the profile, see DATA TYPES. This option is mandatory.
112 {data_dir, path()}:
114 Directory where the profile can save persistent data. If omitted,
115 all cookies are treated as session cookies.
116 The client can be stopped using inets:stop(httpc, Pid) or
118 inets:stop(httpc, Profile).
119
121 cancel_request(RequestId) ->
122 cancel_request(RequestId, Profile) -> ok
123 Types:
125 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 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 cookie_header(Url) ->
137 cookie_header(Url, Profile | Opts) -> header() | {error, Reason}
138 cookie_header(Url, Opts, Profile) -> header() | {error, Reason}
139 Types:
141 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 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 Option ipv6_host_with_bracket deals with how to parse IPv6
153 addresses. For details, see argument Options of request/[4,5].
154 get_options(OptionItems) -> {ok, Values} | {error, Reason}
156 get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}
157 Types:
159 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 Retrieves the options currently used by the client.
171 info() -> list()
173 info(Profile) -> list()
174 Types:
176 Profile = profile() | pid()
178 When started stand_alone only the pid can be used.
179 Produces a list of miscellaneous information. Intended for
181 debugging. If no profile is specified, the default profile is
182 used.
183 reset_cookies() -> void()
185 reset_cookies(Profile) -> void()
186 Types:
188 Profile = profile() | pid()
190 When started stand_alone only the pid can be used.
191 Resets (clears) the cookie database for the specified Profile.
193 If no profile is specified the default profile is used.
194 request(Url) ->
196 request(Url, Profile) -> {ok, Result} | {error, Reason}
197 Types:
199 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 Equivalent to httpc:request(get, {Url, []}, [], []).
209 request(Method, Request, HTTPOptions, Options) ->
211 request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result}
212 | {ok, saved_to_file} | {error, Reason}
213 Types:
215 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()} | {url_encode, boolean()}
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 = {connect_failed, term()} | {send_failed, term()} |
245 term()
246 Sends an HTTP request. The function can be both synchronous and
248 asynchronous. In the latter case, the function returns {ok,
249 RequestId} and then the information is delivered to the receiver
250 depending on that value.
251 HTTP option (http_option()) details:
253 timeout:
255 Time-out time for the request.
256 The clock starts ticking when the request is sent.
258 Time is in milliseconds.
260 Default is infinity.
262 connect_timeout:
264 Connection time-out time, used during the initial request,
265 when the client is connecting to the server.
266 Time is in milliseconds.
268 Default is the value of option timeout.
270 ssl:
272 This is the SSL/TLS connectin configuration option.
273 Defaults to []. See ssl:connect/[2,3,4] for available
275 options.
276 autoredirect:
278 The client automatically retrieves the information from the
279 new URI and returns that as the result, instead of a 30X-
280 result code.
281 For some 30X-result codes, automatic redirect is not
283 allowed. In these cases the 30X-result is always returned.
284 Default is true.
286 proxy_auth:
288 A proxy-authorization header using the provided username and
289 password is added to the request.
290 version:
292 Can be used to make the client act as an HTTP/1.0 or
293 HTTP/0.9 client. By default this is an HTTP/1.1 client. When
294 using HTTP/1.0 persistent connections are not used.
295 Default is the string "HTTP/1.1".
297 relaxed:
299 If set to true, workarounds for known server deviations from
300 the HTTP-standard are enabled.
301 Default is false.
303 url_encode:
305 Applies Percent-encoding, also known as URL encoding on the
306 URL.
307 Default is false.
309 Option (option()) details:
311 sync:
313 Option for the request to be synchronous or asynchronous.
314 Default is true.
316 stream:
318 Streams the body of a 200 or 206 response to the calling
319 process or to a file. When streaming to the calling process
320 using option self, the following stream messages are sent to
321 that process: {http, {RequestId, stream_start, Headers}},
322 {http, {RequestId, stream, BinBodyPart}}, and {http,
323 {RequestId, stream_end, Headers}}.
324 When streaming to the calling processes using option {self,
326 once}, the first message has an extra element, that is,
327 {http, {RequestId, stream_start, Headers, Pid}}. This is the
328 process id to be used as an argument to httpc:stream_next/1
329 to trigger the next message to be sent to the calling
330 process.
331 Notice that chunked encoding can add headers so that there
333 are more headers in the stream_end message than in
334 stream_start. When streaming to a file and the request is
335 asynchronous, the message {http, {RequestId, saved_to_file}}
336 is sent.
337 Default is none.
339 body_format:
341 Defines if the body is to be delivered as a string or
342 binary. This option is only valid for the synchronous
343 request.
344 Default is string.
346 full_result:
348 Defines if a "full result" is to be returned to the caller
349 (that is, the body, the headers, and the entire status line)
350 or not (the body and the status code).
351 Default is true.
353 headers_as_is:
355 Defines if the headers provided by the user are to be made
356 lower case or to be regarded as case sensitive.
357 The HTTP standard requires them to be case insensitive. Use
359 this feature only if there is no other way to communicate
360 with the server or for testing purpose. When this option is
361 used, no headers are automatically added. All necessary
362 headers must be provided by the user.
363 Default is false.
365 socket_opts:
367 Socket options to be used for this request.
368 Overrides any value set by function set_options.
370 The validity of the options is not checked by the HTTP
372 client they are assumed to be correct and passed on to ssl
373 application and inet driver, which may reject them if they
374 are not correct.
375 Note:
377 Persistent connections are not supported when setting the
378 socket_opts option. When socket_opts is not set the current
379 implementation assumes the requests to the same host, port
380 combination will use the same socket options.
381 By default the socket options set by function
384 set_options/[1,2] are used when establishing a connection.
385 receiver:
387 Defines how the client delivers the result of an asynchro‐
388 nous request (sync has the value false).
389 pid():
391 Messages are sent to this process in the format {http,
392 ReplyInfo}.
393 function/1:
395 Information is delivered to the receiver through calls to
396 the provided fun Receiver(ReplyInfo).
397 {Module, Function, Args}:
399 Information is delivered to the receiver through calls to
400 the callback function apply(Module, Function, [ReplyInfo |
401 Args]).
402 In all of these cases, ReplyInfo has the following struc‐
404 ture:
405 {RequestId, saved_to_file}
407 {RequestId, {error, Reason}}
408 {RequestId, Result}
409 {RequestId, stream_start, Headers}
410 {RequestId, stream_start, Headers, HandlerPid}
411 {RequestId, stream, BinBodyPart}
412 {RequestId, stream_end, Headers}
413 Default is the pid of the process calling the request func‐
415 tion (self()).
416 ipv6_host_with_brackets:
418 Defines when parsing the Host-Port part of an URI with an
419 IPv6 address with brackets, if those brackets are to be
420 retained (true) or stripped (false).
421 Default is false.
423 set_options(Options) ->
425 set_options(Options, Profile) -> ok | {error, Reason}
426 Types:
428 Options = [Option]
430 Option = {proxy, {Proxy, NoProxy}}
431 | {https_proxy, {Proxy, NoProxy}}
432 | {max_sessions, MaxSessions}
433 | {max_keep_alive_length, MaxKeepAlive}
434 | {keep_alive_timeout, KeepAliveTimeout}
435 | {max_pipeline_length, MaxPipeline}
436 | {pipeline_timeout, PipelineTimeout}
437 | {cookies, CookieMode}
438 | {ipfamily, IpFamily}
439 | {ip, IpAddress}
440 | {port, Port}
441 | {socket_opts, socket_opts()}
442 | {verbose, VerboseMode}
443 | {unix_socket, UnixSocket}
444 Proxy = {Hostname, Port}
445 Hostname = string()
446 Example: "localhost" or "foo.bar.se"
447 Port = integer()
448 Example: 8080
449 NoProxy = [NoProxyDesc]
450 NoProxyDesc = DomainDesc | HostName | IPDesc
451 DomainDesc = "*.Domain"
452 Example: "*.ericsson.se"
453 IpDesc = string()
454 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
455 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
456 "[2010:836B:4179::836B:4179]" (a complete IP address).
457 proxy defaults to {undefined, []}, that is, no proxy is
458 configured and https_proxy defaults to the value of proxy.
459 MaxSessions = integer()
460 Maximum number of persistent connections to a host. Default
461 is 2.
462 MaxKeepAlive = integer()
463 Maximum number of outstanding requests on the same connec‐
464 tion to a host. Default is 5.
465 KeepAliveTimeout = integer()
466 If a persistent connection is idle longer than the
467 keep_alive_timeout in milliseconds, the client closes the
468 connection. The server can also have such a time-out but do
469 not take that for granted. Default is 120000 (= 2 min).
470 MaxPipeline = integer()
471 Maximum number of outstanding requests on a pipelined con‐
472 nection to a host. Default is 2.
473 PipelineTimeout = integer()
474 If a persistent connection is idle longer than the pipe‐
475 line_timeout in milliseconds, the client closes the connec‐
476 tion. Default is 0, which results in pipelining not being
477 used.
478 CookieMode = enabled | disabled | verify
479 If cookies are enabled, all valid cookies are automatically
480 saved in the cookie database of the client manager. If
481 option verify is used, function store_cookies/2 has to be
482 called for the cookies to be saved. Default is disabled.
483 IpFamily = inet | inet6 | local
484 Default is inet.
485 IpAddress = ip_address()
486 If the host has several network interfaces, this option
487 specifies which one to use. See gen_tcp:connect/3,4 for
488 details.
489 Port = integer()
490 Local port number to use. See gen_tcp:connect/3,4 for
491 details.
492 socket_opts() = [socket_opt()]
493 The options are appended to the socket options used by the
494 client. These are the default values when a new request
495 handler is started (for the initial connect). They are
496 passed directly to the underlying transport (gen_tcp or
497 SSL) without verification.
498 VerboseMode = false | verbose | debug | trace
499 Default is false. This option is used to switch on (or off)
500 different levels of Erlang trace on the client. It is a
501 debug feature.
502 Profile = profile() | pid()
503 When started stand_alone only the pid can be used.
504 UnixSocket = path()
505 Experimental option for sending HTTP requests over a unix
506 domain socket. The value of unix_socket shall be the full
507 path to a unix domain socket file with read/write permis‐
508 sions for the erlang process. Default is undefined.
509 Sets options to be used for subsequent requests.
511 Note:
513 If possible, the client keeps its connections alive and uses
514 persistent connections with or without pipeline depending on
515 configuration and current circumstances. The HTTP/1.1 specifica‐
516 tion does not provide a guideline for how many requests that are
517 ideal to be sent on a persistent connection. This depends much
518 on the application.
519 A long queue of requests can cause a user-perceived delay, as
521 earlier requests can take a long time to complete. The HTTP/1.1
522 specification suggests a limit of two persistent connections per
523 server, which is the default value of option max_sessions.
524 The current implementation assumes the requests to the same
526 host, port combination will use the same socket options.
527 store_cookies(SetCookieHeaders, Url) ->
530 store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
531 Types:
533 SetCookieHeaders = headers() - where field = "set-cookie"
535 Url = url()
536 Profile = profile() | pid()
537 When started stand_alone only the pid can be used.
538 Saves the cookies defined in SetCookieHeaders in the client pro‐
540 file cookie database. Call this function if option cookies is
541 set to verify. If no profile is specified, the default profile
542 is used.
543 stream_next(Pid) -> ok
545 Types:
547 Pid = pid()
549 As received in the stream_start message
550 Triggers the next message to be streamed, that is, the same
552 behavior as active ones for sockets.
553 which_cookies() -> cookies()
555 which_cookies(Profile) -> cookies()
556 Types:
558 Profile = profile() | pid()
560 When started stand_alone only the pid can be used.
561 cookies() = [cookie_stores()]
562 cookie_stores() = {cookies, cookies()} | {session_cookies,
563 cookies()}
564 cookies() = [cookie()]
565 cookie() = term()
566 Produces a list of the entire cookie database. Intended for
568 debugging/testing purposes. If no profile is specified, the
569 default profile is used.
570 which_sessions() -> session_info()
572 which_sessions(Profile) -> session_info()
573 Types:
575 Profile = profile() | pid()
577 When started stand_alone only the pid can be used.
578 session_info() = {GoodSessions, BadSessions, NonSessions}
579 GoodSessions = session()
580 BadSessions = tuple()
581 NonSessions = term()
582 Produces a slightly processed dump of the session database. It
584 is intended for debugging. If no profile is specified, the
585 default profile is used.
586
588 RFC 2616, inets(3), gen_tcp(3), ssl(3)
589Ericsson AB inets 6.5.2.4 httpc(3)