From 0db4f1d2a5b7545af4a9bc1997b65900f1a757a7 Mon Sep 17 00:00:00 2001
From: Logan Buesching <ljbuesch@php.net>
Date: Fri, 1 Jun 2007 03:01:42 +0000
Subject: [PATCH] Finished the documentation for the cURL library.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@236790 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/curl/functions/curl-exec.xml        |  6 +-
 .../curl/functions/curl-multi-add-handle.xml  | 43 +++++++++++-
 reference/curl/functions/curl-multi-close.xml | 44 ++++++++++++-
 reference/curl/functions/curl-multi-exec.xml  | 66 +++++++++++++++++--
 .../curl/functions/curl-multi-getcontent.xml  | 17 +++--
 .../curl/functions/curl-multi-info-read.xml   | 39 +++++++++--
 reference/curl/functions/curl-multi-init.xml  | 57 ++++++++++++++--
 .../functions/curl-multi-remove-handle.xml    | 18 +++--
 .../curl/functions/curl-multi-select.xml      | 16 ++++-
 9 files changed, 277 insertions(+), 29 deletions(-)

diff --git a/reference/curl/functions/curl-exec.xml b/reference/curl/functions/curl-exec.xml
index 3fd5102db8..7957e7044e 100644
--- a/reference/curl/functions/curl-exec.xml
+++ b/reference/curl/functions/curl-exec.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <refentry id="function.curl-exec">
  <refnamediv>
   <refname>curl_exec</refname>
@@ -33,8 +33,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   &return.success; However, if the CURLOPT_RETURNTRANSFER option is set,
-   it will return the result on success, &false; on failure.
+   &return.success; However, if the <constant>CURLOPT_RETURNTRANSFER</constant>
+   option is set, it will return the result on success, &false; on failure.
   </para>
  </refsect1>
    
diff --git a/reference/curl/functions/curl-multi-add-handle.xml b/reference/curl/functions/curl-multi-add-handle.xml
index a7cc023cbe..34ef3a74ec 100644
--- a/reference/curl/functions/curl-multi-add-handle.xml
+++ b/reference/curl/functions/curl-multi-add-handle.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.curl-multi-add-handle">
  <refnamediv>
   <refname>curl_multi_add_handle</refname>
@@ -36,7 +36,48 @@
    code.
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_multi_add_handle</function> example</title>
+    <para>
+     This example will create two cURL handles, add them to a multi
+     handle, and then run them in parallel.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
 
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh);
+
+//close all the handles
+curl_multi_close();
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/curl/functions/curl-multi-close.xml b/reference/curl/functions/curl-multi-close.xml
index 27a938ad1f..600ea0d3c3 100644
--- a/reference/curl/functions/curl-multi-close.xml
+++ b/reference/curl/functions/curl-multi-close.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.curl-multi-close">
  <refnamediv>
   <refname>curl_multi_close</refname>
@@ -33,6 +33,48 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_multi_close</function> example</title>
+    <para>
+     This example will create two cURL handles, add them to a multi
+     handle, and then run them in parallel.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh);
+
+//close the handles
+curl_multi_close();
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/curl/functions/curl-multi-exec.xml b/reference/curl/functions/curl-multi-exec.xml
index 01b958106d..2d3d50d1bf 100644
--- a/reference/curl/functions/curl-multi-exec.xml
+++ b/reference/curl/functions/curl-multi-exec.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="function.curl-multi-exec">
  <refnamediv>
   <refname>curl_multi_exec</refname>
@@ -13,9 +13,10 @@
    <methodparam><type>resource</type><parameter>mh</parameter></methodparam>
    <methodparam><type>int</type><parameter role="reference">still_running</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   Processes each of the handles in the stack.  This method can be called whether or not a handle
+   needs to read or write data.
+  </para> 
  </refsect1>
 
  <refsect1 role="parameters">
@@ -27,6 +28,7 @@
      <term><parameter>still_running</parameter></term>
      <listitem>
       <para>
+       A reference to a flag to tell whether the operations are still running.
       </para>
      </listitem>
     </varlistentry>
@@ -34,6 +36,62 @@
   </para>
  </refsect1>
 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   A cURL code defined in the cURL <link linkend="curl.constants">Predefined Constants</link>.
+  </para>
+  <note>
+   <para>
+    This only returns errors regarding the whole multi stack. There might still have 
+    occurred problems on individual transfers even when this function returns 
+    <constant>CURLM_OK</constant>.
+   </para>
+  </note>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_multi_exec</function> example</title>
+    <para>
+     This example will create two cURL handles, add them to a multi
+     handle, and then run them in parallel.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh);
+
+//close the handles
+curl_multi_close();
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/curl/functions/curl-multi-getcontent.xml b/reference/curl/functions/curl-multi-getcontent.xml
index cd24044123..809b01ddc4 100644
--- a/reference/curl/functions/curl-multi-getcontent.xml
+++ b/reference/curl/functions/curl-multi-getcontent.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="function.curl-multi-getcontent">
  <refnamediv>
   <refname>curl_multi_getcontent</refname>
@@ -12,9 +12,11 @@
    <type>string</type><methodname>curl_multi_getcontent</methodname>
    <methodparam><type>resource</type><parameter>ch</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   If <constant>CURLOPT_RETURNTRANSFER</constant> is an option that is set for a specific handle, 
