From c686b9be32b2ac888000d5b129defce89beb186f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?=
 <cataphract@php.net>
Date: Thu, 24 Dec 2009 20:26:33 +0000
Subject: [PATCH] Updated RAR extension documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@292613 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/rar/book.xml                        |   1 +
 reference/rar/rararchive/issolid.xml          | 114 ++++++++++
 reference/rar/rarexception.xml                | 207 ++++++++++++++++++
 .../rar/rarexception/isusingexceptions.xml    |  89 ++++++++
 .../rar/rarexception/setusingexceptions.xml   | 124 +++++++++++
 reference/rar/versions.xml                    |  16 ++
 6 files changed, 551 insertions(+)
 create mode 100644 reference/rar/rararchive/issolid.xml
 create mode 100644 reference/rar/rarexception.xml
 create mode 100644 reference/rar/rarexception/isusingexceptions.xml
 create mode 100644 reference/rar/rarexception/setusingexceptions.xml

diff --git a/reference/rar/book.xml b/reference/rar/book.xml
index fa79b71e50..9ebb82a433 100644
--- a/reference/rar/book.xml
+++ b/reference/rar/book.xml
@@ -28,6 +28,7 @@
  &reference.rar.examples;
  &reference.rar.rararchive;
  &reference.rar.rarentry;
+ &reference.rar.rarexception;
 
 </book>
 
