Updated RAR extension documentation.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@292613 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gustavo André dos Santos Lopes 2009-12-24 20:26:33 +00:00
parent 2ffa54d106
commit c686b9be32
6 changed files with 551 additions and 0 deletions

View file

@ -28,6 +28,7 @@
&reference.rar.examples;
&reference.rar.rararchive;
&reference.rar.rarentry;
&reference.rar.rarexception;
</book>

View file

@ -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
-->

View file

@ -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
-->

View file

@ -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
-->

View file

@ -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
-->

View file

@ -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