diff options
Diffstat (limited to 'lib/inets/doc/src/httpc.xml')
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 333 |
1 files changed, 177 insertions, 156 deletions
diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 7430a62b1b..d1671ac9bd 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> @@ -76,38 +76,37 @@ socket_opt() = See the Options used by gen_tcp(3) and <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() -filename() = string() +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> </section> <section> <title>SSL DATA TYPES </title> - <p>Some type definitions relevant when using https, - for details <seealso marker="ssl:ssl">ssl(3)</seealso>: </p> - <code type="none"><![CDATA[ -ssl_options() = {verify, code()} | - {depth, depth()} | - {certfile, path()} | - {keyfile, path()} | - {password, string()} | - {cacertfile, path()} | - {ciphers, string()} - ]]></code> + <p>See <seealso marker="ssl:ssl">ssl(3)</seealso> for information + about ssl options (<c>ssloptions()</c>). </p> </section> <section> @@ -117,7 +116,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 +128,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> @@ -142,13 +141,14 @@ ssl_options() = {verify, code()} | <fsummary>Sends a get HTTP-request</fsummary> <type> <v>Url = url() </v> - <v>Result = {status_line(), headers(), body()} | - {status_code(), body()} | request_id() </v> - <v>Profile = profile()</v> + <v>Result = {status_line(), headers(), Body} | + {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> </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> @@ -166,11 +166,14 @@ ssl_options() = {verify, code()} | <v>http_options() = [http_option()]</v> <v>http_option() = {timeout, timeout()} | {connect_timeout, timeout()} | - {ssl, ssl_options()} | + {ssl, ssloptions()} | + {ossl, ssloptions()} | + {essl, ssloptions()} | {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> @@ -188,26 +191,27 @@ ssl_options() = {verify, code()} | <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> - <v>Profile = profile() </v> + <v>Result = {status_line(), headers(), Body} | + {status_code(), Body} | request_id() </v> + <v>Body = string() | binary()</v> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> <v>Reason = {connect_failed, term()} | {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 - {ok, RequestId} and later on the information will be delivered - to the <c>receiver</c> depending on that value. </p> + 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>Http option (<c>http_option()</c>) details: </p> <taglist> <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 - sent. </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> </item> @@ -215,50 +219,71 @@ ssl_options() = {verify, code()} | <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> + 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> </item> <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>essl</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 - 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>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> </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> + password will be 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 trsing <c>"HTTP/1.1"</c>. </p> + <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> </item> <tag><c><![CDATA[relaxed]]></c></tag> <item> - <p>If set to true workarounds for known server deviations from - the HTTP-standard are enabled. </p> + <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> @@ -272,77 +297,77 @@ ssl_options() = {verify, code()} | <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 the following stream messages - will be sent to that process: {http, {RequestId, - stream_start, Headers}, {http, {RequestId, stream, - BinBodyPart}, {http, {RequestId, stream_end, Headers}. 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}, - 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 - the calling process. </p> + 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, + stream_start, Headers}, {http, {RequestId, stream, + 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. <c>{http, {RequestId, stream_start, Headers, Pid}</c>, + this is the process id that should 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 - 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. </p> + 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> </item> <tag><c><![CDATA[body_format]]></c></tag> <item> <p>Defines if the body shall be delivered as a string or as a - binary. This option is only valid for the synchronous - request. </p> + binary. This option is only valid for the synchronous + request. </p> <p>Defaults to <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> + 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> </item> <tag><c><![CDATA[header_as_is]]></c></tag> <item> <p>Shall the headers provided by the user be made - lower case or be regarded as case sensitive. </p> + 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 - 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 - provided by the user. </p> - <p>Defaults to <c>false</c>. </p> + 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 have to be + provided by the user. </p> + <p>Defaults to <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> + 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> + 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 - request handler. </p> - <p>By defaults the socket options set by the - <seealso marker="#set_options">set_options/1,2</seealso> - function is used when establishing connection. </p> + (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> </item> <tag><c><![CDATA[receiver]]></c></tag> <item> - <p>Defines how the client will deliver the result for a - asynchroneous request (<c>sync</c> has the value - <c>false</c>). </p> + <p>Defines how the client will deliver the result of an + asynchroneous request (<c>sync</c> has the value + <c>false</c>). </p> <taglist> <tag><c><![CDATA[pid()]]></c></tag> @@ -356,7 +381,7 @@ ssl_options() = {verify, code()} | <tag><c><![CDATA[function/1]]></c></tag> <item> <p>Information will be delivered to the receiver via calls - to the provided fun: </p> + to the provided fun: </p> <pre> Receiver(ReplyInfo) </pre> @@ -365,14 +390,14 @@ Receiver(ReplyInfo) <tag><c><![CDATA[{Module, Funcion, Args}]]></c></tag> <item> <p>Information will be delivered to the receiver via calls - to the callback function: </p> + to the callback function: </p> <pre> apply(Module, Function, [ReplyInfo | Args]) </pre> </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> @@ -386,7 +411,7 @@ apply(Module, Function, [ReplyInfo | Args]) </pre> <p>Defaults to the <c>pid()</c> of the process calling the request - function (<c>self()</c>). </p> + function (<c>self()</c>). </p> </item> </taglist> @@ -401,7 +426,7 @@ apply(Module, Function, [ReplyInfo | Args]) <type> <v>RequestId = request_id() - A unique identifier as returned by request/4</v> - <v>Profile = profile()</v> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> </type> <desc> <p>Cancels an asynchronous HTTP-request. </p> @@ -447,67 +472,66 @@ 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> - <v>Profile = profile()</v> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> </type> <desc> - <p>Sets options to be used for subsequent - requests.</p> + <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 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> @@ -524,28 +548,28 @@ apply(Module, Function, [ReplyInfo | Args]) </type> <desc> <p>Triggers the next message to be streamed, e.i. - same behavior as active once for sockets.</p> + 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> <v>Url = url()</v> - <v>Profile = profile()</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 set the option cookies to <c>verify</c>. - If no profile is specified the default profile will be used. - </p> + 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> @@ -553,18 +577,17 @@ 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> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> </type> <desc> <p>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. - </p> + 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> <marker id="reset_cookies"></marker> </desc> @@ -576,12 +599,12 @@ apply(Module, Function, [ReplyInfo | Args]) <name>reset_cookies(Profile) -> void()</name> <fsummary>Reset the cookie database.</fsummary> <type> - <v>Profile = profile()</v> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> </type> <desc> - <p>Resets (clears) the cookie database for the specified Profile. - If no profile is specified the default profile will be used. - </p> + <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> </func> @@ -591,17 +614,16 @@ apply(Module, Function, [ReplyInfo | Args]) <name>which_cookies(Profile) -> cookies()</name> <fsummary>Dumps out the entire cookie database.</fsummary> <type> - <v>Profile = profile()</v> - <v>cookies() = [cooie_stores()]</v> - <v>cookie_stores() = {cookies, icookies()} | {session_cookies, icookies()}</v> - <v>icookies() = [icookie()]</v> + <v>Profile = profile() | pid() (when started <c>stand_alone</c>)</v> + <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> + It is intended for debugging/testing purposes. + If no profile is specified the default profile will be used. </p> </desc> </func> </funcs> @@ -615,4 +637,3 @@ apply(Module, Function, [ReplyInfo | Args]) </section> </erlref> - |