<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Get file handler for entry</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="rarentry.getpackedsize.html">RarEntry::getPackedSize</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rarentry.getunpackedsize.html">RarEntry::getUnpackedSize</a></div>
<div class="up"><a href="class.rarentry.html">RarEntry</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="rarentry.getstream" class="refentry">
<div class="refnamediv">
<h1 class="refname">RarEntry::getStream</h1>
<p class="verinfo">(PECL rar >= 2.0.0)</p><p class="refpurpose"><span class="refname">RarEntry::getStream</span> — <span class="dc-title">Get file handler for entry</span></p>
</div>
<div class="refsect1 description" id="refsect1-rarentry.getstream-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">resource</span> <span class="methodname"><strong>RarEntry::getStream</strong></span>
([ <span class="methodparam"><span class="type">string</span> <code class="parameter">$password</code></span>
] )</div>
<p class="para rdfs-comment">
Returns a file handler that
supports read operations. This handler provides on-the-fly decompression
for this entry.
</p>
<p class="para">
The handler is not invalidated by calling
<span class="function"><a href="rararchive.close.html" class="function">rar_close()</a></span>.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="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.</p>
</div>
</div>
<div class="refsect1 parameters" id="refsect1-rarentry.getstream-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">password</code></em></span>
<dd>
<p class="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
<span class="function"><a href="rararchive.open.html" class="function">rar_open()</a></span>, if any, will be used. If a wrong password is given, either explicitly
or implicitly via <span class="function"><a href="rararchive.open.html" class="function">rar_open()</a></span>, this method's resulting stream will produce wrong
output. If no password is given and one is required, this method will fail and return <strong><code>FALSE</code></strong>.
You can check whether an entry is encrypted with <span class="methodname"><a href="rarentry.isencrypted.html" class="methodname">RarEntry::isEncrypted()</a></span>.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-rarentry.getstream-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
The file handler or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-rarentry.getstream-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>3.0.0</td>
<td>
Support for RAR archives with repeated entry names is no longer defective.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-rarentry.getstream-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-771">
<p><strong>Example #1 <span class="methodname"><strong>RarEntry::getStream()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$rar_file </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'example.rar'</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$rar_file </span><span style="color: #007700">=== </span><span style="color: #0000BB">false</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed to open Rar archive"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$entry </span><span style="color: #007700">= </span><span style="color: #0000BB">rar_entry_get</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">, </span><span style="color: #DD0000">'Dir/file.txt'</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$entry </span><span style="color: #007700">=== </span><span style="color: #0000BB">false</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed to find such entry"</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$stream </span><span style="color: #007700">= </span><span style="color: #0000BB">$entry</span><span style="color: #007700">-></span><span style="color: #0000BB">getStream</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$stream </span><span style="color: #007700">=== </span><span style="color: #0000BB">false</span><span style="color: #007700">)<br /> die(</span><span style="color: #DD0000">"Failed to obtain stream."</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">rar_close</span><span style="color: #007700">(</span><span style="color: #0000BB">$rar_file</span><span style="color: #007700">); </span><span style="color: #FF8000">//stream is independent from file<br /><br /></span><span style="color: #007700">while (!</span><span style="color: #0000BB">feof</span><span style="color: #007700">(</span><span style="color: #0000BB">$stream</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">$buff </span><span style="color: #007700">= </span><span style="color: #0000BB">fread</span><span style="color: #007700">(</span><span style="color: #0000BB">$stream</span><span style="color: #007700">, </span><span style="color: #0000BB">8192</span><span style="color: #007700">);<br /> if (</span><span style="color: #0000BB">$buff </span><span style="color: #007700">!== </span><span style="color: #0000BB">false</span><span style="color: #007700">)<br /> echo </span><span style="color: #0000BB">$buff</span><span style="color: #007700">;<br /> else<br /> break; </span><span style="color: #FF8000">//fread error<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #0000BB">fclose</span><span style="color: #007700">(</span><span style="color: #0000BB">$stream</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-rarentry.getstream-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="rarentry.extract.html" class="methodname" rel="rdfs-seeAlso">RarEntry::extract()</a> - Extract entry from the archive</span></li>
<li class="member"><a href="wrappers.rar.html" class="link"><em>rar://</em> wrapper</a></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="rarentry.getpackedsize.html">RarEntry::getPackedSize</a></div>
<div class="next" style="text-align: right; float: right;"><a href="rarentry.getunpackedsize.html">RarEntry::getUnpackedSize</a></div>
<div class="up"><a href="class.rarentry.html">RarEntry</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