diff --git a/reference/rar/rararchive/issolid.xml b/reference/rar/rararchive/issolid.xml
new file mode 100644
index 0000000000..ad3b80f058
--- /dev/null
+++ b/reference/rar/rararchive/issolid.xml
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: $ -->
+
+<refentry xml:id="rararchive.issolid" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>RarArchive::isSolid</refname>
+  <refname>rar_solid_is</refname>
+  <refpurpose>Check whether the RAR archive is solid.</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <para>Object oriented style (method):</para>
+   <methodsynopsis>
+   <modifier>public</modifier> <type>bool</type><methodname>RarArchive::isSolid</methodname>
+   <void />
+   </methodsynopsis>
+  <para>Procedural style:</para>
+  <methodsynopsis>
+   <type>bool</type><methodname>rar_solid_is</methodname>
+   <methodparam><type>RarArchive</type><parameter>rarfile</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Check whether the RAR archive is solid. Individual file extraction is slower on solid
+   archives.
+  </para> 
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>rarfile</parameter></term>
+     <listitem>
+      <para>
+       A <type>RarArchive</type> object, opened with <function>rar_open</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if the archive is solid, &false; otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Object oriented style</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arch1 = RarArchive::open("store_method.rar");
+$arch2 = RarArchive::open("solid.rar");
+echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
+echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
+?>
+]]>
+     </programlisting>
+     &example.outputs.similar;
+     <screen>
+<![CDATA[
+RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
+RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Procedural style</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$arch1 = rar_open("store_method.rar");
+$arch2 = rar_open("solid.rar");
+echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
+echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
+?>
+]]>
+     </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/rar/rarexception.xml b/reference/rar/rarexception.xml
new file mode 100644
index 0000000000..b207adcb09
--- /dev/null
+++ b/reference/rar/rarexception.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: $ -->
+
+<phpdoc:classref xml:id="class.rarexception" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <title>The RarException class</title>
+ <titleabbrev>RarException</titleabbrev>
+
+ <partintro>
+
+<!-- {{{ RarException intro -->
+  <section xml:id="rarexception.intro">
+   &reftitle.intro;
+   <para>
+    This class serves two purposes: it is the type of the exceptions thrown by the RAR extension
+	functions and methods and it allows, through static methods to query and define the error
+	behaviour of the extension, i.e., whether exceptions are thrown or only warnings are emitted.
+   </para>
+   <para>
+    The following error codes are used:
+   </para>
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      -1 - error outside UnRAR library
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      11 - insufficient memory
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      12 - bad data
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      13 - bad archive
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      14 - unknown format
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      15 - file open error
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      16 - file create error
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      17 - file close error
+     </simpara>
+    </listitem>
+	
+    <listitem>
+     <simpara>
+      18 - read error
+     </simpara>
+    </listitem>
+     <listitem>
+     <simpara>
+      19 - write error
+     </simpara>
+    </listitem>
+ 
+    <listitem>
+     <simpara>
+      20 - buffer too small
+     </simpara>
+    </listitem>
+ 
+    <listitem>
+     <simpara>
+      21 - unkown RAR error
+     </simpara>
+    </listitem>
+ 
+    <listitem>
+     <simpara>
+      22 - password required but not given
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </section>
+<!-- }}} -->
+
+  <section xml:id="rarexception.synopsis">
+   &reftitle.classsynopsis;
+
+<!-- {{{ Synopsis -->
+   <classsynopsis>
+    <ooclass><classname>RarException</classname></ooclass>
+
+<!-- {{{ Class synopsis -->
+    <classsynopsisinfo>
+     <ooclass>
+	  <modifier>final</modifier>
+      <classname>RarException</classname>
+     </ooclass>
+     
+     <ooclass>
+      <modifier>extends</modifier>
+      <classname>Exception</classname>
+     </ooclass>
+    </classsynopsisinfo>
+<!-- }}} -->
+    <classsynopsisinfo role="comment">Properties</classsynopsisinfo>
+    <fieldsynopsis>
+	 <modifier>private</modifier>
+     <modifier>static</modifier>
+     <varname linkend="rarexception.props.usingexceptions">usingExceptions</varname>
+    </fieldsynopsis>
+
+    
+    <classsynopsisinfo role="comment">Methods</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.rarexception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+    
+    <classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
+
+   </classsynopsis>
+<!-- }}} -->
+
+  </section>
+
+  
+<!-- {{{ RarException properties -->
+  <section xml:id="rarexception.props">
+   &reftitle.properties;
+   <variablelist>
+    <varlistentry xml:id="rarexception.props.message">
+     <term><varname>message</varname></term>
+     <listitem>
+      <para>Not part of the contract. Use <methodname>RarException::getMessage</methodname>.</para>
+     </listitem>
+    </varlistentry>
+    <varlistentry xml:id="rarexception.props.code">
+     <term><varname>code</varname></term>
+     <listitem>
+      <para>Not part of the contract. Use <methodname>RarException::getCode</methodname>.</para>
+     </listitem>
+    </varlistentry>
+    <varlistentry xml:id="rarexception.props.file">
+     <term><varname>file</varname></term>
+     <listitem>
+      <para>Not part of the contract. Use <methodname>RarException::getFile</methodname>.</para>
+     </listitem>
+    </varlistentry>
+    <varlistentry xml:id="rarexception.props.line">
+     <term><varname>line</varname></term>
+     <listitem>
+      <para>Not part of the contract. Use <methodname>RarException::getLine</methodname>.</para>
+     </listitem>
+    </varlistentry>
+    <varlistentry xml:id="rarexception.props.usingexceptions">
+     <term><varname>usingExceptions</varname></term>
+     <listitem>
+      <para>Not part of the contract.
+	  Use <methodname>RarException::isUsingExceptions</methodname> and <methodname>RarException::setUsingExceptions</methodname>.</para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+<!-- }}} -->
+
+
+ </partintro>
+
+ &reference.rar.entities.rarexception;
+
+</phpdoc:classref>
+
+<!-- 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
+-->
diff --git a/reference/rar/rarexception/isusingexceptions.xml b/reference/rar/rarexception/isusingexceptions.xml
new file mode 100644
index 0000000000..c339667fa5
--- /dev/null
+++ b/reference/rar/rarexception/isusingexceptions.xml
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: $ -->
+
+<refentry xml:id="rarexception.isusingexceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>RarException::isUsingExceptions</refname>
+  <refpurpose>Check whether error handling with exceptions is in use</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>bool</type><methodname>RarException::isUsingExceptions</methodname>
+   <void />
+  </methodsynopsis>
+  <para>
+   Checks whether the RAR functions will emit warnings and return error values or whether they
+   will throw exceptions in most of the circumstances (does not include some programmatic
+   errors such as passing the wrong type of arguments).
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  &no.function.parameters;
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if exceptions are being used, &false; otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>RarException::isUsingExceptions</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+//The default is not to use exceptions
+var_dump(RarException::isUsingExceptions());
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+bool(false)
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>RarException::setUsingExceptions</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/rar/rarexception/setusingexceptions.xml b/reference/rar/rarexception/setusingexceptions.xml
new file mode 100644
index 0000000000..c3e8d3542d
--- /dev/null
+++ b/reference/rar/rarexception/setusingexceptions.xml
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: $ -->
+
+<refentry xml:id="rarexception.setusingexceptions" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>RarException::setUsingExceptions</refname>
+  <refpurpose>Activate and deactivate error handling with exceptions</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <modifier>public</modifier> <modifier>static</modifier> <type>void</type><methodname>RarException::setUsingExceptions</methodname>
+   <methodparam><type>string</type><parameter>using_exceptions</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   If and only if the argument is &true;, then, instead of emitting warnings and returning a special value indicating error when the UnRAR library encounters an error, an exception of type <type>RarExzception</type> will be thrown.
+  </para>
+  <para>
+   Exceptions will also be thrown for the following errors, which occur outside the library (their error code will be -1):
+  </para>
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     attempting some operations on a closed <type>RarArchive</type> object or a <type>RarEntry</type> object relative to the first;
+    </simpara>
+   </listitem>
+   
+   <listitem>
+    <simpara>
+     attempting to get an entry that does not exist with <methodname>RarArchive::getEntry</methodname>.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>using_exceptions</parameter></term>
+     <listitem>
+      <para>
+       Should be &true; to activate exception throwing, &false; to deactivate (the default).
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>RarException::setUsingExceptions</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(RarException::isUsingExceptions());
+$arch = RarArchive::open("does_not_exist.rar");
+var_dump($arch);
+
+RarException::setUsingExceptions(true);
+var_dump(RarException::isUsingExceptions());
+$arch = RarArchive::open("does_not_exist.rar");
+var_dump($arch); //not reached
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+bool(false)
+
+Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
+bool(false)
+bool(true)
+
+Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
+Stack trace:
+#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
+#1 {main}
+  thrown in C:\php_rar\trunk\tests\test.php on line 8
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><methodname>RarException::isUsingExceptions</methodname></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
+
+<!-- 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
+-->
diff --git a/reference/rar/versions.xml b/reference/rar/versions.xml
index 42e99d10d8..3bfffba53e 100644
--- a/reference/rar/versions.xml
+++ b/reference/rar/versions.xml
@@ -9,15 +9,18 @@
  <function name='rar_open' from='PECL rar &gt;= 0.1'/>
  <function name='rar_list' from='PECL rar &gt;= 0.1'/>
  <function name='rar_entry_get' from='PECL rar &gt;= 0.1'/>
