From a2a1883e04aaa923b385cbbc496395ed5bf1dc17 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Mon, 6 Jul 2015 21:21:27 +0200 Subject: Inets Reference Manual Editorial changes --- lib/inets/doc/src/httpc.xml | 658 ++++++++++++++++++++++---------------------- 1 file changed, 330 insertions(+), 328 deletions(-) (limited to 'lib/inets/doc/src/httpc.xml') diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 05eec9cfd3..70400d1ca7 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -31,108 +31,117 @@ httpc - An HTTP/1.1 client + An HTTP/1.1 client -

This module provides the API to a HTTP/1.1 compatible client according - to RFC 2616, caching is currently not supported.

+

This module provides the API to an HTTP/1.1 compatible client according + to RFC 2616. + Caching is not supported.

-

When starting the Inets application a manager process for the - default profile will be started. The functions in this API - that do not explicitly use a profile will access the +

When starting the Inets application, a manager process for the + default profile is started. The functions in this API + that do not explicitly use a profile accesses the default profile. A profile keeps track of proxy options, - cookies and other options that can be applied to more than one - request.

+ cookies, and other options that can be applied to more than one + request.

-

If the scheme https is used the ssl application needs to be - started. When https links needs to go through a proxy the +

If the scheme https is used, the SSL application must + be started. When https links need to go through a proxy, the CONNECT method extension to HTTP-1.1 is used to establish a - tunnel and then the connection is upgraded to TLS, - however "TLS upgrade" according to RFC 2817 is not + tunnel and then the connection is upgraded to TLS. + However, "TLS upgrade" according to RFC 2817 is not supported.

-

Also note that pipelining will only be used if the pipeline - timeout is set, otherwise persistent connections without - pipelining will be used e.i. the client always waits for +

Pipelining is only used if the pipeline + time-out is set, otherwise persistent connections without + pipelining are used. For example, the client always waits for the previous response before sending the next request.

 -

There are some usage examples in the Inets User's Guide.

+

Some examples are provided in the Inets User's Guide.
- COMMON DATA TYPES + DATA TYPES +

Type definitions that are used more than once in this module:

- - +

boolean() = true | false

+

string() = list of ASCII characters

+

request_id() = ref()

+

profile() = atom()

+

path() = string() representing a file path or directory path

+

ip_address() = See the + inet(3) manual page in Kernel.

+

socket_opt() = See the options used by + gen_tcp(3) gen_tcp(3) and + ssl(3) connect(s)

+
- HTTP DATA TYPES -

Type definitions that are related to HTTP:

-

For more information about HTTP see rfc 2616

- - body_processing_result(), - accumulator()} | - {chunkify, - fun(accumulator()) -> body_processing_result(), - accumulator()} -body_processing_result() = eof | {ok, iolist(), accumulator()} -accumulator() = term() -filename() = string() - ]]> + HTTP DATA TYPES +

Type definitions related to HTTP:

-
+

method() = head | get | put | post | trace | options | delete

+ + request() +

= {url(), headers()}

+

| {url(), headers(), content_type(), body()}

+ + +

url() = string() syntax according to the URI definition in + RFC 2396, + for example "http://www.erlang.org"

+

status_line() = {http_version(), status_code(), reason_phrase()}

+

http_version() = string(), for example, "HTTP/1.1"

+

status_code() = integer()

+

reason_phrase() = string()

+

content_type() = string()

+

headers() = [header()]

+

header() = {field(), value()}

+

field() = string()

+

value() = string()

+ + body() +

= string() | binary()

+

| {fun(accumulator())

+

-> body_processing_result(), accumulator()}

+

| {chunkify, fun(accumulator())

+

-> body_processing_result(), accumulator()}

+ + +

body_processing_result() = eof | {ok, iolist(), accumulator()}

+

accumulator() = term()

+

filename() = string()

+

For more information about HTTP, see + RFC 2616.

+
- SSL DATA TYPES + SSL DATA TYPES

See ssl(3) for information - about ssl options (ssloptions()).

+ about SSL options (ssloptions()).

- HTTP CLIENT SERVICE START/STOP + HTTP CLIENT SERVICE START/STOP -

A HTTP client can be configured to start when starting the inets +

An HTTP client can be configured to start when starting the Inets application or started dynamically in runtime by calling the - inets application API inets:start(httpc, ServiceConfig), or - inets:start(httpc, ServiceConfig, How) - see inets(3). Below follows a - description of the available configuration options.

+ Inets application API inets:start(httpc, ServiceConfig) + or inets:start(httpc, ServiceConfig, How), + see inets(3). + The configuration options are as follows:

{profile, profile()} - Name of the profile, see - common data types below, this option is mandatory. +

Name of the profile, see + DATA TYPES. + This option is mandatory.

 {data_dir, path()} - Directory where the profile - may save persistent data, if omitted all cookies will be treated - as session cookies. +

