From d29e172cab4cce6dff2854b65e7c47de55f60dad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?= Date: Sat, 3 Jul 2010 08:19:20 +0000 Subject: [PATCH] - Added rarEntry::getPosition - Added rar:// wrapper documentation - Other improvements on the rar extension documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@300966 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/wrappers.xml | 265 ++++++++++++++++++ reference/rar/examples.xml | 4 + .../rar/functions/rar-wrapper-cache-stats.xml | 2 +- reference/rar/rararchive/close.xml | 2 +- reference/rar/rararchive/getcomment.xml | 2 +- reference/rar/rararchive/getentries.xml | 45 ++- reference/rar/rararchive/getentry.xml | 13 +- reference/rar/rararchive/issolid.xml | 2 +- reference/rar/rararchive/open.xml | 12 +- reference/rar/rararchive/tostring.xml | 2 +- reference/rar/rarentry/extract.xml | 9 +- reference/rar/rarentry/getattr.xml | 2 +- reference/rar/rarentry/getcrc.xml | 2 +- reference/rar/rarentry/getfiletime.xml | 2 +- reference/rar/rarentry/gethostos.xml | 2 +- reference/rar/rarentry/getmethod.xml | 2 +- reference/rar/rarentry/getname.xml | 2 +- reference/rar/rarentry/getpackedsize.xml | 2 +- reference/rar/rarentry/getstream.xml | 27 +- reference/rar/rarentry/getunpackedsize.xml | 2 +- reference/rar/rarentry/getversion.xml | 2 +- reference/rar/rarentry/isdirectory.xml | 2 +- reference/rar/rarentry/isencrypted.xml | 2 +- reference/rar/rarentry/tostring.xml | 2 +- .../rar/rarexception/isusingexceptions.xml | 2 +- .../rar/rarexception/setusingexceptions.xml | 2 +- 26 files changed, 389 insertions(+), 24 deletions(-) diff --git a/appendices/wrappers.xml b/appendices/wrappers.xml index 92167f0c86..ddd3135d32 100644 --- a/appendices/wrappers.xml +++ b/appendices/wrappers.xml @@ -1257,6 +1257,271 @@ $stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r'); + +
+ Rar + + rar:// + Available since PECL rar 3.0.0 + + + + rar://<url encoded archive name>[*][#[<url encoded entry name>]] + + + + This wrapper is not enabled by default + + In order to use the rar:// wrapper, you must install + the rar extension + available from PECL. + + + + + The wrapper takes the url encoded path to the RAR archive (relative or absolute), + an optional asterik (*), an optional number sign + (#) and an optional url encoded entry name, as stored in the + archive. Specifying an entry name requires the number sign; a leading forward + slash in the entry name is optional. + + + + This wrapper can open both files and directories. When opening directories, the + asterisk sign forces the directory entries names to be returned unencoded. If it's + not specified, they will be returned url encoded – the reason for this is to allow + the wrapper to be correctly used with built-in functionality like the + RecursiveDirectoryIterator in the presence of file names that seem like + url encoded data. + + + + If the pound sign and the entry name part are not included, the root of the archive + will be displayed. This differs from regular directories in that the resulting + stream will not contain information such as the modification time, as the root + directory is not stored in an inidivual entry in the archive. + The usage of the the wrapper with RecursiveDirectoryIterator requires + the number sign to be included in the URL when accessing the root, so that the + URLs of the children may be constructed correctly. + + + + + Traversing a RAR archive + +getSubPathName()) . + (is_dir(parent::current())?" [DIR]":""); + } +} + +$f = "rar://" . rawurlencode(dirname(__FILE__)) . + DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#'; + +$it = new RecursiveTreeIterator(new MyRecDirIt($f)); + +foreach ($it as $s) { + echo $s, "\n"; +} +?> +]]> + + &example.outputs.similar; + + + + + + + + Opening an encrypted file (header encryption) + + + array( + 'open_password' => 'samplepassword' + ) + ) + ) + ); +var_dump(stream_get_contents($stream)); +/* creation and last access date is opt-in in WinRAR, hence most + * files don't have them */ +var_dump(fstat($stream)); +?> +]]> + + &example.outputs.similar; + + 0 + [1] => 0 + [2] => 33206 + [3] => 1 + [4] => 0 + [5] => 0 + [6] => 0 + [7] => 26 + [8] => 0 + [9] => 1259550052 + [10] => 0 + [11] => -1 + [12] => -1 + [dev] => 0 + [ino] => 0 + [mode] => 33206 + [nlink] => 1 + [uid] => 0 + [gid] => 0 + [rdev] => 0 + [size] => 26 + [atime] => 0 + [mtime] => 1259550052 + [ctime] => 0 + [blksize] => -1 + [blocks] => -1 +) +]]> + + + + + + + Wrapper Summary + + + + Attribute + Supported + + + + + Restricted by allow_url_fopen + No + + + Restricted by allow_url_include + No + + + Allows Reading + Yes + + + Allows Writing + No + + + Allows Appending + No + + + Allows Simultaneous Reading and Writing + No + + + Supports stat + Yes + + + Supports unlink + No + + + Supports rename + No + + + Supports mkdir + No + + + Supports rmdir + No + + + +
+ + + + + Context options + + + + Name + Usage + Default + + + + + open_password + The password used to encrypt the headers of the archive, + if any. WinRAR will encrypt all the files with the same password + as the headers password when the later is present, so for archives + with encrypted headers, file_password will be + ignored. + + + + + file_password + The password used to encrypt a file, if any. If the headers + are also encrypted, this option will be ignored in favor of + open_password. The reason there are two options + is to cover the possibility of supporting archives with different + headers and file passwords, should those archives arise. Note that + if the archive does not have its headers encrypted, + open_password will be ignored and this option + must be used instead. + + + + + volume_callback + A callback to determine the path of missing volumes. See + RarArchive::open for more information. + + + + + +
+ + +
+
Audio Streams diff --git a/reference/rar/examples.xml b/reference/rar/examples.xml index 977b310f5f..58981ee455 100644 --- a/reference/rar/examples.xml +++ b/reference/rar/examples.xml @@ -4,6 +4,10 @@ &reftitle.examples; + + See also the examples under rar:// wrapper. + + On-the-fly decompression diff --git a/reference/rar/functions/rar-wrapper-cache-stats.xml b/reference/rar/functions/rar-wrapper-cache-stats.xml index 7be4e13a12..a6d5c5384e 100644 --- a/reference/rar/functions/rar-wrapper-cache-stats.xml +++ b/reference/rar/functions/rar-wrapper-cache-stats.xml @@ -4,7 +4,7 @@ rar_wrapper_cache_stats - Cache hits and misses for the URL wrapper. + Cache hits and misses for the URL wrapper diff --git a/reference/rar/rararchive/close.xml b/reference/rar/rararchive/close.xml index 79d121af8e..776d74ca35 100644 --- a/reference/rar/rararchive/close.xml +++ b/reference/rar/rararchive/close.xml @@ -5,7 +5,7 @@ RarArchive::close rar_close - Close RAR archive and free all resources. + Close RAR archive and free all resources diff --git a/reference/rar/rararchive/getcomment.xml b/reference/rar/rararchive/getcomment.xml index 6c9bf5940d..e9db28cfa7 100644 --- a/reference/rar/rararchive/getcomment.xml +++ b/reference/rar/rararchive/getcomment.xml @@ -5,7 +5,7 @@ RarArchive::getComment rar_comment_get - Get comment text from the RAR archive. + Get comment text from the RAR archive diff --git a/reference/rar/rararchive/getentries.xml b/reference/rar/rararchive/getentries.xml index 6d2a2f204c..3ab2679d22 100644 --- a/reference/rar/rararchive/getentries.xml +++ b/reference/rar/rararchive/getentries.xml @@ -5,7 +5,7 @@ RarArchive::getEntries rar_list - Get full list of entries from the RAR archive. + Get full list of entries from the RAR archive @@ -23,6 +23,16 @@ Get entries list (files and directories) from the RAR archive. + + + If the archive has + entries with the same name, this method, together with RarArchive + foreach iteration and array-like access with numeric indexes, + are the only ones to access all the entries (i.e., + RarArchive::getEntry and the + rar:// wrapper are insufficient). + + @@ -48,6 +58,30 @@ &return.falseforfailure;. + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 3.0.0 + + Support for RAR archives with repeated entry names is no longer defective. + + + + + + + &reftitle.examples; @@ -113,6 +147,15 @@ rar_close($rar_arch); + + &reftitle.seealso; + + + RarArchive::getEntry + rar:// wrapper + + + diff --git a/reference/rar/rararchive/getentry.xml b/reference/rar/rararchive/getentry.xml index 33783a156b..305773eaab 100644 --- a/reference/rar/rararchive/getentry.xml +++ b/reference/rar/rararchive/getentry.xml @@ -5,7 +5,7 @@ RarArchive::getEntry rar_entry_get - Get entry object from the RAR archive. + Get entry object from the RAR archive @@ -26,6 +26,8 @@ You can also get entry objects using RarArchive::getEntries. + Note that a RAR archive can have multiple entries with the same name; this method + will retrieve only the first. @@ -115,6 +117,15 @@ rar_close($rar_arch); + + &reftitle.seealso; + + + RarArchive::getEntries + rar:// wrapper + + + diff --git a/reference/rar/rararchive/issolid.xml b/reference/rar/rararchive/issolid.xml index f4b6667158..84fec5c69c 100644 --- a/reference/rar/rararchive/issolid.xml +++ b/reference/rar/rararchive/issolid.xml @@ -5,7 +5,7 @@ RarArchive::isSolid rar_solid_is - Check whether the RAR archive is solid. + Check whether the RAR archive is solid diff --git a/reference/rar/rararchive/open.xml b/reference/rar/rararchive/open.xml index 31d1462b4c..fe95a7ce4b 100644 --- a/reference/rar/rararchive/open.xml +++ b/reference/rar/rararchive/open.xml @@ -5,7 +5,7 @@ RarArchive::open rar_open - Open RAR archive. + Open RAR archive @@ -208,11 +208,21 @@ function resolve($vol) { $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"); +?> ]]> + + + &reftitle.seealso; + + + rar:// wrapper + + + diff --git a/reference/rar/rararchive/tostring.xml b/reference/rar/rararchive/tostring.xml index a40861195a..bc92634c59 100644 --- a/reference/rar/rararchive/tostring.xml +++ b/reference/rar/rararchive/tostring.xml @@ -4,7 +4,7 @@ RarArchive::__toString - Get text representation. + Get text representation diff --git a/reference/rar/rarentry/extract.xml b/reference/rar/rarentry/extract.xml index e1a393df9c..2a4af6f464 100644 --- a/reference/rar/rarentry/extract.xml +++ b/reference/rar/rarentry/extract.xml @@ -3,7 +3,7 @@ RarEntry::extract - Extract entry from the archive. + Extract entry from the archive @@ -106,6 +106,12 @@ extended_data was added. + + 3.0.0 + + Support for RAR archives with repeated entry names is no longer defective. + + @@ -163,6 +169,7 @@ rar_close($rar_file); RarEntry::getStream + rar:// wrapper diff --git a/reference/rar/rarentry/getattr.xml b/reference/rar/rarentry/getattr.xml index 222cb51927..35f2e1caeb 100644 --- a/reference/rar/rarentry/getattr.xml +++ b/reference/rar/rarentry/getattr.xml @@ -3,7 +3,7 @@ RarEntry::getAttr - Get attributes of the entry. + Get attributes of the entry diff --git a/reference/rar/rarentry/getcrc.xml b/reference/rar/rarentry/getcrc.xml index b9a2344b90..3b4c4b44be 100644 --- a/reference/rar/rarentry/getcrc.xml +++ b/reference/rar/rarentry/getcrc.xml @@ -4,7 +4,7 @@ RarEntry::getCrc - Get CRC of the entry. + Get CRC of the entry diff --git a/reference/rar/rarentry/getfiletime.xml b/reference/rar/rarentry/getfiletime.xml index d0b4c00369..ceb0977c88 100644 --- a/reference/rar/rarentry/getfiletime.xml +++ b/reference/rar/rarentry/getfiletime.xml @@ -4,7 +4,7 @@ RarEntry::getFileTime - Get entry last modification time. + Get entry last modification time diff --git a/reference/rar/rarentry/gethostos.xml b/reference/rar/rarentry/gethostos.xml index a24eac5405..940a607e5e 100644 --- a/reference/rar/rarentry/gethostos.xml +++ b/reference/rar/rarentry/gethostos.xml @@ -4,7 +4,7 @@ RarEntry::getHostOs - Get entry host OS. + Get entry host OS diff --git a/reference/rar/rarentry/getmethod.xml b/reference/rar/rarentry/getmethod.xml index 9d2e3bb16a..ad3099b5e1 100644 --- a/reference/rar/rarentry/getmethod.xml +++ b/reference/rar/rarentry/getmethod.xml @@ -4,7 +4,7 @@ RarEntry::getMethod - Get pack method of the entry. + Get pack method of the entry diff --git a/reference/rar/rarentry/getname.xml b/reference/rar/rarentry/getname.xml index b20a67f160..ed4b4db6d5 100644 --- a/reference/rar/rarentry/getname.xml +++ b/reference/rar/rarentry/getname.xml @@ -4,7 +4,7 @@ RarEntry::getName - Get name of the entry. + Get name of the entry diff --git a/reference/rar/rarentry/getpackedsize.xml b/reference/rar/rarentry/getpackedsize.xml index 244cc64e81..bb5aff50b0 100644 --- a/reference/rar/rarentry/getpackedsize.xml +++ b/reference/rar/rarentry/getpackedsize.xml @@ -4,7 +4,7 @@ RarEntry::getPackedSize - Get packed size of the entry. + Get packed size of the entry diff --git a/reference/rar/rarentry/getstream.xml b/reference/rar/rarentry/getstream.xml index 12346d6ea3..3a3645e706 100644 --- a/reference/rar/rarentry/getstream.xml +++ b/reference/rar/rarentry/getstream.xml @@ -4,7 +4,7 @@ RarEntry::getStream - Get file handler for entry. + Get file handler for entry @@ -57,6 +57,30 @@ + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 3.0.0 + + Support for RAR archives with repeated entry names is no longer defective. + + + + + + + + &reftitle.examples; @@ -102,6 +126,7 @@ fclose($stream); RarEntry::extract + rar:// wrapper diff --git a/reference/rar/rarentry/getunpackedsize.xml b/reference/rar/rarentry/getunpackedsize.xml index b45ab1f3e5..9d7c410669 100644 --- a/reference/rar/rarentry/getunpackedsize.xml +++ b/reference/rar/rarentry/getunpackedsize.xml @@ -4,7 +4,7 @@ RarEntry::getUnpackedSize - Get unpacked size of the entry. + Get unpacked size of the entry diff --git a/reference/rar/rarentry/getversion.xml b/reference/rar/rarentry/getversion.xml index a1454c6747..5e6069c0cb 100644 --- a/reference/rar/rarentry/getversion.xml +++ b/reference/rar/rarentry/getversion.xml @@ -4,7 +4,7 @@ RarEntry::getVersion - Get minimum version of RAR program required to unpack the entry. + Get minimum version of RAR program required to unpack the entry diff --git a/reference/rar/rarentry/isdirectory.xml b/reference/rar/rarentry/isdirectory.xml index 594329e181..015b56b21e 100644 --- a/reference/rar/rarentry/isdirectory.xml +++ b/reference/rar/rarentry/isdirectory.xml @@ -4,7 +4,7 @@ RarEntry::isDirectory - Test whether an entry represents a directory. + Test whether an entry represents a directory diff --git a/reference/rar/rarentry/isencrypted.xml b/reference/rar/rarentry/isencrypted.xml index 581cb3e16a..4f7172a915 100644 --- a/reference/rar/rarentry/isencrypted.xml +++ b/reference/rar/rarentry/isencrypted.xml @@ -4,7 +4,7 @@ RarEntry::isEncrypted - Test whether an entry is encrypted. + Test whether an entry is encrypted diff --git a/reference/rar/rarentry/tostring.xml b/reference/rar/rarentry/tostring.xml index 28782a16c8..e25f18c8ce 100644 --- a/reference/rar/rarentry/tostring.xml +++ b/reference/rar/rarentry/tostring.xml @@ -4,7 +4,7 @@ RarEntry::__toString - Get text representation of entry. + Get text representation of entry diff --git a/reference/rar/rarexception/isusingexceptions.xml b/reference/rar/rarexception/isusingexceptions.xml index f0c065a662..da2bfeea12 100644 --- a/reference/rar/rarexception/isusingexceptions.xml +++ b/reference/rar/rarexception/isusingexceptions.xml @@ -4,7 +4,7 @@ RarException::isUsingExceptions - Check whether error handling with exceptions is in use. + Check whether error handling with exceptions is in use diff --git a/reference/rar/rarexception/setusingexceptions.xml b/reference/rar/rarexception/setusingexceptions.xml index 08b7bec305..adfd9b00da 100644 --- a/reference/rar/rarexception/setusingexceptions.xml +++ b/reference/rar/rarexception/setusingexceptions.xml @@ -4,7 +4,7 @@ RarException::setUsingExceptions - Activate and deactivate error handling with exceptions. + Activate and deactivate error handling with exceptions