net.i2p.sam

## Class MasterSession

- java.lang.Object
- - net.i2p.sam.SAMStreamSession
  - - net.i2p.sam.SAMv3StreamSession
    - - net.i2p.sam.MasterSession

- All Implemented Interfaces:
    Closeable, AutoCloseable, I2PSessionListener, I2PSessionMuxedListener, SAMDatagramReceiver, SAMMessageSess, SAMRawReceiver, Session

      class MasterSession
      extends SAMv3StreamSession
      implements SAMDatagramReceiver, SAMRawReceiver, SAMMessageSess, I2PSessionMuxedListener

  A session that does nothing, but implements interfaces for raw, datagram, and streaming for convenience. We extend SAMv3StreamSession as we must have it set up the I2PSession, in case user adds a STREAM session (and he probably will). This session receives all data from I2P, but you can't send any data on it.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class net.i2p.sam.SAMStreamSession

      `SAMStreamSession.DisconnectListener, SAMStreamSession.SAMStreamSessionServer, SAMStreamSession.SAMStreamSessionSocketReader, SAMStreamSession.SAMv1StreamSessionSocketReader, SAMStreamSession.StreamSender`

  - ### Field Summary

    - ### Fields inherited from class net.i2p.sam.SAMStreamSession

      `_isOwnSession, _log, canCreate, DEFAULT_FORCE_FLUSH, forceFlush, PROP_FORCE_FLUSH, recv, server, SOCKET_HANDLER_BUF_SIZE, socketMgr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MasterSession(String nick, SAMv3DatagramServer dgServer, SAMv3Handler handler, Properties props)` Build a Session according to information registered with the given nickname.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `accept(SAMv3Handler handler, boolean verbose)` Accept a single incoming STREAM on the socket stolen from the handler.
    `String` | `add(String nick, String style, Properties props)` Add a session
    `void` | `close()` Close the primary/master session and all subsessions.
    `void` | `connect(SAMv3Handler handler, String dest, Properties props)` Connect the SAM STREAM session to the specified Destination for a single connection, using the socket stolen from the handler.
    `void` | `disconnected(I2PSession session)` Notify the client that the session has been terminated.
    `void` | `errorOccurred(I2PSession session, String message, Throwable error)` Notify the client that some error occurred.
    `int` | `getListenPort()`
    `int` | `getListenProtocol()`
    `void` | `messageAvailable(I2PSession session, int msgId, long size)` Will be called only if you register via setSessionListener() or addSessionListener().
    `void` | `messageAvailable(I2PSession session, int msgId, long size, int proto, int fromPort, int toPort)` Instruct the client that the given session has received a message Will be called only if you register via addMuxedSessionListener().
    `void` | `receiveDatagramBytes(Destination sender, byte[] data, int proto, int fromPort, int toPort)` Send a byte array to a SAM client.
    `void` | `receiveRawBytes(byte[] data, int proto, int fromPort, int toPort)` Send a byte array to a SAM client, without informations regarding the sender.
    `String` | `remove(String nick, Properties props)` Remove a session
    `void` | `reportAbuse(I2PSession session, int severity)` Instruct the client that the session specified seems to be under attack and that the client may wish to move its destination to another router.
    `void` | `start()` Overridden to start the acceptor.
    `void` | `startForwardingIncoming(Properties props, boolean sendPorts)` Forward sockets from I2P to the host/port provided.
    `void` | `stopDatagramReceiving()` Does nothing.
    `void` | `stopForwardingIncoming()` does nothing
    `void` | `stopRawReceiving()` Does nothing.

    - ### Methods inherited from class net.i2p.sam.SAMv3StreamSession

      `getDB, getNick, getSocketServer, queueSocket`

    - ### Methods inherited from class net.i2p.sam.SAMStreamSession

      `checkSocketHandlerId, closeConnection, connect, createSocketHandler, getDestination, getSocketReader, isDestroyed, newSAMStreamSessionSocketReader, newStreamSender, removeSocketHandler, sendBytes, sendBytes, sendBytes, setReceiveLimit`

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

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

    - ### Methods inherited from interface net.i2p.sam.SAMMessageSess

      `getDestination, sendBytes, sendBytes`