Directory where the profile + can save persistent data. If omitted, all cookies are treated + as session cookies.

The client can be stopped using inets:stop(httpc, Pid) or @@ -145,14 +154,15 @@ filename() = string() request(Url) -> request(Url, Profile) -> {ok, Result} | {error, Reason} - Sends a get HTTP-request + Sends a get HTTP request. - Url = url() + Url = url() Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id() + {status_code(), Body} | request_id() Body = string() | binary() - Profile = profile() | pid() (when started stand_alone) - Reason = term() + Profile = profile() | pid() + When started stand_alone. + Reason = term()

Equivalent to httpc:request(get, {Url, []}, [], []).

@@ -162,12 +172,12 @@ filename() = string() - request(Method, Request, HTTPOptions, Options) -> + request(Method, Request, HTTPOptions, Options) -> request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason} - Sends a HTTP-request + Sends an HTTP request. - Method = method() + Method = method() Request = request() HTTPOptions = http_options() http_options() = [http_option()] @@ -191,215 +201,198 @@ filename() = string() {socket_opts, socket_opts()} | {receiver, receiver()}, {ipv6_host_with_brackets, boolean()}} - stream_to() = none | self | {self, once} | filename() + stream_to() = none | self | {self, once} | filename() socket_opts() = [socket_opt()] - receiver() = pid() | function()/1 | {Module, Function, Args} - Module = atom() - Function = atom() - Args = list() - body_format() = string | binary + receiver() = pid() | function()/1 | {Module, Function, Args} + Module = atom() + Function = atom() + Args = list() + body_format() = string | binary Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id() + {status_code(), Body} | request_id() Body = string() | binary() - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. Reason = {connect_failed, term()} | - {send_failed, term()} | term() + {send_failed, term()} | term() -

Sends a HTTP-request. The function can be both synchronous - and asynchronous. In the later case the function will return - {ok, RequestId} and later on the information will be delivered - to the receiver depending on that value.

+

Sends an HTTP request. The function can be both synchronous + and asynchronous. In the latter case, the function returns + {ok, RequestId} and then the information is delivered + to the receiver depending on that value.

-

Http option (http_option()) details:

+

HTTP option (http_option()) details:

-

Timeout time for the request.

-

The clock starts ticking as soon as the request has been - sent.

-

Time is in milliseconds.

-

Defaults to infinity.

+

Time-out time for the request.

+

The clock starts ticking when the request is sent.

+

Time is in milliseconds.

+

Default is infinity.

 -

Connection timeout time, used during the initial request, - when the client is connecting to the server.

-

Time is in milliseconds.

-

Defaults to the value of the timeout option.

+

Connection time-out time, used during the initial request, + when the client is connecting to the server.

+

Time is in milliseconds.

+

Default is the value of option timeout.

 -

This is the default ssl config option, currently defaults to - essl, see below.

-

Defaults to [].

- - - - -

If using the Erlang based implementation of SSL, - these SSL-specific options are used.

-

Defaults to [].

+

This is the default SSL configuration option.

+

Defaults to [].

 -

Should the client automatically retrieve the information - from the new URI and return that as the result instead - of a 30X-result code.

-

Note that for some 30X-result codes automatic redirect - is not allowed. In these cases the 30X-result will always - be returned.

-

Defaults to true.

+

The client automatically retrieves the information + from the new URI and returns that as the result, instead + of a 30X-result code.

+

For some 30X-result codes, automatic redirect + is not allowed. In these cases the 30X-result is always to + be returned.

+

Default is true.

 -

A proxy-authorization header using the provided user name and - password will be added to the request.

+

A proxy-authorization header using the provided username and + password is added to the request.

Can be used to make the client act as an HTTP/1.0 or HTTP/0.9 client. By default this is an HTTP/1.1 - client. When using HTTP/1.0 persistent connections will - not be used.

-

Defaults to the string "HTTP/1.1".

+ client. When using HTTP/1.0 persistent connections are + not used.

+

Default is the string "HTTP/1.1".

 -

If set to true workarounds for known server deviations - from the HTTP-standard are enabled.

-

Defaults to false.

+

If set to true, workarounds for known server deviations + from the HTTP-standard are enabled.

+

Default is false.

 -

Will apply Percent-encoding, also known as URL encoding on the +

Applies Percent-encoding, also known as URL encoding on the URL.

-

Defaults to false.

+

Default is false.

 -

Option (option()) details:

+

Option (option()) details:

-

Shall the request be synchronous or asynchronous.

-

Defaults to true.

+

Option for the request to be synchronous or asynchronous.

+

Default is true.

