<?php

namespace React\Socket;

use React\Stream\DuplexStreamInterface;

/**

* Any incoming and outgoing connection is represented by this interface,

* such as a normal TCP/IP connection.

*

* An incoming or outgoing connection is a duplex stream (both readable and

* writable) that implements React's

* [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).

* It contains additional properties for the local and remote address (client IP)

* where this connection has been established to/from.

*

* Most commonly, instances implementing this `ConnectionInterface` are emitted

* by all classes implementing the [`ServerInterface`](#serverinterface) and

* used by all classes implementing the [`ConnectorInterface`](#connectorinterface).

*

* Because the `ConnectionInterface` implements the underlying

* [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)

* you can use any of its events and methods as usual:

*

* ```php

* $connection->on('data', function ($chunk) {

* echo $chunk;

* });

*

* $connection->on('end', function () {

* echo 'ended';

* });

*

* $connection->on('error', function (Exception $e) {

* echo 'error: ' . $e->getMessage();

* });

*

* $connection->on('close', function () {

* echo 'closed';

* });

*

* $connection->write($data);

* $connection->end($data = null);

* $connection->close();

* // …

* ```

*

* For more details, see the

* [`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface).

*

* @see DuplexStreamInterface

* @see ServerInterface

* @see ConnectorInterface

*/

interface ConnectionInterface extends DuplexStreamInterface

{

/**

* Returns the full remote address (URI) where this connection has been established with

*

* ```php

* $address = $connection->getRemoteAddress();

* echo 'Connection with ' . $address . PHP_EOL;

* ```

*

* If the remote address can not be determined or is unknown at this time (such as

* after the connection has been closed), it MAY return a `NULL` value instead.

*

* Otherwise, it will return the full address (URI) as a string value, such

* as `tcp://127.0.0.1:8080`, `tcp://[::1]:80`, `tls://127.0.0.1:443`,

* `unix://example.sock` or `unix:///path/to/example.sock`.

* Note that individual URI components are application specific and depend

* on the underlying transport protocol.

*

* If this is a TCP/IP based connection and you only want the remote IP, you may

* use something like this:

*

* ```php

* $address = $connection->getRemoteAddress();

* $ip = trim(parse_url(/sitelet?url=https%3A%2F%2Fgithub.com%2Fquestnet%2Fsocket%2Fblob%2Fcallbuilder%2Fsrc%2F%24address%2C%2520PHP_URL_HOST), '[]');

* echo 'Connection with ' . $ip . PHP_EOL;

* ```

*

* @return ?string remote address (URI) or null if unknown

*/

public function getRemoteAddress();

/**

* Returns the full local address (full URI with scheme, IP and port) where this connection has been established with

*

* ```php

* $address = $connection->getLocalAddress();

* echo 'Connection with ' . $address . PHP_EOL;

* ```

*

* If the local address can not be determined or is unknown at this time (such as

* after the connection has been closed), it MAY return a `NULL` value instead.

*

* Otherwise, it will return the full address (URI) as a string value, such

* as `tcp://127.0.0.1:8080`, `tcp://[::1]:80`, `tls://127.0.0.1:443`,

* `unix://example.sock` or `unix:///path/to/example.sock`.

* Note that individual URI components are application specific and depend

* on the underlying transport protocol.

*

* This method complements the [`getRemoteAddress()`](#getremoteaddress) method,

* so they should not be confused.

*

* If your `TcpServer` instance is listening on multiple interfaces (e.g. using

* the address `0.0.0.0`), you can use this method to find out which interface

* actually accepted this connection (such as a public or local interface).

*

* If your system has multiple interfaces (e.g. a WAN and a LAN interface),

* you can use this method to find out which interface was actually

* used for this connection.

*

* @return ?string local address (URI) or null if unknown

* @see self::getRemoteAddress()

*/

public function getLocalAddress();

}