Fixed sending of charset converted streams;

Regenerated Doxygen settings from the latest release;
Doc and CS fixes (notably: Short descriptions of properties instead of "var" descriptions).

Author: boenrobot

RELEASE-1.0.0b6

@@ -15,6 +15,7 @@ Util stuff, mostly.
 * Script::parseValue() now recognizes dates in the "M/d/Y H:i:s" format (used across RouterOS), and turns that into a DateTime object for that time (or midnight in UTC if the time part is omitted).
 * Util::getAll() now throws a NotSupportedException if the arguments "follow", "follow-only" or "count-only" are used. The first two, because PHP would hang (since Client::sendSync() is used under the hood), and the last one because it's unredable in the returned output (use Util::count() instead).
 * Util::setMenu() can now go back to the root menu.
+* Util::exec() and stream valued arguments in both Util and Client no longer cause a hang when using charset conversion.
 * Util::get() can now accept a query as an argument for $number
 * Util::get() can have $valueName set to NULL (as is now by default), in which case all properties are retrieved in an array, parsed with Script::parseValueToArray().
 * Util::get() no longer fallbacks automatically with a "print" request for buggy versions. You may "manually" call Util::getAll() if you suspect that's an issue.

docs/doxygen.ini

@@ -64,38 +64,52 @@ class Client
     const FILTER_ALL = 3;
 
     /**
-     * @var Communicator The communicator for this client.
+     * The communicator for this client.
+     *
+     * @var Communicator
      */
     protected $com;
 
     /**
-     * @var int The number of currently pending requests.
+     * The number of currently pending requests.
+     *
+     * @var int
      */
     protected $pendingRequestsCount = 0;
 
     /**
-     * @var array<string,Response[]> An array of responses that have not yet
-     *     been extracted or passed to a callback.
-     *     Key is the tag of the request, and the value is an array of
-     *     associated responses.
+     * An array of responses that have not yet been extracted
+     * or passed to a callback.
+     *
+     * Key is the tag of the request, and the value is an array of
+     * associated responses.
+     *
+     * @var array<string,Response[]>
      */
     protected $responseBuffer = array();
 
     /**
-     * @var array<string,callback> An array of callbacks to be executed
-     *     as responses come.
-     *     Key is the tag of the request, and the value is the callback for it.
+     * An array of callbacks to be executed as responses come.
+     *
+     * Key is the tag of the request, and the value is the callback for it.
+     *
+     * @var array<string,callback>
      */
     protected $callbacks = array();
 
     /**
-     * @var Registry A registry for the operations. Particularly helpful at
-     *     persistent connections.
+     * A registry for the operations.
+     *
+     * Particularly helpful at persistent connections.
+     *
+     * @var Registry
      */
     protected $registry = null;
 
     /**
-     * @var bool Whether to stream future responses.
+     * Whether to stream future responses.
+     *
+     * @var bool
      */
     private $_streamingResponses = false;
 
@@ -836,7 +850,8 @@ protected function dispatchNextResponse($sTimeout = 0, $usTimeout = 0)
                     try {
                         $this->cancelRequest($tag);
                     } catch (DataFlowException $e) {
-                        if ($e->getCode() !== DataFlowException::CODE_UNKNOWN_REQUEST) {
+                        if ($e->getCode() !== DataFlowException::CODE_UNKNOWN_REQUEST
+                        ) {
                             throw $e;
                         }
                     }

src/PEAR2/Net/RouterOS/Client.php

@@ -67,24 +67,30 @@ class Communicator
     const CHARSET_LOCAL = 1;
 
     /**
-     * @var array<string,string|null> An array with
-     *     the default charset types as keys, and
-     *     the default charsets as values.
+     * An array with the default charset.
+     *
+     * Charset types as keys, and the default charsets as values.
+     *
+     * @var array<string,string|null>
      */
     protected static $defaultCharsets = array(
         self::CHARSET_REMOTE => null,
         self::CHARSET_LOCAL  => null
     );
 
     /**
-     * @var array<string,string|null> An array with
-     *     the current charset types as keys, and
-     *     the current charsets as values.
+     * An array with the current charset.
+     *
+     * Charset types as keys, and the current charsets as values.
+     *
+     * @var array<string,string|null>
      */
     protected $charsets = array();
 
     /**
-     * @var T\TcpClient The transmitter for the connection.
+     * The transmitter for the connection.
+     *
+     * @var T\TcpClient
      */
     protected $trans;
 
@@ -230,8 +236,11 @@ public static function iconvStream($inCharset, $outCharset, $stream)
         );
 
         flock($stream, LOCK_SH);