Streams the body of a 200 or 206 response to the calling process or to a file. When streaming to the calling process - using the option self the following stream messages - will be sent to that process: {http, {RequestId, + using option self, the following stream messages + are sent to that process: {http, {RequestId, stream_start, Headers}}, {http, {RequestId, stream, - BinBodyPart}}, {http, {RequestId, stream_end, Headers}}. When - streaming to the calling processes using the option - {self, once} the first message will have an additional - element e.i. {http, {RequestId, stream_start, Headers, Pid}}, - this is the process id that should be used as an argument to + BinBodyPart}}, and {http, {RequestId, stream_end, Headers}}.

+

When streaming to the calling processes using option + {self, once}, the first message has an extra + element, that is, {http, {RequestId, stream_start, Headers, Pid}}. + This is the process id to be used as an argument to http:stream_next/1 to trigger the next message to be sent to - the calling process.

-

Note that it is possible that chunked encoding will add + the calling process.

+

Notice that chunked encoding can add headers so that there are more headers in the stream_end - message than in the stream_start. - When streaming to a file and the request is asynchronous the - message {http, {RequestId, saved_to_file}} will be sent.

-

Defaults to none.

+ message than in stream_start. + When streaming to a file and the request is asynchronous, the + message {http, {RequestId, saved_to_file}} is sent.

+

Default is none.

 -

Defines if the body shall be delivered as a string or as a +

Defines if the body is to be delivered as a string or binary. This option is only valid for the synchronous - request.

-

Defaults to string.

+ request.

+

Default is string.

 -

Should a "full result" be returned to the caller (that is, - the body, the headers and the entire status-line) or not - (the body and the status code).

-

Defaults to true.

+

Defines if a "full result" is to be returned to the caller (that is, + the body, the headers, and the entire status line) or not + (the body and the status code).

+

Default is true.

 -

Shall the headers provided by the user be made - lower case or be regarded as case sensitive.

-

Note that the http standard requires them to be - case insenstive. This feature should only be used if there is +

Defines if the headers provided by the user are to be made + lower case or to be regarded as case sensitive.

+

The HTTP standard requires them to be + case insensitive. Use this feature only if there is no other way to communicate with the server or for testing - purpose. Also note that when this option is used no headers - will be automatically added, all necessary headers have to be - provided by the user.

-

Defaults to false.

+ purpose. When this option is used, no headers + are automatically added. All necessary headers must be + provided by the user.

+

Default is false.

Socket options to be used for this and subsequent - request(s).

-

Overrides any value set by the - set_options - function.

-

Note that the validity of the options are not - checked in any way.

-

Note that this may change the socket behaviour + requests.

+

Overrides any value set by function + set_options.

+

The validity of the options is not + checked in any way.

+

Notice that this can change the socket behavior (see inet:setopts/2) for an already existing one, and therefore an already connected - request handler.

-

By default the socket options set by the + request handler.

+

By default the socket options set by function set_options/1,2 - function are used when establishing a connection.

+ are used when establishing a connection.

 -

Defines how the client will deliver the result of an - asynchronous request (sync has the value - false).

+

Defines how the client delivers the result of an + asynchronous request (sync has the value + false).

-

Message(s) will be sent to this process in the format:

-
-{http, ReplyInfo}
-
+

Messages are sent to this process in the format + {http, ReplyInfo}.

 -

Information will be delivered to the receiver via calls - to the provided fun:

-
-Receiver(ReplyInfo)
-
+

Information is delivered to the receiver through calls + to the provided fun Receiver(ReplyInfo).

 -

Information will be delivered to the receiver via calls - to the callback function:

-
-apply(Module, Function, [ReplyInfo | Args])
-
+

Information is delivered to the receiver through calls + to the callback function + apply(Module, Function, [ReplyInfo | Args]).

 - -

In all of the above cases, ReplyInfo has the following - structure:

+

In all of these cases, ReplyInfo has the following + structure:

 {RequestId, saved_to_file}
@@ -407,11 +400,10 @@ apply(Module, Function, [ReplyInfo | Args])
 {RequestId, Result}
 {RequestId, stream_start, Headers}
 {RequestId, stream_start, Headers, HandlerPid}
-{RequestId, stream,       BinBodyPart}
-{RequestId, stream_end,   Headers}
-
+{RequestId, stream, BinBodyPart} +{RequestId, stream_end, Headers} -

Defaults to the pid() of the process calling the request +

Default is the pid() of the process calling the request function (self()).

@@ -419,10 +411,10 @@ apply(Module, Function, [ReplyInfo | Args]) -

When parsing the Host-Port part of an URI with a IPv6 address - with brackets, shall we retain those brackets (true) or - strip them (false).

-

Defaults to false.

+

Defines when parsing the Host-Port part of an URI with an IPv6 address + with brackets, if those brackets are to be retained (true) + or stripped (false).

+

