<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.3 Maintainer: matty Status: working -->
 <reference id="ref.curl">
  <title>CURL, Client URL Library Functions</title>
  <titleabbrev>CURL</titleabbrev>

  <partintro id="curl.partintro">
   <para>
    PHP   libcurl,     Daniel Stenberg, 
           .
    libcurl    http, https, ftp, gopher, telnet, dict, 
	file,  ldap.
	libcurl ,     HTTPS certificates, HTTP
    POST, HTTP PUT, FTP uploading (    PHP's
    ftp extension), HTTP form based upload, proxies, cookies, and
    user+password authentication.
   </para>
   <para>
        CURL functions     <ulink
    url="&url.curl;">CURL</ulink>. PHP     CURL 7.0.2-beta 
	. PHP       CURL   7.0.2-beta.
   </para>
   <para>
       PHP's CURL support    PHP <option
    role="configure">--with-curl[=DIR]</option>  DIR  
          lib   include.
     "include"     "curl" 
	    easy.h  curl.h.
      "libcurl.a"     "lib".
   </para>
   <para>
        PHP 4.0.2. 
   </para>
   <para>
      PHP   CURL support,  
      curl.      CURL
      CURL session  <function>curl_init</function>,   
	       <function>curl_exec</function>
    ,    session     <function>curl_close</function>.
	     CURL     
	  PHP  :
    <example>
	 <title>  PHP's CURL module        PHP</title>
     <programlisting role="php">
<![CDATA[
<?php

$ch = curl_init ("http://www.php.net/");
$fp = fopen ("php_homepage.txt", "w");

curl_setopt ($ch, CURLOPT_FILE, $fp);
curl_setopt ($ch, CURLOPT_HEADER, 0);

curl_exec ($ch);
curl_close ($ch);
fclose ($fp);
?>
]]>
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.curl-init">
   <refnamediv>
    <refname>curl_init</refname>
    <refpurpose>  CURL session</refpurpose>
   </refnamediv>
   <refsect1>
    <title></title>
     <methodsynopsis>
      <type>int</type><methodname>curl_init</methodname>
      <methodparam choice="opt"><type>string</type><parameter>
        url
       </parameter></methodparam>
     </methodsynopsis>
    <para>
      <function>curl_init</function>  session
        CURL   <function>curl_setopt</function>,
	 <function>curl_exec</function>, <function>curl_close</function>
	 functions.
	    <parameter>url</parameter>   
      CURLOPT_URL      .
                
     <function>curl_setopt</function>.
     <example>
      <title>
         CURL session   
      </title>
      <programlisting role="php">
