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()}
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 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 HTTP option (http_option()) details:
252 timeout:
254 Time-out time for the request.
255 The clock starts ticking when the request is sent.
257 Time is in milliseconds.
259 Default is infinity.
261 connect_timeout:
263 Connection time-out time, used during the initial request,
264 when the client is connecting to the server.
265 Time is in milliseconds.
267 Default is the value of option timeout.
269 ssl:
271 This is the SSL/TLS connectin configuration option.
272 Defaults to []. See ssl:connect/[2,3,4] for available
274 options.
275 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 For some 30X-result codes, automatic redirect is not
282 allowed. In these cases the 30X-result is always returned.
283 Default is true.
285 proxy_auth:
287 A proxy-authorization header using the provided username and
288 password is added to the request.
289 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 Default is the string "HTTP/1.1".
296 relaxed:
298 If set to true, workarounds for known server deviations from
299 the HTTP-standard are enabled.
300 Default is false.
302 Option (option()) details:
304 sync:
306 Option for the request to be synchronous or asynchronous.
307 Default is true.
309 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 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 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 Default is none.
332 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 Default is string.
339 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 Default is true.
346 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 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 Default is false.
358 socket_opts:
360 Socket options to be used for this request.
361 Overrides any value set by function set_options.
363 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 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 By default the socket options set by function
377 set_options/[1,2] are used when establishing a connection.
378 receiver:
380 Defines how the client delivers the result of an asynchro‐
381 nous request (sync has the value false).
382 pid():
384 Messages are sent to this process in the format {http,
385 ReplyInfo}.
386 function/1:
388 Information is delivered to the receiver through calls to
389 the provided fun Receiver(ReplyInfo).
390 {Module, Function, Args}:
392 Information is delivered to the receiver through calls to
393 the callback function apply(Module, Function, [ReplyInfo |
394 Args]).
395 In all of these cases, ReplyInfo has the following struc‐
397 ture:
398 {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 Default is the pid of the process calling the request func‐
408 tion (self()).
409 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 Default is false.
416 set_options(Options) ->
418 set_options(Options, Profile) -> ok | {error, Reason}
419 Types:
421 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 Sets options to be used for subsequent requests.
504 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 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 The current implementation assumes the requests to the same
519 host, port combination will use the same socket options.
520 store_cookies(SetCookieHeaders, Url) ->
523 store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
524 Types:
526 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 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 stream_next(Pid) -> ok
538 Types:
540 Pid = pid()
542 As received in the stream_start message
543 Triggers the next message to be streamed, that is, the same
545 behavior as active ones for sockets.
546 which_cookies() -> cookies()
548 which_cookies(Profile) -> cookies()
549 Types:
551 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 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 which_sessions() -> session_info()
565 which_sessions(Profile) -> session_info()
566 Types:
568 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 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
583 RFC 2616, inets(3), gen_tcp(3), ssl(3)
584Ericsson AB inets 7.1.3 httpc(3)