Default is false.

 @@ -432,18 +424,19 @@ apply(Module, Function, [ReplyInfo | Args]) - cancel_request(RequestId) -> + cancel_request(RequestId) -> cancel_request(RequestId, Profile) -> ok - Cancels an asynchronous HTTP-request. + Cancels an asynchronous HTTP request. RequestId = request_id() - A unique identifier as returned by request/4 - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. -

Cancels an asynchronous HTTP-request. Note this does not guarantee - that the request response will not be delivered, as it is asynchronous the - the request may already have been completed when the cancellation arrives. +

Cancels an asynchronous HTTP request. Notice that this does not guarantee + that the request response is not delivered. Because it is asynchronous, + the request can already have been completed when the cancellation arrives.

@@ -456,106 +449,106 @@ apply(Module, Function, [ReplyInfo | Args]) Sets options to be used for subsequent requests. Options = [Option] - Option = {proxy, {Proxy, NoProxy}} | - {https_proxy, {Proxy, NoProxy}} | - {max_sessions, MaxSessions} | - {max_keep_alive_length, MaxKeepAlive} | - {keep_alive_timeout, KeepAliveTimeout} | - {max_pipeline_length, MaxPipeline} | - {pipeline_timeout, PipelineTimeout} | - {cookies, CookieMode} | - {ipfamily, IpFamily} | - {ip, IpAddress} | - {port, Port} | - {socket_opts, socket_opts()} | - {verbose, VerboseMode} - + Option = {proxy, {Proxy, NoProxy}} + | {https_proxy, {Proxy, NoProxy}} + | {max_sessions, MaxSessions} + | {max_keep_alive_length, MaxKeepAlive} + | {keep_alive_timeout, KeepAliveTimeout} + | {max_pipeline_length, MaxPipeline} + | {pipeline_timeout, PipelineTimeout} + | {cookies, CookieMode} + | {ipfamily, IpFamily} + | {ip, IpAddress} + | {port, Port} + | {socket_opts, socket_opts()} + | {verbose, VerboseMode} Proxy = {Hostname, Port} - Hostname = string() - ex: "localhost" or "foo.bar.se" + Hostname = string() + Example: "localhost" or "foo.bar.se" Port = integer() - ex: 8080 + Example: 8080 NoProxy = [NoProxyDesc] NoProxyDesc = DomainDesc | HostName | IPDesc DomainDesc = "*.Domain" - ex: "*.ericsson.se" + Example: "*.ericsson.se" IpDesc = string() - ex: "134.138" or "[FEDC:BA98" (all IP-addresses starting with 134.138 or FEDC:BA98), "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP-address). - - proxy defaults to {undefined, []} e.i. no proxy is configured and https_proxy defaults to - the value of proxy. - - MaxSessions = integer() - Default is 2. - Maximum number of persistent connections to a host. - MaxKeepAlive = integer() - Default is 5. - Maximum number of outstanding requests on the same connection to - a host. - KeepAliveTimeout = integer() - Default is 120000 (= 2 min). - If a persistent connection is idle longer than the + Example: "134.138" or "[FEDC:BA98" + (all IP addresses starting with 134.138 or FEDC:BA98), + "66.35.250.150" or "[2010:836B:4179::836B:4179]" (a complete IP address). + proxy defaults to {undefined, []}, + that is, no proxy is configured and + https_proxy defaults to the value of proxy. + MaxSessions = integer() + Maximum number of persistent connections to a host. + Default is 2. + MaxKeepAlive = integer() + Maximum number of outstanding requests on the same connection to + a host. Default is 5. + KeepAliveTimeout = integer() + If a persistent connection is idle longer than the keep_alive_timeout in milliseconds, - the client will close the connection. - The server may also have such a time out but you should - not count on it! - MaxPipeline = integer() - Default is 2. - Maximum number of outstanding requests on a pipelined connection - to a host. - PipelineTimeout = integer() - Default is 0, - which will result in pipelining not being used. - If a persistent connection is idle longer than the + the client closes the connection. + The server can also have such a time-out but do not take that for granted. + Default is 120000 (= 2 min). + MaxPipeline = integer() + Maximum number of outstanding requests on a pipelined connection + to a host. Default is 2. + PipelineTimeout = integer() + If a persistent connection is idle longer than the pipeline_timeout in milliseconds, - the client will close the connection. - CookieMode = enabled | disabled | verify - Default is disabled. - If Cookies are enabled all valid cookies will automatically be - saved in the client manager's cookie database. - If the option verify is used the function store_cookies/2 - has to be called for the cookies to be saved. - IpFamily = inet | inet6 | inet6fb4 - By default inet. - When it is set to inet6fb4 you can use both ipv4 and ipv6. - It first tries inet6 and if that does not works falls back to inet. - The option is here to provide a workaround for buggy ipv6 stacks to ensure that - ipv4 will always work. - IpAddress = ip_address() - If the host has several network interfaces, this option specifies which one to use. - See gen_tcp:connect/3,4 for more info. - Port = integer() - Specify which local port number to use. - See gen_tcp:connect/3,4 for more info. + the client closes the connection. Default is 0, + which results in pipelining not being used. + CookieMode = enabled | disabled | verify + If cookies are enabled, all valid cookies are automatically + saved in the cookie database of the client manager. + If option verify is used, function store_cookies/2 + has to be called for the cookies to be saved. + Default is disabled. + IpFamily = inet | inet6 | inet6fb4 + When set to inet6fb4, both IPv4 and IPv6 can be used. + First inet6 is tried and if that does not work it falls + back to inet. + The option is to provide a workaround for buggy IPv6 stacks to ensure that + IPv4 always works. Default is inet. + IpAddress = ip_address() + If the host has several network interfaces, this option specifies + which one to use. + See gen_tcp:connect/3,4 + for details. + Port = integer() + Local port number to use. + See gen_tcp:connect/3,4 + for details. socket_opts() = [socket_opt()] The options are appended to the socket options used by the - client. + client. These are the default values when a new request handler is started (for the initial connect). They are passed directly - to the underlying transport (gen_tcp or ssl) without - verification! - VerboseMode = false | verbose | debug | trace + to the underlying transport (gen_tcp or SSL) + without verification. + VerboseMode = false | verbose | debug | trace Default is false. This option is used to switch on (or off) - different levels of erlang trace on the client. + different levels of Erlang trace on the client. It is a debug feature. - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone.

Sets options to be used for subsequent requests.

-

If possible the client will keep its connections - alive and use persistent connections - with or without pipeline depending on configuration +

If possible, the client keeps its connections + alive and uses persistent connections + with or without pipeline depending on configuration and current circumstances. The HTTP/1.1 specification does not - provide a guideline for how many requests would be - ideal to be sent on a persistent connection, - this very much depends on the - application. Note that a very long queue of requests may cause a - user perceived delay as earlier requests may take a long time - to complete. The HTTP/1.1 specification does suggest a - limit of 2 persistent connections per server, which is the - default value of the max_sessions option.

+ provide a guideline for how many requests that are + ideal to be sent on a persistent connection. + This depends much on the application.

+

A long queue of requests can cause a + user-perceived delay, as earlier requests can take a long time + to complete. The HTTP/1.1 specification suggests a + limit of two persistent connections per server, which is the + default value of option max_sessions.

 @@ -581,9 +574,10 @@ apply(Module, Function, [ReplyInfo | Args]) port | socket_opts | verbose - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid( + When started stand_alone. Values = [{option_item(), term()}] - Reason = term() + Reason = term()

Retrieves the options currently used by the client.

@@ -594,15 +588,16 @@ apply(Module, Function, [ReplyInfo | Args]) stream_next(Pid) -> ok - Triggers the next message to be streamed, e.i. - same behavior as active once for sockets. + Triggers the next message to be streamed, that is, + the same behavior as active ones for sockets. - Pid = pid() - as received in the stream_start message + Pid = pid() + As received in the stream_start message -

Triggers the next message to be streamed, e.i. - same behavior as active once for sockets.

+

Triggers the next message to be streamed, that is, + the same behavior as active ones for sockets.

@@ -612,18 +607,19 @@ apply(Module, Function, [ReplyInfo | Args]) store_cookies(SetCookieHeaders, Url) -> store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason} - Saves the cookies defined in SetCookieHeaders in the client profile's cookie database. + Saves the cookies defined in SetCookieHeaders in the + client profile cookie database. SetCookieHeaders = headers() - where field = "set-cookie" Url = url() - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. -

Saves the cookies defined in SetCookieHeaders - in the client profile's cookie database. You need to - call this function if you have set the option cookies - to verify. - If no profile is specified the default profile will be used.

+

Saves the cookies defined in SetCookieHeaders + in the client profile cookie database. + Call this function if option cookies is set to verify. + If no profile is specified, the default profile is used.

 @@ -633,22 +629,23 @@ apply(Module, Function, [ReplyInfo | Args]) cookie_header(Url) -> cookie_header(Url, Profile | Opts) -> header() | {error, Reason} cookie_header(Url, Opts, Profile) -> header() | {error, Reason} - Returns the cookie header that would be sent when - making a request to Url using the profile Profile. + Returns the cookie header that would have been sent when + making a request to URL using the profile Profile. Url = url() Opts = [cookie_header_opt()] - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. cookie_header_opt() = {ipv6_host_with_brackets, boolean()} -

Returns the cookie header that would be sent - when making a request to Url using the profile Profile. - If no profile is specified the default profile will be used.

-

The option ipv6_host_with_bracket deals with how to - parse IPv6 addresses. - See the Options argument of the - request/4,5 for more info.

+

Returns the cookie header that would have been sent + when making a request to Url using profile Profile. + If no profile is specified, the default profile is used.

+

Option ipv6_host_with_bracket deals with how to + parse IPv6 addresses. For details, + see argument Options of + request/4,5.

 @@ -658,14 +655,15 @@ apply(Module, Function, [ReplyInfo | Args]) reset_cookies() -> void() reset_cookies(Profile) -> void() - Reset the cookie database. + Resets the cookie database. - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone.

Resets (clears) the cookie database for the specified Profile. If no profile is specified the default profile - will be used.

+ is used.

 @@ -675,18 +673,19 @@ apply(Module, Function, [ReplyInfo | Args]) which_cookies() -> cookies() which_cookies(Profile) -> cookies() - Dumps out the entire cookie database. + Dumps the entire cookie database. - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. cookies() = [cookie_stores()] cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()} cookies() = [cookie()] cookie() = term() -

