diff options
Diffstat (limited to 'lib/inets/doc/src/httpc.xml')
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 860 |
1 files changed, 422 insertions, 438 deletions
diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 4178cb7d4c..31e44f405c 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -8,16 +8,17 @@ <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -30,143 +31,252 @@ </header> <module>httpc</module> - <modulesummary>An HTTP/1.1 client </modulesummary> + <modulesummary>An HTTP/1.1 client</modulesummary> <description> - <p>This module provides the API to a HTTP/1.1 compatible client according - to RFC 2616, caching is currently not supported.</p> + <p>This module provides the API to an HTTP/1.1 compatible client according + to <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>. + Caching is not supported.</p> <note> - <p>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 + <p>When starting the <c>Inets</c> 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. </p> + cookies, and other options that can be applied to more than one + request.</p> - <p>If the scheme https is used the ssl application needs to be - started. When https links needs to go through a proxy the + <p>If the scheme <c>https</c> is used, the <c>SSL</c> application must + be started. When <c>https</c> 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 <url href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</url>is not supported.</p> - <p>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 + <p>Pipelining is only used if the pipeline + time-out is set, otherwise persistent connections without + pipelining are used. That is, the client always waits for the previous response before sending the next request.</p> </note> - <p>There are some usage examples in the <seealso - marker="http_client">Inets User's Guide.</seealso></p> + <p>Some examples are provided in the <seealso + marker="http_client">Inets User's Guide</seealso>.</p> </description> <section> - <title>COMMON DATA TYPES </title> + <title>DATA TYPES</title> + <marker id="DATA_TYPES"></marker> <p>Type definitions that are used more than once in this module:</p> - <code type="none"><![CDATA[ -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 inet(3) -socket_opt() = See the Options used by gen_tcp(3) and - ssl(3) connect(s) - ]]></code> - + <p><c>boolean() = true | false</c></p> + <p><c>string()</c> = list of ASCII characters</p> + <p><c>request_id() = ref()</c></p> + <p><c>profile() = atom()</c></p> + <p><c>path() = string()</c> representing a file path or directory path</p> + <p><c>ip_address()</c> = See the + <seealso marker="kernel:inet">inet(3)</seealso> manual page in <c>Kernel</c>.</p> + <p><c>socket_opt()</c> = See the options used by + <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> <c>gen_tcp(3)</c> and + <seealso marker="ssl:ssl">ssl(3)</seealso> connect(s)</p> + </section> <section> - <title>HTTP DATA TYPES </title> - <p>Type definitions that are related to HTTP:</p> - <p>For more information about HTTP see rfc 2616</p> - - <code type="none"><![CDATA[ -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, ex: "http://www.erlang.org" -status_line() = {http_version(), status_code(), reason_phrase()} -http_version() = string() ex: "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() - ]]></code> + <title>HTTP DATA TYPES</title> + <p>Type definitions related to HTTP:</p> - </section> + <p><c>method() = head | get | put | post | trace | options | delete</c></p> + <taglist> + <tag><c>request()</c></tag> + <item><p>= <c>{url(), headers()}</c></p> + <p>| <c>{url(), headers(), content_type(), body()}</c></p> + </item> + </taglist> + <p><c>url() = string()</c> syntax according to the URI definition in + <url href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</url>, + for example <c>"http://www.erlang.org"</c></p> + <p><c>status_line() = {http_version(), status_code(), reason_phrase()}</c></p> + <p><c>http_version() = string()</c>, for example, <c>"HTTP/1.1"</c></p> + <p><c>status_code() = integer()</c></p> + <p><c>reason_phrase() = string()</c></p> + <p><c>content_type() = string()</c></p> + <p><c>headers() = [header()]</c></p> + <p><c>header() = {field(), value()}</c></p> + <p><c>field() = string()</c></p> + <p><c>value() = string()</c></p> + <taglist> + <tag><c>body()</c></tag> + <item><p>= <c>string() | binary()</c></p> + <p>| <c>{fun(accumulator())</c></p> + <p><c> -> body_processing_result(), accumulator()}</c></p> + <p>| <c>{chunkify, fun(accumulator())</c></p> + <p><c> -> body_processing_result(), accumulator()}</c></p> + </item> + </taglist> + <p><c>body_processing_result() = eof | {ok, iolist(), accumulator()}</c></p> + <p><c>accumulator() = term()</c></p> + <p><c>filename() = string()</c></p> + <p>For more information about HTTP, see + <url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>.</p> +</section> <section> - <title>SSL DATA TYPES </title> + <title>SSL DATA TYPES</title> <p>See <seealso marker="ssl:ssl">ssl(3)</seealso> for information - about ssl options (<c>ssloptions()</c>). </p> + about <c>SSL</c> options (<c>ssloptions()</c>). </p> </section> <section> - <title>HTTP CLIENT SERVICE START/STOP </title> + <title>HTTP CLIENT SERVICE START/STOP</title> - <p>A HTTP client can be configured to start when starting the inets + <p>An HTTP client can be configured to start when starting the <c>Inets</c> application or started dynamically in runtime by calling the - inets application API <c>inets:start(httpc, ServiceConfig)</c>, or - <c>inets:start(httpc, ServiceConfig, How)</c> - see <seealso marker="inets">inets(3)</seealso>. Below follows a - description of the available configuration options.</p> + <c>Inets</c> application API <c>inets:start(httpc, ServiceConfig)</c> + or <c>inets:start(httpc, ServiceConfig, How)</c>, + see <seealso marker="inets">inets(3)</seealso>. + The configuration options are as follows:</p> <taglist> <tag>{profile, profile()}</tag> - <item>Name of the profile, see - common data types below, this option is mandatory.</item> + <item><p>Name of the profile, see + <seealso marker="#DATA_TYPES">DATA TYPES</seealso>. + This option is mandatory.</p></item> <tag>{data_dir, path()}</tag> - <item>Directory where the profile - may save persistent data, if omitted all cookies will be treated - as session cookies.</item> + <item><p>Directory where the profile + can save persistent data. If omitted, all cookies are treated + as session cookies.</p></item> </taglist> <p>The client can be stopped using <c>inets:stop(httpc, Pid)</c> or <c>inets:stop(httpc, Profile)</c>.</p> - - <marker id="request1"></marker> </section> <funcs> + + <func> + <name>cancel_request(RequestId) -></name> + <name>cancel_request(RequestId, Profile) -> ok</name> + <fsummary>Cancels an asynchronous HTTP request.</fsummary> + <type> + <v>RequestId = request_id() - A unique identifier as returned + by request/4</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> + </type> + <desc> + <p>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. + </p> + </desc> + </func> + + <func> + <name>cookie_header(Url) -> </name> + <name>cookie_header(Url, Profile | Opts) -> header() | {error, Reason}</name> + <name>cookie_header(Url, Opts, Profile) -> header() | {error, Reason}</name> + <fsummary>Returns the cookie header that would have been sent when + making a request to URL using the profile <c>Profile</c>.</fsummary> + <type> + <v>Url = url()</v> + <v>Opts = [cookie_header_opt()]</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c>.</d> + <v>cookie_header_opt() = {ipv6_host_with_brackets, boolean()}</v> + </type> + <desc> + <p>Returns the cookie header that would have been sent + when making a request to <c>Url</c> using profile <c>Profile</c>. + If no profile is specified, the default profile is used.</p> + <p>Option <c>ipv6_host_with_bracket</c> deals with how to + parse IPv6 addresses. For details, + see argument <c>Options</c> of + <seealso marker="#request-4">request/[4,5]</seealso>.</p> + </desc> + </func> + + <func> + <name>get_options(OptionItems) -> {ok, Values} | {error, Reason}</name> + <name>get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}</name> + <fsummary>Gets the currently used options.</fsummary> + <type> + <v>OptionItems = all | [option_item()]</v> + <v>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</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can used.</d> + <v>Values = [{option_item(), term()}]</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Retrieves the options currently used by the client.</p> + </desc> + </func> + + <func> + <name>info() -> list()</name> + <name>info(Profile) -> list()</name> + <fsummary>Produces a list of miscellaneous information.</fsummary> + <type> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> + </type> + <desc> + <p>Produces a list of miscellaneous information. + Intended for debugging. + If no profile is specified, the default profile is used.</p> + </desc> + </func> + + + <func> + <name>reset_cookies() -> void()</name> + <name>reset_cookies(Profile) -> void()</name> + <fsummary>Resets the cookie database.</fsummary> + <type> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> + </type> + <desc> + <p>Resets (clears) the cookie database for the specified + <c>Profile</c>. If no profile is specified the default profile + is used.</p> + </desc> + </func> + <func> <name>request(Url) -> </name> <name>request(Url, Profile) -> {ok, Result} | {error, Reason}</name> - <fsummary>Sends a get HTTP-request</fsummary> + <fsummary>Sends a get HTTP request.</fsummary> <type> - <v>Url = url() </v> + <v>Url = url()</v> <v>Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id() </v> + {status_code(), Body} | request_id()</v> <v>Body = string() | binary()</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - <v>Reason = term() </v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> + <v>Reason = term()</v> </type> <desc> <p>Equivalent to <c>httpc:request(get, {Url, []}, [], [])</c>.</p> - - <marker id="request2"></marker> </desc> </func> <func> - <name>request(Method, Request, HTTPOptions, Options) -> </name> + <name>request(Method, Request, HTTPOptions, Options) -></name> <name>request(Method, Request, HTTPOptions, Options, Profile) -> {ok, Result} | {ok, saved_to_file} | {error, Reason}</name> - <fsummary>Sends a HTTP-request</fsummary> + <fsummary>Sends an HTTP request.</fsummary> <type> - <v>Method = method() </v> + <v>Method = method()</v> <v>Request = request()</v> <v>HTTPOptions = http_options()</v> <v>http_options() = [http_option()]</v> @@ -190,215 +300,200 @@ filename() = string() {socket_opts, socket_opts()} | {receiver, receiver()}, {ipv6_host_with_brackets, boolean()}}</v> - <v>stream_to() = none | self | {self, once} | filename() </v> + <v>stream_to() = none | self | {self, once} | filename()</v> <v>socket_opts() = [socket_opt()]</v> - <v>receiver() = pid() | function()/1 | {Module, Function, Args} </v> - <v>Module = atom() </v> - <v>Function = atom() </v> - <v>Args = list() </v> - <v>body_format() = string | binary </v> + <v>receiver() = pid() | function()/1 | {Module, Function, Args}</v> + <v>Module = atom()</v> + <v>Function = atom()</v> + <v>Args = list()</v> + <v>body_format() = string | binary</v> <v>Result = {status_line(), headers(), Body} | - {status_code(), Body} | request_id() </v> + {status_code(), Body} | request_id()</v> <v>Body = string() | binary()</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> <v>Reason = {connect_failed, term()} | - {send_failed, term()} | term() </v> + {send_failed, term()} | term()</v> </type> <desc> - <p>Sends a HTTP-request. The function can be both synchronous - and asynchronous. In the later case the function will return - <c>{ok, RequestId}</c> and later on the information will be delivered - to the <c>receiver</c> depending on that value. </p> + <p>Sends an HTTP request. The function can be both synchronous + and asynchronous. In the latter case, the function returns + <c>{ok, RequestId}</c> and then the information is delivered + to the <c>receiver</c> depending on that value.</p> - <p>Http option (<c>http_option()</c>) details: </p> + <p>HTTP option (<c>http_option()</c>) details:</p> <marker id="request2_http_options"></marker> <taglist> <tag><c><![CDATA[timeout]]></c></tag> <item> - <p>Timeout time for the request. </p> - <p>The clock starts ticking as soon as the request has been - sent. </p> - <p>Time is in milliseconds. </p> - <p>Defaults to <c>infinity</c>. </p> + <p>Time-out time for the request.</p> + <p>The clock starts ticking when the request is sent.</p> + <p>Time is in milliseconds.</p> + <p>Default is <c>infinity</c>.</p> </item> <tag><c><![CDATA[connect_timeout]]></c></tag> <item> - <p>Connection timeout time, used during the initial request, - when the client is <em>connecting</em> to the server. </p> - <p>Time is in milliseconds. </p> - <p>Defaults to the value of the <c>timeout</c> option. </p> + <p>Connection time-out time, used during the initial request, + when the client is <em>connecting</em> to the server.</p> + <p>Time is in milliseconds.</p> + <p>Default is the value of option <c>timeout</c>.</p> </item> <tag><c><![CDATA[ssl]]></c></tag> <item> - <p>This is the default ssl config option, currently defaults to - <c>essl</c>, see below. </p> - <p>Defaults to <c>[]</c>. </p> - </item> - - <tag><c><![CDATA[essl]]></c></tag> - <item> - <p>If using the Erlang based implementation of SSL, - these SSL-specific options are used. </p> - <p>Defaults to <c>[]</c>. </p> + <p>This is the <c>SSL/TLS</c> connectin configuration option.</p> + <p>Defaults to <c>[]</c>. See <seealso marker="ssl:ssl">ssl:connect/[2, 3,4]</seealso> for availble options.</p> </item> <tag><c><![CDATA[autoredirect]]></c></tag> <item> - <p>Should the client automatically retrieve the information - from the new URI and return that as the result instead - of a 30X-result code. </p> - <p>Note that for some 30X-result codes automatic redirect - is not allowed. In these cases the 30X-result will always - be returned. </p> - <p>Defaults to <c>true</c>. </p> + <p>The client automatically retrieves the information + from the new URI and returns that as the result, instead + of a 30X-result code.</p> + <p>For some 30X-result codes, automatic redirect + is not allowed. In these cases the 30X-result is always + returned.</p> + <p>Default is <c>true</c>.</p> </item> <tag><c><![CDATA[proxy_auth]]></c></tag> <item> - <p>A proxy-authorization header using the provided user name and - password will be added to the request. </p> + <p>A proxy-authorization header using the provided username and + password is added to the request.</p> </item> <tag><c><![CDATA[version]]></c></tag> <item> <p>Can be used to make the client act as an <c>HTTP/1.0</c> or <c>HTTP/0.9</c> client. By default this is an <c>HTTP/1.1</c> - client. When using <c>HTTP/1.0</c> persistent connections will - not be used. </p> - <p>Defaults to the string <c>"HTTP/1.1"</c>. </p> + client. When using <c>HTTP/1.0</c> persistent connections are + not used.</p> + <p>Default is the string <c>"HTTP/1.1"</c>.</p> </item> <tag><c><![CDATA[relaxed]]></c></tag> <item> - <p>If set to <c>true</c> workarounds for known server deviations - from the HTTP-standard are enabled. </p> - <p>Defaults to <c>false</c>. </p> + <p>If set to <c>true</c>, workarounds for known server deviations + from the HTTP-standard are enabled.</p> + <p>Default is <c>false</c>.</p> </item> <tag><c><![CDATA[url_encode]]></c></tag> <item> - <p>Will apply Percent-encoding, also known as URL encoding on the + <p>Applies Percent-encoding, also known as URL encoding on the URL.</p> - <p>Defaults to <c>false</c>. </p> + <p>Default is <c>false</c>.</p> </item> </taglist> - <p>Option (<c>option()</c>) details: </p> + <p>Option (<c>option()</c>) details:</p> <taglist> <tag><c><![CDATA[sync]]></c></tag> <item> - <p>Shall the request be synchronous or asynchronous. </p> - <p>Defaults to <c>true</c>. </p> + <p>Option for the request to be synchronous or asynchronous.</p> + <p>Default is <c>true</c>.</p> </item> <tag><c><![CDATA[stream]]></c></tag> <item> <p>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 <c>self</c> the following stream messages - will be sent to that process: <c>{http, {RequestId, + using option <c>self</c>, the following stream messages + are sent to that process: <c>{http, {RequestId, stream_start, Headers}}, {http, {RequestId, stream, - BinBodyPart}}, {http, {RequestId, stream_end, Headers}}</c>. When - streaming to the calling processes using the option - <c>{self, once}</c> the first message will have an additional - element e.i. <c>{http, {RequestId, stream_start, Headers, Pid}}</c>, - this is the process id that should be used as an argument to + BinBodyPart}}, and {http, {RequestId, stream_end, Headers}}</c>.</p> + <p>When streaming to the calling processes using option + <c>{self, once}</c>, the first message has an extra + element, that is, <c>{http, {RequestId, stream_start, Headers, Pid}}</c>. + This is the process id to be used as an argument to <c>http:stream_next/1</c> to trigger the next message to be sent to - the calling process. </p> - <p>Note that it is possible that chunked encoding will add + the calling process.</p> + <p>Notice that chunked encoding can add headers so that there are more headers in the <c>stream_end</c> - message than in the <c>stream_start</c>. - When streaming to a file and the request is asynchronous the - message <c>{http, {RequestId, saved_to_file}}</c> will be sent. </p> - <p>Defaults to <c>none</c>. </p> + message than in <c>stream_start</c>. + When streaming to a file and the request is asynchronous, the + message <c>{http, {RequestId, saved_to_file}}</c> is sent.</p> + <p>Default is <c>none</c>.</p> </item> <tag><c><![CDATA[body_format]]></c></tag> <item> - <p>Defines if the body shall be delivered as a string or as a + <p>Defines if the body is to be delivered as a string or binary. This option is only valid for the synchronous - request. </p> - <p>Defaults to <c>string</c>. </p> + request.</p> + <p>Default is <c>string</c>.</p> </item> <tag><c><![CDATA[full_result]]></c></tag> <item> - <p>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). </p> - <p>Defaults to <c>true</c>. </p> + <p>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).</p> + <p>Default is <c>true</c>.</p> </item> <tag><c><![CDATA[headers_as_is]]></c></tag> <item> - <p>Shall the headers provided by the user be made - lower case or be regarded as case sensitive. </p> - <p>Note that the http standard requires them to be - case insenstive. This feature should only be used if there is + <p>Defines if the headers provided by the user are to be made + lower case or to be regarded as case sensitive.</p> + <p>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. </p> - <p>Defaults to <c>false</c>. </p> + purpose. When this option is used, no headers + are automatically added. All necessary headers must be + provided by the user.</p> + <p>Default is <c>false</c>.</p> </item> <tag><c><![CDATA[socket_opts]]></c></tag> <item> <p>Socket options to be used for this and subsequent - request(s). </p> - <p>Overrides any value set by the - <seealso marker="#set_options">set_options</seealso> - function. </p> - <p>Note that the validity of the options are <em>not</em> - checked in any way. </p> - <p>Note that this may change the socket behaviour - (see <seealso marker="kernel:inet#setopts/2">inet:setopts/2</seealso>) - for an already existing one, and therefore an already connected - request handler. </p> - <p>By default the socket options set by the - <seealso marker="#set_options">set_options/1,2</seealso> - function are used when establishing a connection. </p> + requests.</p> + <p>Overrides any value set by function + <seealso marker="#set_options-1">set_options</seealso>.</p> + <p>The validity of the options is <em>not</em> 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. + </p> + + <p>By default the socket options set by function + <seealso marker="#set_options-1">set_options/[1,2]</seealso> + are used when establishing a connection.</p> </item> <tag><c><![CDATA[receiver]]></c></tag> <item> - <p>Defines how the client will deliver the result of an - asynchroneous request (<c>sync</c> has the value - <c>false</c>). </p> + <p>Defines how the client delivers the result of an + asynchronous request (<c>sync</c> has the value + <c>false</c>).</p> <taglist> <tag><c><![CDATA[pid()]]></c></tag> <item> - <p>Message(s) will be sent to this process in the format: </p> -<pre> -{http, ReplyInfo} -</pre> + <p>Messages are sent to this process in the format + <c>{http, ReplyInfo}</c>.</p> </item> <tag><c><![CDATA[function/1]]></c></tag> <item> - <p>Information will be delivered to the receiver via calls - to the provided fun: </p> -<pre> -Receiver(ReplyInfo) -</pre> + <p>Information is delivered to the receiver through calls + to the provided fun <c>Receiver(ReplyInfo)</c>.</p> </item> <tag><c><![CDATA[{Module, Function, Args}]]></c></tag> <item> - <p>Information will be delivered to the receiver via calls - to the callback function: </p> -<pre> -apply(Module, Function, [ReplyInfo | Args]) -</pre> + <p>Information is delivered to the receiver through calls + to the callback function + <c>apply(Module, Function, [ReplyInfo | Args])</c>.</p> </item> - </taglist> - <p>In all of the above cases, <c>ReplyInfo</c> has the following - structure: </p> + <p>In all of these cases, <c>ReplyInfo</c> has the following + structure:</p> <pre> {RequestId, saved_to_file} @@ -406,11 +501,10 @@ apply(Module, Function, [ReplyInfo | Args]) {RequestId, Result} {RequestId, stream_start, Headers} {RequestId, stream_start, Headers, HandlerPid} -{RequestId, stream, BinBodyPart} -{RequestId, stream_end, Headers} -</pre> +{RequestId, stream, BinBodyPart} +{RequestId, stream_end, Headers}</pre> - <p>Defaults to the <c>pid()</c> of the process calling the request + <p>Default is the <c>pid</c> of the process calling the request function (<c>self()</c>). </p> <marker id="ipv6_host_with_brackets"></marker> @@ -418,276 +512,178 @@ apply(Module, Function, [ReplyInfo | Args]) <tag><c><![CDATA[ipv6_host_with_brackets]]></c></tag> <item> - <p>When parsing the Host-Port part of an URI with a IPv6 address - with brackets, shall we retain those brackets (<c>true</c>) or - strip them (<c>false</c>). </p> - <p>Defaults to <c>false</c>. </p> + <p>Defines when parsing the Host-Port part of an URI with an IPv6 address + with brackets, if those brackets are to be retained (<c>true</c>) + or stripped (<c>false</c>).</p> + <p>Default is <c>false</c>.</p> </item> </taglist> - - <marker id="cancel_request"></marker> - </desc> - </func> - - <func> - <name>cancel_request(RequestId) -> </name> - <name>cancel_request(RequestId, Profile) -> ok</name> - <fsummary>Cancels an asynchronous HTTP-request.</fsummary> - <type> - <v>RequestId = request_id() - A unique identifier as returned - by request/4</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - </type> - <desc> - <p>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. - </p> - - <marker id="set_options"></marker> </desc> </func> + <func> <name>set_options(Options) -> </name> <name>set_options(Options, Profile) -> ok | {error, Reason}</name> <fsummary>Sets options to be used for subsequent requests.</fsummary> <type> <v>Options = [Option]</v> - <v>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} </v> - + <v>Option = {proxy, {Proxy, NoProxy}}</v> + <v>| {https_proxy, {Proxy, NoProxy}}</v> + <v>| {max_sessions, MaxSessions}</v> + <v>| {max_keep_alive_length, MaxKeepAlive}</v> + <v>| {keep_alive_timeout, KeepAliveTimeout}</v> + <v>| {max_pipeline_length, MaxPipeline}</v> + <v>| {pipeline_timeout, PipelineTimeout}</v> + <v>| {cookies, CookieMode}</v> + <v>| {ipfamily, IpFamily}</v> + <v>| {ip, IpAddress}</v> + <v>| {port, Port}</v> + <v>| {socket_opts, socket_opts()}</v> + <v>| {verbose, VerboseMode}</v> <v>Proxy = {Hostname, Port}</v> - <v>Hostname = string() </v> - <d>ex: "localhost" or "foo.bar.se"</d> + <v>Hostname = string()</v> + <d>Example: "localhost" or "foo.bar.se"</d> <v>Port = integer()</v> - <d>ex: 8080 </d> + <d>Example: 8080</d> <v>NoProxy = [NoProxyDesc]</v> <v>NoProxyDesc = DomainDesc | HostName | IPDesc</v> <v>DomainDesc = "*.Domain"</v> - <d>ex: "*.ericsson.se"</d> + <d>Example: "*.ericsson.se"</d> <v>IpDesc = string()</v> - <d>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).</d> - - <d>proxy defaults to {undefined, []} e.i. no proxy is configured and https_proxy defaults to - the value of proxy.</d> - - <v>MaxSessions = integer() </v> - <d>Default is <c>2</c>. - Maximum number of persistent connections to a host.</d> - <v>MaxKeepAlive = integer() </v> - <d>Default is <c>5</c>. - Maximum number of outstanding requests on the same connection to - a host.</d> - <v>KeepAliveTimeout = integer() </v> - <d>Default is <c>120000</c> (= 2 min). - If a persistent connection is idle longer than the + <d>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).</d> + <d><c>proxy</c> defaults to <c>{undefined, []}</c>, + that is, no proxy is configured and + <c>https_proxy</c> defaults to the value of <c>proxy</c>.</d> + <v>MaxSessions = integer()</v> + <d>Maximum number of persistent connections to a host. + Default is <c>2</c>.</d> + <v>MaxKeepAlive = integer()</v> + <d>Maximum number of outstanding requests on the same connection to + a host. Default is <c>5</c>.</d> + <v>KeepAliveTimeout = integer()</v> + <d>If a persistent connection is idle longer than the <c>keep_alive_timeout</c> in milliseconds, - the client will close the connection. - The server may also have such a time out but you should - not count on it!</d> - <v>MaxPipeline = integer() </v> - <d>Default is <c>2</c>. - Maximum number of outstanding requests on a pipelined connection - to a host.</d> - <v>PipelineTimeout = integer() </v> - <d>Default is <c>0</c>, - 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 <c>120000</c> (= 2 min).</d> + <v>MaxPipeline = integer()</v> + <d>Maximum number of outstanding requests on a pipelined connection + to a host. Default is <c>2</c>.</d> + <v>PipelineTimeout = integer()</v> + <d>If a persistent connection is idle longer than the <c>pipeline_timeout</c> in milliseconds, - the client will close the connection. </d> - <v>CookieMode = enabled | disabled | verify </v> - <d>Default is <c>disabled</c>. - If Cookies are enabled all valid cookies will automatically be - saved in the client manager's cookie database. - If the option <c>verify</c> is used the function <c>store_cookies/2</c> - has to be called for the cookies to be saved.</d> - <v>IpFamily = inet | inet6 | inet6fb4 </v> - <d>By default <c>inet</c>. - When it is set to <c>inet6fb4</c> you can use both ipv4 and ipv6. - It first tries <c>inet6</c> and if that does not works falls back to <c>inet</c>. - The option is here to provide a workaround for buggy ipv6 stacks to ensure that - ipv4 will always work.</d> - <v>IpAddress = ip_address() </v> - <d>If the host has several network interfaces, this option specifies which one to use. - See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> for more info. </d> - <v>Port = integer() </v> - <d>Specify which local port number to use. - See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> for more info. </d> + the client closes the connection. Default is <c>0</c>, + which results in pipelining not being used.</d> + <v>CookieMode = enabled | disabled | verify</v> + <d>If cookies are enabled, all valid cookies are automatically + saved in the cookie database of the client manager. + If option <c>verify</c> is used, function <c>store_cookies/2</c> + has to be called for the cookies to be saved. + Default is <c>disabled</c>.</d> + <v>IpFamily = inet | inet6 </v> + <d>Default is <c>inet</c>.</d> + <v>IpAddress = ip_address()</v> + <d>If the host has several network interfaces, this option specifies + which one to use. + See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> + for details.</d> + <v>Port = integer()</v> + <d>Local port number to use. + See <seealso marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seealso> + for details.</d> <v>socket_opts() = [socket_opt()]</v> <d>The options are appended to the socket options used by the - client. </d> + client.</d> <d>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) <em>without</em> - verification! </d> - <v>VerboseMode = false | verbose | debug | trace </v> + to the underlying transport (<c>gen_tcp</c> or <c>SSL</c>) + <em>without</em> verification.</d> + <v>VerboseMode = false | verbose | debug | trace</v> <d>Default is <c>false</c>. 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.</d> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> </type> <desc> <p>Sets options to be used for subsequent requests.</p> <note> - <p>If possible the client will keep its connections - alive and use persistent connections - with or without pipeline depending on configuration + <p>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 <c>max_sessions</c> option. </p> + provide a guideline for how many requests that are + ideal to be sent on a persistent connection. + This depends much on the application.</p> + <p>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 <c>max_sessions</c>.</p> </note> <marker id="get_options"></marker> </desc> </func> - - <func> - <name>get_options(OptionItems) -> {ok, Values} | {error, Reason}</name> - <name>get_options(OptionItems, Profile) -> {ok, Values} | {error, Reason}</name> - <fsummary>Gets the currently used options.</fsummary> - <type> - <v>OptionItems = all | [option_item()]</v> - <v>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</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - <v>Values = [{option_item(), term()}]</v> - <v>Reason = term() </v> - </type> - <desc> - <p>Retrieves the options currently used by the client.</p> - - <marker id="stream_next"></marker> - </desc> - </func> - - <func> - <name>stream_next(Pid) -> ok</name> - <fsummary> Triggers the next message to be streamed, e.i. - same behavior as active once for sockets. - </fsummary> - <type> - <v>Pid = pid() - as received in the stream_start message</v> - </type> - <desc> - <p>Triggers the next message to be streamed, e.i. - same behavior as active once for sockets. </p> - - <marker id="verify_cookies"></marker> - <marker id="store_cookies"></marker> - </desc> - </func> - + <func> <name>store_cookies(SetCookieHeaders, Url) -> </name> <name>store_cookies(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name> - <fsummary>Saves the cookies defined in SetCookieHeaders in the client profile's cookie database.</fsummary> + <fsummary>Saves the cookies defined in <c>SetCookieHeaders</c> in the + client profile cookie database.</fsummary> <type> <v>SetCookieHeaders = headers() - where field = "set-cookie"</v> <v>Url = url()</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - </type> - <desc> - <p>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 <c>cookies</c> - to <c>verify</c>. - If no profile is specified the default profile will be used. </p> - - <marker id="cookie_header"></marker> - </desc> - </func> - - <func> - <name>cookie_header(Url) -> </name> - <name>cookie_header(Url, Profile | Opts) -> header() | {error, Reason}</name> - <name>cookie_header(Url, Opts, Profile) -> header() | {error, Reason}</name> - <fsummary>Returns the cookie header that would be sent when - making a request to Url using the profile <c>Profile</c>.</fsummary> - <type> - <v>Url = url()</v> - <v>Opts = [cookie_header_opt()]</v> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - <v>cookie_header_opt() = {ipv6_host_with_brackets, boolean()}</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> </type> <desc> - <p>Returns the cookie header that would be sent - when making a request to <c>Url</c> using the profile <c>Profile</c>. - If no profile is specified the default profile will be used. </p> - <p>The option <c>ipv6_host_with_bracket</c> deals with how to - parse IPv6 addresses. - See the <c>Options</c> argument of the - <seealso marker="#request2">request/4,5</seealso> for more info. </p> - - <marker id="reset_cookies"></marker> + <p>Saves the cookies defined in <c>SetCookieHeaders</c> + in the client profile cookie database. + Call this function if option <c>cookies</c> is set to <c>verify</c>. + If no profile is specified, the default profile is used.</p> </desc> </func> - <func> - <name>reset_cookies() -> void()</name> - <name>reset_cookies(Profile) -> void()</name> - <fsummary>Reset the cookie database.</fsummary> + <name>stream_next(Pid) -> ok</name> + <fsummary>Triggers the next message to be streamed, that is, + the same behavior as active one for sockets. + </fsummary> <type> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <v>Pid = pid()</v> + <d>As received in the <c>stream_start message</c></d> </type> <desc> - <p>Resets (clears) the cookie database for the specified - <c>Profile</c>. If no profile is specified the default profile - will be used. </p> + <p>Triggers the next message to be streamed, that is, + the same behavior as active ones for sockets.</p> - <marker id="which_cookies"></marker> + <marker id="verify_cookies"></marker> + <marker id="store_cookies"></marker> </desc> </func> - - + <func> <name>which_cookies() -> cookies()</name> <name>which_cookies(Profile) -> cookies()</name> - <fsummary>Dumps out the entire cookie database.</fsummary> + <fsummary>Dumps the entire cookie database.</fsummary> <type> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> <v>cookies() = [cookie_stores()]</v> <v>cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()}</v> <v>cookies() = [cookie()]</v> <v>cookie() = term()</v> </type> <desc> - <p>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. </p> - - <marker id="which_sessions"></marker> + <p>Produces a list of the entire cookie database. + Intended for debugging/testing purposes. + If no profile is specified, the default profile is used.</p> </desc> </func> @@ -696,41 +692,29 @@ apply(Module, Function, [ReplyInfo | Args]) <name>which_sessions(Profile) -> session_info()</name> <fsummary>Produces a slightly processed dump of the sessions database.</fsummary> <type> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <v>Profile = profile() | pid()</v> + <d>When started <c>stand_alone</c> only the pid can be used.</d> <v>session_info() = {GoodSessions, BadSessions, NonSessions}</v> <v>GoodSessions = session()</v> <v>BadSessions = tuple()</v> <v>NonSessions = term()</v> </type> <desc> - <p>This function produces a slightly processed dump of the session + <p>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. </p> - - <marker id="info"></marker> + If no profile is specified, the default profile is used.</p> </desc> </func> - <func> - <name>info() -> list()</name> - <name>info(Profile) -> list()</name> - <fsummary>Produces a list of miscelleneous info</fsummary> - <type> - <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> - </type> - <desc> - <p>This function produces a list of miscelleneous info. - It is intended for debugging. - If no profile is specified the default profile will be used. </p> - </desc> - </func> + </funcs> <section> <title>SEE ALSO</title> - <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>, - <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>, - <seealso marker="ssl:ssl">ssl(3)</seealso> + <p><url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>, + <seealso marker="inets">inets(3)</seealso>, + <seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso>, + <seealso marker="ssl:ssl">ssl(3)</seealso> </p> </section> |