OTP-8016, OTP-8056, OTP-8103, OTP-8106, OTP-8312, OTP-8315, OTP-8327, OTP-8349,

OTP-8351, OTP-8359 & OTP-8371.

1 files changed, 581 insertions, 0 deletions

diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml
new file mode 100644
index 0000000000..680473cc38
--- /dev/null
+++ b/lib/inets/doc/src/httpc.xml
@@ -0,0 +1,581 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2004</year><year>2010</year>
+      <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.
+
+    </legalnotice>
+
+    <title>http</title>
+    <prepared>Ingela Anderton Andin</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <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>
+    <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
+	default profile. A profile keeps track of proxy options,
+	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.</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
+      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>
+  </description>
+  
+  <section>
+    <title>COMMON DATA TYPES </title>
+    <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)
+    ]]></code>
+
+  </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() 
+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>
+  </section>
+
+  <section>
+    <title>HTTP CLIENT SERVICE START/STOP </title>
+    
+    <p>A HTTP client can be configured to start when starting the inets
+      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>
+    <taglist>
+      <tag>{profile, profile()}</tag>
+      <item>Name of the profile, see
+	common data types below, this option is mandatory.</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>
+    </taglist>
+
+    <p>The client can be stopped using inets:stop(httpc, Pid) or
+    inets:stop(httpc, Profile).</p>
+    
+    <marker id="request1"></marker>
+  </section>
+  
+  <funcs>
+    <func>
+      <name>request(Url) -> </name>
+      <name>request(Url, Profile) -> {ok, Result} | {error, Reason}</name>
+      <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>Reason = term() </v>
+      </type>
+      <desc>
+        <p>Equivalent to httpc:request(get, {Url, []}, [], []).</p>
+
+        <marker id="request2"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <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>
+      <type>
+        <v>Method = method() </v>
+        <v>Request = request()</v>
+        <v>HTTPOptions = http_options()</v>
+        <v>http_options() = [http_option()]</v>
+        <v>http_option() = {timeout, timeout()} | 
+                           {connect_timeout, timeout()} | 
+                           {ssl, ssl_options()} | 
+                           {autoredirect, boolean()} | 
+                           {proxy_auth, {userstring(), passwordstring()}} | 
+                           {version, http_version()} | 
+                           {relaxed, boolean()}</v>
+        <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() |
+                      {receiver,      receiver()}}</v>
+        <v>stream_to() = none | self | {self, once} | filename() </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>
+        <v>Profile = profile() </v>
+        <v>Reason = 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>
+
+        <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>Time is in milliseconds. </p>
+            <p>Defaults to <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>
+	  </item>
+
+          <tag><c><![CDATA[ssl]]></c></tag>
+          <item>
+            <p>If using 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>
+	  </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>
+	  </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>
+	  </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>Defaults to <c>false</c>. </p>
+	  </item>
+
+        </taglist>
+
+        <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>
+	  </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 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>
+	    <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>
+            <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>
+            <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>
+            <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>
+            <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>
+	  </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>
+
+            <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>
+	      </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>
+  	      </item>
+
+              <tag><c><![CDATA[{Module, Funcion, 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>
+	      </item>
+
+            </taglist>
+            <p>In all cases above, <c>ReplyInfo</c> has the following 
+              structure: </p>
+
+<pre>
+{RequestId, saved_to_file}
+{RequestId, {error, Reason}}
+{RequestId, Result}
+{RequestId, stream_start, Headers}
+{RequestId, stream_start, Headers, HandlerPid}
+{RequestId, stream,       BinBodyPart}
+{RequestId, stream_end,   Headers}
+</pre>
+
+            <p>Defaults to the <c>pid()</c> of the process calling the request 
+              function (<c>self()</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()</v>
+      </type>
+      <desc>
+        <p>Cancels an asynchronous HTTP-request. </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}} | {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} | 
+          {verbose, VerboseMode} </v>
+        <v>Proxy = {Hostname, Port}</v>
+        <v>Hostname = string() </v>
+        <d>ex: "localhost" or "foo.bar.se"</d>
+        <v>Port = integer()</v>
+        <d>ex: 8080 </d>
+        <v>NoProxy = [NoProxyDesc]</v>
+        <v>NoProxyDesc = DomainDesc | HostName | IPDesc</v>
+        <v>DomainDesc = "*.Domain"</v>
+        <d>ex: "*.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>
+        <v>MaxSessions = integer() </v>
+        <d>Default is <em>2</em>. 
+          Maximum number of persistent connections to a host.</d>
+	<v>MaxKeepAlive = integer() </v>
+        <d>Default is <em>5</em>. 
+          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). 
+          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 
+          not count on it!</d>
+	<v>MaxPipeline = integer() </v>
+        <d>Default is <em>2</em>. 
+          Maximum number of outstanding requests on a pipelined connection to a host.</d>
+        <v>PipelineTimeout = integer() </v>
+        <d>Default is <em>0</em>, 
+          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>
+        <v>CookieMode = enabled | disabled | verify </v>
+        <d>Default is <em>disabled</em>. 
+          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>
+        <v>IpFamily = inet | inet6 | inet6fb4 </v>
+        <d>By default <em>inet</em>. 
+          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>
+	<v>Port = integer() </v>
+        <d>Specify which local port number to use. 
+          See gen_tcp:connect/3,4 for more info. </d>
+        <v>VerboseMode = false | verbose | debug | trace </v>
+        <d>Default is <em>false</em>. 
+          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>
+      </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 that 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
+            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>
+        </note>
+
+        <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_cookie"></marker>
+        <marker id="store_cookie"></marker>
+      </desc>
+    </func>
+    
+    <func>
+      <name>store_cookie(SetCookieHeaders, Url) -> </name>
+      <name>store_cookie(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>
+      </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>
+
+        <marker id="cookie_header"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>cookie_header(Url) -> </name>
+      <name>cookie_header(Url, Profile) -> header() | {error, Rason}</name>
+      <fsummary>Returns the cookie header that would be sent when
+      making a request to Url using the profile Profile.</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.
+	  If no profile is specified the default profile will be used.
+	</p>
+
+        <marker id="reset_cookies"></marker>
+      </desc>
+    </func>
+
+
+    <func>
+      <name>reset_cookies() -> void()</name>
+      <name>reset_cookies(Profile) -> void()</name>
+      <fsummary>Reset the cookie database.</fsummary>
+      <type>
+	<v>Profile = profile()</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>
+      </desc>
+    </func>
+
+
+    <func>
+      <name>which_cookies() -> cookies()</name>
+      <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>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>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>RFC 2616, <seealso marker="inets">inets(3)</seealso>,
+      <seealso marker="ssl:ssl">ssl(3)</seealso>
+    </p>
+  </section>
+  
+</erlref>
+