From e5868a071fcd0db735dde2e50bd84ae7e8763602 Mon Sep 17 00:00:00 2001
From: Adam Scheller <kazymjir@php.net>
Date: Sat, 15 Jun 2013 21:02:02 +0000
Subject: [PATCH] Documentation for curl_share_* functions

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@330511 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/curl/functions/curl-share-close.xml |  61 +++++++++-
 reference/curl/functions/curl-share-init.xml  |  60 +++++++++-
 .../curl/functions/curl-share-setopt.xml      | 112 ++++++++++++++++--
 3 files changed, 217 insertions(+), 16 deletions(-)

diff --git a/reference/curl/functions/curl-share-close.xml b/reference/curl/functions/curl-share-close.xml
index 60d5b55e2c..2d831ec4cc 100644
--- a/reference/curl/functions/curl-share-close.xml
+++ b/reference/curl/functions/curl-share-close.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="function.curl-share-close" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>curl_share_close</refname>
-  <refpurpose>Close a set of cURL handles</refpurpose>
+  <refpurpose>Close a cURL share handle</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,9 @@
    <methodparam><type>resource</type><parameter>sh</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   Closes a cURL share handle and frees all resources.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -28,7 +26,7 @@
     <term><parameter>sh</parameter></term>
     <listitem>
      <para>
-      
+      A cURL share handle returned by <function>curl_share_init</function>
      </para>
     </listitem>
    </varlistentry>
@@ -41,6 +39,59 @@
    &return.void;
   </para>
  </refsect1>
+ 
+<refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_share_setopt</function> example</title>
+    <para>
+     This example will create a cURL share handle, add two cURL handles to it,
+     and then run them with cookie data sharing.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Create cURL share handle and set it to share cookie data
+$sh = curl_share_init();
+curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
+
+// Initialize the first cURL handle and assign the share handle to it
+$ch1 = curl_init("http://example.com/");
+curl_setopt($ch1, CURLOPT_SHARE, $sh);
+
+// Execute the first cURL handle
+curl_exec($ch1);
+
+// Initialize the second cURL handle and assign the share handle to it
+$ch2 = curl_init("http://php.net/");
+curl_setopt($ch2, CURLOPT_SHARE, $sh);
+
+// Execute the second cURL handle
+//  all cookies from $ch1 handle are shared with $ch2 handle
+curl_exec($ch2);
+
+// Close the cURL share handle
+curl_share_close($sh);
+
+// Close the cURL handles
+curl_close($ch1);
+curl_close($ch2);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>curl_share_init</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 
 </refentry>
 
diff --git a/reference/curl/functions/curl-share-init.xml b/reference/curl/functions/curl-share-init.xml
index 5dd3fbb6d1..4c13d14c06 100644
--- a/reference/curl/functions/curl-share-init.xml
+++ b/reference/curl/functions/curl-share-init.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="function.curl-share-init" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>curl_share_init</refname>
-  <refpurpose>Initialize a share curl handle</refpurpose>
+  <refpurpose>Initialize a cURL share handle</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -14,11 +14,9 @@
    <void />
   </methodsynopsis>
   <para>
-
+   Allows to share data between cURL handles.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -32,6 +30,60 @@
    Returns resource of type "cURL Share Handle".
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_share_init</function> example</title>
+    <para>
+     This example will create a cURL share handle, add two cURL handles to it,
+     and then run them with cookie data sharing.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Create cURL share handle and set it to share cookie data
+$sh = curl_share_init();
+curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
+
+// Initialize the first cURL handle and assign the share handle to it
+$ch1 = curl_init("http://example.com/");
+curl_setopt($ch1, CURLOPT_SHARE, $sh);
+
+// Execute the first cURL handle
+curl_exec($ch1);
+
+// Initialize the second cURL handle and assign the share handle to it
+$ch2 = curl_init("http://php.net/");
+curl_setopt($ch2, CURLOPT_SHARE, $sh);
+
+// Execute the second cURL handle
+//  all cookies from $ch1 handle are shared with $ch2 handle
+curl_exec($ch2);
+
+// Close the cURL share handle
+curl_share_close($sh);
+
+// Close the cURL handles
+curl_close($ch1);
+curl_close($ch2);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>curl_share_setopt</function></member>
+    <member><function>curl_share_close</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 
 </refentry>
 
