application/hub/main/listener/class_BaseListener.php

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