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 An HTTP client can be configured to start when starting the Inets ap‐
34 plication or started dynamically in runtime by calling the Inets appli‐
35 cation API inets:start(httpc, ServiceConfig) or inets:start(httpc, Ser‐
36 viceConfig, How), see inets(3). The configuration options are as fol‐
37 lows:
38 {profile, Profile :: atom() | pid()}:
40 Name of the profile. This option is mandatory.
41 {data_dir, Path :: string()}:
43 Directory where the profile can save persistent data. If omitted,
44 all cookies are treated as session cookies. Path represents a file
45 path or directory path.
46 The client can be stopped using inets:stop(httpc, Pid) or in‐
48 ets:stop(httpc, Profile).
49 Warning:
51 Please note that httpc normalizes input URIs before internal processing
52 and special care shall be taken when the URI has percent ("%") charac‐
53 ters. A percent serves as the indicator for percent-encoded octets and
54 it must be percent-encoded as "%25" for that octet to be used as data
55 within the URI.
56 For example, in order to send an HTTP GET request with the URI
58 http://localhost/foo%25bar, the percent character must be percent-en‐
59 coded when creating the request: httpc:request("http://local‐
60 host/foo%2525bar").
61
64 cancel_request(RequestId) -> ok
65 cancel_request(RequestId, Profile) -> ok
67 Types:
69 RequestId = any()
71 A unique identifier as returned by request/4
72 Profile = atom() | pid()
73 When started stand_alone only the pid can be used.
74 Cancels an asynchronous HTTP request. Notice that this does not
76 guarantee that the request response is not delivered. Because it
77 is asynchronous, the request can already have been completed
78 when the cancellation arrives.
79 cookie_header(Url) -> HttpHeader | {error, Reason}
81 cookie_header(Url, ProfileOrOpts) -> HttpHeader | {error, Reason}
83 Types:
85 Url = uri_string:uri_string()
87 HttpHeader = {Field :: [byte()], Value :: binary() |
88 iolist()}
89 ProfileOrOpts = Profile | Opts
90 Profile = atom() | pid()
91 When started stand_alone only the pid can be used.
92 Opts = [CookieHeaderOpt]
93 CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
94 Reason = term()
95 Returns the cookie header that would have been sent when making
97 a request to Url using profile Profile. If no profile is speci‐
98 fied, the default profile is used.
99 Option ipv6_host_with_bracket deals with how to parse IPv6 ad‐
101 dresses. For details, see argument Options of request/[4,5].
102 cookie_header(Url, Opts, Profile) -> HttpHeader | {error, Reason}
104 Types:
106 Url = uri_string:uri_string()
108 HttpHeader = {Field :: [byte()], Value :: binary() |
109 iolist()}
110 Profile = atom() | pid()
111 When started stand_alone only the pid can be used.
112 Opts = [CookieHeaderOpt]
113 CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
114 Reason = term()
115 Returns the cookie header that would have been sent when making
117 a request to Url using profile Profile. If no profile is speci‐
118 fied, the default profile is used.
119 Option ipv6_host_with_bracket deals with how to parse IPv6 ad‐
121 dresses. For details, see argument Options of request/[4,5].
122 get_options(OptionItems) -> {ok, Values} | {error, Reason}
124 get_options(OptionItems, Profile) ->
126 {ok, Values} | {error, Reason}
127 Types:
129 OptionItems = all | [OptionItem]
131 OptionItem =
132 proxy | https_proxy | max_sessions | keep_alive_timeout |
133 max_keep_alive_length | pipeline_timeout |
134 max_pipeline_length | cookies | ipfamily | ip | port |
135 socket_opts | verbose | unix_socket
136 Values = [{OptionItem, term()}]
137 Profile = atom() | pid()
138 When started stand_alone only the pid can be used.
139 Reason = term()
140 Retrieves the options currently used by the client.
142 info() -> list() | {error, Reason}
144 info(Profile) -> list() | {error, Reason}
146 Types:
148 Reason = term()
150 Profile = atom() | pid()
151 When started stand_alone only the pid can be used.
152 Produces a list of miscellaneous information. Intended for de‐
154 bugging. If no profile is specified, the default profile is
155 used.
156 reset_cookies() -> Void
158 reset_cookies(Profile) -> Void
160 Types:
162 Profile = atom() | pid()
164 When started stand_alone only the pid can be used.
165 Void = term()
166 Resets (clears) the cookie database for the specified Profile.
168 If no profile is specified the default profile is used.
169 request(Url :: uri_string:uri_string()) ->
171 {ok, Result} | {error, term()}
172 request(Url, Profile) -> {ok, Result} | {error, term()}
174 Types:
176 Url = uri_string:uri_string()
178 Profile = atom() | pid()
179 When started stand_alone only the pid can be used.
180 Result =
181 {StatusLine, [HttpHeader], HttpBodyResult} |
182 {StatusCode, HttpBodyResult} |
183 RequestId | saved_to_file
184 HttpHeader = {Field :: [byte()], Value :: binary() |
185 iolist()}
186 HttpBodyResult = uri_string:uri_string() | binary()
187 StatusLine = {HttpVersion, StatusCode, string()}
188 HttpVersion = uri_string:uri_string()
189 StatusCode = integer() >= 0
190 RequestId = any()
191 Equivalent to httpc:request(get, {Url, []}, [], []).
193 request(Method, Request, HttpOptions, Options) ->
195 {ok, Result} | {error, term()}
196 request(Method, Request, HttpOptions, Options, Profile) ->
198 {ok, Result} | {error, term()}
199 Types:
201 Method =
203 head | get | put | patch | post | trace | options |
204 delete
205 Request =
206 {uri_string:uri_string(), [HttpHeader]} |
207 {uri_string:uri_string(),
208 [HttpHeader],
209 ContentType :: uri_string:uri_string(),
210 HttpBody}
211 HttpBody =
212 iolist() |
213 binary() |
214 {fun((Accumulator :: term()) ->
215 eof | {ok, iolist(), Accumulator :: term()}),
216 Accumulator :: term()} |
217 {chunkify,
218 fun((Accumulator :: term()) ->
219 eof | {ok, iolist(), Accumulator :: term()}),
220 Accumulator :: term()}
221 HttpHeader = {Field :: [byte()], Value :: binary() |
222 iolist()}
223 HttpOptions = [HttpOption]
224 HttpOption =
225 {timeout, timeout()} |
226 {connect_timeout, timeout()} |
227 {ssl, [ssl:tls_option()]} |
228 {autoredirect, boolean()} |
229 {proxy_auth, {string(), string()}} |
230 {version, HttpVersion} |
231 {relaxed, boolean()}
232 Options = [OptionRequest]
233 OptionRequest =
234 {sync, boolean()} |
235 {stream, StreamTo} |
236 {body_format, BodyFormat} |
237 {full_result, boolean()} |
238 {headers_as_is, boolean()} |
239 {socket_opts, [SocketOpt]} |
240 {receiver, Receiver} |
241 {ipv6_host_with_brackets, boolean()}
242 StreamTo = none | self | {self, once} | file:name_all()
243 BodyFormat = string() | binary() | atom()
244 SocketOpt = term()
245 Receiver =
246 pid() |
247 fun((term()) -> term()) |
248 {ReceiverModule :: atom(),
249 ReceiverFunction :: atom(),
250 ReceiverArgs :: list()}
251 Profile = atom() | pid()
252 When Profile is stand_alone only the pid can be used.
253 HttpVersion = uri_string:uri_string()
254 Result =
255 {StatusLine, [HttpHeader], HttpBodyResult} |
256 {StatusCode, HttpBodyResult} |
257 RequestId | saved_to_file
258 StatusLine = {HttpVersion, StatusCode, string()}
259 StatusCode = integer() >= 0
260 HttpBodyResult = uri_string:uri_string() | binary()
261 RequestId = any()
262 Sends an HTTP request. The function can be both synchronous and
264 asynchronous. In the latter case, the function returns {ok, Re‐
265 questId} and then the information is delivered to the receiver
266 depending on that value.
267 When Profile is stand_alone only the pid can be used.
269 HTTP options:
271 timeout:
273 Time-out time for the request.
274 The clock starts ticking when the request is sent.
276 Time is in milliseconds.
278 Default is infinity.
280 connect_timeout:
282 Connection time-out time, used during the initial request,
283 when the client is connecting to the server.
284 Time is in milliseconds.
286 Default is the value of option timeout.
288 ssl:
290 This is the SSL/TLS connecting configuration option.
291 Default value is obtained by calling httpc:ssl_ver‐
293 ify_host_options(true). . See ssl:connect/[2,3,4] for avail‐
294 able options.
295 autoredirect:
297 The client automatically retrieves the information from the
298 new URI and returns that as the result, instead of a 30X-re‐
299 sult code.
300 For some 30X-result codes, automatic redirect is not al‐
302 lowed. In these cases the 30X-result is always returned.
303 Default is true.
305 proxy_auth:
307 A proxy-authorization header using a tuple where the first
308 element is the username and the second element of the tuple
309 is the password added to the request.
310 version:
312 Can be used to make the client act as an HTTP/1.0 client. By
313 default this is an HTTP/1.1 client. When using HTTP/1.0 per‐
314 sistent connections are not used.
315 Default is the string "HTTP/1.1".
317 relaxed:
319 If set to true, workarounds for known server deviations from
320 the HTTP-standard are enabled.
321 Default is false.
323 Options details:
325 sync:
327 Option for the request to be synchronous or asynchronous.
328 Default is true.
330 stream:
332 Streams the body of a 200 or 206 response to the calling
333 process or to a file. When streaming to the calling process
334 using option self, the following stream messages are sent to
335 that process: {http, {RequestId, stream_start, Headers}},
336 {http, {RequestId, stream, BinBodyPart}}, and {http, {Re‐
337 questId, stream_end, Headers}}.
338 When streaming to the calling processes using option {self,
340 once}, the first message has an extra element, that is,
341 {http, {RequestId, stream_start, Headers, Pid}}. This is the
342 process id to be used as an argument to httpc:stream_next/1
343 to trigger the next message to be sent to the calling
344 process.
345 Notice that chunked encoding can add headers so that there
347 are more headers in the stream_end message than in
348 stream_start. When streaming to a file and the request is
349 asynchronous, the message {http, {RequestId, saved_to_file}}
350 is sent.
351 Default is none.
353 body_format:
355 Defines if the body is to be delivered as a string or bi‐
356 nary. This option is only valid for the synchronous request.
357 Default is string.
359 full_result:
361 Defines if a "full result" is to be returned to the caller
362 (that is, the body, the headers, and the entire status line)
363 or not (the body and the status code).
364 Default is true.
366 headers_as_is:
368 Defines if the headers provided by the user are to be made
369 lower case or to be regarded as case sensitive.
370 The HTTP standard requires them to be case insensitive. Use
372 this feature only if there is no other way to communicate
373 with the server or for testing purpose. When this option is
374 used, no headers are automatically added. All necessary
375 headers must be provided by the user.
376 Default is false.
378 socket_opts:
380 Socket options to be used for this request.
381 See the options used by gen_tcp(3) and ssl(3)
383 Overrides any value set by function set_options.
385 The validity of the options is not checked by the HTTP
387 client they are assumed to be correct and passed on to ssl
388 application and inet driver, which may reject them if they
389 are not correct.
390 Note:
392 Persistent connections are not supported when setting the
393 socket_opts option. When socket_opts is not set the current
394 implementation assumes the requests to the same host, port
395 combination will use the same socket options.
396 By default the socket options set by function set_op‐
399 tions/[1,2] are used when establishing a connection.
400 receiver:
402 Defines how the client delivers the result of an asynchro‐
403 nous request (sync has the value false).
404 pid():
406 Messages are sent to this process in the format {http, Re‐
407 plyInfo}.
408 function/1:
410 Information is delivered to the receiver through calls to
411 the provided fun Receiver(ReplyInfo).
412 {Module, Function, Args}:
414 Information is delivered to the receiver through calls to
415 the callback function apply(Module, Function, [ReplyInfo |
416 Args]).
417 In all of these cases, ReplyInfo has the following struc‐
419 ture:
420 {RequestId, saved_to_file}
422 {RequestId, {error, Reason}}
423 {RequestId, Result}
424 {RequestId, stream_start, Headers}
425 {RequestId, stream_start, Headers, HandlerPid}
426 {RequestId, stream, BinBodyPart}
427 {RequestId, stream_end, Headers}
428 Default is the pid of the process calling the request func‐
430 tion (self()).
431 ipv6_host_with_brackets:
433 Defines when parsing the Host-Port part of an URI with an
434 IPv6 address with brackets, if those brackets are to be re‐
435 tained (true) or stripped (false).
436 Default is false.
438 set_options(Options) -> ok | {error, Reason}
440 set_options(Options, Profile) -> ok | {error, Reason}
442 Types:
444 Options = [Option]
446 Option =
447 {proxy, {Proxy, NoProxy}} |
448 {https_proxy, {Proxy, NoProxy}} |
449 {max_sessions, MaxSessions} |
450 {max_keep_alive_length, MaxKeepAlive} |
451 {keep_alive_timeout, KeepAliveTimeout} |
452 {max_pipeline_length, MaxPipeline} |
453 {pipeline_timeout, PipelineTimeout} |
454 {cookies, CookieMode} |
455 {ipfamily, IpFamily} |
456 {ip, IpAddress} |
457 {port, Port} |
458 {socket_opts, [SocketOpt]} |
459 {verbose, VerboseMode} |
460 {unix_socket, UnixSocket}
461 Profile = atom() | pid()
462 SocketOpt = term()
463 Proxy = {HostName, Port}
464 Port = integer() >= 0
465 NoProxy = [DomainDesc | HostName | IpAddressDesc]
466 MaxSessions = MaxKeepAlive = KeepAliveTimeout = MaxPipeline =
467 PipelineTimeout = integer()
468 CookieMode = enabled | disabled | verify
469 IpFamily = inet | inet6 | local | inet6fb4
470 IpAddressDesc = uri_string:uri_string()
471 IpAddress = inet:ip_address()
472 VerboseMode = false | verbose | debug | trace
473 UnixSocket = string()
474 Reason = term()
475 DomainDesc = string()
476 HostName = uri_string:uri_string()
477 Sets options to be used for subsequent requests.
479 HostName:
481 Example: "localhost" or "foo.bar.se"
482 DomainDesc:
484 Example "*.Domain" or "*.ericsson.se"
485 IpAddressDesc:
487 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
488 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
489 "[2010:836B:4179::836B:4179]" (a complete IP address). proxy
490 defaults to {undefined, []}, that is, no proxy is configured
491 and https_proxy defaults to the value of proxy.
492 MaxSessions:
494 MaxSessions Maximum number of persistent connections to a
495 host. Default is 2.
496 MaxKeepAlive:
498 MaxKeepAlive Maximum number of outstanding requests on the
499 same connection to a host. Default is 5.
500 KeepAliveTimeout:
502 KeepAliveTimeout If a persistent connection is idle longer
503 than the keep_alive_timeout in milliseconds, the client
504 closes the connection. The server can also have such a time-
505 out but do not take that for granted. Default is 120000 (= 2
506 min).
507 MaxPipeline:
509 MaxPipeline Maximum number of outstanding requests on a
510 pipelined connection to a host. Default is 2.
511 PipelineTimeout:
513 PipelineTimeout If a persistent connection is idle longer
514 than the pipeline_timeout in milliseconds, the client closes
515 the connection. Default is 0, which results in pipelining
516 not being used.
517 CookieMode:
519 If cookies are enabled, all valid cookies are automatically
520 saved in the cookie database of the client manager. If op‐
521 tion verify is used, function store_cookies/2 has to be
522 called for the cookies to be saved. Default is disabled.
523 IpFamily:
525 Default is inet. With inet6fb4 option, IPv6 will be pre‐
526 ferred but if connection fails, an IPv4 fallback connection
527 attempt will be made.
528 IpAddress:
530 If the host has several network interfaces, this option
531 specifies which one to use. See gen_tcp:connect/3,4 for de‐
532 tails.
533 Port:
535 Example: 8080. Local port number to use. See gen_tcp:con‐
536 nect/3,4 for details.
537 SocketOpts:
539 The options are appended to the socket options used by the
540 client. These are the default values when a new request han‐
541 dler is started (for the initial connect). They are passed
542 directly to the underlying transport (gen_tcp or SSL) with‐
543 out verification.
544 See the options used by gen_tcp(3) and ssl(3)
546 VerboseMode:
548 Default is false. This option is used to switch on (or off)
549 different levels of Erlang trace on the client. It is a de‐
550 bug feature.
551 Profile:
553 When started stand_alone only the pid can be used.
554 UnixSocket:
556 Experimental option for sending HTTP requests over a unix
557 domain socket. The value of unix_socket shall be the full
558 path to a unix domain socket file with read/write permis‐
559 sions for the erlang process. Default is undefined.
560 Note:
562 If possible, the client keeps its connections alive and uses
563 persistent connections with or without pipeline depending on
564 configuration and current circumstances. The HTTP/1.1 specifica‐
565 tion does not provide a guideline for how many requests that are
566 ideal to be sent on a persistent connection. This depends much
567 on the application.
568 A long queue of requests can cause a user-perceived delay, as
570 earlier requests can take a long time to complete. The HTTP/1.1
571 specification suggests a limit of two persistent connections per
572 server, which is the default value of option max_sessions.
573 The current implementation assumes the requests to the same
575 host, port combination will use the same socket options.
576 ssl_verify_host_options(WildcardHostName) -> list()
579 Types:
581 WildcardHostName = boolean()
583 Returns ssl options which can be used to verify the host, uses
585 public_key:cacerts_get() to read CA certicates and if Wildcard‐
586 HostName is true adds the hostname check from public_key:pub‐
587 lic_key:pkix_verify_hostname_match_fun(https) to the options.
588 store_cookies(SetCookieHeaders, Url) -> ok | {error, Reason}
590 store_cookies(SetCookieHeaders, Url, Profile) ->
592 ok | {error, Reason}
593 Types:
595 SetCookieHeaders = [HttpHeader]
597 Where field = "set-cookie"
598 HttpHeader = {Field :: [byte()], Value :: binary() |
599 iolist()}
600 Url = term()
601 Profile = atom() | pid()
602 When started stand_alone only the pid can be used.
603 Reason = term()
604 Saves the cookies defined in SetCookieHeaders in the client pro‐
606 file cookie database. Call this function if option cookies is
607 set to verify. If no profile is specified, the default profile
608 is used.
609 stream_next(Pid) -> ok
611 Types:
613 Pid = pid()
615 As received in the stream_start message
616 Triggers the next message to be streamed, that is, the same be‐
618 havior as active ones for sockets.
619 which_cookies() -> [CookieStores]
621 which_cookies(Profile) -> [CookieStores]
623 Types:
625 Profile = atom() | pid()
627 When started stand_alone only the pid can be used.
628 CookieStores = {cookies, Cookies} | {session_cookies, Cook‐
629 ies}
630 Cookies = [term()]
631 Produces a list of the entire cookie database. Intended for de‐
633 bugging/testing purposes. If no profile is specified, the de‐
634 fault profile is used.
635 which_sessions() -> SessionInfo
637 which_sessions(Profile) -> SessionInfo
639 Types:
641 Profile = atom() | pid()
643 When started stand_alone only the pid can be used.
644 SessionInfo = {GoodSession, BadSessions, NonSessions}
645 GoodSession = [Session]
646 BadSessions = NonSessions = [term()]
647 Session = term()
648 Internal representation of a session.
649 This function is intended for debugging only. It produces a
651 slightly processed dump of the session database. The first list
652 of the session information tuple will contain session informa‐
653 tion on an internal format. The last two lists of the session
654 information tuple should always be empty if the code is working
655 as intended. If no profile is specified, the default profile is
656 used.
657
659 RFC 2616, inets(3), gen_tcp(3), ssl(3)
660Ericsson AB inets 9.0.2 httpc(3)