cortesi Mon Mar 25 20:53:23 2002 EDT
Modified files:
/phpdoc/it/functions curl.xml
Log:
updated but not yet finished
Index: phpdoc/it/functions/curl.xml
diff -u /dev/null phpdoc/it/functions/curl.xml:1.5
--- /dev/null Mon Mar 25 20:53:23 2002
+++ phpdoc/it/functions/curl.xml Mon Mar 25 20:53:23 2002
@@ -0,0 +1,645 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- EN-Revision: 1.28 Maintainer: cortesi Status: working -->
+<!-- CREDITS: cucinato -->
+ <reference id="ref.curl">
+ <title>Funzioni CURL, Client URL Library</title>
+ <titleabbrev>CURL</titleabbrev>
+
+ <partintro id="curl.partintro">
+ <para>
+ PHP supporta libcurl, una libreria creata da Daniel Stenberg, che
+ permette di collegarsi e comunicare con parecchi tipi di
+ server e con parecchi tipi di protocolli. Libcurl al momento
+ supporta i protocolli http, https, ftp, gopher, telnet, dict, file, e
+ ldap. libcurl supporta anche i certificati HTTPS, HTTP
+ POST, HTTP PUT, l'upload via FTP (questo pu� essere ottenuto anche con
+l'estensione
+ ftp di PHP), upload attraverso una form HTTP, proxy, cookie e
+ autenticazione con utente e password.
+ </para>
+ <para>
+ Per utilizzare le funzioni CURL occorre installare il pacchetto <ulink
+ url="&url.curl;">CURL</ulink>. PHP richiede che si usi
+ CURL 7.0.2-beta o successivi. PHP non funzioner� con alcuna versione di
+ CURL antecedente alla 7.0.2-beta.
+ </para>
+ <para>
+ Al fine di utilizzare il supporto CURL occorre anche compilare il PHP con <option
+ role="configure">--with-curl[=DIR]</option> dove DIR � il
+ percorso della directory che contiene le directory lib e
+ include. Nella directory "include" ci dovrebbe essere una cartella
+ chiamata "curl" che dovrebbe contenere i file easy.h e curl.h.
+ Ci dovrebbe essere un file chiamato "libcurl.a" nella directory
+ "lib".
+ </para>
+ <para>
+ Queste funzioni sono state aggiunte nel PHP 4.0.2.
+ </para>
+ <para>
+ Una volta compilato PHP con il supporto CURL, si pu� iniziare a usare
+ le funzioni curl. L'idea di condo che sta dietro le funzioni CURL �
+ che si inizializza una sessione CURL usando
+ <function>curl_init</function>, quindi si possono impostare le
+ opzioni per il trasferimento tramite <function>curl_exec</function>
+ e quindi si termina la sessione usando
+ <function>curl_close</function>. Qui di seguito si trova un esempio
+ che fa uso delle funzioni CURL per scaricare la homepage del sito PHP e metterla
+in un file:
+ <example>
+ <title>Usare il modulo CURL di PHP per scaricare la homepage di PHP</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$ch = curl_init ("http://www.php.net/";);
+$fp = fopen ("homepage_php.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>Inizializza una sessione CURL</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</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> inizializza una nuova sessione
+ e restituisce un handle CURL da usarsi con le funzioni
+ <function>curl_setopt</function>, <function>curl_exec</function>
+ e <function>curl_close</function>. Se viene dato il parametro
+ opzionale <parameter>url</parameter>, allora l'opzione
+ CURLOPT_URL verr� impostata al valore di quel parametro.
+ Questo si pu� impostare manualmente usando la funzione
+ <function>curl_setopt</function>.
+ <example>
+ <title>
+ Inizializzare una nuova sessione CURL e scaricare una paginaweb
+ </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>
+ Vedere anche: <function>curl_close</function> e
+ <function>curl_setopt</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.curl-setopt">
+ <refnamediv>
+ <refname>curl_setopt</refname>
+ <refpurpose>Imposta una opzione per un trasferimento CURLr</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</title>
+ <methodsynopsis>
+ <type>bool</type><methodname>curl_setopt</methodname>
+ <methodparam><type>int</type><parameter>ch</parameter></methodparam>
+ <methodparam><type>string</type><parameter>opzione</parameter></methodparam>
+ <methodparam><type>mixed</type><parameter>valore</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ La funzione <function>curl_setopt</function> will set options
+ for a CURL session identified by the <parameter>ch</parameter>
+ parameter. The <parameter>opzione</parameter> parameter is the
+ option you want to set, and the <parameter>valore</parameter> is
+ the value of the option given by the
+ <parameter>opzione</parameter>.
+ </para>
+ <para>
+ The <parameter>value</parameter> should be a long for the
+ following options (specified in the <parameter>option</parameter>
+ parameter):
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_INFILESIZE</parameter>: When you are
+ uploading a file to a remote site, this option should be used
+ to tell PHP what the expected size of the infile will be.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_VERBOSE</parameter>: Set this option to a
+ non-zero value if you want CURL to report everything that is
+ happening.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_HEADER</parameter>: Set this option to a
+ non-zero value if you want the header to be included in the
+ output.
+ </simpara>
+ </listitem>
+ <listitem>
+ <para>
+ <parameter>CURLOPT_NOPROGRESS</parameter>: Set this option to
+ a non-zero value if you don't want PHP to display a progress
+ meter for CURL transfers
+ <note>
+ <simpara>
+ PHP automatically sets this option to a non-zero parameter,
+ this should only be changed for debugging purposes.
+ </simpara>
+ </note>
+ </para>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_NOBODY</parameter>: Set this option to a
+ non-zero value if you don't want the body included with the
+ output.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_FAILONERROR</parameter>: Set this option to
+ a non-zero value if you want PHP to fail silently if the HTTP
+ code returned is greater than 300. The default behavior is
+ to return the page normally, ignoring the code.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_UPLOAD</parameter>: Set this option to a
+ non-zero value if you want PHP to prepare for an upload.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_POST</parameter>: Set this option to a
+ non-zero value if you want PHP to do a regular HTTP POST.
+ This POST is a normal application/x-www-form-urlencoded kind,
+ most commonly used by HTML forms.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <parameter>CURLOPT_FTPLISTONLY</parameter>: Set this option to
+ a non-zero value and PHP will just list the names of an FTP
+ directory.
+ </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>Descrizione</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>Chiude una sessione CURL</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</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>Restituisce la versione di CURL in uso</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</title>
+ <methodsynopsis>
+ <type>string</type><methodname>curl_version</methodname>
+ <void/>
+ </methodsynopsis>
+ <para>
+ La funzione <function>curl_version</function> restituisce una stringa
+ contenente la versione di CURL attualmente in uso.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id='function.curl-errno'>
+ <refnamediv>
+ <refname>curl_errno</refname>
+ <refpurpose>Restituisce un intero contenente il numero dell'ultimo
+errore</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</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>
+ Restituisce una stringa contenente l'ultimo errore relativo alla sessione
+corrente
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</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>
+ Ottiene informazioni relative a un determinato trasferimento
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descrizione</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
+-->
