3 * A general ConnectionHelper class
5 * @author Roland Haeder <webmaster@ship-simu.org>
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.ship-simu.org
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.
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.
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/>.
24 class BaseConnectionHelper extends BaseHubHelper implements Registerable, ProtocolHandler {
26 const EXCEPTION_UNSUPPORTED_ERROR_HANDLER = 0x900;
31 private $protocol = 'invalid';
46 private $sentData = 0;
54 * Whether this connection is initialized
56 private $isInitialized = false;
59 * Whether this connection is shutted down
61 private $shuttedDown = false;
64 * Currently queued chunks
66 private $queuedChunks = array();
71 private $currentFinalHash = '';
74 * Protected constructor
76 * @param $className Name of the class
79 protected function __construct ($className) {
80 // Call parent constructor
81 parent::__construct($className);
83 // Initialize output stream
84 $streamInstance = ObjectFactory::createObjectByConfiguredName('node_raw_data_output_stream_class');
86 // And add it to this connection helper
87 $this->setOutputStreamInstance($streamInstance);
89 // Init state which sets the state to 'init'
92 // Register this connection helper
93 Registry::getRegistry()->addInstance('connection', $this);
95 // Get the fragmenter instance
96 $fragmenterInstance = FragmenterFactory::createFragmenterInstance('package');
99 $this->setFragmenterInstance($fragmenterInstance);
103 * Getter for real class name, overwrites generic method and is final
105 * @return $class Name of this class
107 public final function __toString () {
108 // Class name representation
109 $class = self::getConnectionClassName($this->getAddress(), $this->getPort(), parent::__toString());
116 * Getter for port number to satify ProtocolHandler
118 * @return $port The port number
120 public final function getPort () {
125 * Setter for port number to satify ProtocolHandler
127 * @param $port The port number
130 protected final function setPort ($port) {
135 * Getter for protocol
137 * @return $protocol Used protocol
139 public final function getProtocol () {
140 return $this->protocol;
144 * Setter for protocol
146 * @param $protocol Used protocol
149 protected final function setProtocol ($protocol) {
150 $this->protocol = $protocol;
154 * Getter for IP address
156 * @return $address The IP address
158 public final function getAddress () {
159 return $this->address;
163 * Setter for IP address
165 * @param $address The IP address
168 protected final function setAddress ($address) {
169 $this->address = $address;
173 * Initializes the current connection
176 * @throws SocketOptionException If setting any socket option fails
178 protected function initConnection () {
179 // Get socket resource
180 $socketResource = $this->getSocketResource();
182 // Set the option to reuse the port
183 if (!socket_set_option($socketResource, SOL_SOCKET, SO_REUSEADDR, 1)) {
184 // Handle this socket error with a faked recipientData array
185 $this->handleSocketError($socketResource, array('0.0.0.0', '0'));
188 // @TODO Move this to the socket error handler
189 throw new SocketOptionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
193 * Set socket to non-blocking mode before trying to establish a link to
194 * it. This is now the default behaviour for all connection helpers who
195 * call initConnection(); .
197 if (!socket_set_nonblock($socketResource)) {
198 // Handle this socket error with a faked recipientData array
199 $helperInstance->handleSocketError($socketResource, array('0.0.0.0', '0'));
202 throw new SocketOptionException(array($helperInstance, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
205 // Last step: mark connection as initialized
206 $this->isInitialized = true;
210 * Attempts to connect to a peer by given IP number and port from a valid
211 * recipientData array with currently configured timeout.
213 * @param $recipientData A valid recipient data array, 0=IP; 1=PORT
214 * @return $isConnected Whether the connection went fine
215 * @see Please see http://de.php.net/manual/en/function.socket-connect.php#84465 for original code
216 * @todo Rewrite the while() loop to a iterator to not let the software stay very long here
218 protected function connectToPeerByRecipientDataArray (array $recipientData) {
219 // Only call this if the connection is initialized by initConnection()
220 assert($this->isInitialized === true);
225 // "Cache" socket resource and timeout config
226 $socketResource = $this->getSocketResource();
227 $timeout = $this->getConfigInstance()->getConfigEntry('socket_timeout_seconds');
230 $this->debugOutput('CONNECTION-HELPER: Trying to connect to ' . $recipientData[0] . ':' . $recipientData[1] . ' with socketResource[' . gettype($socketResource) . ']=' . $socketResource . ' ...');
232 // Try to connect until it is connected
233 while ($isConnected = !@socket_connect($socketResource, $recipientData[0], $recipientData[1])) {
234 // Get last socket error
235 $socketError = socket_last_error($socketResource);
237 // Skip any errors which may happen on non-blocking connections
238 if (($socketError == SOCKET_EINPROGRESS) || ($socketError == SOCKET_EALREADY)) {
239 // Now, is that attempt within parameters?
240 if ((time() - $time) >= $timeout) {
241 // Didn't work within timeout
242 $isConnected = false;
246 // Sleep about one second
248 } elseif ($socketError != 0) {
249 // Stop on everything else pronto
250 $isConnected = false;
255 // Is the peer connected?
256 if ($isConnected === true) {
257 // Connection is fully established here, so change the state.
258 PeerStateFactory::createPeerStateInstanceByName('connected', $this);
261 * There was a problem connecting to the peer (this state is a meta
262 * state until the error handler has found the real cause).
264 PeerStateFactory::createPeerStateInstanceByName('problem', $this);
272 * Static "getter" for this connection class' name
274 * @param $address IP address
275 * @param $port Port number
276 * @param $className Original class name
277 * @return $class Expanded class name
279 public static function getConnectionClassName ($address, $port, $className) {
281 $class = $address . ':' . $port . ':' . $className;
288 * Initializes the peer's state which sets it to 'init'
292 private function initState() {
294 * Get the state factory and create the initial state, we don't need
295 * the state instance here
297 PeerStateFactory::createPeerStateInstanceByName('init', $this);
301 * "Getter" for raw data from a package array. A fragmenter is used which
302 * will returns us only so many raw data which fits into the back buffer.
303 * The rest is being held in a back-buffer and waits there for the next
304 * cycle and while be then sent.
306 * This method does 4 simple steps:
307 * 1) Aquire fragmenter object instance from the factory
308 * 2) Handle over the package data array to the fragmenter
310 * 4) Finally return the chunk (array) to the caller
312 * @param $packageData Raw package data array
313 * @return $chunkData Raw data chunk
315 private function getRawDataFromPackageArray (array $packageData) {
316 // Implode the package data array and fragement the resulting string, returns the final hash
317 $finalHash = $this->getFragmenterInstance()->fragmentPackageArray($packageData, $this);
318 if ($finalHash !== true) {
319 $this->currentFinalHash = $finalHash;
323 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: currentFinalHash=' . $this->currentFinalHash);
325 // Get the next raw data chunk from the fragmenter
326 $rawDataChunk = $this->getFragmenterInstance()->getNextRawDataChunk($this->currentFinalHash);
328 // Get chunk hashes and chunk data
329 $chunkHashes = array_keys($rawDataChunk);
330 $chunkData = array_values($rawDataChunk);
332 // Is the required data there?
333 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: chunkHashes[]=' . count($chunkHashes) . ',chunkData[]=' . count($chunkData));
334 //* NOISY-DEBUG: */ $this->debugOutput('chunkData='.print_r($chunkData,true));
335 if ((isset($chunkHashes[0])) && (isset($chunkData[0]))) {
336 // Remember this chunk as queued
337 $this->queuedChunks[$chunkHashes[0]] = $chunkData[0];
339 // Return the raw data
340 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: Returning ' . strlen($chunkData[0]) . ' bytes from ' . __METHOD__ . ' ...');
341 return $chunkData[0];
343 // Return zero string
344 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: Returning zero bytes from ' . __METHOD__ . '!');
350 * "Accept" a visitor by simply calling it back
352 * @param $visitorInstance A Visitor instance
355 protected final function accept (Visitor $visitorInstance) {
356 // Just call the visitor
357 $visitorInstance->visitConnectionHelper($this);
361 * Sends raw package data to the recipient
363 * @param $packageData Raw package data
364 * @return $totalSentBytes Total sent bytes to the peer
365 * @throws InvalidSocketException If we got a problem with this socket
367 public function sendRawPackageData (array $packageData) {
368 // The helper's state must be 'connected'
369 $this->getStateInstance()->validatePeerStateConnected();
371 // Cache buffer length
372 $bufferSize = $this->getConfigInstance()->getConfigEntry($this->getProtocol() . '_buffer_length');
379 // Fill sending buffer with data
380 while (strlen($dataStream) > 0) {
381 // Convert the package data array to a raw data stream
382 $dataStream = $this->getRawDataFromPackageArray($packageData);
383 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: Adding ' . strlen($dataStream) . ' bytes to the sending buffer ...');
384 $rawData .= $dataStream;
386 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: rawData[' . strlen($rawData) . ']=' . $rawData);
388 // Nothing to sent is bad news, so assert on it
389 assert(strlen($rawData) > 0);
391 // Encode the raw data with our output-stream
392 $encodedData = $this->getOutputStreamInstance()->streamData($rawData);
394 // Calculate difference
395 $this->diff = $bufferSize - strlen($encodedData);
397 // Get socket resource
398 $socketResource = $this->getSocketResource();
404 while ($sentBytes !== false) {
406 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: Sending out ' . strlen($encodedData) . ' bytes,bufferSize=' . $bufferSize . ',diff=' . $this->diff);
407 if ($this->diff >= 0) {
408 // Send all out (encodedData is smaller than or equal buffer size)
409 $sentBytes = @socket_write($socketResource, $encodedData, ($bufferSize - $this->diff));
411 // Send buffer size out
412 $sentBytes = @socket_write($socketResource, $encodedData, $bufferSize);
415 // If there was an error, we don't continue here
416 if ($sentBytes === false) {
417 // Handle the error with a faked recipientData array
418 $this->handleSocketError($socketResource, array('0.0.0.0', '0'));
421 throw new InvalidSocketException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
422 } elseif (($sentBytes == 0) && (strlen($encodedData) > 0)) {
423 // Nothing sent means we are done
424 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: All sent! (LINE=' . __LINE__ . ')');
428 // The difference between sent bytes and length of raw data should not go below zero
429 assert((strlen($encodedData) - $sentBytes) >= 0);
431 // Add total sent bytes
432 $totalSentBytes += $sentBytes;
434 // Cut out the last unsent bytes
435 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: Sent out ' . $sentBytes . ' of ' . strlen($encodedData) . ' bytes ...');
436 $encodedData = substr($encodedData, $sentBytes);
438 // Calculate difference again
439 $this->diff = $bufferSize - strlen($encodedData);
442 if (strlen($encodedData) <= 0) {
443 // Abort here, all sent!
444 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: All sent! (LINE=' . __LINE__ . ')');
450 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: totalSentBytes=' . $totalSentBytes . ',diff=' . $this->diff);
451 return $totalSentBytes;
455 * Marks this connection as shutted down
459 protected final function markConnectionShuttedDown () {
460 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: ' . $this->__toString() . ' has been marked as shutted down');
461 $this->shuttedDown = true;
463 // And remove the (now invalid) socket
464 $this->setSocketResource(false);
468 * Getter for shuttedDown
470 * @return $shuttedDown Whether this connection is shutted down
472 public final function isShuttedDown () {
473 //* NOISY-DEBUG: */ $this->debugOutput('CONNECTION: ' . $this->__toString() . ',shuttedDown=' . intval($this->shuttedDown));
474 return $this->shuttedDown;
477 // ************************************************************************
478 // Socket error handler call-back methods
479 // ************************************************************************
482 * Handles socket error 'connection timed out', but does not clear it for
483 * later debugging purposes.
485 * @param $socketResource A valid socket resource
487 * @throws SocketConnectionException The connection attempts fails with a time-out
489 protected function socketErrorConnectionTimedOutHandler ($socketResource) {
490 // Get socket error code for verification
491 $socketError = socket_last_error($socketResource);
494 $errorMessage = socket_strerror($socketError);
496 // Shutdown this socket
497 $this->shutdownSocket($socketResource);
500 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
504 * Handles socket error 'resource temporary unavailable', but does not
505 * clear it for later debugging purposes.
507 * @param $socketResource A valid socket resource
509 * @throws SocketConnectionException The connection attempts fails with a time-out
511 protected function socketErrorResourceUnavailableHandler ($socketResource) {
512 // Get socket error code for verification
513 $socketError = socket_last_error($socketResource);
516 $errorMessage = socket_strerror($socketError);
518 // Shutdown this socket
519 $this->shutdownSocket($socketResource);
522 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
526 * Handles socket error 'connection refused', but does not clear it for
527 * later debugging purposes.
529 * @param $socketResource A valid socket resource
531 * @throws SocketConnectionException The connection attempts fails with a time-out
533 protected function socketErrorConnectionRefusedHandler ($socketResource) {
534 // Get socket error code for verification
535 $socketError = socket_last_error($socketResource);
538 $errorMessage = socket_strerror($socketError);
540 // Shutdown this socket
541 $this->shutdownSocket($socketResource);
544 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
548 * Handles socket error 'no route to host', but does not clear it for later
549 * debugging purposes.
551 * @param $socketResource A valid socket resource
553 * @throws SocketConnectionException The connection attempts fails with a time-out
555 protected function socketErrorNoRouteToHostHandler ($socketResource) {
556 // Get socket error code for verification
557 $socketError = socket_last_error($socketResource);
560 $errorMessage = socket_strerror($socketError);
562 // Shutdown this socket
563 $this->shutdownSocket($socketResource);
566 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
570 * Handles socket error 'operation already in progress' which happens in
571 * method connectToPeerByRecipientDataArray() on timed out connection
574 * @param $socketResource A valid socket resource
576 * @throws SocketConnectionException The connection attempts fails with a time-out
578 protected function socketErrorOperationAlreadyProgressHandler ($socketResource) {
579 // Get socket error code for verification
580 $socketError = socket_last_error($socketResource);
583 $errorMessage = socket_strerror($socketError);
585 // Half-shutdown this socket (see there for difference to shutdownSocket())
586 $this->halfShutdownSocket($socketResource);
589 throw new SocketConnectionException(array($this, $socketResource, $socketError, $errorMessage), BaseListener::EXCEPTION_INVALID_SOCKET);
593 * Handles socket "error" 'operation now in progress' which can be safely
594 * passed on with non-blocking connections.
596 * @param $socketResource A valid socket resource
599 protected function socketErrorOperationInProgressHandler ($socketResource) {
600 $this->debugOutput('CONNECTION: Operation is now in progress, this is usual for non-blocking connections and is no bug.');