+ <function name='rar_solid_is' from='PECL rar &gt;= 2.0.0'/>
  <function name='rar_comment_get' from='PECL rar &gt;= 2.0.0'/>
  <function name='rar_close' from='PECL rar &gt;= 0.1'/>
  <!-- Methods -->
  <function name='rararchive::open' from='PECL rar &gt;= 2.0.0'/>
  <function name='rararchive::list' from='PECL rar &gt;= 2.0.0'/>
  <function name='rararchive::getentry' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rararchive::issolid' from='PECL rar &gt;= 2.0.0'/>
  <function name='rararchive::getcomment' from='PECL rar &gt;= 2.0.0'/>
  <function name='rararchive::close' from='PECL rar &gt;= 2.0.0'/>
  <function name='rararchive::__tostring' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rararchive::__construct' from='PECL rar &gt;= 2.0.0'/>
  <function name='rarentry::extract' from='PECL rar &gt;= 0.1'/>
  <function name='rarentry::getname' from='PECL rar &gt;= 0.1'/>
  <function name='rarentry::getunpackedsize' from='PECL rar &gt;= 0.1'/>
@@ -32,6 +35,19 @@
  <function name='rarentry::isdirectory' from='PECL rar &gt;= 2.0.0'/>
  <function name='rarentry::isencrypted' from='PECL rar &gt;= 2.0.0'/>
  <function name='rarentry::__tostring' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarentry::__construct' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::setusingexceptions' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::isusingexceptions' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::__clone' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::__construct' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::getmessage' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::getcode' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::getfile' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::getline' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::gettrace' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::getprevious' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::gettraceasstring' from='PECL rar &gt;= 2.0.0'/>
+ <function name='rarexception::__tostring' from='PECL rar &gt;= 2.0.0'/>
 </versions>
 
 <!-- Keep this comment at the end of the file