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 Defaults to []. See ssl:connect/[2,3,4] for available op‐
293 tions.
294 autoredirect:
296 The client automatically retrieves the information from the
297 new URI and returns that as the result, instead of a 30X-re‐
298 sult code.
299 For some 30X-result codes, automatic redirect is not al‐
301 lowed. In these cases the 30X-result is always returned.
302 Default is true.
304 proxy_auth:
306 A proxy-authorization header using a tuple where the first
307 element is the username and the second element of the tuple
308 is the password added to the request.
309 version:
311 Can be used to make the client act as an HTTP/1.0 client. By
312 default this is an HTTP/1.1 client. When using HTTP/1.0 per‐
313 sistent connections are not used.
314 Default is the string "HTTP/1.1".
316 relaxed:
318 If set to true, workarounds for known server deviations from
319 the HTTP-standard are enabled.
320 Default is false.
322 Options details:
324 sync:
326 Option for the request to be synchronous or asynchronous.
327 Default is true.
329 stream:
331 Streams the body of a 200 or 206 response to the calling
332 process or to a file. When streaming to the calling process
333 using option self, the following stream messages are sent to
334 that process: {http, {RequestId, stream_start, Headers}},
335 {http, {RequestId, stream, BinBodyPart}}, and {http, {Re‐
336 questId, stream_end, Headers}}.
337 When streaming to the calling processes using option {self,
339 once}, the first message has an extra element, that is,
340 {http, {RequestId, stream_start, Headers, Pid}}. This is the
341 process id to be used as an argument to httpc:stream_next/1
342 to trigger the next message to be sent to the calling
343 process.
344 Notice that chunked encoding can add headers so that there
346 are more headers in the stream_end message than in
347 stream_start. When streaming to a file and the request is
348 asynchronous, the message {http, {RequestId, saved_to_file}}
349 is sent.
350 Default is none.
352 body_format:
354 Defines if the body is to be delivered as a string or bi‐
355 nary. This option is only valid for the synchronous request.
356 Default is string.
358 full_result:
360 Defines if a "full result" is to be returned to the caller
361 (that is, the body, the headers, and the entire status line)
362 or not (the body and the status code).
363 Default is true.
365 headers_as_is:
367 Defines if the headers provided by the user are to be made
368 lower case or to be regarded as case sensitive.
369 The HTTP standard requires them to be case insensitive. Use
371 this feature only if there is no other way to communicate
372 with the server or for testing purpose. When this option is
373 used, no headers are automatically added. All necessary
374 headers must be provided by the user.
375 Default is false.
377 socket_opts:
379 Socket options to be used for this request.
380 See the options used by gen_tcp(3) and ssl(3)
382 Overrides any value set by function set_options.
384 The validity of the options is not checked by the HTTP
386 client they are assumed to be correct and passed on to ssl
387 application and inet driver, which may reject them if they
388 are not correct.
389 Note:
391 Persistent connections are not supported when setting the
392 socket_opts option. When socket_opts is not set the current
393 implementation assumes the requests to the same host, port
394 combination will use the same socket options.
395 By default the socket options set by function set_op‐
398 tions/[1,2] are used when establishing a connection.
399 receiver:
401 Defines how the client delivers the result of an asynchro‐
402 nous request (sync has the value false).
403 pid():
405 Messages are sent to this process in the format {http, Re‐
406 plyInfo}.
407 function/1:
409 Information is delivered to the receiver through calls to
410 the provided fun Receiver(ReplyInfo).
411 {Module, Function, Args}:
413 Information is delivered to the receiver through calls to
414 the callback function apply(Module, Function, [ReplyInfo |
415 Args]).
416 In all of these cases, ReplyInfo has the following struc‐
418 ture:
419 {RequestId, saved_to_file}
421 {RequestId, {error, Reason}}
422 {RequestId, Result}
423 {RequestId, stream_start, Headers}
424 {RequestId, stream_start, Headers, HandlerPid}
425 {RequestId, stream, BinBodyPart}
426 {RequestId, stream_end, Headers}
427 Default is the pid of the process calling the request func‐
429 tion (self()).
430 ipv6_host_with_brackets:
432 Defines when parsing the Host-Port part of an URI with an
433 IPv6 address with brackets, if those brackets are to be re‐
434 tained (true) or stripped (false).
435 Default is false.
437 set_options(Options) -> ok | {error, Reason}
439 set_options(Options, Profile) -> ok | {error, Reason}
441 Types:
443 Options = [Option]
445 Option =
446 {proxy, {Proxy, NoProxy}} |
447 {https_proxy, {Proxy, NoProxy}} |
448 {max_sessions, MaxSessions} |
449 {max_keep_alive_length, MaxKeepAlive} |
450 {keep_alive_timeout, KeepAliveTimeout} |
451 {max_pipeline_length, MaxPipeline} |
452 {pipeline_timeout, PipelineTimeout} |
453 {cookies, CookieMode} |
454 {ipfamily, IpFamily} |
455 {ip, IpAddress} |
456 {port, Port} |
457 {socket_opts, [SocketOpt]} |
458 {verbose, VerboseMode} |
459 {unix_socket, UnixSocket}
460 Profile = atom() | pid()
461 SocketOpt = term()
462 Proxy = {HostName, Port}
463 Port = integer() >= 0
464 NoProxy = [DomainDesc | HostName | IpAddressDesc]
465 MaxSessions = MaxKeepAlive = KeepAliveTimeout = MaxPipeline =
466 PipelineTimeout = integer()
467 CookieMode = enabled | disabled | verify
468 IpFamily = inet | inet6 | local | inet6fb4
469 IpAddressDesc = uri_string:uri_string()
470 IpAddress = inet:ip_address()
471 VerboseMode = false | verbose | debug | trace
472 UnixSocket = string()
473 Reason = term()
474 DomainDesc = string()
475 HostName = uri_string:uri_string()
476 Sets options to be used for subsequent requests.
478 HostName:
480 Example: "localhost" or "foo.bar.se"
481 DomainDesc:
483 Example "*.Domain" or "*.ericsson.se"
484 IpAddressDesc:
486 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
487 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
488 "[2010:836B:4179::836B:4179]" (a complete IP address). proxy
489 defaults to {undefined, []}, that is, no proxy is configured
490 and https_proxy defaults to the value of proxy.
491 MaxSessions:
493 MaxSessions Maximum number of persistent connections to a
494 host. Default is 2.
495 MaxKeepAlive:
497 MaxKeepAlive Maximum number of outstanding requests on the
498 same connection to a host. Default is 5.
499 KeepAliveTimeout:
501 KeepAliveTimeout If a persistent connection is idle longer
502 than the keep_alive_timeout in milliseconds, the client
503 closes the connection. The server can also have such a time-
504 out but do not take that for granted. Default is 120000 (= 2
505 min).
506 MaxPipeline:
508 MaxPipeline Maximum number of outstanding requests on a
509 pipelined connection to a host. Default is 2.
510 PipelineTimeout:
512 PipelineTimeout If a persistent connection is idle longer
513 than the pipeline_timeout in milliseconds, the client closes
514 the connection. Default is 0, which results in pipelining
515 not being used.
516 CookieMode:
518 If cookies are enabled, all valid cookies are automatically
519 saved in the cookie database of the client manager. If op‐
520 tion verify is used, function store_cookies/2 has to be
521 called for the cookies to be saved. Default is disabled.
522 IpFamily:
524 Default is inet. With inet6fb4 option, IPv6 will be pre‐
525 ferred but if connection fails, an IPv4 fallback connection
526 attempt will be made.
527 IpAddress:
529 If the host has several network interfaces, this option
530 specifies which one to use. See gen_tcp:connect/3,4 for de‐
531 tails.
532 Port:
534 Example: 8080. Local port number to use. See gen_tcp:con‐
535 nect/3,4 for details.
536 SocketOpts:
538 The options are appended to the socket options used by the
539 client. These are the default values when a new request han‐
540 dler is started (for the initial connect). They are passed
541 directly to the underlying transport (gen_tcp or SSL) with‐
542 out verification.
543 See the options used by gen_tcp(3) and ssl(3)
545 VerboseMode:
547 Default is false. This option is used to switch on (or off)
548 different levels of Erlang trace on the client. It is a de‐
549 bug feature.
550 Profile:
552 When started stand_alone only the pid can be used.
553 UnixSocket:
555 Experimental option for sending HTTP requests over a unix
556 domain socket. The value of unix_socket shall be the full
557 path to a unix domain socket file with read/write permis‐
558 sions for the erlang process. Default is undefined.
559 Note:
561 If possible, the client keeps its connections alive and uses
562 persistent connections with or without pipeline depending on
563 configuration and current circumstances. The HTTP/1.1 specifica‐
564 tion does not provide a guideline for how many requests that are
565 ideal to be sent on a persistent connection. This depends much
566 on the application.
567 A long queue of requests can cause a user-perceived delay, as
569 earlier requests can take a long time to complete. The HTTP/1.1
570 specification suggests a limit of two persistent connections per
571 server, which is the default value of option max_sessions.
572 The current implementation assumes the requests to the same
574 host, port combination will use the same socket options.
575 ssl_verify_host_options(WildcardHostName) -> list()
578 Types:
580 WildcardHostName = boolean()
582 Returns ssl options which can be used to verify the host, uses
584 public_key:cacerts_get() to read CA certicates and if Wildcard‐
585 HostName is true adds the hostname check from public_key:pub‐
586 lic_key:pkix_verify_hostname_match_fun(https) to the options.
587 store_cookies(SetCookieHeaders, Url) -> ok | {error, Reason}
589 store_cookies(SetCookieHeaders, Url, Profile) ->
591 ok | {error, Reason}
592 Types:
594 SetCookieHeaders = [HttpHeader]
596 Where field = "set-cookie"
597 HttpHeader = {Field :: [byte()], Value :: binary() |
598 iolist()}
599 Url = term()
600 Profile = atom() | pid()
601 When started stand_alone only the pid can be used.
602 Reason = term()
603 Saves the cookies defined in SetCookieHeaders in the client pro‐
605 file cookie database. Call this function if option cookies is
606 set to verify. If no profile is specified, the default profile
607 is used.
608 stream_next(Pid) -> ok
610 Types:
612 Pid = pid()
614 As received in the stream_start message
615 Triggers the next message to be streamed, that is, the same be‐
617 havior as active ones for sockets.
618 which_cookies() -> [CookieStores]
620 which_cookies(Profile) -> [CookieStores]
622 Types:
624 Profile = atom() | pid()
626 When started stand_alone only the pid can be used.
627 CookieStores = {cookies, Cookies} | {session_cookies, Cook‐
628 ies}
629 Cookies = [term()]
630 Produces a list of the entire cookie database. Intended for de‐
632 bugging/testing purposes. If no profile is specified, the de‐
633 fault profile is used.
634 which_sessions() -> SessionInfo
636 which_sessions(Profile) -> SessionInfo
638 Types:
640 Profile = atom() | pid()
642 When started stand_alone only the pid can be used.
643 SessionInfo = {GoodSession, BadSessions, NonSessions}
644 GoodSession = [Session]
645 BadSessions = NonSessions = [term()]
646 Session = term()
647 Internal representation of a session.
648 This function is intended for debugging only. It produces a
650 slightly processed dump of the session database. The first list
651 of the session information tuple will contain session informa‐
652 tion on an internal format. The last two lists of the session
653 information tuple should always be empty if the code is working
654 as intended. If no profile is specified, the default profile is
655 used.
656
658 RFC 2616, inets(3), gen_tcp(3), ssl(3)
659Ericsson AB inets 8.3.1.2 httpc(3)