-        while (!feof($stream)) {
-            $bytes += stream_copy_to_stream($stream, $result, 0xFFFFF);
+        $reader = new T\Stream($stream, false);
+        $writer = new T\Stream($result, false);
+        $chunkSize = $reader->getChunk(T\Stream::DIRECTION_RECEIVE);
+        while ($reader->isAvailable() && $reader->isDataAwaiting()) {
+            $bytes += $writer->send(fread($stream, $chunkSize));
         }
         fseek($stream, -$bytes, SEEK_CUR);
         flock($stream, LOCK_UN);

src/PEAR2/Net/RouterOS/Communicator.php

@@ -47,7 +47,9 @@ class LengthException extends L implements Exception
     const CODE_BEYOND_SHEME = 1301;
 
     /**
-     * @var int|double|null The problematic length.
+     * The problematic length.
+     *
+     * @var int|double|null
      */
     private $_length;
 

src/PEAR2/Net/RouterOS/LengthException.php

@@ -48,14 +48,19 @@ abstract class Message implements IteratorAggregate, Countable
 {
 
     /**
-     * @var array<string,string|resource> An array with message attributes.
-     *     Each array key is the the name of an attribute,
-     *     and the corresponding array value is the value for that attribute.
+     * An array with message attributes.
+     *
+     * Each array key is the the name of an attribute,
+     * and the corresponding array value is the value for that attribute.
+     *
+     * @var array<string,string|resource>
      */
     protected $attributes = array();
 
     /**
-     * @var string An optional tag to associate the message with.
+     * An optional tag to associate the message with.
+     *
+     * @var string
      */
     private $_tag = null;
 

src/PEAR2/Net/RouterOS/Message.php

@@ -45,7 +45,9 @@ class NotSupportedException extends E implements Exception
     const CODE_ARG_PROHIBITED = 60001;
 
     /**
-     * @var mixed The unsupported value.
+     * The unsupported value.
+     *
+     * @var mixed
      */
     private $_value;
 

src/PEAR2/Net/RouterOS/NotSupportedException.php

@@ -63,10 +63,13 @@ class Query
     const OP_GT = '>';
 
     /**
-     * @var array<string,string|null>[] An array of the words forming the query.
-     *     Each value is an array with the first member being the predicate
-     *     (operator and name), and the second member being the value
-     *     for the predicate.
+     * An array of the words forming the query.
+     *
+     * Each value is an array with the first member being the predicate
+     * (operator and name), and the second member being the value
+     * for the predicate.
+     *
+     * @var array<string,string|null>[]
      */
     protected $words = array();
 
@@ -242,14 +245,14 @@ private function _send(Communicator $com)
 
     /**
      * Verifies the query.
-     * 
+     *
      * Verifies the query against a communicator, i.e. whether the query
      * could successfully be sent (assuming the connection is still opened).
-     * 
+     *
      * @param Communicator $com The Communicator to check against.
-     * 
+     *
      * @return $this The query object itself.
-     * 
+     *
      * @throws LengthException If the resulting length of an API word is not
      *     supported.
      */

src/PEAR2/Net/RouterOS/Query.php

@@ -42,22 +42,30 @@
 class Registry
 {
     /**
-     * @var SHM The storage.
+     * The storage.
+     *
+     * @var SHM
      */
     protected $shm;
 
     /**
-     * @var int ID of request. Populated at first instance in request.
+     * ID of request. Populated at first instance in request.
+     *
+     * @var int
      */
     protected static $requestId = -1;
 
     /**
-     * @var int ID to be given to next instance, after incrementing it.
+     * ID to be given to next instance, after incrementing it.
+     *
+     * @var int
      */
     protected static $instanceIdSeed = -1;
 
     /**
-     * @var int ID of instance within the request.
+     * ID of instance within the request.
+     *
+     * @var int
      */
     protected $instanceId;
 

src/PEAR2/Net/RouterOS/Registry.php

@@ -38,12 +38,16 @@ class Request extends Message
 {
 
     /**
-     * @var string The command to be executed.
+     * The command to be executed.
+     *
+     * @var string
      */
     private $_command;
 
     /**
-     * @var Query A query for the command.
+     * A query for the command.
+     *
+     * @var Query
      */
     private $_query;
 
@@ -341,14 +345,14 @@ private function _send(Communicator $com)
 
     /**
      * Verifies the request.
-     * 
+     *
      * Verifies the request against a communicator, i.e. whether the request
      * could successfully be sent (assuming the connection is still opened).
-     * 
+     *
      * @param Communicator $com The Communicator to check against.
-     * 
+     *
      * @return $this The request object itself.
-     * 
+     *
      * @throws LengthException If the resulting length of an API word is not
      *     supported.
      */