diff options
Diffstat (limited to 'lib/inets/doc/src/httpc.xml')
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 140 |
1 files changed, 81 insertions, 59 deletions
diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 7430a62b1b..8f68087871 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>2004</year><year>2010</year> + <year>2004</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -36,7 +36,7 @@ <note> <p>When starting the Inets application a manager process for the default profile will be started. The functions in this API - that does not explicitly use a profile will accesses the + that do not explicitly use a profile will access the default profile. A profile keeps track of proxy options, cookies and other options that can be applied to more than one request. </p> @@ -117,7 +117,7 @@ ssl_options() = {verify, code()} | 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 + see <seealso marker="inets">inets(3)</seealso>. Below follows a description of the available configuration options.</p> <taglist> <tag>{profile, profile()}</tag> @@ -129,8 +129,8 @@ ssl_options() = {verify, code()} | as session cookies.</item> </taglist> - <p>The client can be stopped using inets:stop(httpc, Pid) or - inets:stop(httpc, Profile).</p> + <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> @@ -148,7 +148,7 @@ ssl_options() = {verify, code()} | <v>Reason = term() </v> </type> <desc> - <p>Equivalent to httpc:request(get, {Url, []}, [], []).</p> + <p>Equivalent to <c>httpc:request(get, {Url, []}, [], [])</c>.</p> <marker id="request2"></marker> </desc> @@ -167,10 +167,13 @@ ssl_options() = {verify, code()} | <v>http_option() = {timeout, timeout()} | {connect_timeout, timeout()} | {ssl, ssl_options()} | + {ossl, ssl_options()} | + {essl, ssl_options()} | {autoredirect, boolean()} | {proxy_auth, {userstring(), passwordstring()}} | {version, http_version()} | - {relaxed, boolean()}</v> + {relaxed, boolean()} | + {url_encode, boolean()}</v> <v>timeout() = integer() >= 0 | infinity</v> <v>Options = options()</v> <v>options() = [option()]</v> @@ -198,7 +201,7 @@ ssl_options() = {verify, code()} | <desc> <p>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 + <c>{ok, RequestId}</c> and later on the information will be delivered to the <c>receiver</c> depending on that value. </p> <p>Http option (<c>http_option()</c>) details: </p> @@ -206,7 +209,7 @@ ssl_options() = {verify, code()} | <tag><c><![CDATA[timeout]]></c></tag> <item> <p>Timeout time for the request. </p> - <p>The clock start ticking as soon as the request has been + <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> @@ -222,17 +225,32 @@ ssl_options() = {verify, code()} | <tag><c><![CDATA[ssl]]></c></tag> <item> - <p>If using SSL, these SSL-specific options are used. </p> + <p>This is the default ssl config option, currently defaults to + <c>ossl</c>, see below. </p> + <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, + these SSL-specific options are used. </p> <p>Defaults to <c>[]</c>. </p> </item> <tag><c><![CDATA[autoredirect]]></c></tag> <item> - <p>Should the client automatically retreive the information + <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 + is not allowed. In these cases the 30X-result will always be returned. </p> <p>Defaults to <c>true</c>. </p> </item> @@ -249,16 +267,21 @@ ssl_options() = {verify, code()} | <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 trsing <c>"HTTP/1.1"</c>. </p> + <p>Defaults to the string <c>"HTTP/1.1"</c>. </p> </item> <tag><c><![CDATA[relaxed]]></c></tag> <item> - <p>If set to true workarounds for known server deviations from + <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> </item> + <tag><c><![CDATA[url_encode]]></c></tag> + <item> + <p>Will apply Percent-encoding, also known as URL encoding on the URL.</p> + <p>Defaults to <c>false</c>. </p> + </item> </taglist> <p>Option (<c>option()</c>) details: </p> @@ -273,21 +296,21 @@ ssl_options() = {verify, code()} | <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 the following stream messages - will be sent to that process: {http, {RequestId, + using the option <c>self</c> the following stream messages + will be sent to that process: <c>{http, {RequestId, stream_start, Headers}, {http, {RequestId, stream, - BinBodyPart}, {http, {RequestId, stream_end, Headers}. When + BinBodyPart}, {http, {RequestId, stream_end, Headers}</c>. When streaming to to the calling processes using the option <c>{self, once}</c> the first message will have an additional - element e.i. {http, {RequestId, stream_start, Headers, Pid}, + element e.i. <c>{http, {RequestId, stream_start, Headers, Pid}</c>, this is the process id that should be used as an argument to - http:stream_next/1 to trigger the next message to be sent 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 - headers so that there are more headers in the stream_end - message than in the stream_start. + 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 {http, {RequestId, saved_to_file}} will be sent. </p> + message <c>{http, {RequestId, saved_to_file}}</c> will be sent. </p> <p>Defaults to <c>none</c>. </p> </item> @@ -315,7 +338,7 @@ ssl_options() = {verify, code()} | case insenstive. This feature should only be used 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 has to be + will be automatically added, all necessary headers have to be provided by the user. </p> <p>Defaults to <c>false</c>. </p> </item> @@ -325,22 +348,22 @@ ssl_options() = {verify, code()} | <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> + <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">inet:setopts/2</seealso>) - for an already existing, and therefor already connected + (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 defaults the socket options set by the + <p>By default the socket options set by the <seealso marker="#set_options">set_options/1,2</seealso> - function is used when establishing connection. </p> + function are used when establishing a connection. </p> </item> <tag><c><![CDATA[receiver]]></c></tag> <item> - <p>Defines how the client will deliver the result for a + <p>Defines how the client will deliver the result of an asynchroneous request (<c>sync</c> has the value <c>false</c>). </p> @@ -372,7 +395,7 @@ apply(Module, Function, [ReplyInfo | Args]) </item> </taglist> - <p>In all cases above, <c>ReplyInfo</c> has the following + <p>In all of the above cases, <c>ReplyInfo</c> has the following structure: </p> <pre> @@ -447,46 +470,46 @@ apply(Module, Function, [ReplyInfo | Args]) <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> <v>MaxSessions = integer() </v> - <d>Default is <em>2</em>. + <d>Default is <c>2</c>. Maximum number of persistent connections to a host.</d> <v>MaxKeepAlive = integer() </v> - <d>Default is <em>5</em>. + <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 <em>120000</em> (= 2 min). + <d>Default is <c>120000</c> (= 2 min). If a persistent connection is idle longer than the - keep_alive_timeout the client will close the connection. - The server may also have a such a time out but you should + <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> <v>MaxPipeline = integer() </v> - <d>Default is <em>2</em>. + <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 <em>0</em>, + <d>Default is <c>0</c>, which will result in pipelining not being used. If a persistent connection is idle longer than the - pipeline_timeout the client will close the connection. </d> + <c>pipeline_timeout</c> the client will close the connection. </d> <v>CookieMode = enabled | disabled | verify </v> - <d>Default is <em>disabled</em>. + <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 verify is used the function http:verify_cookie/2 - has to be called for the cookie to be saved.</d> + 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 <em>inet</em>. + <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 gen_tcp:connect/3,4 for more info. </d> + 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 gen_tcp:connect/3,4 for more info. </d> + 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 <em>false</em>. + <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> @@ -500,14 +523,14 @@ apply(Module, Function, [ReplyInfo | Args]) 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 that would be + 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 delays as earlier request may take a long time + 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. </p> + default value of the <c>max_sessions</c> option. </p> </note> <marker id="stream_next"></marker> @@ -526,14 +549,14 @@ apply(Module, Function, [ReplyInfo | Args]) <p>Triggers the next message to be streamed, e.i. same behavior as active once for sockets.</p> - <marker id="verify_cookie"></marker> - <marker id="store_cookie"></marker> + <marker id="verify_cookies"></marker> + <marker id="store_cookies"></marker> </desc> </func> <func> - <name>store_cookie(SetCookieHeaders, Url) -> </name> - <name>store_cookie(SetCookieHeaders, Url, Profile) -> ok | {error, Reason}</name> + <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> <type> <v>SetCookieHeaders = headers() - where field = "set-cookie"</v> @@ -543,7 +566,7 @@ apply(Module, Function, [ReplyInfo | Args]) <desc> <p>Saves the cookies defined in SetCookieHeaders in the client profile's cookie database. You need to - call this function if you set the option cookies to <c>verify</c>. + 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> @@ -553,16 +576,16 @@ apply(Module, Function, [ReplyInfo | Args]) <func> <name>cookie_header(Url) -> </name> - <name>cookie_header(Url, Profile) -> header() | {error, Rason}</name> + <name>cookie_header(Url, Profile) -> header() | {error, Reason}</name> <fsummary>Returns the cookie header that would be sent when - making a request to Url using the profile Profile.</fsummary> + making a request to Url using the profile <c>Profile</c>.</fsummary> <type> <v>Url = url()</v> <v>Profile = profile()</v> </type> <desc> <p>Returns the cookie header that would be sent - when making a request to Url using the profile Profile. + 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> @@ -579,7 +602,7 @@ apply(Module, Function, [ReplyInfo | Args]) <v>Profile = profile()</v> </type> <desc> - <p>Resets (clears) the cookie database for the specified Profile. + <p>Resets (clears) the cookie database for the specified <c>Profile</c>. If no profile is specified the default profile will be used. </p> </desc> @@ -615,4 +638,3 @@ apply(Module, Function, [ReplyInfo | Args]) </section> </erlref> - |