+   then this function will return the content of that cURL handle in the form
+   of a string.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -25,6 +27,13 @@
    </variablelist>
   </para>
  </refsect1>
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Return the content of a cURL handle if <constant>CURLOPT_RETURNTRANSFER</constant> is set.
+  </para>
+ </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
diff --git a/reference/curl/functions/curl-multi-info-read.xml b/reference/curl/functions/curl-multi-info-read.xml
index f7ce547c9a..afcb1ce720 100644
--- a/reference/curl/functions/curl-multi-info-read.xml
+++ b/reference/curl/functions/curl-multi-info-read.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <refentry id="function.curl-multi-info-read">
  <refnamediv>
   <refname>curl_multi_info_read</refname>
@@ -13,20 +13,49 @@
    <methodparam><type>resource</type><parameter>mh</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>msgs_in_queue</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   Ask the multi handle if there are any messages/informationals from the individual transfers. 
+   Messages may include informationals such as an error code from the transfer or just the fact 
+   that a transfer is completed.
+  </para>
+  <para>   
+   Repeated calls to this function will return a new result each time, until a &false; is returned 
+   as a signal that there is no more to get at this point. The integer pointed to with 
+   <parameter>msgs_in_queue</parameter> will contain the number of remaining messages after this 
+   function was called.
+  </para>
+  <warning>
+   <para>
+    The data the returned resource points to will not survive calling 
+    <function>curl_multi_remove_handle</function>.
+   </para>
+  </warning>
  </refsect1>
-
+ 
  <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
    <variablelist>
     &curl.mh.description;
+    <varlistentry>
+     <term><parameter>msgs_in_queue</parameter></term>
+     <listitem>
+      <para>
+       Number of messages that are still in the queue
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
  
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   On success, returns an associative array for the message, &false; on failure.
+  </para>
+ </refsect1>
+ 
  <refsect1 role="changelog">
   &reftitle.changelog;
   <para>
diff --git a/reference/curl/functions/curl-multi-init.xml b/reference/curl/functions/curl-multi-init.xml
index 0592aa54fc..be42a0f3d4 100644
--- a/reference/curl/functions/curl-multi-init.xml
+++ b/reference/curl/functions/curl-multi-init.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.curl-multi-init">
  <refnamediv>
   <refname>curl_multi_init</refname>
@@ -12,9 +12,9 @@
    <type>resource</type><methodname>curl_multi_init</methodname>
    <void />
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   Allows the processing of multiple cURL handles in parallel.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -26,6 +26,55 @@
   </para>
  </refsect1>
 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns a cURL on handle on success, &false; on failure.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_multi_init</function> example</title>
+    <para>
+     This example will create two cURL handles, add them to a multi
+     handle, and then run them in parallel.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// create both cURL resources
+$ch1 = curl_init();
+$ch2 = curl_init();
+
+// set URL and other appropriate options
+curl_setopt($ch, CURLOPT_URL, "http://www.example.com/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+curl_setopt($ch, CURLOPT_URL, "http://www.php.net/");
+curl_setopt($ch, CURLOPT_HEADER, 0);
+
+//create the multiple cURL handle
+$mh = curl_multi_init();
+
+//add the two handles
+curl_multi_add_handle($mh,$ch1);
+curl_multi_add_handle($mh,$ch2);
+
+//execute the handles
+curl_multi_exec($mh);
+
+//close the handles
+curl_multi_close();
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/curl/functions/curl-multi-remove-handle.xml b/reference/curl/functions/curl-multi-remove-handle.xml
index 9a0b1bfbf6..86bd1e7828 100644
--- a/reference/curl/functions/curl-multi-remove-handle.xml
+++ b/reference/curl/functions/curl-multi-remove-handle.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.curl-multi-remove-handle">
  <refnamediv>
   <refname>curl_multi_remove_handle</refname>
@@ -13,9 +13,12 @@
    <methodparam><type>resource</type><parameter>mh</parameter></methodparam>
    <methodparam><type>resource</type><parameter>ch</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
-
+  <para>
+   Removes a given <parameter>ch</parameter> handle from the given <parameter>mh</parameter>
+   handle. When the <parameter>ch</parameter> handle has been removed, it is again perfectly 
+   legal to run <function>curl_exec</function> on this handle.  Removing a handle while being 
+   used, will effectively halt all transfers in progress.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -27,6 +30,13 @@
    </variablelist>
   </para>
  </refsect1>
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   On success, returns a cURL handle, &false; on failure.
+  </para>
+ </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
diff --git a/reference/curl/functions/curl-multi-select.xml b/reference/curl/functions/curl-multi-select.xml
index c313573a27..5d7a490bfa 100644
--- a/reference/curl/functions/curl-multi-select.xml
+++ b/reference/curl/functions/curl-multi-select.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.curl-multi-select">
  <refnamediv>
   <refname>curl_multi_select</refname>
@@ -13,8 +13,9 @@
    <methodparam><type>resource</type><parameter>mh</parameter></methodparam>
    <methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam>
   </methodsynopsis>
-
-  &warn.undocumented.func;
+  <para>
+   Get all the sockets associated with the cURL extension, which can then be "selected".
+  </para>
 
  </refsect1>
 
@@ -27,12 +28,21 @@
      <term><parameter>timeout</parameter></term>
      <listitem>
       <para>
+       Time, in seconds, to wait for a response.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect1>
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   On success, returns the number of descriptors contained in, 
+   the descriptor sets.  On failure, this function will return &false;.
+  </para>
+ </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;