net.i2p.client.streaming.impl

## Class I2PSocketManagerFull

- java.lang.Object
- - net.i2p.client.streaming.impl.I2PSocketManagerFull

- All Implemented Interfaces:
    I2PSocketManager

      public class I2PSocketManagerFull
      extends Object
      implements I2PSocketManager

  Centralize the coordination and multiplexing of the local client's streaming. There should be one I2PSocketManager for each I2PSession, and if an application is sending and receiving data through the streaming library using an I2PSocketManager, it should not attempt to call I2PSession's setSessionListener or receive any messages with its .receiveMessage This is what I2PSocketManagerFactory.createManager() returns. Direct instantiation by others is deprecated.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface net.i2p.client.streaming.I2PSocketManager

      `I2PSocketManager.DisconnectListener`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static PcapWriter` | `pcapWriter`
    `(package private) static String` | `PROP_PCAP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `I2PSocketManagerFull(I2PAppContext context, I2PSession session, Properties opts, String name, IncomingConnectionFilter connectionFilter)` This is what I2PSocketManagerFactory.createManager() returns.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDisconnectListener(I2PSocketManager.DisconnectListener lsnr)`
    `I2PSession` | `addSubsession(InputStream privateKeyStream, Properties opts)` For a server, you must call connect() on the returned object.
    `I2PSocketOptions` | `buildOptions()` Create a copy of the current options, to be used in a setDefaultOptions() call.
    `I2PSocketOptions` | `buildOptions(Properties opts)` Create a modified copy of the current options, to be used in a setDefaultOptions() call.
    `I2PSocket` | `connect(Destination peer)` Create a new connected socket.
    `I2PSocket` | `connect(Destination peer, I2PSocketOptions options)` Create a new connected socket.
    `Socket` | `connectToSocket(Destination peer)` Like connect() but returns a real Socket, and throws only IOE, for easier porting of apps.
    `Socket` | `connectToSocket(Destination peer, int timeout)` Like connect() but returns a real Socket, and throws only IOE, for easier porting of apps.
    `void` | `destroySocketManager()` Destroy the socket manager, freeing all the associated resources.
    `long` | `getAcceptTimeout()`
    `ConnectionManager` | `getConnectionManager()`
    `I2PSocketOptions` | `getDefaultOptions()` Current options, not a copy, setters may be used to make changes.
    `String` | `getName()` For logging / diagnostics only
    `I2PServerSocket` | `getServerSocket()` Returns non-null socket.
    `I2PSession` | `getSession()`
    `ServerSocket` | `getStandardServerSocket()` Like getServerSocket but returns a real ServerSocket for easier porting of apps.
    `List<I2PSession>` | `getSubsessions()`
    `boolean` | `isDestroyed()` Has the socket manager been destroyed?
    `Set<I2PSocket>` | `listSockets()` Retrieve a set of currently connected I2PSockets, either initiated locally or remotely.
    `boolean` | `ping(Destination peer, int localPort, int remotePort, long timeoutMs)` Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise.
    `byte[]` | `ping(Destination peer, int localPort, int remotePort, long timeoutMs, byte[] payload)` Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise.
    `boolean` | `ping(Destination peer, long timeoutMs)` Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise.
    `I2PSocket` | `receiveSocket()` The accept() call.
    `void` | `removeDisconnectListener(I2PSocketManager.DisconnectListener lsnr)`
    `void` | `removeSubsession(I2PSession session)` Remove the subsession
    `void` | `setAcceptTimeout(long ms)` How long should we wait for the client to .accept() a socket before sending back a NACK/Close?
    `void` | `setDefaultOptions(I2PSocketOptions options)` Update the options on a running socket manager.
    `void` | `setName(String name)` For logging / diagnostics only

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface net.i2p.client.streaming.I2PSocketManager

      `init`

- - ### Field Detail

    - #### pcapWriter

          static PcapWriter pcapWriter

    - #### PROP_PCAP

          static final String PROP_PCAP

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### I2PSocketManagerFull

          public I2PSocketManagerFull(I2PAppContext context,
                                      I2PSession session,
                                      Properties opts,
                                      String name,
                                      IncomingConnectionFilter connectionFilter)

      This is what I2PSocketManagerFactory.createManager() returns. Direct instantiation by others is deprecated.
      Parameters:
        `context` - non-null
        `session` - non-null
        `opts` - may be null
        `name` - non-null

  - ### Method Detail

    - #### addDisconnectListener

          public void addDisconnectListener(I2PSocketManager.DisconnectListener lsnr)

      Specified by:
        `addDisconnectListener` in interface `I2PSocketManager`

    - #### addSubsession

          public I2PSession addSubsession(InputStream privateKeyStream,
                                          Properties opts)
                                   throws I2PSessionException

      For a server, you must call connect() on the returned object. Connecting the primary session does NOT connect any subsessions. If the primary session is not connected, connecting a subsession will connect the primary session first.
      Specified by:
        `addSubsession` in interface `I2PSocketManager`
      Parameters:
        `privateKeyStream` - null for transient, if non-null must have same encryption keys as primary session and different signing keys
        `opts` - subsession options if any, may be null
      Returns:
        a new subsession, non-null
      Throws:
        `I2PSessionException`

    - #### buildOptions

          public I2PSocketOptions buildOptions()

      Create a copy of the current options, to be used in a setDefaultOptions() call.
      Specified by:
        `buildOptions` in interface `I2PSocketManager`

    - #### buildOptions

          public I2PSocketOptions buildOptions(Properties opts)

      Create a modified copy of the current options, to be used in a setDefaultOptions() call. As of 0.9.19, defaults in opts are honored.
      Specified by:
        `buildOptions` in interface `I2PSocketManager`
      Parameters:
        `opts` - The new options, may be null

    - #### connect

          public I2PSocket connect(Destination peer)
                            throws I2PException,
                                   NoRouteToHostException

      Create a new connected socket. Blocks until the socket is created, unless the connectDelay option (i2p.streaming.connectDelay) is set and greater than zero in the default options. If so this will return immediately, and the client may quickly write initial data to the socket and this data will be bundled in the SYN packet.
      Specified by:
        `connect` in interface `I2PSocketManager`
      Parameters:
        `peer` - Destination to connect to
      Returns:
        I2PSocket if successful
      Throws:
        `NoRouteToHostException` - if the peer is not found or not reachable
        `I2PException` - if there is some other I2P-related problem

    - #### connect

          public I2PSocket connect(Destination peer,
                                   I2PSocketOptions options)
                            throws I2PException,
                                   NoRouteToHostException

      Create a new connected socket. Blocks until the socket is created, unless the connectDelay option (i2p.streaming.connectDelay) is set and greater than zero. If so this will return immediately, and the client may quickly write initial data to the socket and this data will be bundled in the SYN packet.
      Specified by:
        `connect` in interface `I2PSocketManager`
      Parameters:
        `peer` - Destination to connect to
        `options` - I2P socket options to be used for connecting, may be null
      Returns:
        I2PSocket if successful
      Throws:
        `NoRouteToHostException` - if the peer is not found or not reachable
        `I2PException` - if there is some other I2P-related problem

    - #### connectToSocket

          public Socket connectToSocket(Destination peer)
                                 throws IOException

      Like connect() but returns a real Socket, and throws only IOE, for easier porting of apps.
      Specified by:
        `connectToSocket` in interface `I2PSocketManager`
      Throws:
        `IOException`

    - #### connectToSocket

          public Socket connectToSocket(Destination peer,
                                        int timeout)
                                 throws IOException

      Like connect() but returns a real Socket, and throws only IOE, for easier porting of apps.
      Specified by:
        `connectToSocket` in interface `I2PSocketManager`
      Parameters:
        `timeout` - ms if > 0, forces blocking (disables connectDelay)
      Throws:
        `IOException`

    - #### destroySocketManager

          public void destroySocketManager()

      Destroy the socket manager, freeing all the associated resources. This method will block until all the managed sockets are closed. CANNOT be restarted.
      Specified by:
        `destroySocketManager` in interface `I2PSocketManager`

    - #### getAcceptTimeout

          public long getAcceptTimeout()

      Specified by:
        `getAcceptTimeout` in interface `I2PSocketManager`

    - #### getConnectionManager

          public ConnectionManager getConnectionManager()

    - #### getDefaultOptions

          public I2PSocketOptions getDefaultOptions()

      Current options, not a copy, setters may be used to make changes. TODO There is no facility to specify the session.
      Specified by:
        `getDefaultOptions` in interface `I2PSocketManager`

    - #### getName

          public String getName()

      For logging / diagnostics only
      Specified by:
        `getName` in interface `I2PSocketManager`

    - #### getServerSocket

          public I2PServerSocket getServerSocket()

      Returns non-null socket. This method does not throw exceptions, but methods on the returned socket may throw exceptions if the socket or socket manager is closed. This only listens on the primary session. There is no way to get incoming connections on a subsession.
      Specified by:
        `getServerSocket` in interface `I2PSocketManager`
      Returns:
        non-null

    - #### getSession

          public I2PSession getSession()

      Specified by:
        `getSession` in interface `I2PSocketManager`
      Returns:
        the session, non-null

    - #### getStandardServerSocket

          public ServerSocket getStandardServerSocket()
                                               throws IOException

      Like getServerSocket but returns a real ServerSocket for easier porting of apps. This only listens on the primary session. There is no way to get incoming connections on a subsession.
      Specified by:
        `getStandardServerSocket` in interface `I2PSocketManager`
      Throws:
        `IOException`

    - #### getSubsessions

          public List<I2PSession> getSubsessions()

      Specified by:
        `getSubsessions` in interface `I2PSocketManager`
      Returns:
        a list of subsessions, non-null, does not include the primary session

    - #### isDestroyed

          public boolean isDestroyed()

      Has the socket manager been destroyed?
      Specified by:
        `isDestroyed` in interface `I2PSocketManager`

    - #### listSockets

          public Set<I2PSocket> listSockets()

      Retrieve a set of currently connected I2PSockets, either initiated locally or remotely.
      Specified by:
        `listSockets` in interface `I2PSocketManager`
      Returns:
        set of currently connected I2PSockets

    - #### ping

          public boolean ping(Destination peer,
                              int localPort,
                              int remotePort,
                              long timeoutMs)

      Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise. This call blocks. Uses the ports specified. TODO There is no way to ping on a subsession.
      Specified by:
        `ping` in interface `I2PSocketManager`
      Parameters:
        `peer` - Destination to ping
        `localPort` - 0 - 65535
        `remotePort` - 0 - 65535
        `timeoutMs` - timeout in ms, greater than zero
      Returns:
        success or failure
      Throws:
        `IllegalArgumentException`

    - #### ping

          public byte[] ping(Destination peer,
                             int localPort,
                             int remotePort,
                             long timeoutMs,
                             byte[] payload)

      Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise. This call blocks. Uses the ports specified. TODO There is no way to ping on a subsession.
      Specified by:
        `ping` in interface `I2PSocketManager`
      Parameters:
        `peer` - Destination to ping
        `localPort` - 0 - 65535
        `remotePort` - 0 - 65535
        `timeoutMs` - timeout in ms, greater than zero
        `payload` - to include in the ping
      Returns:
        the payload received in the pong, zero-length if none, null on failure or timeout
      Throws:
        `IllegalArgumentException`

    - #### ping

          public boolean ping(Destination peer,
                              long timeoutMs)

      Ping the specified peer, returning true if they replied to the ping within the timeout specified, false otherwise. This call blocks. Uses the ports from the default options. TODO There is no way to ping on a subsession.
      Specified by:
        `ping` in interface `I2PSocketManager`
      Parameters:
        `peer` -
        `timeoutMs` - timeout in ms, greater than zero
      Returns:
        true on success, false on failure
      Throws:
        `IllegalArgumentException`

    - #### receiveSocket

          public I2PSocket receiveSocket()
                                  throws I2PException,
                                         ConnectException,
                                         SocketTimeoutException

      The accept() call. This only listens on the primary session. There is no way to get incoming connections on a subsession.
      Returns:
        connected I2PSocket, or null through 0.9.16, non-null as of 0.9.17
      Throws:
        `I2PException` - if session is closed
        `RouterRestartException` - (extends I2PException) if the router is apparently restarting, since 0.9.34
        `ConnectException` - (since 0.9.17; I2PServerSocket interface always declared it)
        `SocketTimeoutException` - if a timeout was previously set with setSoTimeout and the timeout has been reached.

    - #### removeDisconnectListener

          public void removeDisconnectListener(I2PSocketManager.DisconnectListener lsnr)

      Specified by:
        `removeDisconnectListener` in interface `I2PSocketManager`

    - #### removeSubsession

          public void removeSubsession(I2PSession session)

      Remove the subsession
      Specified by:
        `removeSubsession` in interface `I2PSocketManager`

    - #### setAcceptTimeout

          public void setAcceptTimeout(long ms)

      How long should we wait for the client to .accept() a socket before sending back a NACK/Close?
      Specified by:
        `setAcceptTimeout` in interface `I2PSocketManager`
      Parameters:
        `ms` - milliseconds to wait, maximum

    - #### setDefaultOptions

          public void setDefaultOptions(I2PSocketOptions options)

      Update the options on a running socket manager. Parameters in the I2PSocketOptions interface may be changed directly with the setters; no need to use this method for those. This does NOT update the underlying I2CP or tunnel options; use getSession().updateOptions() for that. TODO There is no way to update the options on a subsession.
      Specified by:
        `setDefaultOptions` in interface `I2PSocketManager`
      Parameters:
        `options` - as created from a call to buildOptions(properties), non-null

    - #### setName

          public void setName(String name)

      For logging / diagnostics only
      Specified by:
        `setName` in interface `I2PSocketManager`