This function produces a list of the entire cookie database. - It is intended for debugging/testing purposes. - If no profile is specified the default profile will be used.

+

Produces a list of the entire cookie database. + Intended for debugging/testing purposes. + If no profile is specified, the default profile is used.

 @@ -697,16 +696,17 @@ apply(Module, Function, [ReplyInfo | Args]) which_sessions(Profile) -> session_info() Produces a slightly processed dump of the sessions database. - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. session_info() = {GoodSessions, BadSessions, NonSessions} GoodSessions = session() BadSessions = tuple() NonSessions = term() -

This function produces a slightly processed dump of the session +

Produces a slightly processed dump of the session database. It is intended for debugging. - If no profile is specified the default profile will be used.

+ If no profile is specified, the default profile is used.

 @@ -715,23 +715,25 @@ apply(Module, Function, [ReplyInfo | Args]) info() -> list() info(Profile) -> list() - Produces a list of miscelleneous info + Produces a list of miscellaneous information. - Profile = profile() | pid() (when started stand_alone) + Profile = profile() | pid() + When started stand_alone. -

This function produces a list of miscelleneous info. - It is intended for debugging. - If no profile is specified the default profile will be used.

+

Produces a list of miscellaneous information. + Intended for debugging. + If no profile is specified, the default profile is used.
SEE ALSO -