- - ### Constructor Detail

    - #### MasterSession

          public MasterSession(String nick,
                               SAMv3DatagramServer dgServer,
                               SAMv3Handler handler,
                               Properties props)
                        throws IOException,
                               DataFormatException,
                               SAMException

      Build a Session according to information registered with the given nickname. Caller MUST call start().
      Parameters:
        `nick` - nickname of the session
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

  - ### Method Detail

    - #### accept

          public void accept(SAMv3Handler handler,
                             boolean verbose)
                      throws SAMException

      Description copied from class: `SAMv3StreamSession`
      Accept a single incoming STREAM on the socket stolen from the handler. As of version 3.2 (0.9.24), multiple simultaneous accepts are allowed. Accepts and forwarding may not be done at the same time.
      Overrides:
        `accept` in class `SAMv3StreamSession`
      Parameters:
        `handler` - The handler that communicates with the requesting client
        `verbose` - If true, SAM will send the Base64-encoded peer Destination of an incoming socket as the first line of data sent to its client on the handler socket
      Throws:
        `SAMException` - always

    - #### add

          public String add(String nick,
                            String style,
                            Properties props)

      Add a session
      Returns:
        null for success, or error message

    - #### close

          public void close()

      Close the primary/master session and all subsessions. Overridden to stop the acceptor and the subsessions.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `SAMMessageSess`
      Overrides:
        `close` in class `SAMv3StreamSession`

    - #### connect

          public void connect(SAMv3Handler handler,
                              String dest,
                              Properties props)
                       throws I2PException

      Description copied from class: `SAMv3StreamSession`
      Connect the SAM STREAM session to the specified Destination for a single connection, using the socket stolen from the handler.
      Overrides:
        `connect` in class `SAMv3StreamSession`
      Parameters:
        `handler` - The handler that communicates with the requesting client
        `dest` - Base64-encoded Destination to connect to
        `props` - Options to be used for connection
      Throws:
        `I2PException` - always

    - #### disconnected

          public void disconnected(I2PSession session)

      Description copied from interface: `I2PSessionMuxedListener`
      Notify the client that the session has been terminated. All registered listeners will be called.
      Specified by:
        `disconnected` in interface `I2PSessionListener`
      Specified by:
        `disconnected` in interface `I2PSessionMuxedListener`

    - #### errorOccurred

          public void errorOccurred(I2PSession session,
                                    String message,
                                    Throwable error)

      Description copied from interface: `I2PSessionMuxedListener`
      Notify the client that some error occurred. All registered listeners will be called.
      Specified by:
        `errorOccurred` in interface `I2PSessionListener`
      Specified by:
        `errorOccurred` in interface `I2PSessionMuxedListener`
        `error` - can be null? or not?

    - #### getListenPort

          public int getListenPort()

      Specified by:
        `getListenPort` in interface `SAMMessageSess`
      Overrides:
        `getListenPort` in class `SAMStreamSession`

    - #### getListenProtocol

          public int getListenProtocol()

      Specified by:
        `getListenProtocol` in interface `SAMMessageSess`
      Overrides:
        `getListenProtocol` in class `SAMStreamSession`

    - #### messageAvailable

          public void messageAvailable(I2PSession session,
                                       int msgId,
                                       long size)

      Description copied from interface: `I2PSessionMuxedListener`
      Will be called only if you register via setSessionListener() or addSessionListener(). And if you are doing that, just use I2PSessionListener. If you register via addSessionListener(), this will be called only for the proto(s) and toport(s) you register for. After this is called, the client should call receiveMessage(msgId). There is currently no method for the client to reject the message. If the client does not call receiveMessage() within a timeout period (currently 30 seconds), the session will delete the message and log an error.
      Specified by:
        `messageAvailable` in interface `I2PSessionListener`
      Specified by:
        `messageAvailable` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to notify
        `msgId` - message number available
        `size` - size of the message - why it's a long and not an int is a mystery

    - #### messageAvailable

          public void messageAvailable(I2PSession session,
                                       int msgId,
                                       long size,
                                       int proto,
                                       int fromPort,
                                       int toPort)

      Description copied from interface: `I2PSessionMuxedListener`
      Instruct the client that the given session has received a message Will be called only if you register via addMuxedSessionListener(). Will be called only for the proto(s) and toport(s) you register for. After this is called, the client should call receiveMessage(msgId). There is currently no method for the client to reject the message. If the client does not call receiveMessage() within a timeout period (currently 30 seconds), the session will delete the message and log an error. Only one listener is called for a given message, even if more than one have registered. See I2PSessionDemultiplexer for details.
      Specified by:
        `messageAvailable` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to notify
        `msgId` - message number available
        `size` - size of the message - why it's a long and not an int is a mystery
        `proto` - 1-254 or 0 for unspecified
        `fromPort` - 1-65535 or 0 for unspecified
        `toPort` - 1-65535 or 0 for unspecified

    - #### receiveDatagramBytes

          public void receiveDatagramBytes(Destination sender,
                                           byte[] data,
                                           int proto,
                                           int fromPort,
                                           int toPort)
                                    throws IOException

      Description copied from interface: `SAMDatagramReceiver`
      Send a byte array to a SAM client.
      Specified by:
        `receiveDatagramBytes` in interface `SAMDatagramReceiver`
      Parameters:
        `sender` - Destination
        `data` - Byte array to be received
        `proto` - I2CP protocol
        `fromPort` - I2CP from port
        `toPort` - I2CP to port
      Throws:
        `IOException` - always

    - #### receiveRawBytes

          public void receiveRawBytes(byte[] data,
                                      int proto,
                                      int fromPort,
                                      int toPort)
                               throws IOException

      Description copied from interface: `SAMRawReceiver`
      Send a byte array to a SAM client, without informations regarding the sender.
      Specified by:
        `receiveRawBytes` in interface `SAMRawReceiver`
      Parameters:
        `data` - Byte array to be received
        `proto` - I2CP protocol
        `fromPort` - I2CP from port
        `toPort` - I2CP to port
      Throws:
        `IOException` - always

    - #### remove

          public String remove(String nick,
                               Properties props)

      Remove a session
      Parameters:
        `props` - ignored, may be null
      Returns:
        null for success, or error message

    - #### reportAbuse

          public void reportAbuse(I2PSession session,
                                  int severity)

      Description copied from interface: `I2PSessionMuxedListener`
      Instruct the client that the session specified seems to be under attack and that the client may wish to move its destination to another router. All registered listeners will be called. Unused. Not fully implemented.
      Specified by:
        `reportAbuse` in interface `I2PSessionListener`
      Specified by:
        `reportAbuse` in interface `I2PSessionMuxedListener`
      Parameters:
        `session` - session to report abuse to
        `severity` - how bad the abuse is

    - #### start

          public void start()

      Overridden to start the acceptor.
      Specified by:
        `start` in interface `SAMMessageSess`
      Overrides:
        `start` in class `SAMStreamSession`

    - #### startForwardingIncoming

          public void startForwardingIncoming(Properties props,
                                              boolean sendPorts)
                                       throws SAMException

      Description copied from class: `SAMv3StreamSession`
      Forward sockets from I2P to the host/port provided. Accepts and forwarding may not be done at the same time.
      Overrides:
        `startForwardingIncoming` in class `SAMv3StreamSession`
      Throws:
        `SAMException` - always

    - #### stopDatagramReceiving

          public void stopDatagramReceiving()

      Does nothing.
      Specified by:
        `stopDatagramReceiving` in interface `SAMDatagramReceiver`

    - #### stopForwardingIncoming

          public void stopForwardingIncoming()

      does nothing
      Overrides:
        `stopForwardingIncoming` in class `SAMv3StreamSession`

    - #### stopRawReceiving

          public void stopRawReceiving()

      Does nothing.
      Specified by:
        `stopRawReceiving` in interface `SAMRawReceiver`