diff options
Diffstat (limited to 'lib/inets/doc/src/httpc.xml')
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 222 |
1 files changed, 153 insertions, 69 deletions
diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index d1671ac9bd..14ce3cbe7f 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2004</year><year>2011</year> + <year>2004</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,8 +28,10 @@ <date></date> <rev></rev> </header> + <module>httpc</module> <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> @@ -167,7 +169,6 @@ filename() = string() <v>http_option() = {timeout, timeout()} | {connect_timeout, timeout()} | {ssl, ssloptions()} | - {ossl, ssloptions()} | {essl, ssloptions()} | {autoredirect, boolean()} | {proxy_auth, {userstring(), passwordstring()}} | @@ -177,13 +178,14 @@ filename() = string() <v>timeout() = integer() >= 0 | infinity</v> <v>Options = options()</v> <v>options() = [option()]</v> - <v>option() = {sync, boolean()} | - {stream, stream_to()} | - {body_format, body_format()} | - {full_result, boolean()} | - {headers_as_is, boolean() | - {socket_opts, socket_opts()} | - {receiver, receiver()}}</v> + <v>option() = {sync, boolean()} | + {stream, stream_to()} | + {body_format, body_format()} | + {full_result, boolean()} | + {headers_as_is, boolean() | + {socket_opts, socket_opts()} | + {receiver, receiver()}, + {ipv6_host_with_brackets, boolean()}}</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> @@ -206,6 +208,7 @@ filename() = string() to the <c>receiver</c> depending on that value. </p> <p>Http option (<c>http_option()</c>) details: </p> + <marker id="request2_http_options"></marker> <taglist> <tag><c><![CDATA[timeout]]></c></tag> <item> @@ -231,16 +234,9 @@ filename() = string() <p>Defaults to <c>[]</c>. </p> </item> - <tag><c><![CDATA[ossl]]></c></tag> - <item> - <p>If using the OpenSSL based (old) implementation of SSL, - these SSL-specific options are used. </p> - <p>Defaults to <c>[]</c>. </p> - </item> - <tag><c><![CDATA[essl]]></c></tag> <item> - <p>If using the Erlang based (new) implementation of SSL, + <p>If using the Erlang based implementation of SSL, these SSL-specific options are used. </p> <p>Defaults to <c>[]</c>. </p> </item> @@ -412,7 +408,18 @@ apply(Module, Function, [ReplyInfo | Args]) <p>Defaults to the <c>pid()</c> of the process calling the request function (<c>self()</c>). </p> + + <marker id="ipv6_host_with_brackets"></marker> + </item> + + <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> </item> + </taglist> <marker id="cancel_request"></marker> @@ -473,66 +480,98 @@ apply(Module, Function, [ReplyInfo | Args]) <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> <v>MaxSessions = integer() </v> <d>Default is <c>2</c>. - Maximum number of persistent connections to a host.</d> + 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 - <c>keep_alive_timeout</c> the client will close the connection. - The server may also have such a time out but you should - not count on it!</d> + <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 + <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 - <c>pipeline_timeout</c> the client will close the connection. </d> + <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 + <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> + 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> + <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> - <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. - It is a debug feature.</d> + <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> + <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. + It is a debug feature.</d> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + </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 + 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> + </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 | + 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>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 - 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> - </note> + <p>Retrieves the options currently used by the client.</p> <marker id="stream_next"></marker> </desc> @@ -577,17 +616,24 @@ apply(Module, Function, [ReplyInfo | Args]) <func> <name>cookie_header(Url) -> </name> - <name>cookie_header(Url, Profile) -> header() | {error, Reason}</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> </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> </desc> @@ -605,6 +651,8 @@ apply(Module, Function, [ReplyInfo | Args]) <p>Resets (clears) the cookie database for the specified <c>Profile</c>. If no profile is specified the default profile will be used. </p> + + <marker id="which_cookies"></marker> </desc> </func> @@ -624,6 +672,42 @@ apply(Module, Function, [ReplyInfo | Args]) <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> + </desc> + </func> + + <func> + <name>which_sessions() -> session_info()</name> + <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>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 + database. It is intended for debugging. + If no profile is specified the default profile will be used. </p> + + <marker id="info"></marker> + </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> |