net.i2p.client.streaming

## Interface I2PSocketManager

- All Known Implementing Classes:
    I2PSocketManagerFull

      public interface 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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `I2PSocketManager.DisconnectListener` Listener for notification when an I2P session is disconnected

  - ### Method Summary

    All Methods Instance Methods Abstract 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 (block until the socket is created)
    `I2PSocket` | `connect(Destination peer, I2PSocketOptions options)` Create a new connected socket (block until the socket is created)
    `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()`
    `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()`
    `void` | `init(I2PAppContext context, I2PSession session, Properties opts, String name)` Deprecated - Factory will initialize.
    `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.
    `void` | `removeDisconnectListener(I2PSocketManager.DisconnectListener lsnr)`
    `void` | `removeSubsession(I2PSession session)`
    `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

- - ### Method Detail

    - #### addDisconnectListener

          void addDisconnectListener(I2PSocketManager.DisconnectListener lsnr)

    - #### addSubsession

          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.
      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

          I2PSocketOptions buildOptions()

      Create a copy of the current options, to be used in a setDefaultOptions() call.

    - #### buildOptions

          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.
      Parameters:
        `opts` - The new options, may be null

    - #### connect

          I2PSocket connect(Destination peer)
                     throws I2PException,
                            ConnectException,
                            NoRouteToHostException,
                            InterruptedIOException

      Create a new connected socket (block until the socket is created)
      Parameters:
        `peer` - Destination to connect to
      Returns:
        new connected socket
      Throws:
        `ConnectException` - if the peer refuses the connection
        `NoRouteToHostException` - if the peer is not found or not reachable
        `InterruptedIOException` - if the connection timeouts
        `I2PException` - if there is some other I2P-related problem

    - #### connect

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

      Create a new connected socket (block until the socket is created)
      Parameters:
        `peer` - Destination to connect to
        `options` - I2P socket options to be used for connecting
      Returns:
        new connected socket
      Throws:
        `ConnectException` - if the peer refuses the connection
        `NoRouteToHostException` - if the peer is not found or not reachable
        `InterruptedIOException` - if the connection timeouts
        `I2PException` - if there is some other I2P-related problem

    - #### connectToSocket

          Socket connectToSocket(Destination peer)
                          throws IOException

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

    - #### connectToSocket

          Socket connectToSocket(Destination peer,
                                 int timeout)
                          throws IOException

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

    - #### destroySocketManager

          void destroySocketManager()

      Destroy the socket manager, freeing all the associated resources. This method will block untill all the managed sockets are closed. The socket manager CANNOT be reused after this.

    - #### getAcceptTimeout

          long getAcceptTimeout()

    - #### getDefaultOptions

          I2PSocketOptions getDefaultOptions()

      Current options, not a copy, setters may be used to make changes.

    - #### getName

          String getName()

      For logging / diagnostics only

    - #### getServerSocket

          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.
      Returns:
        non-null

    - #### getSession

          I2PSession getSession()

      Returns:
        the session, non-null

    - #### getStandardServerSocket

          ServerSocket getStandardServerSocket()
                                        throws IOException

      Like getServerSocket but returns a real ServerSocket for easier porting of apps.
      Throws:
        `IOException`

    - #### getSubsessions

          List<I2PSession> getSubsessions()

      Returns:
        a list of subsessions, non-null, does not include the primary session

    - #### init

          void init(I2PAppContext context,
                    I2PSession session,
                    Properties opts,
                    String name)

      Deprecated - Factory will initialize.
      Throws:
        `UnsupportedOperationException` - always

    - #### isDestroyed

          boolean isDestroyed()

      Has the socket manager been destroyed?

    - #### listSockets

          Set<I2PSocket> listSockets()

      Retrieve a set of currently connected I2PSockets, either initiated locally or remotely.
      Returns:
        a set of currently connected I2PSockets

    - #### ping

          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.
      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

          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.
      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

          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.
      Parameters:
        `peer` - Destination to ping
        `timeoutMs` - timeout in ms, greater than zero
      Returns:
        success or failure
      Throws:
        `IllegalArgumentException`

    - #### removeDisconnectListener

          void removeDisconnectListener(I2PSocketManager.DisconnectListener lsnr)

    - #### removeSubsession

          void removeSubsession(I2PSession session)

    - #### setAcceptTimeout

          void setAcceptTimeout(long ms)

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

    - #### setDefaultOptions

          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.
      Parameters:
        `options` - as created from a call to buildOptions(properties), non-null

    - #### setName

          void setName(String name)

      For logging / diagnostics only