RFC 2616, inets(3), - gen_tcp(3), - ssl(3) +

RFC 2616, + inets(3), + gen_tcp(3), + ssl(3)

-- cgit v1.2.3 From 474dfaf674ac8746367ff856534ef0b63afc6307 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 1 Sep 2015 17:32:34 +0200 Subject: inets: Align with alphabetical order and clean local anchor handling Functions in the same module can be referenced as #Function-Arity, no need to make special markers for them. --- lib/inets/doc/src/httpc.xml | 255 +++++++++++++++++++++----------------------- 1 file changed, 119 insertions(+), 136 deletions(-) (limited to 'lib/inets/doc/src/httpc.xml') diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 70400d1ca7..9a24226e78 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -146,11 +146,112 @@

The client can be stopped using inets:stop(httpc, Pid) or inets:stop(httpc, Profile).

- -
+ + + cancel_request(RequestId) -> + cancel_request(RequestId, Profile) -> ok + Cancels an asynchronous HTTP request. + + RequestId = request_id() - A unique identifier as returned + by request/4 + Profile = profile() | pid() + When started stand_alone. + + +

Cancels an asynchronous HTTP request. Notice that this does not guarantee + that the request response is not delivered. Because it is asynchronous, + the request can already have been completed when the cancellation arrives. +

+ + + + + cookie_header(Url) -> + cookie_header(Url, Profile | Opts) -> header() | {error, Reason} + cookie_header(Url, Opts, Profile) -> header() | {error, Reason} + Returns the cookie header that would have been sent when + making a request to URL using the profile Profile. + + Url = url() + Opts = [cookie_header_opt()] + Profile = profile() | pid() + When started stand_alone. + cookie_header_opt() = {ipv6_host_with_brackets, boolean()} + + +

Returns the cookie header that would have been sent + when making a request to Url using profile Profile. + If no profile is specified, the default profile is used.

+

Option ipv6_host_with_bracket deals with how to + parse IPv6 addresses. For details, + see argument Options of + request/4,5.

