net.i2p.i2ptunnel

## Class I2PTunnel

- java.lang.Object
- - net.i2p.util.EventDispatcherImpl
  - - net.i2p.i2ptunnel.I2PTunnel

- All Implemented Interfaces:
    Logging, EventDispatcher

      public class I2PTunnel
      extends EventDispatcherImpl
      implements Logging

  Manages I2PTunnelTasks and I2PSessions.

  Typically one of each. TODO: Poor error propagation as most events aren't listened to elsewhere.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `I2PTunnel.ConnectionEventListener` Callback routine to find out

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `String` | `filterDefinition` Absolute path to filter definition file
    `String` | `host` the I2CP host, non-null
    `String` | `listenHost` the listen-on host.
    `boolean` | `ownDest`
    `static int` | `PACKET_DELAY`
    `String` | `port` the I2CP port, non-null
    `long` | `readTimeout`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `I2PTunnel()` Standard constructor for embedded, uses args "-nocli -die" to return immediately
    `I2PTunnel(String[] args)` See usage() for options
    `I2PTunnel(String[] args, I2PTunnel.ConnectionEventListener lsnr)` See usage() for options
    `I2PTunnel(TunnelController tc)` New standard constructor in router, with back ref to tc

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConnectionEventListener(I2PTunnel.ConnectionEventListener lsnr)` Registers a listener for connection events.
    `(package private) void` | `addSession(I2PSession session)`
    `Properties` | `getClientOptions()` Generic options used for clients and servers.
    `I2PAppContext` | `getContext()` Gets the application context.
    `(package private) TunnelController` | `getController()` TunnelController that constructed this, or null.
    `List<I2PSession>` | `getSessions()`
    `void` | `log(String s)` Log the given message (using both the logging subsystem and standard output...)
    `static void` | `main(String[] args)`
    `void` | `removeConnectionEventListener(I2PTunnel.ConnectionEventListener lsnr)` Unregisters a connection event listener.
    `(package private) void` | `removeSession(I2PSession session)`
    `(package private) void` | `routerDisconnected()` Called when the router disconnects unexpectedly.
    `void` | `runClient(String[] args, Logging l)` Run the client on the given port number pointing at the specified destination (either the base64 of the destination or file:fileNameContainingDestination).
    `void` | `runClientOptions(String[] args, Logging l)` Configure the extra I2CP options to use in any subsequent I2CP sessions.
    `void` | `runClose(String[] args, Logging l)` Close the given task (or all tasks), optionally forcing them to die a hard death Sets the event "closeResult" = "ok" after the closing is complete
    `void` | `runCommand(String cmd, Logging l)` Parses and executes a tunnel management command.
    `void` | `runConnectClient(String[] args, Logging l)` Run a CONNECT client on the given port number
    `void` | `runHttpBidirServer(String[] args, Logging l)` Run the HTTP server pointing at the host and port specified using the private i2p destination loaded from the specified file, replacing the HTTP headers so that the Host: specified is the one spoofed.
    `void` | `runHttpClient(String[] args, Logging l)` Run an HTTP client on the given port number Sets the event "httpclientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error).
    `void` | `runHttpServer(String[] args, Logging l)` Run the HTTP server pointing at the host and port specified using the private i2p destination loaded from the specified file, replacing the HTTP headers so that the Host: specified is the one spoofed.
    `void` | `runIrcClient(String[] args, Logging l)` Run an IRC client on the given port number Sets the event "ircclientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error).
    `void` | `runIrcServer(String[] args, Logging l)` Same args as runServer (we should stop duplicating all this code...)
    `void` | `runListenOn(String[] args, Logging l)` Specify the hostname / IP address of the interface that the tunnels should bind to Sets the event "listen_onResult" = "ok" or "error" after the interface has been specified
    `void` | `runReadTimeout(String[] args, Logging l)` Specify the read timeout going to be used for newly-created I2PSockets Sets the event "read_timeoutResult" = "ok" or "error" after the interface has been specified
    `void` | `runServer(String[] args, Logging l)` Run the server pointing at the host and port specified using the private i2p destination loaded from the specified file.
    `void` | `runSOCKSIRCTunnel(String[] args, Logging l)` Run an SOCKS IRC tunnel on the given port number
    `void` | `runSOCKSTunnel(String[] args, Logging l)` Run an SOCKS tunnel on the given port number Sets the event "sockstunnelTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error).
    `void` | `runStreamrClient(String[] args, Logging l)` Streamr client
    `void` | `runStreamrServer(String[] args, Logging l)` Streamr server
    `void` | `runTextServer(String[] args, Logging l)` Run the server pointing at the host and port specified using the private i2p destination loaded from the given base64 stream.
    `void` | `setClientOptions(Properties opts)` Generic options used for clients and servers.

    - ### Methods inherited from class net.i2p.util.EventDispatcherImpl

      `attachEventDispatcher, detachEventDispatcher, getEventDispatcher, getEvents, getEventValue, ignoreEvents, notifyEvent, unIgnoreEvents, waitEventValue`

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

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

- - ### Field Detail

    - #### filterDefinition

          public String filterDefinition

      Absolute path to filter definition file

    - #### host

          public String host

      the I2CP host, non-null

    - #### listenHost

          public String listenHost

      the listen-on host. Sadly the listen-on port does not have a field.

    - #### ownDest

          public volatile boolean ownDest

    - #### PACKET_DELAY

          public static final int PACKET_DELAY

      See Also:
        Constant Field Values

    - #### port

          public String port

      the I2CP port, non-null

    - #### readTimeout

          public long readTimeout

  - ### Constructor Detail

    - #### I2PTunnel

          public I2PTunnel()

      Standard constructor for embedded, uses args "-nocli -die" to return immediately

    - #### I2PTunnel

          public I2PTunnel(String[] args)

      See usage() for options
      Throws:
        `IllegalArgumentException`

    - #### I2PTunnel

          public I2PTunnel(String[] args,
                           I2PTunnel.ConnectionEventListener lsnr)

      See usage() for options
      Parameters:
        `lsnr` - may be null
      Throws:
        `IllegalArgumentException`

    - #### I2PTunnel

          public I2PTunnel(TunnelController tc)

      New standard constructor in router, with back ref to tc
      Parameters:
        `tc` - may be null
      Throws:
        `IllegalArgumentException`

  - ### Method Detail

    - #### addConnectionEventListener

          public void addConnectionEventListener(I2PTunnel.ConnectionEventListener lsnr)

      Registers a listener for connection events.

      The listener will be notified of router disconnection events.

      Parameters:
        `lsnr` - the listener to add; ignored if null

    - #### addSession

          void addSession(I2PSession session)

      Parameters:
        `session` - null ok

    - #### getClientOptions

          public Properties getClientOptions()

      Generic options used for clients and servers. NOT a copy, Do NOT modify for per-connection options, make a copy.
      Returns:
        non-null, NOT a copy, do NOT modify for per-connection options

    - #### getContext

          public I2PAppContext getContext()

      Gets the application context.
      Returns:
        the I2P application context

    - #### getController

          TunnelController getController()

      TunnelController that constructed this, or null.
      Returns:
        controller or null

    - #### getSessions

          public List<I2PSession> getSessions()

      Returns:
        A copy, unmodifiable, non-null

    - #### log

          public void log(String s)

      Log the given message (using both the logging subsystem and standard output...)
      Specified by:
        `log` in interface `Logging`

    - #### main

          public static void main(String[] args)

    - #### removeConnectionEventListener

          public void removeConnectionEventListener(I2PTunnel.ConnectionEventListener lsnr)

      Unregisters a connection event listener.
      Parameters:
        `lsnr` - the listener to remove; ignored if null

    - #### removeSession

          void removeSession(I2PSession session)

      Parameters:
        `session` - null ok

    - #### routerDisconnected

          void routerDisconnected()

      Called when the router disconnects unexpectedly.

      This method notifies all registered ConnectionEventListeners that the router connection has been lost.

    - #### runClient

          public void runClient(String[] args,
                                Logging l)

      Run the client on the given port number pointing at the specified destination (either the base64 of the destination or file:fileNameContainingDestination). Sets the event "clientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error) Also sets the event "openClientResult" = "error" or "ok" (before setting the value to "ok" it also adds "Ready! Port #" to the logger as well). In addition, it will also set "clientLocalPort" = Integer port number if the client is listening sharedClient parameter is a String "true" or "false"
      Parameters:
        `args` - {portNumber, destinationBase64 or "file:filename"[, sharedClient [, privKeyFile]]}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runClientOptions

          public void runClientOptions(String[] args,
                                       Logging l)

      Configure the extra I2CP options to use in any subsequent I2CP sessions. Generic options used for clients and servers Usage: "clientoptions[ key=value]*" . Sets the event "clientoptions_onResult" = "ok" after completion. Deprecated To be made private, use setClientOptions(). This does NOT update a running TunnelTask.
      Parameters:
        `args` - each args[i] is a key=value pair to add to the options
        `l` - logger to receive events and output

    - #### runClose

          public void runClose(String[] args,
                               Logging l)

      Close the given task (or all tasks), optionally forcing them to die a hard death Sets the event "closeResult" = "ok" after the closing is complete
      Parameters:
        `args` - {jobNumber}, {"forced", jobNumber}, {"forced", "all"}, {"destroy", jobNumber}, {"destroy", "all"}
        `l` - logger to receive events and output

    - #### runCommand

          public void runCommand(String cmd,
                                 Logging l)

      Parses and executes a tunnel management command.

      This method is the command dispatcher for tunnel management operations. It parses the command string into command name and arguments, then dispatches to the appropriate handler method.

      Supported Commands:

      - help - Display available commands
      - client/server - Create tunnel instances
      - list - List active tunnels
      - close - Close tunnels
      - config - Configure I2CP connection
      - genkeys - Generate destination keys
      Parameters:
        `cmd` - the command string to execute, format: "commandName arg1 arg2 ..."
        `l` - the Logging instance for command output
      See Also:
        `runHelp(Logging)`

    - #### runConnectClient

          public void runConnectClient(String[] args,
                                       Logging l)

      Run a CONNECT client on the given port number
      Parameters:
        `args` - {portNumber[, sharedClient][, proxy to be used for the WWW]}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runHttpBidirServer

          public void runHttpBidirServer(String[] args,
                                         Logging l)

      Run the HTTP server pointing at the host and port specified using the private i2p destination loaded from the specified file, replacing the HTTP headers so that the Host: specified is the one spoofed. Also runs an HTTP proxy for bidirectional communications on the same tunnel destination.

      Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error) Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after 'ok'). So, success = serverTaskId != -1 and openServerResult = ok.

      Parameters:
        `args` - {hostname, portNumber, proxyPortNumber, spoofedHost, privKeyFilename}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runHttpClient

          public void runHttpClient(String[] args,
                                    Logging l)

      Run an HTTP client on the given port number Sets the event "httpclientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error). Also sets "httpclientStatus" = "ok" or "error" after the client tunnel has started. parameter sharedClient is a String, either "true" or "false"
      Parameters:
        `args` - {portNumber[, sharedClient][, proxy to be used for the WWW]}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runHttpServer

          public void runHttpServer(String[] args,
                                    Logging l)

      Run the HTTP server pointing at the host and port specified using the private i2p destination loaded from the specified file, replacing the HTTP headers so that the Host: specified is the one spoofed.

      Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error) Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after 'ok'). So, success = serverTaskId != -1 and openServerResult = ok.

      Parameters:
        `args` - {hostname, portNumber, spoofedHost, privKeyFilename}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runIrcClient

          public void runIrcClient(String[] args,
                                   Logging l)

      Run an IRC client on the given port number Sets the event "ircclientTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error). Also sets "ircclientStatus" = "ok" or "error" after the client tunnel has started. parameter sharedClient is a String, either "true" or "false"
      Parameters:
        `args` - {portNumber,destinationBase64 or "file:filename" [, sharedClient [, privKeyFile]]}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runIrcServer

          public void runIrcServer(String[] args,
                                   Logging l)

      Same args as runServer (we should stop duplicating all this code...)
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runListenOn

          public void runListenOn(String[] args,
                                  Logging l)

      Specify the hostname / IP address of the interface that the tunnels should bind to Sets the event "listen_onResult" = "ok" or "error" after the interface has been specified
      Parameters:
        `args` - {hostname}
        `l` - logger to receive events and output

    - #### runReadTimeout

          public void runReadTimeout(String[] args,
                                     Logging l)

      Specify the read timeout going to be used for newly-created I2PSockets Sets the event "read_timeoutResult" = "ok" or "error" after the interface has been specified
      Parameters:
        `args` - {hostname}
        `l` - logger to receive events and output

    - #### runServer

          public void runServer(String[] args,
                                Logging l)

      Run the server pointing at the host and port specified using the private i2p destination loaded from the specified file.

      Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error) Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after 'ok'). So, success = serverTaskId != -1 and openServerResult = ok.

      Parameters:
        `args` - {hostname, portNumber, privKeyFilename}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runSOCKSIRCTunnel

          public void runSOCKSIRCTunnel(String[] args,
                                        Logging l)

      Run an SOCKS IRC tunnel on the given port number
      Parameters:
        `args` - {portNumber [, sharedClient]} or (portNumber, ignored (false), privKeyFile)
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runSOCKSTunnel

          public void runSOCKSTunnel(String[] args,
                                     Logging l)

      Run an SOCKS tunnel on the given port number Sets the event "sockstunnelTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error). Also sets "openSOCKSTunnelResult" = "ok" or "error" after the client tunnel has started.
      Parameters:
        `args` - {portNumber [, sharedClient]} or (portNumber, ignored (false), privKeyFile)
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runStreamrClient

          public void runStreamrClient(String[] args,
                                       Logging l)

      Streamr client
      Parameters:
        `args` - {targethost, targetport, destinationString}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runStreamrServer

          public void runStreamrServer(String[] args,
                                       Logging l)

      Streamr server
      Parameters:
        `args` - {port, privkeyfile}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### runTextServer

          public void runTextServer(String[] args,
                                    Logging l)

      Run the server pointing at the host and port specified using the private i2p destination loaded from the given base64 stream.

      Deprecated? Why run a server with a private destination? Not available from the war GUI Sets the event "serverTaskId" = Integer(taskId) after the tunnel has been started (or -1 on error) Also sets the event "openServerResult" = "ok" or "error" (displaying "Ready!" on the logger after 'ok'). So, success = serverTaskId != -1 and openServerResult = ok.

      Parameters:
        `args` - {hostname, portNumber, privKeyBase64}
        `l` - logger to receive events and output
      Throws:
        `IllegalArgumentException` - on config problem

    - #### setClientOptions

          public void setClientOptions(Properties opts)

      Generic options used for clients and servers. This DOES update a running TunnelTask, but NOT the session. A more efficient runClientOptions(). Defaults in opts properties are not recommended, they may or may not be honored.
      Parameters:
        `opts` - non-null