path: root/lib/inets/doc/src/httpc.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2004</year><year>2022</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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>

    <title>httpc</title>
    <prepared>Ingela Anderton Andin</prepared>
    <responsible></responsible>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>

  <module since="OTP R13B04">httpc</module>
  <modulesummary>An HTTP/1.1 client</modulesummary>

  <description>
    <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 <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>

	<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 <url href="http://www.ietf.org/rfc/rfc2817.txt">RFC 2817</url>is not
	supported.</p>

      <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>Some examples are provided in the <seeguide
    marker="http_client">Inets User's Guide</seeguide>.</p>
  </description>

  <section>
    <title>HTTP CLIENT SERVICE START/STOP</title>
    
    <p>An HTTP client can be configured to start when starting the <c>Inets</c>
      application or started dynamically in runtime by calling the
      <c>Inets</c> application API <c>inets:start(httpc, ServiceConfig)</c>
      or <c>inets:start(httpc,  ServiceConfig, How)</c>,
      see <seeerl marker="inets">inets(3)</seeerl>.
      The configuration options are as follows:</p>
    <taglist>
      <tag>{profile, Profile :: atom() | pid()}</tag>
      <item>Name of the profile.
      This option is mandatory.</item>
      <tag>{data_dir, Path :: string()}</tag>
      <item>Directory where the profile
	can save persistent data. If omitted, all cookies are treated
	as session cookies. <c>Path</c> represents a file path or directory path.</item>
    </taglist>

    <p>The client can be stopped using <seemfa marker="inets#stop/2"><c>inets:stop(httpc, Pid)</c></seemfa> or
    <seemfa marker="inets#stop/2"><c>inets:stop(httpc, Profile)</c></seemfa>.</p>

    <warning><p>Please note that <c>httpc</c> normalizes input URIs before internal
    processing and special care shall be taken when the URI has percent ("%")
    characters. A percent serves as the indicator for percent-encoded octets and
    it must be percent-encoded as "%25" for that octet to be used as data within
    the URI.</p>
    <p>For example, in order to send an <c>HTTP GET</c> request with the
    URI <c>http://localhost/foo%25bar</c>, the percent character must be
    percent-encoded when creating the request:
    <c>httpc:request("http://localhost/foo%2525bar").</c> </p></warning>
  </section>

  <funcs>
    <func>
      <name since="OTP R13B04" name="cancel_request" arity="1" />
      <name since="OTP R13B04" name="cancel_request" arity="2" />
      <fsummary>Cancels an asynchronous HTTP request.</fsummary>
      <type variable="RequestId" />
      <type_desc variable="RequestId">
        A unique identifier as returned by
        <seemfa marker="#request/4"><c>request/4</c></seemfa>
      </type_desc>
      <type variable="Profile" />
	    <type_desc variable="Profile">
        When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <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 since="OTP R13B04" name="cookie_header" arity="1"/>
      <name since="OTP R13B04" name="cookie_header" arity="2"/>
      <fsummary>Returns the cookie header that would have been sent when making
      a request to <c><anno>URL</anno></c>, using the profile
      <c><anno>Profile</anno></c>.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <p>Returns the cookie header that would have been sent when making a
        request to <c><anno>Url</anno></c> using profile
        <c><anno>Profile</anno></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 <seemfa
	     marker="#request/4">request/[4,5]</seemfa>.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R15B"   name="cookie_header" arity="3"/>
      <fsummary>Returns the cookie header that would have been sent when making
      a request to <c><anno>URL</anno></c> using the profile
      <c><anno>Profile</anno></c>.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <p>Returns the cookie header that would have been sent when making a
        request to <c><anno>Url</anno></c> using profile
        <c><anno>Profile</anno></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 <seemfa
	     marker="#request/4">request/[4,5]</seemfa>.</p>
      </desc>
    </func>

     <func>
      <name since="OTP R15B01" name="get_options" arity="1"/>
      <name since="OTP R15B01" name="get_options" arity="2"/>
      <fsummary>Gets the currently used options.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <p>Retrieves the options currently used by the client.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R15B02" name="info" arity="0"/>
      <name since="OTP R15B02" name="info" arity="1"/>
      <fsummary>Produces a list of miscellaneous information.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <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 since="OTP R13B04" name="reset_cookies" arity="0"/>
      <name since="OTP R13B04" name="reset_cookies" arity="1"/>
      <fsummary>Resets the cookie database.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <p>Resets (clears) the cookie database for the specified
        <c><anno>Profile</anno></c>. If no profile is specified the default
        profile is used.</p>
      </desc>
    </func>
    
    <func>
      <name since="OTP R13B04" name="request" arity="1"/>
      <name since="OTP R13B04" name="request" arity="2"/>
      <fsummary>Sends a get HTTP request.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <p>Equivalent to <seemfa marker="httpc#request/4"><c>httpc:request(get, {Url, []}, [], [])</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name since="OTP R13B04" name="request" arity="4"/>
      <name since="OTP R13B04" name="request" arity="5"/>
      <fsummary>Sends an HTTP request.</fsummary>
      <type_desc variable="Profile">
        When <c><anno>Profile</anno></c> is <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <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>When  <c><anno>Profile</anno></c> is <c>stand_alone</c> only the pid can be used.</p>
        <p>HTTP options:</p>

        <taglist>
          <tag><c>timeout</c></tag>
          <item>
            <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>connect_timeout</c></tag>
          <item>
            <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>ssl</c></tag>
          <item>
            <p>This is the <c>SSL/TLS</c> connecting configuration option.</p>
            <p>Defaults to <c>[]</c>. See <seeerl marker="ssl:ssl">ssl:connect/[2,3,4]</seeerl>  for available options.</p>
	        </item>

          <tag><c>autoredirect</c></tag>
          <item>
	          <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>proxy_auth</c></tag>
          <item>
            <p>A proxy-authorization header using a tuple where the first element is the <c>username</c> and
	          the second element of the tuple is the <c>password</c> added to the request.</p>
	        </item>

          <tag><c>version</c></tag>
          <item>
            <p>Can be used to make the client act as an <c>HTTP/1.0</c>
            client. By default this is an <c>HTTP/1.1</c>
            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>relaxed</c></tag>
          <item>
            <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>
        </taglist>

        <p>Options details:</p>
        <taglist>
          <tag><c>sync</c></tag>
          <item>
            <p>Option for the request to be synchronous or asynchronous.</p>
            <p>Default is <c>true</c>.</p>
	        </item>

          <tag><c>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 option
            <c>self</c>, the following stream messages are sent to that process:
            <c>{http, {RequestId, stream_start, Headers}}, {http, {RequestId,
            stream, 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>httpc:stream_next/1</c>
	          to trigger the next message to be sent to 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
	          <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>body_format</c></tag>
          <item>
            <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>Default is <c>string</c>.</p>
	        </item>

          <tag><c>full_result</c></tag>
          <item>
            <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>headers_as_is</c></tag>
          <item>
            <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. 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>socket_opts</c></tag>
          <item>
            <p>Socket options to be used for this request.</p>
            <p>See the options used by
            <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl> and
            <seeerl marker="ssl:ssl">ssl(3)</seeerl>
            </p>
	          <p>Overrides any value set by function
	          <seemfa marker="#set_options/1">set_options</seemfa>.</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.
	          </p>
	          <note>
	            <p>
		            Persistent connections are not supported when setting the
		            <c>socket_opts</c> option. When <c>socket_opts</c> is not set
		            the current implementation assumes the requests to the same
		            host, port combination will use the same socket options.
	            </p>
	          </note>

            <p>By default the socket options set by function <seemfa
            marker="#set_options/1">set_options/[1,2]</seemfa> are used when
            establishing a connection.</p>
	        </item>

          <tag><c>receiver</c></tag>
          <item>
            <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>pid()</c></tag>
              <item>
	              <p>Messages are sent to this process in the format <c>{http,
	              ReplyInfo}</c>.</p>
	            </item>

              <tag><c>function/1</c></tag>
              <item>
	              <p>Information is delivered to the receiver through calls to the
	              provided fun <c>Receiver(ReplyInfo)</c>.</p>
  	          </item>

              <tag><c>{Module, Function, Args}</c></tag>
              <item>
	              <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 these cases, <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>Default is 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>ipv6_host_with_brackets</c></tag>
          <item>
            <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>
      </desc>
    </func>

  
    <func>
      <name since="OTP R13B04" name="set_options" arity="1"/>
      <name since="OTP R13B04" name="set_options" arity="2"/>
      <fsummary>Sets options to be used for subsequent requests.</fsummary>
      <desc>
	      <p>Sets options to be used for subsequent requests.</p>
        <taglist>
        <tag><c>HostName</c></tag>
        <item>
          Example: "localhost" or "foo.bar.se"
        </item>
        <tag><c>DomainDesc</c></tag>
        <item>
          Example <c>"*.Domain"</c> or <c>"*.ericsson.se"</c>
        </item>
        <tag><c>IpAddressDesc</c></tag>
        <item>
        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). <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>.
        </item>
        <tag><c>MaxSessions</c></tag>
        <item>
          <c><anno>MaxSessions</anno></c> Maximum number of persistent connections to a host. Default is <c>2</c>.
        </item>

      <tag><c>MaxKeepAlive</c></tag>
      <item>
        <c><anno>MaxKeepAlive</anno></c> Maximum number of outstanding requests
        on the same connection to a host. Default is <c>5</c>.
      </item>
      <tag><c>KeepAliveTimeout</c></tag>
      <item>
       <c><anno>KeepAliveTimeout</anno></c> If a persistent connection is idle longer than the
       <c>keep_alive_timeout</c> in milliseconds, 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).
      </item>
      <tag><c>MaxPipeline</c></tag>
      <item>
       <c><anno>MaxPipeline</anno></c> Maximum number of outstanding requests on a pipelined connection to a
       host. Default is <c>2</c>.
      </item>
      <tag><c>PipelineTimeout</c></tag>
      <item>
       <c><anno>PipelineTimeout</anno></c> If a persistent connection is idle longer than the
       <c>pipeline_timeout</c> in milliseconds, the client closes the
       connection. Default is <c>0</c>, which results in pipelining not being
       used.
      </item>
      <tag><c>CookieMode</c></tag>
      <item>
        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>.
      </item>
      <tag><c>IpFamily</c></tag>
      <item>
       Default is <c>inet</c>. With <c>inet6fb4</c> option, IPv6
        will be preferred but if connection fails, an IPv4 fallback connection
        attempt will be made.
      </item>
      <tag><c>IpAddress</c></tag>
      <item>
        If the host has several network interfaces, this option specifies
        which one to use. See
        <seeerl marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> for
        details.
      </item>
      <tag><c>Port</c></tag>
      <item>
        Example: <c>8080</c>.
        Local port number to use. See <seeerl
        marker="kernel:gen_tcp#connect">gen_tcp:connect/3,4</seeerl> for
        details.
      </item>
      <tag><c>SocketOpts</c></tag>
      <item>
        The options are appended to the socket options used by the client.
        These are the default values when a new request handler is started (for
        the initial connect). They are passed directly to the underlying
        transport (<c>gen_tcp</c> or <c>SSL</c>) without
        verification.
        <p>See the options used by
        <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl> and
        <seeerl marker="ssl:ssl">ssl(3)</seeerl>
        </p>
      </item>
      <tag><c>VerboseMode</c></tag>
      <item>
        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.
      </item>
      <tag><c>Profile</c></tag>
      <item>
        When started <c>stand_alone</c> only the pid can be used.
      </item>
      <tag><c>UnixSocket</c></tag>
      <item>
        Experimental option for sending HTTP requests over a unix domain
        socket. The value of <c>unix_socket</c> shall be the full path to a unix
        domain socket file with read/write permissions for the erlang process.
        Default is <c>undefined</c>.
      </item>

        </taglist>

	      <note>
	        <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 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>
	       <p>The current implementation assumes the requests to the same host,
	       port combination will use the same socket options.
	       </p>
	      </note>
        <marker id="get_options"></marker>
      </desc>
    </func>

    <func>
      <name since="OTP 25.1" name="ssl_verify_host_options" arity="1"/>
      <fsummary>Returns ssl options for host verification.</fsummary>
      <desc>
        <p>Returns ssl options which can be used to verify the host, uses
        <seemfa marker="public_key:public_key#cacerts_get/0"><c>public_key:cacerts_get()</c></seemfa>
        to read CA certicates and if <c><anno>WildcardHostName</anno></c> is true adds the hostname check from
        <seemfa marker="public_key:public_key#pkix_verify_hostname_match_fun/1">
          <c> public_key:public_key:pkix_verify_hostname_match_fun(https)</c></seemfa> to the options.
        </p>
      </desc>
    </func>

    <func>
      <name since="OTP R14B02" name="store_cookies" arity="2"/>
      <name since="OTP R14B02" name="store_cookies" arity="3"/>
      <fsummary>Saves the cookies defined in <c>SetCookieHeaders</c> in the 
      client profile cookie database.</fsummary>
      <type_desc variable="SetCookieHeaders">
        Where field = "set-cookie"
      </type_desc>
      <type_desc variable="Profile">
        When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <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 since="OTP R13B04" name="stream_next" arity="1"/>
      <fsummary>Triggers the next message to be streamed, that is,
	the same behavior as active one for sockets.
      </fsummary>
      <type_desc variable="Pid">
        As received in the <c>stream_start message</c>
      </type_desc>
      <desc>
        <p>Triggers the next message to be streamed, that is, the same behavior
        as active ones for sockets.</p>
        <marker id="verify_cookies"></marker>
        <marker id="store_cookies"></marker>
      </desc>
    </func>
    
    <func>
      <name since="OTP R13B04" name="which_cookies" arity="0"/>
      <name since="OTP R13B04" name="which_cookies" arity="1"/>
      <fsummary>Dumps the entire cookie database.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <desc>
        <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>

    <func>
      <name since="OTP R15B02" name="which_sessions" arity="0"/>
      <name since="OTP R15B02" name="which_sessions" arity="1"/>
      <fsummary>Produces a slightly processed dump of the sessions database.</fsummary>
      <type_desc variable="Profile">
		    When started <c>stand_alone</c> only the pid can be used.
      </type_desc>
      <type_desc variable="Session">
		    Internal representation of a session.
      </type_desc>
      <desc>
        <p> This function is intended for debugging only. It produces
        a slightly processed dump of the session database. The first
        list of the session information tuple will contain session
        information on an internal format. The last two lists of the
        session information tuple should always be empty if the code
        is working as intended. If no profile is specified, the default
        profile is used.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>SEE ALSO</title>
    <p><url href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</url>, 
    <seeerl marker="inets">inets(3)</seeerl>,
    <seeerl marker="kernel:gen_tcp">gen_tcp(3)</seeerl>, 
    <seeerl marker="ssl:ssl">ssl(3)</seeerl>
    </p>
  </section>
  
</erlref>