application/hub/main/listener/class_BaseListener.php

   1 <?php
   2 /**
   3  * A general listener class
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Hub Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class BaseListener extends BaseHubSystem implements Visitable {
  25         // Exception code constants
  26         const EXCEPTION_INVALID_SOCKET                   = 0xa00;
  27         const EXCEPTION_SOCKET_ALREADY_REGISTERED        = 0xa01;
  28         const EXCEPTION_SOCKET_CREATION_FAILED           = 0xa02;
  29         const EXCEPTION_NO_SOCKET_ERROR                  = 0xa03;
  30         const EXCEPTION_CONNECTION_ALREADY_REGISTERED    = 0xa04;
  31         const EXCEPTION_UNEXPECTED_PACKAGE_STATUS        = 0xa05;
  32         const EXCEPTION_UNSUPPORTED_PACKAGE_CODE_HANDLER = 0xa06;
  33         const EXCEPTION_FINAL_CHUNK_VERIFICATION         = 0xa07;
  34
  35         /**
  36          * Used protocol (Default: invalid, which is indeed invalid...)
  37          */
  38         private $protocol = 'invalid';
  39
  40         /**
  41          * Address (IP mostly) we shall listen on
  42          */
  43         private $listenAddress = '0.0.0.0'; // This is the default and listens on all interfaces
  44
  45         /**
  46          * Port we shall listen on (or wait for incoming data)
  47          */
  48         private $listenPort = 0; // This port MUST be changed by your application
  49
  50         /**
  51          * Whether we are in blocking or non-blocking mode (default: non-blocking
  52          */
  53         private $blockingMode = false;
  54
  55         /**
  56          * A peer pool instance
  57          */
  58         private $poolInstance = NULL;
  59
  60         /**
  61          * Protected constructor
  62          *
  63          * @param       $className      Name of the class
  64          * @return      void
  65          */
  66         protected function __construct ($className) {
  67                 // Call parent constructor
  68                 parent::__construct($className);
  69         }
  70
  71         /**
  72          * Checks whether the given socket resource is a server socket
  73          *
  74          * @param       $socketResource         A valid socket resource
  75          * @return      $isServerSocket         Whether the socket resource is a server socket
  76          */
  77         protected function isServerSocketResource ($socketResource) {
  78                 // Check it
  79                 $isServerSocket = ((is_resource($socketResource)) && (!@socket_getpeername($socketResource, $peerName)));
  80
  81                 // We need to clear the error here if it is a resource
  82                 if ($isServerSocket === true) {
  83                         // Clear the error
  84                         //* DEBUG: */ $this->debugOutput('socketResource[]=' . gettype($socketResource));
  85                         socket_clear_error($socketResource);
  86                 } // END - if
  87
  88                 // Check peer name, it must be empty
  89                 $isServerSocket = (($isServerSocket) && (empty($peerName)));
  90
  91                 // Return result
  92                 return $isServerSocket;
  93         }
  94
  95         /**
  96          * Setter for listen address
  97          *
  98          * @param       $listenAddress  The address this listener should listen on
  99          * @return      void
 100          */
 101         protected final function setListenAddress ($listenAddress) {
 102                 $this->listenAddress = (string) $listenAddress;
 103         }
 104
 105         /**
 106          * Getter for listen address
 107          *
 108          * @return      $listenAddress  The address this listener should listen on
 109          */
 110         public final function getListenAddress () {
 111                 return $this->listenAddress;
 112         }
 113
 114         /**
 115          * Setter for listen port
 116          *
 117          * @param       $listenPort             The port this listener should listen on
 118          * @return      void
 119          */
 120         protected final function setListenPort ($listenPort) {
 121                 $this->listenPort = (int) $listenPort;
 122         }
 123
 124         /**
 125          * Getter for listen port
 126          *
 127          * @return      $listenPort             The port this listener should listen on
 128          */
 129         public final function getListenPort () {
 130                 return $this->listenPort;
 131         }
 132
 133         /**
 134          * Getter for port number to satify ProtocolHandler
 135          *
 136          * @return      $port   The port number
 137          */
 138         public final function getPort () {
 139                 return $this->getListenPort();
 140         }
 141
 142         /**
 143          * "Setter" to set listen address from configuration entry
 144          *
 145          * @param       $configEntry    The configuration entry holding our listen address
 146          * @return      void
 147          */
 148         public final function setListenAddressByConfiguration ($configEntry) {
 149                 $this->setListenAddress($this->getConfigInstance()->getConfigEntry($configEntry));
 150         }
 151
 152         /**
 153          * "Setter" to set listen port from configuration entry
 154          *
 155          * @param       $configEntry    The configuration entry holding our listen port
 156          * @return      void
 157          */
 158         public final function setListenPortByConfiguration ($configEntry) {
 159                 $this->setListenPort($this->getConfigInstance()->getConfigEntry($configEntry));
 160         }
 161
 162         /**
 163          * Setter for protocol
 164          *
 165          * @param       $protocol       Used protocol
 166          * @return      void
 167          */
 168         protected final function setProtocol ($protocol) {
 169                 $this->protocol = (string) $protocol;
 170         }
 171
 172         /**
 173          * Getter for protocol
 174          *
 175          * @return      $protocol       Used protocol
 176          */
 177         public final function getProtocol () {
 178                 return $this->protocol;
 179         }
 180
 181         /**
 182          * Setter for blocking-mode
 183          *
 184          * @param       $blockingMode   Whether blocking-mode is disabled (default) or enabled
 185          * @return      void
 186          */
 187         protected final function setBlockingMode ($blockingMode) {
 188                 $this->blockingMode = (boolean) $blockingMode;
 189         }
 190
 191         /**
 192          * Checks whether blocking-mode is enabled or disabled
 193          *
 194          * @return      $blockingMode   Whether blocking mode is disabled or enabled
 195          */
 196         public final function isBlockingModeEnabled () {
 197                 return $this->blockingMode;
 198         }
 199
 200         /**
 201          * Setter for peer pool instance
 202          *
 203          * @param       $poolInstance   The peer pool instance we shall set
 204          * @return      void
 205          */
 206         protected final function setPoolInstance (PoolablePeer $poolInstance) {
 207                 $this->poolInstance = $poolInstance;
 208         }
 209
 210         /**
 211          * Getter for peer pool instance
 212          *
 213          * @return      $poolInstance   The peer pool instance we shall set
 214          */
 215         public final function getPoolInstance () {
 216                 return $this->poolInstance;
 217         }
 218
 219         /**
 220          * Registeres the given socket resource for "this" listener instance. This
 221          * will be done in a seperate class to allow package writers to use it
 222          * again.
 223          *
 224          * @param       $socketResource         A valid server socket resource
 225          * @return      void
 226          * @throws      InvalidServerSocketException            If the given resource is no server socket
 227          * @throws      SocketAlreadyRegisteredException        If the given resource is already registered
 228          */
 229         protected function registerServerSocketResource ($socketResource) {
 230                 // First check if it is valid
 231                 if (!$this->isServerSocketResource($socketResource)) {
 232                         // No server socket
 233                         throw new InvalidServerSocketException(array($this, $socketResource), self::EXCEPTION_INVALID_SOCKET);
 234                 } elseif ($this->isServerSocketRegistered($socketResource)) {
 235                         // Already registered
 236                         throw new SocketAlreadyRegisteredException($this, self::EXCEPTION_SOCKET_ALREADY_REGISTERED);
 237                 }
 238
 239                 // Get a socket registry instance (singleton)
 240                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 241
 242                 // Register the socket
 243                 $registryInstance->registerSocket($this, $socketResource);
 244         }
 245
 246         /**
 247          * Checks whether given socket resource is registered in socket registry
 248          *
 249          * @param       $socketResource         A valid server socket resource
 250          * @return      $isRegistered           Whether given server socket is registered
 251          */
 252         protected function isServerSocketRegistered ($socketResource) {
 253                 // Get a socket registry instance (singleton)
 254                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 255
 256                 // Check it
 257                 $isRegistered = $registryInstance->isSocketRegistered($this, $socketResource);
 258
 259                 // Return result
 260                 return $isRegistered;
 261         }
 262
 263         /**
 264          * Getter for "this" socket resource
 265          *
 266          * @return      $socketResource         A valid socket resource
 267          */
 268         public final function getSocketResource () {
 269                 // Get a socket registry instance (singleton)
 270                 $registryInstance = SocketRegistryFactory::createSocketRegistryInstance();
 271
 272                 // Get the socket resource
 273                 $socketResource = $registryInstance->getRegisteredSocketResource($this);
 274
 275                 // Return it
 276                 return $socketResource;
 277         }
 278
 279         /**
 280          * Accepts the visitor to process the visit "request"
 281          *
 282          * @param       $visitorInstance        An instance of a Visitor class
 283          * @return      void
 284          */
 285         public function accept (Visitor $visitorInstance) {
 286                 // Debug message
 287                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - START');
 288
 289                 // Visit this listener
 290                 $visitorInstance->visitListener($this);
 291
 292                 // Visit the pool if set
 293                 if ($this->getPoolInstance() instanceof Poolable) {
 294                         $this->getPoolInstance()->accept($visitorInstance);
 295                 } // END - if
 296
 297                 // Debug message
 298                 //* DEBUG: */ $this->debugOutput(strtoupper($this->getProtocol()) . '-LISTENER: ' . $visitorInstance->__toString() . ' has visited ' . $this->__toString() . ' - FINISHED');
 299         }
 300
 301         /**
 302          * Monitors incoming raw data from the handler and transfers it to the
 303          * given receiver instance. This method should not be called, please call
 304          * the decorator's version instead to separator node/client traffic.
 305          *
 306          * @param       $receiverInstance       An instance of a Receivable class
 307          * @return      void
 308          * @throws      UnsupportedOperatorException    If this method is called by a mistake
 309          */
 310         public function monitorIncomingRawData (Receivable $receiverInstance) {
 311                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $receiverInstance), self::EXCEPTION_UNSPPORTED_OPERATION);
 312         }
 313 }
 314
 315 // [EOF]
 316 ?>