+ + + + + get_options(OptionItems) -> {ok, Values} | {error, Reason} + get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason} + Gets the currently used options. + + OptionItems = all | [option_item()] + option_item() = proxy | + https_proxy + max_sessions | + keep_alive_timeout | + max_keep_alive_length | + pipeline_timeout | + max_pipeline_length | + cookies | + ipfamily | + ip | + port | + socket_opts | + verbose + Profile = profile() | pid( + When started stand_alone. + Values = [{option_item(), term()}] + Reason = term() + + +

Retrieves the options currently used by the client.

+ + + + + info() -> list() + info(Profile) -> list() + Produces a list of miscellaneous information. + + Profile = profile() | pid() + When started stand_alone. + + +

Produces a list of miscellaneous information. + Intended for debugging. + If no profile is specified, the default profile is used.

+ + + + + + reset_cookies() -> void() + reset_cookies(Profile) -> void() + Resets the cookie database. + + Profile = profile() | pid() + When started stand_alone. + + +

Resets (clears) the cookie database for the specified + Profile. If no profile is specified the default profile + is used.

+ + + request(Url) -> request(Url, Profile) -> {ok, Result} | {error, Reason} @@ -166,8 +267,6 @@

Equivalent to httpc:request(get, {Url, []}, [], []).

- - @@ -353,7 +452,7 @@

Socket options to be used for this and subsequent requests.

Overrides any value set by function - set_options.

+ set_options.

The validity of the options is not checked in any way.

Notice that this can change the socket behavior @@ -361,7 +460,7 @@ for an already existing one, and therefore an already connected request handler.

By default the socket options set by function - set_options/1,2 + set_options/[1,2] are used when establishing a connection.

@@ -418,31 +517,10 @@ - - - - - - - cancel_request(RequestId) -> - cancel_request(RequestId, Profile) -> ok - Cancels an asynchronous HTTP request. - - RequestId = request_id() - A unique identifier as returned - by request/4 - Profile = profile() | pid() - When started stand_alone. - - -

Cancels an asynchronous HTTP request. Notice that this does not guarantee - that the request response is not delivered. Because it is asynchronous, - the request can already have been completed when the cancellation arrives. -

- - + set_options(Options) -> set_options(Options, Profile) -> ok | {error, Reason} @@ -554,56 +632,7 @@ - - - get_options(OptionItems) -> {ok, Values} | {error, Reason} - get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason} - Gets the currently used options. - - OptionItems = all | [option_item()] - option_item() = proxy | - https_proxy - max_sessions | - keep_alive_timeout | - max_keep_alive_length | - pipeline_timeout | - max_pipeline_length | - cookies | - ipfamily | - ip | - port | - socket_opts | - verbose - Profile = profile() | pid( - When started stand_alone. - Values = [{option_item(), term()}] - Reason = term() - - -

Retrieves the options currently used by the client.

- - - - - - - stream_next(Pid) -> ok - Triggers the next message to be streamed, that is, - the same behavior as active ones for sockets. - - - Pid = pid() - As received in the stream_start message - - -

Triggers the next message to be streamed, that is, - the same behavior as active ones for sockets.

- - - - - - + store_cookies(SetCookieHeaders, Url) -> store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason} @@ -620,56 +649,27 @@ in the client profile cookie database. Call this function if option cookies is set to verify. If no profile is specified, the default profile is used.

- - - - - - - cookie_header(Url) -> - cookie_header(Url, Profile | Opts) -> header() | {error, Reason} - cookie_header(Url, Opts, Profile) -> header() | {error, Reason} - Returns the cookie header that would have been sent when - making a request to URL using the profile Profile. - - Url = url() - Opts = [cookie_header_opt()] - Profile = profile() | pid() - When started stand_alone. - cookie_header_opt() = {ipv6_host_with_brackets, boolean()} - - -

Returns the cookie header that would have been sent - when making a request to Url using profile Profile. - If no profile is specified, the default profile is used.

-

Option ipv6_host_with_bracket deals with how to - parse IPv6 addresses. For details, - see argument Options of - request/4,5.

- - - - reset_cookies() -> void() - reset_cookies(Profile) -> void() - Resets the cookie database. + stream_next(Pid) -> ok + Triggers the next message to be streamed, that is, + the same behavior as active ones for sockets. + - Profile = profile() | pid() - When started stand_alone. + Pid = pid() + As received in the stream_start message -

Resets (clears) the cookie database for the specified - Profile. If no profile is specified the default profile - is used.

+

Triggers the next message to be streamed, that is, + the same behavior as active ones for sockets.

- + + - - + which_cookies() -> cookies() which_cookies(Profile) -> cookies() @@ -686,8 +686,6 @@

Produces a list of the entire cookie database. Intended for debugging/testing purposes. If no profile is specified, the default profile is used.

- - @@ -707,25 +705,10 @@

Produces a slightly processed dump of the session database. It is intended for debugging. If no profile is specified, the default profile is used.

- - - - info() -> list() - info(Profile) -> list() - Produces a list of miscellaneous information. - - Profile = profile() | pid() - When started stand_alone. - - -

Produces a list of miscellaneous information. - Intended for debugging. - If no profile is specified, the default profile is used.

