application/hub/main/class_HubCommandProcessor.php

   1 <?php
   2 /**
   3  * A class for handling commands to and from hubs including the master hub
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0
   7  * @copyright   Copyright(c) 2007, 2008 Roland Haeder, this is free software
   8  * @license             GNU GPL 3.0 or any newer version
   9  *
  10  * This program is free software: you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation, either version 3 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  22  */
  23 class HubCommandProcessor extends BaseFrameworkSystem {
  24         /**
  25          * An instance of a HubPeer class
  26          */
  27         private $peerInstance = null;
  28
  29         /**
  30          * A list of sent commands but not replied (yet)
  31          */
  32         private $sentCommandsAwaitingAnswer = array();
  33
  34         /**
  35          * Queued commands from the master hub
  36          */
  37         private $masterCommands = array();
  38
  39         // Exceptions
  40         const EXCEPTION_COMMAND_AWAIT_INVALID   = 0xc00;
  41
  42         /**
  43          * The private constructor
  44          *
  45          * @return      void
  46          */
  47         protected function __construct () {
  48                 // Call parent constructor
  49                 parent::__construct(__CLASS__);
  50
  51                 // Set description
  52                 $this->setObjectDescription("Hub-Command-Processor");
  53
  54                 // Set unique ID
  55                 $this->createUniqueID();
  56
  57                 // Tidy up a little
  58                 $this->removeSystemArray();
  59                 $this->removeNumberFormaters();
  60         }
  61
  62         /**
  63          * Creates an instance of a HubCommandProcessor class by a HubPeer class
  64          *
  65          * @param               $peerInstance           An instance of a HubPeer class
  66          * @return      $command                        An instance of this class
  67          */
  68         public final static function createHubCommandProcessor (HubPeer $peerInstance) {
  69                 // Get a new instance of this class
  70                 $command = new HubCommandProcessor();
  71
  72                 // Set the hub instance
  73                 $command->setPeerInstance($peerInstance);
  74
  75                 // Return the instance
  76                 return $command;
  77         }
  78
  79         /**
  80          * Setter for HubPeer instances
  81          *
  82          * @param               $peerInstance           An instance of a HubPeer class
  83          * @return      void
  84          */
  85         public final function setPeerInstance(HubPeer $peerInstance) {
  86                 $this->peerInstance = $peerInstance;
  87         }
  88
  89         /**
  90          * Getter for HubPeer instances
  91          *
  92          * @return      $peerInstance           An instance of a HubPeer class
  93          */
  94         public final function getPeerInstance() {
  95                 return $this->peerInstance;
  96         }
  97
  98         /**
  99          * Handles simple commands which require an answer command from the peer without any parameters
 100          *
 101          * @param               $sendCommand            The command we shall send to the peer
 102          * @param               $expectCommand          The command we except from the peer
 103          * @return      void
 104          */
 105         public function simpleExecute ($sendCommand, $expectCommand) {
 106                 // Remember the command
 107                 $this->sentCommandsAwaitingAnswer[$expectCommand] = $sendCommand;
 108
 109                 // Debug message
 110                 $this->getPeerInstance()->getHubInstance()->getOutputInstance()->output(sprintf("[%s] Sending command %s to peer %s",
 111                         $this->__toString(),
 112                         $sendCommand,
 113                         $this->getPeerInstance()->getValidatedIP()
 114                 ));
 115
 116                 // Execute the command
 117                 $this->getPeerInstance()->sendMessage($sendCommand);
 118         }
 119
 120         /**
 121          * Awaits a specified command from the peer and returns TRUE if received or FALSE if not.
 122          *
 123          * @param               $exceptCommand                                  The command we are expecting from the peer
 124          * @return      $await                                          Wether the awaited command has been received
 125          * @throws      UnexpectedAwaitCommandException If the awaited command is not being awaited...
 126          */
 127         public function ifAwaitsCommand ($expectCommand) {
 128                 $await = false;
 129
 130                 // Do we wait for this command?
 131                 if (!isset($this->sentCommandsAwaitingAnswer[$expectCommand])) {
 132                         // We are not waiting for this command
 133                         throw new UnexpectedAwaitCommandException (
 134                                 array(
 135                                         'this'  => $this,
 136                                         'await' => $expectCommand
 137                                 ), self::EXCEPTION_COMMAND_AWAIT_INVALID
 138                         );
 139                 } // END - if
 140
 141                 // Then process it... :-)
 142                 $readCommand = $this->getPeerInstance()->readFromSocket();
 143
 144                 // Is the command not empty?
 145                 if (!empty($readCommand)) {
 146                         // Debug message
 147                         $this->getPeerInstance()->getHubInstance()->getOutputInstance()->output(sprintf("[%s] Raw command %s received from peer %s",
 148                                 $this->__toString(),
 149                                 $readCommand,
 150                                 $this->getPeerInstance()->getValidatedIP()
 151                         ));
 152                 } // END - if
 153
 154                 if ($readCommand == $expectCommand) {
 155                         // Debug message
 156                         $this->getPeerInstance()->getHubInstance()->getOutputInstance()->output(sprintf("[%s] Awaited command %s received from peer %s",
 157                                 $this->__toString(),
 158                                 $expectCommand,
 159                                 $this->getPeerInstance()->getValidatedIP()
 160                         ));
 161
 162                         // Expected command has been received!
 163                         unset($this->sentCommandsAwaitingAnswer[$expectCommand]);
 164                         $await = true;
 165
 166                 } // END - if
 167
 168                 // Return the result
 169                 return $await;
 170         }
 171
 172         /**
 173          * Awaits any command from the peer
 174          *
 175          * @return      $command                The sent command from the peer
 176          */
 177         public function awaitAnyCommand () {
 178                 $command = false;
 179                 $readCommand = $this->getPeerInstance()->readFromSocket();
 180                 if (!empty($readCommand)) {
 181                         // Remember this command
 182                         // TODO Add some validation here!
 183                         $this->masterCommands[] = $readCommand;
 184
 185                         // A command is in the queue
 186                         $command = true;
 187                 } // END - if
 188
 189                 // Return status
 190                 return $command;
 191         }
 192
 193 } // END - class
 194
 195 // [EOF]
 196 ?>