diff --git a/reference/curl/functions/curl-share-setopt.xml b/reference/curl/functions/curl-share-setopt.xml
index da61d3b391..8fb430a9cc 100644
--- a/reference/curl/functions/curl-share-setopt.xml
+++ b/reference/curl/functions/curl-share-setopt.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="function.curl-share-setopt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>curl_share_setopt</refname>
-  <refpurpose>Set an option for a cURL transfer</refpurpose>
+  <refpurpose>Set an option for a cURL share handle.</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -16,11 +16,9 @@
    <methodparam><type>string</type><parameter>value</parameter></methodparam>
   </methodsynopsis>
   <para>
-
+   Sets an option on the given cURL share handle.
   </para>
 
-  &warn.undocumented.func;
-
  </refsect1>
 
  <refsect1 role="parameters">
@@ -30,7 +28,7 @@
     <term><parameter>sh</parameter></term>
     <listitem>
      <para>
-      
+      A cURL share handle returned by <function>curl_share_init</function>.
      </para>
     </listitem>
    </varlistentry>
@@ -38,7 +36,30 @@
     <term><parameter>option</parameter></term>
     <listitem>
      <para>
-      
+      <informaltable>
+        <tgroup cols="3">
+         <thead>
+          <row>
+           <entry valign="top">Option</entry>
+           <entry valign="top">Description</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry valign="top"><constant>CURLSHOPT_SHARE</constant></entry>
+           <entry valign="top">
+               Specifies a type of data that should be shared.
+           </entry>
+          </row>
+          <row>
+           <entry valign="top"><constant>CURLSHOPT_UNSHARE</constant></entry>
+           <entry valign="top">
+               Specifies a type of data that will be no longer shared.
+           </entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </informaltable>
      </para>
     </listitem>
    </varlistentry>
@@ -46,7 +67,40 @@
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
-      
+      <informaltable>
+        <tgroup cols="3">
+         <thead>
+          <row>
+           <entry valign="top">Value</entry>
+           <entry valign="top">Description</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry valign="top"><constant>CURL_LOCK_DATA_COOKIE</constant></entry>
+           <entry valign="top">
+               Shares cookie data.
+           </entry>
+          </row>
+          <row>
+           <entry valign="top"><constant>CURL_LOCK_DATA_DNS</constant></entry>
+           <entry valign="top">
+               Shares DNS cache. Note that when you use cURL multi handles,
+               all handles added to the same multi handle will share DNS cache
+               by default.
+           </entry>
+          </row>
+          <row>
+           <entry valign="top"><constant>CURL_LOCK_DATA_SSL_SESSION</constant></entry>
+           <entry valign="top">
+               Shares SSL session IDs, reducing the time spent on the SSL
+               handshake when reconnecting to the same server. Note that SSL
+               session IDs are reused withing the same handle by default.
+           </entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </informaltable>
      </para>
     </listitem>
    </varlistentry>
@@ -59,6 +113,50 @@
    &return.success;
   </para>
  </refsect1>
+ 
+<refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>curl_share_setopt</function> example</title>
+    <para>
+     This example will create a cURL share handle, add two cURL handles to it,
+     and then run them with cookie data sharing.
+    </para>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Create cURL share handle and set it to share cookie data
+$sh = curl_share_init();
+curl_share_setopt($sh, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
+
+// Initialize the first cURL handle and assign the share handle to it
+$ch1 = curl_init("http://example.com/");
+curl_setopt($ch1, CURLOPT_SHARE, $sh);
+
+// Execute the first cURL handle
+curl_exec($ch1);
+
+// Initialize the second cURL handle and assign the share handle to it
+$ch2 = curl_init("http://php.net/");
+curl_setopt($ch2, CURLOPT_SHARE, $sh);
+
+// Execute the second cURL handle
+//  all cookies from $ch1 handle are shared with $ch2 handle
+curl_exec($ch2);
+
+// Close the cURL share handle
+curl_share_close($sh);
+
+// Close the cURL handles
+curl_close($ch1);
+curl_close($ch2);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
 
 </refentry>