- - +
-- cgit v1.2.3 From 8e216b94beeed02e67f08d3bf9307c7c48e3b977 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 2 Sep 2015 12:11:50 +0200 Subject: inets: httpc - Clarify/correct documentation Remove legacy inet6fb4 option from documentation even if the code will still accept it. --- lib/inets/doc/src/httpc.xml | 64 ++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 33 deletions(-) (limited to 'lib/inets/doc/src/httpc.xml') diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 9a24226e78..31e44f405c 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -49,12 +49,12 @@ be started. When https links need to go through a proxy, the CONNECT method extension to HTTP-1.1 is used to establish a tunnel and then the connection is upgraded to TLS. - However, "TLS upgrade" according to RFC 2817 is not + However, "TLS upgrade" according to RFC 2817is not supported.

Pipelining is only used if the pipeline time-out is set, otherwise persistent connections without - pipelining are used. For example, the client always waits for + pipelining are used. That is, the client always waits for the previous response before sending the next request.

Some examples are provided in the RequestId = request_id() - A unique identifier as returned by request/4 Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used.

Cancels an asynchronous HTTP request. Notice that this does not guarantee @@ -188,7 +188,7 @@

Option ipv6_host_with_bracket deals with how to parse IPv6 addresses. For details, see argument Options of - request/4,5.

+ request/[4,5].

@@ -199,7 +199,7 @@ OptionItems = all | [option_item()] option_item() = proxy | - https_proxy + https_proxy | max_sessions | keep_alive_timeout | max_keep_alive_length | @@ -211,8 +211,8 @@ port | socket_opts | verbose - Profile = profile() | pid( - When started stand_alone. + Profile = profile() | pid() + When started stand_alone only the pid can used. Values = [{option_item(), term()}] Reason = term() @@ -227,7 +227,7 @@ Produces a list of miscellaneous information. Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used.

Produces a list of miscellaneous information. @@ -243,7 +243,7 @@ Resets the cookie database. Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used.

Resets (clears) the cookie database for the specified @@ -262,7 +262,7 @@ {status_code(), Body} | request_id() Body = string() | binary() Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used. Reason = term() @@ -311,7 +311,7 @@ {status_code(), Body} | request_id() Body = string() | binary() Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used. Reason = {connect_failed, term()} | {send_failed, term()} | term() @@ -343,8 +343,8 @@ -

This is the default SSL configuration option.

-

Defaults to [].

+

This is the SSL/TLS connectin configuration option.

+

Defaults to []. See ssl:connect/[2, 3,4] for availble options.

@@ -353,8 +353,8 @@ from the new URI and returns that as the result, instead of a 30X-result code.

For some 30X-result codes, automatic redirect - is not allowed. In these cases the 30X-result is always to - be returned.

+ is not allowed. In these cases the 30X-result is always + returned.

Default is true.

@@ -453,12 +453,14 @@ requests.

Overrides any value set by function set_options.

-

The validity of the options is not - checked in any way.

-

Notice that this can change the socket behavior - (see inet:setopts/2) - for an already existing one, and therefore an already connected - request handler.

+

The validity of the options is not checked by + the HTTP client they are assumed to be correct and passed + on to ssl application and inet driver, which may reject + them if they are not correct. Note that the current + implementation assumes the requests to the same host, port + combination will use the same socket options. +

+

By default the socket options set by function set_options/[1,2] are used when establishing a connection.

@@ -502,7 +504,7 @@ {RequestId, stream, BinBodyPart} {RequestId, stream_end, Headers} -

Default is the pid() of the process calling the request +

Default is the pid of the process calling the request function (self()).

@@ -582,12 +584,8 @@ If option verify is used, function store_cookies/2 has to be called for the cookies to be saved. Default is disabled. - IpFamily = inet | inet6 | inet6fb4 - When set to inet6fb4, both IPv4 and IPv6 can be used. - First inet6 is tried and if that does not work it falls - back to inet. - The option is to provide a workaround for buggy IPv6 stacks to ensure that - IPv4 always works. Default is inet. + IpFamily = inet | inet6 + Default is inet. IpAddress = ip_address() If the host has several network interfaces, this option specifies which one to use. @@ -610,7 +608,7 @@ different levels of Erlang trace on the client. It is a debug feature. Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used.

Sets options to be used for subsequent requests.

@@ -642,7 +640,7 @@ SetCookieHeaders = headers() - where field = "set-cookie" Url = url() Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used.

Saves the cookies defined in SetCookieHeaders @@ -655,7 +653,7 @@ stream_next(Pid) -> ok Triggers the next message to be streamed, that is, - the same behavior as active ones for sockets. + the same behavior as active one for sockets. Pid = pid() @@ -676,7 +674,7 @@ Dumps the entire cookie database. Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used. cookies() = [cookie_stores()] cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()} cookies() = [cookie()] @@ -695,7 +693,7 @@ Produces a slightly processed dump of the sessions database. Profile = profile() | pid() - When started stand_alone. + When started stand_alone only the pid can be used. session_info() = {GoodSessions, BadSessions, NonSessions} GoodSessions = session() BadSessions = tuple() -- cgit v1.2.3