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 up‐
22 graded to TLS. However, "TLS upgrade" according to RFC 2817is not sup‐
23 ported.
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 http_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) gen_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() = http_string() syntax according to the URI definition in RFC
61 3986, for example "http://www.erlang.org"
62 Warning:
64 Please note that httpc normalizes input URIs before internal processing
65 and special care shall be taken when the URI has percent ("%") charac‐
66 ters. A percent serves as the indicator for percent-encoded octets and
67 it must be percent-encoded as "%25" for that octet to be used as data
68 within the URI.
69 For example, in order to send an HTTP GET request with the URI
71 http://localhost/foo%25bar, the percent character must be percent-en‐
72 coded when creating the request: httpc:request("http://local‐
73 host/foo%2525bar").
74 status_line() = {http_version(), status_code(), reason_phrase()}
77 http_version() = http_string(), for example, "HTTP/1.1"
79 status_code() = integer()
81 reason_phrase() = string()
83 content_type() = http_string()
85 headers() = [header()]
87 header() = {field(), value()}
89 field() = [byte()]
91 value() = binary() | iolist()
93 body():
95 = http_string() | binary()
96 | {fun(accumulator())
98 -> body_processing_result(), accumulator()}
100 | {chunkify, fun(accumulator())
102 -> body_processing_result(), accumulator()}
104 body_processing_result() = eof | {ok, iolist(), accumulator()}
106 accumulator() = term()
108 filename() = string()
110 For more information about HTTP, see RFC 2616.
112
114 See ssl(3) for information about SSL options (ssloptions()).
115
117 An HTTP client can be configured to start when starting the Inets ap‐
118 plication or started dynamically in runtime by calling the Inets appli‐
119 cation API inets:start(httpc, ServiceConfig) or inets:start(httpc, Ser‐
120 viceConfig, How), see inets(3). The configuration options are as fol‐
121 lows:
122 {profile, profile()}:
124 Name of the profile, see DATA TYPES. This option is mandatory.
125 {data_dir, path()}:
127 Directory where the profile can save persistent data. If omitted,
128 all cookies are treated as session cookies.
129 The client can be stopped using inets:stop(httpc, Pid) or in‐
131 ets:stop(httpc, Profile).
132
134 cancel_request(RequestId) ->
135 cancel_request(RequestId, Profile) -> ok
136 Types:
138 RequestId = request_id() - A unique identifier as returned by
140 request/4
141 Profile = profile() | pid()
142 When started stand_alone only the pid can be used.
143 Cancels an asynchronous HTTP request. Notice that this does not
145 guarantee that the request response is not delivered. Because it
146 is asynchronous, the request can already have been completed
147 when the cancellation arrives.
148 cookie_header(Url) ->
150 cookie_header(Url, Profile | Opts) -> header() | {error, Reason}
151 cookie_header(Url, Opts, Profile) -> header() | {error, Reason}
152 Types:
154 Url = url()
156 Opts = [cookie_header_opt()]
157 Profile = profile() | pid()
158 When started stand_alone.
159 cookie_header_opt() = {ipv6_host_with_brackets, boolean()}
160 Returns the cookie header that would have been sent when making
162 a request to Url using profile Profile. If no profile is speci‐
163 fied, the default profile is used.
164 Option ipv6_host_with_bracket deals with how to parse IPv6 ad‐
166 dresses. For details, see argument Options of request/[4,5].
167 get_options(OptionItems) -> {ok, Values} | {error, Reason}
169 get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}
170 Types:
172 OptionItems = all | [option_item()]
174 option_item() = proxy | https_proxy | max_sessions |
175 keep_alive_timeout | max_keep_alive_length | pipeline_timeout
176 | max_pipeline_length | cookies | ipfamily | ip | port |
177 socket_opts | verbose | unix_socket
178 Profile = profile() | pid()
179 When started stand_alone only the pid can used.
180 Values = [{option_item(), term()}]
181 Reason = term()
182 Retrieves the options currently used by the client.
184 info() -> list()
186 info(Profile) -> list()
187 Types:
189 Profile = profile() | pid()
191 When started stand_alone only the pid can be used.
192 Produces a list of miscellaneous information. Intended for de‐
194 bugging. If no profile is specified, the default profile is
195 used.
196 reset_cookies() -> void()
198 reset_cookies(Profile) -> void()
199 Types:
201 Profile = profile() | pid()
203 When started stand_alone only the pid can be used.
204 Resets (clears) the cookie database for the specified Profile.
206 If no profile is specified the default profile is used.
207 request(Url) ->
209 request(Url, Profile) -> {ok, Result} | {error, Reason}
210 Types:
212 Url = url()
214 Result = {status_line(), headers(), Body} | {status_code(),
215 Body} | request_id()
216 Body = http_string() | binary()
217 Profile = profile() | pid()
218 When started stand_alone only the pid can be used.
219 Reason = term()
220 Equivalent to httpc:request(get, {Url, []}, [], []).
222 request(Method, Request, HTTPOptions, Options) ->
224 request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result}
225 | {ok, saved_to_file} | {error, Reason}
226 Types:
228 Method = method()
230 Request = request()
231 HTTPOptions = http_options()
232 http_options() = [http_option()]
233 http_option() = {timeout, timeout()} | {connect_timeout,
234 timeout()} | {ssl, ssloptions()} | {essl, ssloptions()} |
235 {autoredirect, boolean()} | {proxy_auth, {userstring(), pass‐
236 wordstring()}} | {version, http_version()} | {relaxed, bool‐
237 ean()}
238 timeout() = integer() >= 0 | infinity
239 Options = options()
240 options() = [option()]
241 option() = {sync, boolean()} | {stream, stream_to()} |
242 {body_format, body_format()} | {full_result, boolean()} |
243 {headers_as_is, boolean() | {socket_opts, socket_opts()} |
244 {receiver, receiver()} | {ipv6_host_with_brackets, boolean()}
245 stream_to() = none | self | {self, once} | filename()
246 socket_opts() = [socket_opt()]
247 receiver() = pid() | function()/1 | {Module, Function, Args}
248 Module = atom()
249 Function = atom()
250 Args = list()
251 body_format() = string | binary
252 Result = {status_line(), headers(), Body} | {status_code(),
253 Body} | request_id()
254 Body = http_string() | binary()
255 Profile = profile() | pid()
256 When started stand_alone only the pid can be used.
257 Reason = term()
258 Sends an HTTP request. The function can be both synchronous and
260 asynchronous. In the latter case, the function returns {ok, Re‐
261 questId} and then the information is delivered to the receiver
262 depending on that value.
263 HTTP option (http_option()) details:
265 timeout:
267 Time-out time for the request.
268 The clock starts ticking when the request is sent.
270 Time is in milliseconds.
272 Default is infinity.
274 connect_timeout:
276 Connection time-out time, used during the initial request,
277 when the client is connecting to the server.
278 Time is in milliseconds.
280 Default is the value of option timeout.
282 ssl:
284 This is the SSL/TLS connecting configuration option.
285 Defaults to []. See ssl:connect/[2,3,4] for available op‐
287 tions.
288 autoredirect:
290 The client automatically retrieves the information from the
291 new URI and returns that as the result, instead of a 30X-re‐
292 sult code.
293 For some 30X-result codes, automatic redirect is not al‐
295 lowed. In these cases the 30X-result is always returned.
296 Default is true.
298 proxy_auth:
300 A proxy-authorization header using the provided username and
301 password is added to the request.
302 version:
304 Can be used to make the client act as an HTTP/1.0 client. By
305 default this is an HTTP/1.1 client. When using HTTP/1.0 per‐
306 sistent connections are not used.
307 Default is the string "HTTP/1.1".
309 relaxed:
311 If set to true, workarounds for known server deviations from
312 the HTTP-standard are enabled.
313 Default is false.
315 Option (option()) details:
317 sync:
319 Option for the request to be synchronous or asynchronous.
320 Default is true.
322 stream:
324 Streams the body of a 200 or 206 response to the calling
325 process or to a file. When streaming to the calling process
326 using option self, the following stream messages are sent to
327 that process: {http, {RequestId, stream_start, Headers}},
328 {http, {RequestId, stream, BinBodyPart}}, and {http, {Re‐
329 questId, stream_end, Headers}}.
330 When streaming to the calling processes using option {self,
332 once}, the first message has an extra element, that is,
333 {http, {RequestId, stream_start, Headers, Pid}}. This is the
334 process id to be used as an argument to httpc:stream_next/1
335 to trigger the next message to be sent to the calling
336 process.
337 Notice that chunked encoding can add headers so that there
339 are more headers in the stream_end message than in
340 stream_start. When streaming to a file and the request is
341 asynchronous, the message {http, {RequestId, saved_to_file}}
342 is sent.
343 Default is none.
345 body_format:
347 Defines if the body is to be delivered as a string or bi‐
348 nary. This option is only valid for the synchronous request.
349 Default is string.
351 full_result:
353 Defines if a "full result" is to be returned to the caller
354 (that is, the body, the headers, and the entire status line)
355 or not (the body and the status code).
356 Default is true.
358 headers_as_is:
360 Defines if the headers provided by the user are to be made
361 lower case or to be regarded as case sensitive.
362 The HTTP standard requires them to be case insensitive. Use
364 this feature only if there is no other way to communicate
365 with the server or for testing purpose. When this option is
366 used, no headers are automatically added. All necessary
367 headers must be provided by the user.
368 Default is false.
370 socket_opts:
372 Socket options to be used for this request.
373 Overrides any value set by function set_options.
375 The validity of the options is not checked by the HTTP
377 client they are assumed to be correct and passed on to ssl
378 application and inet driver, which may reject them if they
379 are not correct.
380 Note:
382 Persistent connections are not supported when setting the
383 socket_opts option. When socket_opts is not set the current
384 implementation assumes the requests to the same host, port
385 combination will use the same socket options.
386 By default the socket options set by function set_op‐
389 tions/[1,2] are used when establishing a connection.
390 receiver:
392 Defines how the client delivers the result of an asynchro‐
393 nous request (sync has the value false).
394 pid():
396 Messages are sent to this process in the format {http, Re‐
397 plyInfo}.
398 function/1:
400 Information is delivered to the receiver through calls to
401 the provided fun Receiver(ReplyInfo).
402 {Module, Function, Args}:
404 Information is delivered to the receiver through calls to
405 the callback function apply(Module, Function, [ReplyInfo |
406 Args]).
407 In all of these cases, ReplyInfo has the following struc‐
409 ture:
410 {RequestId, saved_to_file}
412 {RequestId, {error, Reason}}
413 {RequestId, Result}
414 {RequestId, stream_start, Headers}
415 {RequestId, stream_start, Headers, HandlerPid}
416 {RequestId, stream, BinBodyPart}
417 {RequestId, stream_end, Headers}
418 Default is the pid of the process calling the request func‐
420 tion (self()).
421 ipv6_host_with_brackets:
423 Defines when parsing the Host-Port part of an URI with an
424 IPv6 address with brackets, if those brackets are to be re‐
425 tained (true) or stripped (false).
426 Default is false.
428 set_options(Options) ->
430 set_options(Options, Profile) -> ok | {error, Reason}
431 Types:
433 Options = [Option]
435 Option = {proxy, {Proxy, NoProxy}}
436 | {https_proxy, {Proxy, NoProxy}}
437 | {max_sessions, MaxSessions}
438 | {max_keep_alive_length, MaxKeepAlive}
439 | {keep_alive_timeout, KeepAliveTimeout}
440 | {max_pipeline_length, MaxPipeline}
441 | {pipeline_timeout, PipelineTimeout}
442 | {cookies, CookieMode}
443 | {ipfamily, IpFamily}
444 | {ip, IpAddress}
445 | {port, Port}
446 | {socket_opts, socket_opts()}
447 | {verbose, VerboseMode}
448 | {unix_socket, UnixSocket}
449 Proxy = {Hostname, Port}
450 Hostname = http_string()
451 Example: "localhost" or "foo.bar.se"
452 Port = integer()
453 Example: 8080
454 NoProxy = [NoProxyDesc]
455 NoProxyDesc = DomainDesc | HostName | IPDesc
456 DomainDesc = "*.Domain"
457 Example: "*.ericsson.se"
458 IpDesc = http_string()
459 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
460 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
461 "[2010:836B:4179::836B:4179]" (a complete IP address).
462 proxy defaults to {undefined, []}, that is, no proxy is
463 configured and https_proxy defaults to the value of proxy.
464 MaxSessions = integer()
465 Maximum number of persistent connections to a host. Default
466 is 2.
467 MaxKeepAlive = integer()
468 Maximum number of outstanding requests on the same connec‐
469 tion to a host. Default is 5.
470 KeepAliveTimeout = integer()
471 If a persistent connection is idle longer than the
472 keep_alive_timeout in milliseconds, the client closes the
473 connection. The server can also have such a time-out but do
474 not take that for granted. Default is 120000 (= 2 min).
475 MaxPipeline = integer()
476 Maximum number of outstanding requests on a pipelined con‐
477 nection to a host. Default is 2.
478 PipelineTimeout = integer()
479 If a persistent connection is idle longer than the pipe‐
480 line_timeout in milliseconds, the client closes the connec‐
481 tion. Default is 0, which results in pipelining not being
482 used.
483 CookieMode = enabled | disabled | verify
484 If cookies are enabled, all valid cookies are automatically
485 saved in the cookie database of the client manager. If op‐
486 tion verify is used, function store_cookies/2 has to be
487 called for the cookies to be saved. Default is disabled.
488 IpFamily = inet | inet6 | local
489 Default is inet.
490 IpAddress = ip_address()
491 If the host has several network interfaces, this option
492 specifies which one to use. See gen_tcp:connect/3,4 for de‐
493 tails.
494 Port = integer()
495 Local port number to use. See gen_tcp:connect/3,4 for de‐
496 tails.
497 socket_opts() = [socket_opt()]
498 The options are appended to the socket options used by the
499 client. These are the default values when a new request
500 handler is started (for the initial connect). They are
501 passed directly to the underlying transport (gen_tcp or
502 SSL) without verification.
503 VerboseMode = false | verbose | debug | trace
504 Default is false. This option is used to switch on (or off)
505 different levels of Erlang trace on the client. It is a de‐
506 bug feature.
507 Profile = profile() | pid()
508 When started stand_alone only the pid can be used.
509 UnixSocket = path()
510 Experimental option for sending HTTP requests over a unix
511 domain socket. The value of unix_socket shall be the full
512 path to a unix domain socket file with read/write permis‐
513 sions for the erlang process. Default is undefined.
514 Sets options to be used for subsequent requests.
516 Note:
518 If possible, the client keeps its connections alive and uses
519 persistent connections with or without pipeline depending on
520 configuration and current circumstances. The HTTP/1.1 specifica‐
521 tion does not provide a guideline for how many requests that are
522 ideal to be sent on a persistent connection. This depends much
523 on the application.
524 A long queue of requests can cause a user-perceived delay, as
526 earlier requests can take a long time to complete. The HTTP/1.1
527 specification suggests a limit of two persistent connections per
528 server, which is the default value of option max_sessions.
529 The current implementation assumes the requests to the same
531 host, port combination will use the same socket options.
532 store_cookies(SetCookieHeaders, Url) ->
535 store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
536 Types:
538 SetCookieHeaders = headers() - where field = "set-cookie"
540 Url = url()
541 Profile = profile() | pid()
542 When started stand_alone only the pid can be used.
543 Saves the cookies defined in SetCookieHeaders in the client pro‐
545 file cookie database. Call this function if option cookies is
546 set to verify. If no profile is specified, the default profile
547 is used.
548 stream_next(Pid) -> ok
550 Types:
552 Pid = pid()
554 As received in the stream_start message
555 Triggers the next message to be streamed, that is, the same be‐
557 havior as active ones for sockets.
558 which_cookies() -> cookies()
560 which_cookies(Profile) -> cookies()
561 Types:
563 Profile = profile() | pid()
565 When started stand_alone only the pid can be used.
566 cookies() = [cookie_stores()]
567 cookie_stores() = {cookies, cookies()} | {session_cookies,
568 cookies()}
569 cookies() = [cookie()]
570 cookie() = term()
571 Produces a list of the entire cookie database. Intended for de‐
573 bugging/testing purposes. If no profile is specified, the de‐
574 fault profile is used.
575 which_sessions() -> session_info()
577 which_sessions(Profile) -> session_info()
578 Types:
580 Profile = profile() | pid()
582 When started stand_alone only the pid can be used.
583 session_info() = {[session()], [term()], [term()]}
584 session() = term() - Internal representation of a session
585 This function is intended for debugging only. It produces a
587 slightly processed dump of the session database. The first list
588 of the session information tuple will contain session informa‐
589 tion on an internal format. The last two lists of the session
590 information tuple should always be empty if the code is working
591 as intended. If no profile is specified, the default profile is
592 used.
593
595 RFC 2616, inets(3), gen_tcp(3), ssl(3)
596Ericsson AB inets 7.5.3 httpc(3)