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) ->
83 [HttpHeader] | {error, Reason}
84 Types:
86 Url = uri_string:uri_string()
88 HttpHeader = {Field :: [byte()], Value :: binary() |
89 iolist()}
90 ProfileOrOpts = Profile | Opts
91 Profile = atom() | pid()
92 When started stand_alone only the pid can be used.
93 Opts = [CookieHeaderOpt]
94 CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
95 Reason = term()
96 Returns the cookie header that would have been sent when making
98 a request to Url using profile Profile. If no profile is speci‐
99 fied, the default profile is used.
100 Option ipv6_host_with_bracket deals with how to parse IPv6 ad‐
102 dresses. For details, see argument Options of request/[4,5].
103 cookie_header(Url, Opts, Profile) ->
105 [HttpHeader] | {error, Reason}
106 Types:
108 Url = uri_string:uri_string()
110 HttpHeader = {Field :: [byte()], Value :: binary() |
111 iolist()}
112 Profile = atom() | pid()
113 When started stand_alone only the pid can be used.
114 Opts = [CookieHeaderOpt]
115 CookieHeaderOpt = {ipv6_host_with_brackets, boolean()}
116 Reason = term()
117 Returns the cookie header that would have been sent when making
119 a request to Url using profile Profile. If no profile is speci‐
120 fied, the default profile is used.
121 Option ipv6_host_with_bracket deals with how to parse IPv6 ad‐
123 dresses. For details, see argument Options of request/[4,5].
124 get_options(OptionItems) -> {ok, Values} | {error, Reason}
126 get_options(OptionItems, Profile) ->
128 {ok, Values} | {error, Reason}
129 Types:
131 OptionItems = all | [OptionItem]
133 OptionItem =
134 proxy | https_proxy | max_sessions | keep_alive_timeout |
135 max_keep_alive_length | pipeline_timeout |
136 max_pipeline_length | cookies | ipfamily | ip | port |
137 socket_opts | verbose | unix_socket
138 Values = [{OptionItem, term()}]
139 Profile = atom() | pid()
140 When started stand_alone only the pid can be used.
141 Reason = term()
142 Retrieves the options currently used by the client.
144 info() -> list() | {error, Reason}
146 info(Profile) -> list() | {error, Reason}
148 Types:
150 Reason = term()
152 Profile = atom() | pid()
153 When started stand_alone only the pid can be used.
154 Produces a list of miscellaneous information. Intended for de‐
156 bugging. If no profile is specified, the default profile is
157 used.
158 reset_cookies() -> Void
160 reset_cookies(Profile) -> Void
162 Types:
164 Profile = atom() | pid()
166 When started stand_alone only the pid can be used.
167 Void = term()
168 Resets (clears) the cookie database for the specified Profile.
170 If no profile is specified the default profile is used.
171 request(Url :: uri_string:uri_string()) ->
173 {ok, Result} | {error, term()}
174 request(Url, Profile) -> {ok, Result} | {error, term()}
176 Types:
178 Url = uri_string:uri_string()
180 Profile = atom() | pid()
181 When started stand_alone only the pid can be used.
182 Result =
183 {StatusLine, [HttpHeader], HttpBodyResult} |
184 {StatusCode, HttpBodyResult} |
185 RequestId | saved_to_file
186 HttpHeader = {Field :: [byte()], Value :: binary() |
187 iolist()}
188 HttpBodyResult = uri_string:uri_string() | binary()
189 StatusLine = {HttpVersion, StatusCode, string()}
190 HttpVersion = uri_string:uri_string()
191 StatusCode = integer() >= 0
192 RequestId = any()
193 Equivalent to httpc:request(get, {Url, []}, [], []).
195 request(Method, Request, HttpOptions, Options) ->
197 {ok, Result} | {error, term()}
198 request(Method, Request, HttpOptions, Options, Profile) ->
200 {ok, Result} | {error, term()}
201 Types:
203 Method =
205 head | get | put | patch | post | trace | options |
206 delete
207 Request =
208 {uri_string:uri_string(), [HttpHeader]} |
209 {uri_string:uri_string(),
210 [HttpHeader],
211 ContentType :: uri_string:uri_string(),
212 HttpBody}
213 HttpBody =
214 iolist() |
215 binary() |
216 {fun((Accumulator :: term()) ->
217 eof | {ok, iolist(), Accumulator :: term()}),
218 Accumulator :: term()} |
219 {chunkify,
220 fun((Accumulator :: term()) ->
221 eof | {ok, iolist(), Accumulator :: term()}),
222 Accumulator :: term()}
223 HttpHeader = {Field :: [byte()], Value :: binary() |
224 iolist()}
225 HttpOptions = [HttpOption]
226 HttpOption =
227 {timeout, timeout()} |
228 {connect_timeout, timeout()} |
229 {ssl, [ssl:tls_option()]} |
230 {autoredirect, boolean()} |
231 {proxy_auth, {string(), string()}} |
232 {version, HttpVersion} |
233 {relaxed, boolean()}
234 Options = [OptionRequest]
235 OptionRequest =
236 {sync, boolean()} |
237 {stream, StreamTo} |
238 {body_format, BodyFormat} |
239 {full_result, boolean()} |
240 {headers_as_is, boolean()} |
241 {socket_opts, [SocketOpt]} |
242 {receiver, Receiver} |
243 {ipv6_host_with_brackets, boolean()}
244 StreamTo = none | self | {self, once} | file:name_all()
245 BodyFormat = string() | binary() | atom()
246 SocketOpt = term()
247 Receiver =
248 pid() |
249 fun((term()) -> term()) |
250 {ReceiverModule :: atom(),
251 ReceiverFunction :: atom(),
252 ReceiverArgs :: list()}
253 Profile = atom() | pid()
254 When Profile is stand_alone only the pid can be used.
255 HttpVersion = uri_string:uri_string()
256 Result =
257 {StatusLine, [HttpHeader], HttpBodyResult} |
258 {StatusCode, HttpBodyResult} |
259 RequestId | saved_to_file
260 StatusLine = {HttpVersion, StatusCode, string()}
261 StatusCode = integer() >= 0
262 HttpBodyResult = uri_string:uri_string() | binary()
263 RequestId = any()
264 Sends an HTTP request. The function can be both synchronous and
266 asynchronous. In the latter case, the function returns {ok, Re‐
267 questId} and then the information is delivered to the receiver
268 depending on that value.
269 When Profile is stand_alone only the pid can be used.
271 HTTP options:
273 timeout:
275 Time-out time for the request.
276 The clock starts ticking when the request is sent.
278 Time is in milliseconds.
280 Default is infinity.
282 connect_timeout:
284 Connection time-out time, used during the initial request,
285 when the client is connecting to the server.
286 Time is in milliseconds.
288 Default is the value of option timeout.
290 ssl:
292 This is the SSL/TLS connecting configuration option.
293 Defaults to []. See ssl:connect/[2,3,4] for available op‐
295 tions.
296 autoredirect:
298 The client automatically retrieves the information from the
299 new URI and returns that as the result, instead of a 30X-re‐
300 sult code.
301 For some 30X-result codes, automatic redirect is not al‐
303 lowed. In these cases the 30X-result is always returned.
304 Default is true.
306 proxy_auth:
308 A proxy-authorization header using a tuple where the first
309 element is the username and the second element of the tuple
310 is the password added to the request.
311 version:
313 Can be used to make the client act as an HTTP/1.0 client. By
314 default this is an HTTP/1.1 client. When using HTTP/1.0 per‐
315 sistent connections are not used.
316 Default is the string "HTTP/1.1".
318 relaxed:
320 If set to true, workarounds for known server deviations from
321 the HTTP-standard are enabled.
322 Default is false.
324 Options details:
326 sync:
328 Option for the request to be synchronous or asynchronous.
329 Default is true.
331 stream:
333 Streams the body of a 200 or 206 response to the calling
334 process or to a file. When streaming to the calling process
335 using option self, the following stream messages are sent to
336 that process: {http, {RequestId, stream_start, Headers}},
337 {http, {RequestId, stream, BinBodyPart}}, and {http, {Re‐
338 questId, stream_end, Headers}}.
339 When streaming to the calling processes using option {self,
341 once}, the first message has an extra element, that is,
342 {http, {RequestId, stream_start, Headers, Pid}}. This is the
343 process id to be used as an argument to httpc:stream_next/1
344 to trigger the next message to be sent to the calling
345 process.
346 Notice that chunked encoding can add headers so that there
348 are more headers in the stream_end message than in
349 stream_start. When streaming to a file and the request is
350 asynchronous, the message {http, {RequestId, saved_to_file}}
351 is sent.
352 Default is none.
354 body_format:
356 Defines if the body is to be delivered as a string or bi‐
357 nary. This option is only valid for the synchronous request.
358 Default is string.
360 full_result:
362 Defines if a "full result" is to be returned to the caller
363 (that is, the body, the headers, and the entire status line)
364 or not (the body and the status code).
365 Default is true.
367 headers_as_is:
369 Defines if the headers provided by the user are to be made
370 lower case or to be regarded as case sensitive.
371 The HTTP standard requires them to be case insensitive. Use
373 this feature only if there is no other way to communicate
374 with the server or for testing purpose. When this option is
375 used, no headers are automatically added. All necessary
376 headers must be provided by the user.
377 Default is false.
379 socket_opts:
381 Socket options to be used for this request.
382 See the options used by gen_tcp(3) and ssl(3)
384 Overrides any value set by function set_options.
386 The validity of the options is not checked by the HTTP
388 client they are assumed to be correct and passed on to ssl
389 application and inet driver, which may reject them if they
390 are not correct.
391 Note:
393 Persistent connections are not supported when setting the
394 socket_opts option. When socket_opts is not set the current
395 implementation assumes the requests to the same host, port
396 combination will use the same socket options.
397 By default the socket options set by function set_op‐
400 tions/[1,2] are used when establishing a connection.
401 receiver:
403 Defines how the client delivers the result of an asynchro‐
404 nous request (sync has the value false).
405 pid():
407 Messages are sent to this process in the format {http, Re‐
408 plyInfo}.
409 function/1:
411 Information is delivered to the receiver through calls to
412 the provided fun Receiver(ReplyInfo).
413 {Module, Function, Args}:
415 Information is delivered to the receiver through calls to
416 the callback function apply(Module, Function, [ReplyInfo |
417 Args]).
418 In all of these cases, ReplyInfo has the following struc‐
420 ture:
421 {RequestId, saved_to_file}
423 {RequestId, {error, Reason}}
424 {RequestId, Result}
425 {RequestId, stream_start, Headers}
426 {RequestId, stream_start, Headers, HandlerPid}
427 {RequestId, stream, BinBodyPart}
428 {RequestId, stream_end, Headers}
429 Default is the pid of the process calling the request func‐
431 tion (self()).
432 ipv6_host_with_brackets:
434 Defines when parsing the Host-Port part of an URI with an
435 IPv6 address with brackets, if those brackets are to be re‐
436 tained (true) or stripped (false).
437 Default is false.
439 set_options(Options) -> ok | {error, Reason}
441 set_options(Options, Profile) -> ok | {error, Reason}
443 Types:
445 Options = [Option]
447 Option =
448 {proxy, {Proxy, NoProxy}} |
449 {https_proxy, {Proxy, NoProxy}} |
450 {max_sessions, MaxSessions} |
451 {max_keep_alive_length, MaxKeepAlive} |
452 {keep_alive_timeout, KeepAliveTimeout} |
453 {max_pipeline_length, MaxPipeline} |
454 {pipeline_timeout, PipelineTimeout} |
455 {cookies, CookieMode} |
456 {ipfamily, IpFamily} |
457 {ip, IpAddress} |
458 {port, Port} |
459 {socket_opts, [SocketOpt]} |
460 {verbose, VerboseMode} |
461 {unix_socket, UnixSocket}
462 Profile = atom() | pid()
463 SocketOpt = term()
464 Proxy = {HostName, Port}
465 Port = integer() >= 0
466 NoProxy = [DomainDesc | HostName | IpAddressDesc]
467 MaxSessions = MaxKeepAlive = KeepAliveTimeout = MaxPipeline =
468 PipelineTimeout = integer()
469 CookieMode = enabled | disabled | verify
470 IpFamily = inet | inet6 | local | inet6fb4
471 IpAddressDesc = uri_string:uri_string()
472 IpAddress = inet:ip_address()
473 VerboseMode = false | verbose | debug | trace
474 UnixSocket = string()
475 Reason = term()
476 DomainDesc = string()
477 HostName = uri_string:uri_string()
478 Sets options to be used for subsequent requests.
480 HostName:
482 Example: "localhost" or "foo.bar.se"
483 DomainDesc:
485 Example "*.Domain" or "*.ericsson.se"
486 IpAddressDesc:
488 Example: "134.138" or "[FEDC:BA98" (all IP addresses start‐
489 ing with 134.138 or FEDC:BA98), "66.35.250.150" or
490 "[2010:836B:4179::836B:4179]" (a complete IP address). proxy
491 defaults to {undefined, []}, that is, no proxy is configured
492 and https_proxy defaults to the value of proxy.
493 MaxSessions:
495 MaxSessions Maximum number of persistent connections to a
496 host. Default is 2.
497 MaxKeepAlive:
499 MaxKeepAlive Maximum number of outstanding requests on the
500 same connection to a host. Default is 5.
501 KeepAliveTimeout:
503 KeepAliveTimeout If a persistent connection is idle longer
504 than the keep_alive_timeout in milliseconds, the client
505 closes the connection. The server can also have such a time-
506 out but do not take that for granted. Default is 120000 (= 2
507 min).
508 MaxPipeline:
510 MaxPipeline Maximum number of outstanding requests on a
511 pipelined connection to a host. Default is 2.
512 PipelineTimeout:
514 PipelineTimeout If a persistent connection is idle longer
515 than the pipeline_timeout in milliseconds, the client closes
516 the connection. Default is 0, which results in pipelining
517 not being used.
518 CookieMode:
520 If cookies are enabled, all valid cookies are automatically
521 saved in the cookie database of the client manager. If op‐
522 tion verify is used, function store_cookies/2 has to be
523 called for the cookies to be saved. Default is disabled.
524 IpFamily:
526 Default is inet. With inet6fb4 option, IPv6 will be pre‐
527 ferred but if connection fails, an IPv4 fallback connection
528 attempt will be made.
529 IpAddress:
531 If the host has several network interfaces, this option
532 specifies which one to use. See gen_tcp:connect/3,4 for de‐
533 tails.
534 Port:
536 Example: 8080. Local port number to use. See gen_tcp:con‐
537 nect/3,4 for details.
538 SocketOpts:
540 The options are appended to the socket options used by the
541 client. These are the default values when a new request han‐
542 dler is started (for the initial connect). They are passed
543 directly to the underlying transport (gen_tcp or SSL) with‐
544 out verification.
545 See the options used by gen_tcp(3) and ssl(3)
547 VerboseMode:
549 Default is false. This option is used to switch on (or off)
550 different levels of Erlang trace on the client. It is a de‐
551 bug feature.
552 Profile:
554 When started stand_alone only the pid can be used.
555 UnixSocket:
557 Experimental option for sending HTTP requests over a unix
558 domain socket. The value of unix_socket shall be the full
559 path to a unix domain socket file with read/write permis‐
560 sions for the erlang process. Default is undefined.
561 Note:
563 If possible, the client keeps its connections alive and uses
564 persistent connections with or without pipeline depending on
565 configuration and current circumstances. The HTTP/1.1 specifica‐
566 tion does not provide a guideline for how many requests that are
567 ideal to be sent on a persistent connection. This depends much
568 on the application.
569 A long queue of requests can cause a user-perceived delay, as
571 earlier requests can take a long time to complete. The HTTP/1.1
572 specification suggests a limit of two persistent connections per
573 server, which is the default value of option max_sessions.
574 The current implementation assumes the requests to the same
576 host, port combination will use the same socket options.
577 ssl_verify_host_options(WildcardHostName) -> list()
580 Types:
582 WildcardHostName = boolean()
584 Returns ssl options which can be used to verify the host, uses
586 public_key:cacerts_get() to read CA certicates and if Wildcard‐
587 HostName is true adds the hostname check from public_key:pub‐
588 lic_key:pkix_verify_hostname_match_fun(https) to the options.
589 store_cookies(SetCookieHeaders, Url) -> ok | {error, Reason}
591 store_cookies(SetCookieHeaders, Url, Profile) ->
593 ok | {error, Reason}
594 Types:
596 SetCookieHeaders = [HttpHeader]
598 Where field = "set-cookie"
599 HttpHeader = {Field :: [byte()], Value :: binary() |
600 iolist()}
601 Url = term()
602 Profile = atom() | pid()
603 When started stand_alone only the pid can be used.
604 Reason = term()
605 Saves the cookies defined in SetCookieHeaders in the client pro‐
607 file cookie database. Call this function if option cookies is
608 set to verify. If no profile is specified, the default profile
609 is used.
610 stream_next(Pid) -> ok
612 Types:
614 Pid = pid()
616 As received in the stream_start message
617 Triggers the next message to be streamed, that is, the same be‐
619 havior as active ones for sockets.
620 which_cookies() -> [CookieStores]
622 which_cookies(Profile) -> [CookieStores]
624 Types:
626 Profile = atom() | pid()
628 When started stand_alone only the pid can be used.
629 CookieStores = {cookies, Cookies} | {session_cookies, Cook‐
630 ies}
631 Cookies = [term()]
632 Produces a list of the entire cookie database. Intended for de‐
634 bugging/testing purposes. If no profile is specified, the de‐
635 fault profile is used.
636 which_sessions() -> SessionInfo
638 which_sessions(Profile) -> SessionInfo
640 Types:
642 Profile = atom() | pid()
644 When started stand_alone only the pid can be used.
645 SessionInfo = {GoodSession, BadSessions, NonSessions}
646 GoodSession = [Session]
647 BadSessions = NonSessions = [term()]
648 Session = term()
649 Internal representation of a session.
650 This function is intended for debugging only. It produces a
652 slightly processed dump of the session database. The first list
653 of the session information tuple will contain session informa‐
654 tion on an internal format. The last two lists of the session
655 information tuple should always be empty if the code is working
656 as intended. If no profile is specified, the default profile is
657 used.
658
660 RFC 2616, inets(3), gen_tcp(3), ssl(3)
661Ericsson AB inets 8.2.1 httpc(3)