php-doc-en/reference/rar/rarentry/getstream.xml

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

<refentry xml:id="rarentry.getstream" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>RarEntry::getStream</refname>
  <refpurpose>Get file handler for entry</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>resource</type><methodname>RarEntry::getStream</methodname>
   <methodparam choice="opt"><type>string</type><parameter>password</parameter></methodparam>
  </methodsynopsis>
  <para>
   Returns a file handler that
   supports read operations. This handler provides on-the-fly decompression
   for this entry.
  </para>
  <para>
    The handler is not invalidated by calling
    <function>rar_close</function>.
  </para>
  <warning>
   <para>The resulting stream has no integrity verification. In particular, file corruption and
   decryption with a wrong a key will not be detected. It is the programmer's responsability to use the entry's CRC
   to check for integrity, if he so wishes.</para>
  </warning>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can
       be omitted. If this parameter is omitted and the entry is encrypted, the password given to
       <function>rar_open</function>, if any, will be used. If a wrong password is given, either explicitly
       or implicitly via <function>rar_open</function>, this method's resulting stream will produce wrong
       output. If no password is given and one is required, this method will fail and return &false;.
       You can check whether an entry is encrypted with <methodname>RarEntry::isEncrypted</methodname>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The file handler &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>3.0.0</entry>
       <entry>
        Support for RAR archives with repeated entry names is no longer defective.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><methodname>RarEntry::getStream</methodname> example</title>
    <programlisting role="php">
<![CDATA[
<?php

$rar_file = rar_open('example.rar');
if ($rar_file === false)
    die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
    die("Failed to find such entry");

$stream = $entry->getStream();
if ($stream === false)
    die("Failed to obtain stream.");

rar_close($rar_file); //stream is independent from file

while (!feof($stream)) {
    $buff = fread($stream, 8192);
    if ($buff !== false)
        echo $buff;
    else
        break; //fread error
}

fclose($stream);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>RarEntry::extract</methodname></member>
    <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
-->