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) 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() = string() syntax according to the URI definition in RFC 3986,
61 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-
72 encoded when creating the request: httpc:request("http://local‐
73 host/foo%2525bar").
74 status_line() = {http_version(), status_code(), reason_phrase()}
77 http_version() = string(), for example, "HTTP/1.1"
79 status_code() = integer()
81 reason_phrase() = string()
83 content_type() = string()
85 headers() = [header()]
87 header() = {field(), value()}
89 field() = string()
91 value() = string()
93 body():
95 = 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
118 application or started dynamically in runtime by calling the Inets
119 application API inets:start(httpc, ServiceConfig) or inets:start(httpc,
120 ServiceConfig, How), see inets(3). The configuration options are as
121 follows:
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
131 inets: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
166 addresses. 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
194 debugging. 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 = 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 = 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,
261 RequestId} 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 connectin configuration option.
285 Defaults to []. See ssl:connect/[2,3,4] for available
287 options.
288 autoredirect:
290 The client automatically retrieves the information from the
291 new URI and returns that as the result, instead of a 30X-
292 result code.
293 For some 30X-result codes, automatic redirect is not
295 allowed. 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 or
305 HTTP/0.9 client. By default this is an HTTP/1.1 client. When
306 using HTTP/1.0 persistent 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,
329 {RequestId, 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
348 binary. This option is only valid for the synchronous
349 request.
350 Default is string.
352 full_result:
354 Defines if a "full result" is to be returned to the caller
355 (that is, the body, the headers, and the entire status line)
356 or not (the body and the status code).
357 Default is true.
359 headers_as_is:
361 Defines if the headers provided by the user are to be made
362 lower case or to be regarded as case sensitive.
363 The HTTP standard requires them to be case insensitive. Use
365 this feature only if there is no other way to communicate
366 with the server or for testing purpose. When this option is
367 used, no headers are automatically added. All necessary
368 headers must be provided by the user.
369 Default is false.
371 socket_opts:
373 Socket options to be used for this request.
374 Overrides any value set by function set_options.
376 The validity of the options is not checked by the HTTP
378 client they are assumed to be correct and passed on to ssl
379 application and inet driver, which may reject them if they
380 are not correct.
381 Note:
383 Persistent connections are not supported when setting the
384 socket_opts option. When socket_opts is not set the current
385 implementation assumes the requests to the same host, port
386 combination will use the same socket options.
387 By default the socket options set by function
390 set_options/[1,2] are used when establishing a connection.
391 receiver:
393 Defines how the client delivers the result of an asynchro‐
394 nous request (sync has the value false).
395 pid():
397 Messages are sent to this process in the format {http,
398 ReplyInfo}.
399 function/1:
401 Information is delivered to the receiver through calls to
402 the provided fun Receiver(ReplyInfo).
403 {Module, Function, Args}:
405 Information is delivered to the receiver through calls to
406 the callback function apply(Module, Function, [ReplyInfo |
407 Args]).
408 In all of these cases, ReplyInfo has the following struc‐
410 ture:
411 {RequestId, saved_to_file}
413 {RequestId, {error, Reason}}
414 {RequestId, Result}
415 {RequestId, stream_start, Headers}
416 {RequestId, stream_start, Headers, HandlerPid}
417 {RequestId, stream, BinBodyPart}
418 {RequestId, stream_end, Headers}
419 Default is the pid of the process calling the request func‐
421 tion (self()).
422 ipv6_host_with_brackets:
424 Defines when parsing the Host-Port part of an URI with an
425 IPv6 address with brackets, if those brackets are to be
426 retained (true) or stripped (false).
427 Default is false.
429 set_options(Options) ->
431 set_options(Options, Profile) -> ok | {error, Reason}
432 Types:
434 Options = [Option]
436 Option = {proxy, {Proxy, NoProxy}}
437 | {https_proxy, {Proxy, NoProxy}}
438 | {max_sessions, MaxSessions}
439 | {max_keep_alive_length, MaxKeepAlive}
440 | {keep_alive_timeout, KeepAliveTimeout}
441 | {max_pipeline_length, MaxPipeline}
442 | {pipeline_timeout, PipelineTimeout}
443 | {cookies, CookieMode}
444 | {ipfamily, IpFamily}
445 | {ip, IpAddress}
446 | {port, Port}
447 | {socket_opts, socket_opts()}
448 | {verbose, VerboseMode}
449 | {unix_socket, UnixSocket}
450 Proxy = {Hostname, Port}
451 Hostname = string()
452 Example: "localhost" or "foo.bar.se"
453 Port = integer()
454 Example: 8080
455 NoProxy = [NoProxyDesc]
456 NoProxyDesc = DomainDesc | HostName | IPDesc
457 DomainDesc = "*.Domain"
458 Example: "*.ericsson.se"
459 IpDesc = string()
460 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
461 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
462 "[2010:836B:4179::836B:4179]" (a complete IP address).
463 proxy defaults to {undefined, []}, that is, no proxy is
464 configured and https_proxy defaults to the value of proxy.
465 MaxSessions = integer()
466 Maximum number of persistent connections to a host. Default
467 is 2.
468 MaxKeepAlive = integer()
469 Maximum number of outstanding requests on the same connec‐
470 tion to a host. Default is 5.
471 KeepAliveTimeout = integer()
472 If a persistent connection is idle longer than the
473 keep_alive_timeout in milliseconds, the client closes the
474 connection. The server can also have such a time-out but do
475 not take that for granted. Default is 120000 (= 2 min).
476 MaxPipeline = integer()
477 Maximum number of outstanding requests on a pipelined con‐
478 nection to a host. Default is 2.
479 PipelineTimeout = integer()
480 If a persistent connection is idle longer than the pipe‐
481 line_timeout in milliseconds, the client closes the connec‐
482 tion. Default is 0, which results in pipelining not being
483 used.
484 CookieMode = enabled | disabled | verify
485 If cookies are enabled, all valid cookies are automatically
486 saved in the cookie database of the client manager. If
487 option verify is used, function store_cookies/2 has to be
488 called for the cookies to be saved. Default is disabled.
489 IpFamily = inet | inet6 | local
490 Default is inet.
491 IpAddress = ip_address()
492 If the host has several network interfaces, this option
493 specifies which one to use. See gen_tcp:connect/3,4 for
494 details.
495 Port = integer()
496 Local port number to use. See gen_tcp:connect/3,4 for
497 details.
498 socket_opts() = [socket_opt()]
499 The options are appended to the socket options used by the
500 client. These are the default values when a new request
501 handler is started (for the initial connect). They are
502 passed directly to the underlying transport (gen_tcp or
503 SSL) without verification.
504 VerboseMode = false | verbose | debug | trace
505 Default is false. This option is used to switch on (or off)
506 different levels of Erlang trace on the client. It is a
507 debug feature.
508 Profile = profile() | pid()
509 When started stand_alone only the pid can be used.
510 UnixSocket = path()
511 Experimental option for sending HTTP requests over a unix
512 domain socket. The value of unix_socket shall be the full
513 path to a unix domain socket file with read/write permis‐
514 sions for the erlang process. Default is undefined.
515 Sets options to be used for subsequent requests.
517 Note:
519 If possible, the client keeps its connections alive and uses
520 persistent connections with or without pipeline depending on
521 configuration and current circumstances. The HTTP/1.1 specifica‐
522 tion does not provide a guideline for how many requests that are
523 ideal to be sent on a persistent connection. This depends much
524 on the application.
525 A long queue of requests can cause a user-perceived delay, as
527 earlier requests can take a long time to complete. The HTTP/1.1
528 specification suggests a limit of two persistent connections per
529 server, which is the default value of option max_sessions.
530 The current implementation assumes the requests to the same
532 host, port combination will use the same socket options.
533 store_cookies(SetCookieHeaders, Url) ->
536 store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}
537 Types:
539 SetCookieHeaders = headers() - where field = "set-cookie"
541 Url = url()
542 Profile = profile() | pid()
543 When started stand_alone only the pid can be used.
544 Saves the cookies defined in SetCookieHeaders in the client pro‐
546 file cookie database. Call this function if option cookies is
547 set to verify. If no profile is specified, the default profile
548 is used.
549 stream_next(Pid) -> ok
551 Types:
553 Pid = pid()
555 As received in the stream_start message
556 Triggers the next message to be streamed, that is, the same
558 behavior as active ones for sockets.
559 which_cookies() -> cookies()
561 which_cookies(Profile) -> cookies()
562 Types:
564 Profile = profile() | pid()
566 When started stand_alone only the pid can be used.
567 cookies() = [cookie_stores()]
568 cookie_stores() = {cookies, cookies()} | {session_cookies,
569 cookies()}
570 cookies() = [cookie()]
571 cookie() = term()
572 Produces a list of the entire cookie database. Intended for
574 debugging/testing purposes. If no profile is specified, the
575 default profile is used.
576 which_sessions() -> session_info()
578 which_sessions(Profile) -> session_info()
579 Types:
581 Profile = profile() | pid()
583 When started stand_alone only the pid can be used.
584 session_info() = {[session()], [term()], [term()]}
585 session() = term() - Internal representation of a session
586 This function is intended for debugging only. It produces a
588 slightly processed dump of the session database. The first list
589 of the session information tuple will contain session informa‐
590 tion on an internal format. The last two lists of the session
591 information tuple should always be empty if the code is working
592 as intended. If no profile is specified, the default profile is
593 used.
594
596 RFC 2616, inets(3), gen_tcp(3), ssl(3)
597Ericsson AB inets 7.3.2 httpc(3)