<![CDATA[
<?php
$ch = curl_init();

curl_setopt ($ch, CURLOPT_URL, "http://www.zend.com/");
curl_setopt ($ch, CURLOPT_HEADER, 0);

curl_exec ($ch);

curl_close ($ch);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
      : <function>curl_close</function>,
     <function>curl_setopt</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.curl-setopt">
   <refnamediv>
    <refname>curl_setopt</refname>
    <refpurpose>     CURL</refpurpose>
   </refnamediv>
   <refsect1>
    <title></title>
     <methodsynopsis>
      <type>bool</type><methodname>curl_setopt</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
      <methodparam><type>string</type><parameter>option</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
    <para>
      <function>curl_setopt</function>    
      CURL session     <parameter>ch</parameter>.
	 <parameter>option</parameter>     ,
	  <parameter>value</parameter>      
	  <parameter>option</parameter>.
    </para>
    <para>
      <parameter>value</parameter>    long 
	   (  <parameter>option</parameter>):
     <itemizedlist>
      <listitem>
       <simpara>
        <parameter>CURLOPT_INFILESIZE</parameter>:   
         ,         PHP 
		      .
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_VERBOSE</parameter>:     
             CURL     .
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_HEADER</parameter>:     
             header   .
       </simpara>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_NOPROGRESS</parameter>:     
              PHP  progress meter  CURL transfers
        <note>
         <simpara>
		  PHP        ,
               debugging .
         </simpara>
        </note>
       </para>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_NOBODY</parameter>:     
             body   .
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FAILONERROR</parameter>:     
            PHP   ,  ,  
		     HTTP  300.
		            .
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_UPLOAD</parameter>:     
            PHP   .
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_POST</parameter>:     
            PHP  HTTP POST .
        POST     application/x-www-form-urlencoded,
            HTML forms.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FTPLISTONLY</parameter>:     
            PHP       FTP.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FTPAPPEND</parameter>: Set this option to a
        non-zero value and PHP will append to the remote file instead
        of overwriting it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_NETRC</parameter>: Set this option to a
        non-zero value and PHP will scan your ~./netrc file to find
        your username and password for the remote site that you're
        establishing a connection with.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FOLLOWLOCATION</parameter>: Set this option
        to a non-zero value to follow any "Location: " header that the
        server sends as a part of the HTTP header (note this is
        recursive, PHP will follow as many "Location: " headers that
        it is sent.)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_PUT</parameter>: Set this option a non-zero
        value to HTTP PUT a file.  The file to PUT must be set with
        the CURLOPT_INFILE and CURLOPT_INFILESIZE.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_MUTE</parameter>: Set this option to a
        non-zero value and PHP will be completely silent with regards
        to the CURL functions.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_TIMEOUT</parameter>: Pass a long as a
        parameter that contains the maximum time, in seconds, that
        you'll allow the curl functions to take.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_LOW_SPEED_LIMIT</parameter>: Pass a long as
        a parameter that contains the transfer speed in bytes per
        second that the transfer should be below during
        CURLOPT_LOW_SPEED_TIME seconds for PHP to consider it too slow
        and abort.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_LOW_SPEED_TIME</parameter>: Pass a long as
        a parameter that contains the time in seconds that the
        transfer should be below the CURLOPT_LOW_SPEED_LIMIT for PHP
        to consider it too slow and abort.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_RESUME_FROM</parameter>: Pass a long as a
        parameter that contains the offset, in bytes, that you want
        the transfer to start from.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_SSLVERSION</parameter>: Pass a long as a
        parameter that contains the SSL version (2 or 3) to use.  By
        default PHP will try and determine this by itself, although,
        in some cases you must set this manually.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_SSL_VERIFYHOST</parameter>: Pass a long if
        cURL should verify the Common name of the peer certificate in the 
        SSL handshake.  A value of 1 denotes that we should check for the 
        existence of the common name, a value of 2 denotes that we should 
        make sure it matches the provided hostname.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_TIMECONDITION</parameter>: Pass a long as a
        parameter that defines how the CURLOPT_TIMEVALUE is treated.
        You can set this parameter to TIMECOND_IFMODSINCE or
        TIMECOND_ISUNMODSINCE.  This is a HTTP-only feature.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_TIMEVALUE</parameter>: Pass a long as a
        parameter that is the time in seconds since January 1st, 1970.
        The time will be used as specified by the CURLOPT_TIMEVALUE
        option, or by default the TIMECOND_IFMODSINCE will be used.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_RETURNTRANSFER</parameter>: Pass a non-zero 
        value if you want cURL to directly return the transfer instead 
        of printing it out directly.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The <parameter>value</parameter> parameter should be a string for
     the following values of the <parameter>option</parameter>
     parameter:
     <itemizedlist>
      <listitem>
       <simpara>
        <parameter>CURLOPT_URL</parameter>: This is the URL that you
        want PHP to fetch.  You can also set this option when
        initializing a session with the <function>curl_init</function>
        function.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_USERPWD</parameter>: Pass a string
        formatted in the [username]:[password] manner, for PHP to use
        for the connection.  connection.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_PROXYUSERPWD</parameter>: Pass a string
        formatted in the [username]:[password] format for connection
        to the HTTP proxy.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_RANGE</parameter>: Pass the specified range
        you want.  It should be in the "X-Y" format, where X or Y may
        be left out.  The HTTP transfers also support several
        intervals, separated with commas as in X-Y,N-M.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_POSTFIELDS</parameter>: Pass a string
        containing the full data to post in an HTTP "POST" operation.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_REFERER</parameter>: Pass a string
        containing the "referer" header to be used in an HTTP request.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_USERAGENT</parameter>: Pass a string
        containing the "user-agent" header to be used in an HTTP
        request.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FTPPORT</parameter>: Pass a string
        containing the which will be used to get the IP address to use
        for the ftp "POST" instruction.  The POST instruction tells
        the remote server to connect to our specified IP address.  The
        string may be a plain IP address, a hostname, a network
        interface name (under UNIX), or just a plain '-' to use the
        systems default IP address.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_COOKIE</parameter>: Pass a string
        containing the content of the cookie to be set in the HTTP
        header.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_SSLCERT</parameter>: Pass a string
        containing the filename of PEM formatted certificate.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_SSLCERTPASSWD</parameter>: Pass a string
        containing the password required to use the CURLOPT_SSLCERT
        certificate.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_COOKIEFILE</parameter>: Pass a string
        containing the name of the file containing the cookie data.
        The cookie file can be in Netscape format, or just plain
        HTTP-style headers dumped into a file.
       </simpara>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_CUSTOMREQUEST</parameter>: Pass a string to
        be used instead of <literal>GET</literal> or
        <literal>HEAD</literal> when doing an HTTP request.  This is
        useful for doing <literal>DELETE</literal> or other, more
        obscure, HTTP requests. Valid values are things like
        <literal>GET</literal>, <literal>POST</literal>, and so on; 
        i.e. do not enter a whole HTTP request line here. For instance,
        entering 'GET /index.html HTTP/1.0\r\n\r\n' would be incorrect.
        <note>
         <simpara>
          Don't do this without making sure your server supports the
          command first.
         </simpara>
        </note>
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_PROXY</parameter>: Give the name of the HTTP 
        proxy to tunnel requests through.
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_INTERFACE</parameter>: Pass the name of the 
        outgoing network interface to use.  This can be an interface name, 
        an IP address or a host name.
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_KRB4LEVEL</parameter>: Pass the KRB4 (Kerberos 
        4) security level.  This anyone of the following strings (in 
        order from least powerful, to most powerful): 'clear', 'safe', 
        'confidential', 'private'.  If the string does not match one of
        these, then 'private' is used.   If you set this to NULL, 
        this disables KB4 security.  KB4 security only works with FTP 
        transactions currently.
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_HTTPHEADER</parameter>: Pass an array of HTTP
        header fields to set.
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_QUOTE</parameter>: Pass an array of FTP commands
        to perform on the server prior to the FTP request.
       </para>
      </listitem>
      <listitem>
       <para>
        <parameter>CURLOPT_POSTQUOTE</parameter>: Pass an array of FTP 
        commands to execute on the server, after the FTP request has been 
        performed.
       </para>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The following options expect a file descriptor that is obtained
     by using the <function>fopen</function> function:
     <itemizedlist>
      <listitem>
       <simpara>
        <parameter>CURLOPT_FILE</parameter>: The file where the output
        of your transfer should be placed, the default is STDOUT.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_INFILE</parameter>: The file where the
        input of your transfer comes from.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_WRITEHEADER</parameter>: The file to write
        the header part of the output into.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>CURLOPT_STDERR</parameter>: The file to write
        errors to instead of stderr.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.curl-exec">
   <refnamediv>
    <refname>curl_exec</refname>
    <refpurpose>Perform a CURL session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>curl_exec</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function is should be called after you initialize a CURL
     session and all the options for the session are set.  Its purpose
     is simply to execute the predefined CURL session (given by the
     <parameter>ch</parameter>).
    </para>
    &tip.ob-capture;
   </refsect1>
  </refentry>

  <refentry id="function.curl-close">
   <refnamediv>
    <refname>curl_close</refname>
    <refpurpose>Close a CURL session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>curl_close</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function closes a CURL session and frees all resources.
     The CURL handle, <parameter>ch</parameter>, is also deleted.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.curl-version">
   <refnamediv>
    <refname>curl_version</refname>
    <refpurpose>Return the current CURL version</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>curl_version</methodname>
      <void/>
     </methodsynopsis>
    <para>
     The <function>curl_version</function> function returns a string
     containing the current CURL version.
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.curl-errno'>
   <refnamediv>
    <refname>curl_errno</refname>
    <refpurpose>Return an integer containing the last error number</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>curl_errno</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.curl-error'>
   <refnamediv>
    <refname>curl_error</refname>
    <refpurpose>
     Return a string contain the last error for the current session 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>curl_error</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.curl-getinfo'>
   <refnamediv>
    <refname>curl_getinfo</refname>
    <refpurpose>
     Get information regarding a specific transfer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>curl_getinfo</methodname>
      <methodparam><type>int</type><parameter>ch</parameter></methodparam>
      <methodparam><type>int</type><parameter>opt</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->