<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="rararchive.open" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>RarArchive::open</refname>
  <refname>rar_open</refname>
  <refpurpose>Open RAR archive</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop; (method):</para>
   <methodsynopsis>
   <modifier>public</modifier> <modifier>static</modifier> <type class="union"><type>RarArchive</type><type>false</type></type><methodname>RarArchive::open</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>password</parameter><initializer>NULL</initializer></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>volume_callback</parameter><initializer>NULL</initializer></methodparam>
   </methodsynopsis>
  <para>&style.procedural;:</para>
  <methodsynopsis>
   <type class="union"><type>RarArchive</type><type>false</type></type><methodname>rar_open</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>password</parameter><initializer>NULL</initializer></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>volume_callback</parameter><initializer>NULL</initializer></methodparam>
  </methodsynopsis>
  <para>
   Open specified RAR archive and return <type>RarArchive</type> instance representing it.
  </para>
  <note>
   <para>
    If opening a multi-volume archive, the path of the first volume should be passed as the first parameter.
    Otherwise, not all files will be shown. This is by design.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Path to the Rar archive.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       A plain password, if needed to decrypt the headers. It will also be used by default
       if encrypted files are found. Note that the files may have
       different passwords in respect to the headers and among them.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>volume_callback</parameter></term>
     <listitem>
      <para>
       A function that receives one parameter – the path of the volume
       that was not found – and returns a string with the correct path
       for such volume or &null; if such volume does
       not exist or is not known. The programmer should ensure the
       passed function doesn't cause loops as this function is called
       repeatedly if the path returned in a previous call did not
       correspond to the needed volume. Specifying this parameter omits
       the notice that would otherwise be emitted whenever a volume is
       not found; an implementation that only returns &null;
       can therefore be used to merely omit such notices.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <warning>
   <para>
    Prior to version 2.0.0, this function would not handle relative
    paths correctly. Use <function>realpath</function> as a workaround.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the requested <type>RarArchive</type> instance &return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>PECL rar 3.0.0</entry>
       <entry>
        <parameter>volume_callback</parameter> was added.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>&style.oop;</title>
    <programlisting role="php">
<![CDATA[
<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");
    
$entries = $rar_arch->getEntries();
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");
    
$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

$rar_arch->close();

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>
]]>
     </programlisting>
     &example.outputs.similar;
     <screen>
<![CDATA[
Found 2 files.
Content of first one follows:
Encrypted file 1 contents.
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>&style.procedural;</title>
    <programlisting role="php">
<![CDATA[
<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");
    
$entries = rar_list($rar_arch);
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");
    
$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

rar_close($rar_arch);

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>
]]>
     </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Volume Callback</title>
    <programlisting role="php">
<![CDATA[
<?php
/* In this example, there's a volume named multi_broken.part1.rar
 * whose next volume is named multi.part2.rar */
function resolve($vol) {
    if (preg_match('/_broken/', $vol))
        return str_replace('_broken', '', $vol);
    else
        return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>
]]>
     </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="wrappers.rar"><literal>rar://</literal> wrapper</link></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:"~/.phpdoc/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
-->
