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