From 97d94b3c09a83c4471dc33eb129dc7945f48d6dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustavo=20Andr=C3=A9=20dos=20Santos=20Lopes?= Date: Fri, 20 Nov 2009 17:07:32 +0000 Subject: [PATCH] Updated PECL rar documentation for version 2.0.0. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@291095 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/rar/book.xml | 3 +- reference/rar/functions/rar-comment-get.xml | 71 +++++++++++++++ reference/rar/functions/rar-entry-get.xml | 10 ++- reference/rar/functions/rar-list.xml | 3 +- reference/rar/functions/rar-open.xml | 6 +- reference/rar/rarentry.xml | 70 +++++++++++++++ .../rar-extract.xml => rarentry/extract.xml} | 25 ++++-- .../rar-getattr.xml => rarentry/getattr.xml} | 12 +-- .../rar-getcrc.xml => rarentry/getcrc.xml} | 32 ++++++- .../getfiletime.xml} | 6 +- .../gethostos.xml} | 10 +-- .../getmethod.xml} | 10 +-- .../rar-getname.xml => rarentry/getname.xml} | 23 +++-- .../getpackedsize.xml} | 39 +++++++- reference/rar/rarentry/getstream.xml | 89 +++++++++++++++++++ .../getunpackedsize.xml} | 41 +++++++-- .../getversion.xml} | 8 +- reference/rar/versions.xml | 24 ++--- 18 files changed, 416 insertions(+), 66 deletions(-) create mode 100644 reference/rar/functions/rar-comment-get.xml create mode 100644 reference/rar/rarentry.xml rename reference/rar/{functions/rar-extract.xml => rarentry/extract.xml} (73%) rename reference/rar/{functions/rar-getattr.xml => rarentry/getattr.xml} (88%) rename reference/rar/{functions/rar-getcrc.xml => rarentry/getcrc.xml} (57%) rename reference/rar/{functions/rar-getfiletime.xml => rarentry/getfiletime.xml} (85%) rename reference/rar/{functions/rar-gethostos.xml => rarentry/gethostos.xml} (84%) rename reference/rar/{functions/rar-getmethod.xml => rarentry/getmethod.xml} (80%) rename reference/rar/{functions/rar-getname.xml => rarentry/getname.xml} (74%) rename reference/rar/{functions/rar-getpackedsize.xml => rarentry/getpackedsize.xml} (58%) create mode 100644 reference/rar/rarentry/getstream.xml rename reference/rar/{functions/rar-getunpackedsize.xml => rarentry/getunpackedsize.xml} (57%) rename reference/rar/{functions/rar-getversion.xml => rarentry/getversion.xml} (85%) diff --git a/reference/rar/book.xml b/reference/rar/book.xml index b6f3a1fd51..662b700d5d 100644 --- a/reference/rar/book.xml +++ b/reference/rar/book.xml @@ -14,7 +14,7 @@ Rar is a powerful and effective archiver created by Eugene Roshal. This extension gives you possibility to read Rar archives but doesn't support writing Rar archives, because this is not supported - by UnRar library and is directly prohibited by it's license. + by the UnRar library and is directly prohibited by its license. More information about Rar and UnRar can be found at &reference.rar.reference; diff --git a/reference/rar/functions/rar-comment-get.xml b/reference/rar/functions/rar-comment-get.xml new file mode 100644 index 0000000000..f00accf447 --- /dev/null +++ b/reference/rar/functions/rar-comment-get.xml @@ -0,0 +1,71 @@ + + + + + rar_comment_get + Get comment text from the Rar archive + + + + &reftitle.description; + + RarEntryrar_comment_get + resourcerar_file + + + Get the comment stored in the Rar archive. It may be up to 64 KiB long. + + + + + &reftitle.parameters; + + + + rar_file + + + A Rar file resource, opened with rar_open. + + + + + + + + + &reftitle.returnvalues; + + Returns the comment or &null; if there is none. + + + + Rar has currently no support for unicode comments. The encoding of the + result of this function is not specified, but it will probably be + Windows-1252. + + + + + + + diff --git a/reference/rar/functions/rar-entry-get.xml b/reference/rar/functions/rar-entry-get.xml index 9a980b9d74..8c1538e396 100644 --- a/reference/rar/functions/rar-entry-get.xml +++ b/reference/rar/functions/rar-entry-get.xml @@ -36,16 +36,24 @@ Path to the entry within the Rar archive. + + The path must be the same returned by + RarEntry::getName. + + + You can also get entry objects using + rar_list. + &reftitle.returnvalues; - rar_entry_get returns entry object or &false; on error. + rar_entry_get returns entry object &return.falseforfailure;. diff --git a/reference/rar/functions/rar-list.xml b/reference/rar/functions/rar-list.xml index 99e01cb294..ae170d463f 100644 --- a/reference/rar/functions/rar-list.xml +++ b/reference/rar/functions/rar-list.xml @@ -36,7 +36,8 @@ &reftitle.returnvalues; - rar_list returns array of entries or &false; on error. + rar_list returns array of RarEntry objects + &return.falseforfailure;. diff --git a/reference/rar/functions/rar-open.xml b/reference/rar/functions/rar-open.xml index 0b93915e7c..a9aa471bb7 100644 --- a/reference/rar/functions/rar-open.xml +++ b/reference/rar/functions/rar-open.xml @@ -40,12 +40,16 @@ + + Prior to version 2.0.0, this function would not handle relative + paths correctly. Use realpath as a word-around. + &reftitle.returnvalues; - rar_open returns Rar file resource or &false; on error. + rar_open returns Rar file resource &return.falseforfailure;. diff --git a/reference/rar/rarentry.xml b/reference/rar/rarentry.xml new file mode 100644 index 0000000000..748baee44e --- /dev/null +++ b/reference/rar/rarentry.xml @@ -0,0 +1,70 @@ + + + + The <classname>RarEntry</classname> class + RarEntry + + + + +
+ &reftitle.intro; + + A Rar entry, representing a compressed file inside a Rar archive. + +
+ + +
+ &reftitle.classsynopsis; + + + + RarEntry + + + + + RarEntry + + + + Properties + + + Methods + + + + + +
+ +
+ + + &reference.rar.entities.rarentry; + +
+ + + diff --git a/reference/rar/functions/rar-extract.xml b/reference/rar/rarentry/extract.xml similarity index 73% rename from reference/rar/functions/rar-extract.xml rename to reference/rar/rarentry/extract.xml index 7375c7feac..74c12b7ee8 100644 --- a/reference/rar/functions/rar-extract.xml +++ b/reference/rar/rarentry/extract.xml @@ -1,15 +1,15 @@ - + - Rar::extract + RarEntry::extract Extract entry from the archive &reftitle.description; - Rar + RarEntry boolextract stringdir @@ -17,7 +17,7 @@ - Rar::extract extracts entry's data to the + RarEntry::extract extracts entry's data to the dir. It will create new file in the specified dir with the name identical to the entry's name. @@ -31,7 +31,10 @@ dir - Path to the directory where files should be extracted. + Path to the directory where files should be extracted. This parameter is + considered if and only if filepath is not. If both + parameters are empty an extraction to the current directory will be + attempted. @@ -39,14 +42,18 @@ filepath - If parameter filepath is specified instead - dir, Rar::extract will extract - entry's data to the specified file. + Path (relative or absolute) containing the directory and filename of the + extracted file. This parameter overrides both the parameter + dir and the original file name. + + Prior to version 2.0.0, this function would not handle relative + paths correctly. Use realpath as a word-around. + @@ -60,7 +67,7 @@ &reftitle.examples; - <function>Rar::extract</function> example + <function>RarEntry::extract</function> example - + - Rar::getAttr + RarEntry::getAttr Get attributes of the entry &reftitle.description; - Rar + RarEntry intgetAttr - Rar::getAttr returns attributes of the archive + RarEntry::getAttr returns attributes of the archive entry. @@ -32,7 +32,7 @@ &reftitle.examples; - <function>Rar::getAttr</function> example + <function>RarEntry::getAttr</function> example - + diff --git a/reference/rar/functions/rar-getcrc.xml b/reference/rar/rarentry/getcrc.xml similarity index 57% rename from reference/rar/functions/rar-getcrc.xml rename to reference/rar/rarentry/getcrc.xml index ba09e18332..44a644ed23 100644 --- a/reference/rar/functions/rar-getcrc.xml +++ b/reference/rar/rarentry/getcrc.xml @@ -1,22 +1,22 @@ - + - Rar::getCrc + RarEntry::getCrc Get CRC of the entry &reftitle.description; - Rar + RarEntry intgetCrc - Rar::getCrc returns CRC of the archive entry. + RarEntry::getCrc returns CRC of the archive entry. @@ -27,6 +27,30 @@ + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 2.0.0 + + This method now returns correct values for multiple volume archives. + + + + + + + + - + - Rar::getFileTime + RarEntry::getFileTime Get entry last modification time &reftitle.description; - Rar + RarEntry stringgetFileTime diff --git a/reference/rar/functions/rar-gethostos.xml b/reference/rar/rarentry/gethostos.xml similarity index 84% rename from reference/rar/functions/rar-gethostos.xml rename to reference/rar/rarentry/gethostos.xml index 2c0c06441a..95b366b2cc 100644 --- a/reference/rar/functions/rar-gethostos.xml +++ b/reference/rar/rarentry/gethostos.xml @@ -1,22 +1,22 @@ - + - Rar::getHostOs + RarEntry::getHostOs Get entry host OS &reftitle.description; - Rar + RarEntry intgetHostOs - Rar::getHostOs return code of the host OS of the + RarEntry::getHostOs return code of the host OS of the archive entry. @@ -32,7 +32,7 @@ &reftitle.examples; - <function>Rar::getHostOs</function> example + <function>RarEntry::getHostOs</function> example - + - Rar::getMethod + RarEntry::getMethod Get pack method of the entry &reftitle.description; - Rar + RarEntry intgetMethod - Rar::getMethod returns number of the method used when adding + RarEntry::getMethod returns number of the method used when adding current archive entry. @@ -32,7 +32,7 @@ &reftitle.examples; - <function>Rar::getMethod</function> example + <function>RarEntry::getMethod</function> example - + - Rar::getName + RarEntry::getName Get name of the entry &reftitle.description; - Rar + RarEntry stringgetName - Rar::getName returns full name of the archive entry. + RarEntry::getName returns full name of the archive entry. @@ -55,16 +55,27 @@ &reftitle.examples; - <function>Rar::getName</function> example + <function>RarEntry::getName</function> example getName(); +echo "Entry name: " . mb_convert_encoding( + htmlentities( + $entry->getName(), + ENT_COMPAT, + "UTF-8" + ), + "HTML-ENTITIES", + "UTF-8" +); ?> ]]> diff --git a/reference/rar/functions/rar-getpackedsize.xml b/reference/rar/rarentry/getpackedsize.xml similarity index 58% rename from reference/rar/functions/rar-getpackedsize.xml rename to reference/rar/rarentry/getpackedsize.xml index 8c03216131..a1fef56e62 100644 --- a/reference/rar/functions/rar-getpackedsize.xml +++ b/reference/rar/rarentry/getpackedsize.xml @@ -1,15 +1,15 @@ - + - Rar::getPackedSize + RarEntry::getPackedSize Get packed size of the entry &reftitle.description; - Rar + RarEntry intgetPackedSize @@ -18,6 +18,11 @@ Get packed size of the archive entry. + + Note that on platforms with 32-bit longs (that includes Windows + x64), the maximum size returned is capped at 2 GiB. Check the constant + PHP_INT_MAX. + @@ -27,11 +32,37 @@ + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 2.0.0 + + This method now returns correct values of packed sizes bigger than 2 GiB + on platforms with 64-bit integers and never + returns negative values on other platforms. + + + + + + + + &reftitle.examples; - <function>Rar::getPackedSize</function> example + <function>RarEntry::getPackedSize</function> example + + + + RarEntry::getStream + Get file handler for entry. + + + + &reftitle.description; + + RarEntry + + stringgetStream + + + + + RarEntry::getStream returns a file handler that + supports read operations. This handler provides on-the-fly decompression + for this entry. + + + + + &reftitle.returnvalues; + + The file handler &return.falseforfailure;. + + + + + &reftitle.examples; + + + <function>RarEntry::getStream</function> example + +getStream(); +if ($stream === false) + die("Failed to obtain stream."); + +while (!feof($stream)) { + $buff = fread($stream, 8192); + if ($buff !== false) + echo $buff; + else + break; //fread error +} + +?> +]]> + + + + + + + + diff --git a/reference/rar/functions/rar-getunpackedsize.xml b/reference/rar/rarentry/getunpackedsize.xml similarity index 57% rename from reference/rar/functions/rar-getunpackedsize.xml rename to reference/rar/rarentry/getunpackedsize.xml index 06ec930888..07532cadfc 100644 --- a/reference/rar/functions/rar-getunpackedsize.xml +++ b/reference/rar/rarentry/getunpackedsize.xml @@ -1,15 +1,15 @@ - + - Rar::getUnpackedSize + RarEntry::getUnpackedSize Get unpacked size of the entry &reftitle.description; - Rar + RarEntry intgetUnpackedSize @@ -18,6 +18,11 @@ Get unpacked size of the archive entry. + + Note that on platforms with 32-bit longs (that includes Windows + x64), the maximum size returned is capped at 2 GiB. Check the constant + PHP_INT_MAX. + @@ -27,11 +32,37 @@ - + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 2.0.0 + + This method now returns correct values of unpacked sizes bigger than + 2 GiB on platforms with 64-bit integers and never + returns negative values on other platforms. + + + + + + + + + &reftitle.returnvalues; - <function>Rar::getUnpackedSize</function> example + <function>RarEntry::getUnpackedSize</function> example - + - Rar::getVersion + RarEntry::getVersion Get version of the archiver used to add the entry &reftitle.description; - Rar + RarEntry intgetVersion @@ -31,7 +31,7 @@ &reftitle.examples; - <function>Rar::getVersion</function> example + <function>RarEntry::getVersion</function> example - - - - - - - - - - - + + + + + + + + + + + + +