net.i2p.sam

## Class SAMv1Handler

- java.lang.Object
- - net.i2p.sam.SAMHandler
  - - net.i2p.sam.SAMv1Handler

- All Implemented Interfaces:
    Runnable, Handler, SAMDatagramReceiver, SAMRawReceiver, SAMStreamReceiver
  Direct Known Subclasses:
    SAMv2Handler, SAMv3Handler

      class SAMv1Handler
      extends SAMHandler
      implements SAMRawReceiver, SAMDatagramReceiver, SAMStreamReceiver

  Class able to handle a SAM version 1 client connections.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `_id`
    `protected SAMMessageSess` | `datagramSession`
    `protected SAMMessageSess` | `rawSession`
    `protected static String` | `SESSION_ERROR`
    `protected SAMStreamSession` | `streamSession`

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

      `_log, bridge, i2cpProps, socket, stopHandler, stopLock, thread, verMajor, verMinor`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SAMv1Handler(SocketChannel s, int verMajor, int verMinor, Properties i2cpProps, SAMBridge parent)` Create a new SAM version 1 handler.
    `SAMv1Handler(SocketChannel s, int verMajor, int verMinor, SAMBridge parent)` Create a new SAM version 1 handler.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static String` | `createMessageString(String msg)` Create a string to be appended to a status.
    `protected boolean` | `execDatagramMessage(String opcode, Properties props)`
    `protected boolean` | `execDestMessage(String opcode, Properties props)`
    `protected boolean` | `execNamingMessage(String opcode, Properties props)`
    `protected boolean` | `execRawMessage(String opcode, Properties props)`
    `protected boolean` | `execSessionMessage(String opcode, Properties props)`
    `protected boolean` | `execStreamClose(Properties props)`
    `protected boolean` | `execStreamConnect(Properties props)`
    `protected boolean` | `execStreamMessage(String opcode, Properties props)`
    `protected boolean` | `execStreamSend(Properties props)`
    `protected SAMMessageSess` | `getDatagramSession()`
    `protected SAMMessageSess` | `getRawSession()`
    `protected SAMStreamSession` | `getStreamSession()`
    `void` | `handle()` Actually handle the SAM protocol.
    `void` | `notifyStreamDisconnection(int id, String result, String msg)` Notify that a connection has been closed FIXME: this interface should be cleaner
    `void` | `notifyStreamIncomingConnection(int id, Destination d)` Notify about a new incoming connection
    `void` | `notifyStreamOutgoingConnection(int id, String result, String msg)` Notify about a new outgoing connection
    `void` | `notifyStreamSendBufferFree(int id)` Notifies that the outwards buffer is free for writing
    `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.
    `void` | `receiveStreamBytes(int id, ByteBuffer data)` Transmit a byte array from I2P to a SAM client.
    `void` | `stopDatagramReceiving()` Stop receiving data.
    `void` | `stopRawReceiving()` Stop receiving data.
    `void` | `stopStreamReceiving()` Stop receiving data.
    `void` | `streamSendAnswer(int id, String result, String bufferState)` Sends the result of a stream send operation
    `boolean` | `verifVersion()`
    `protected boolean` | `writeString(String s, String msg)` Write a string and message, escaping the message.

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

      `closeClientSocket, getClientSocket, getWriteLock, run, shouldStop, startHandling, stopHandling, toString, writeBytes, writeString, writeString`

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

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

- - ### Field Detail

    - #### _id

          protected final long _id

    - #### datagramSession

          protected SAMMessageSess datagramSession

    - #### rawSession

          protected SAMMessageSess rawSession

    - #### SESSION_ERROR

          protected static final String SESSION_ERROR

      See Also:
        Constant Field Values

    - #### streamSession

          protected SAMStreamSession streamSession

  - ### Constructor Detail

    - #### SAMv1Handler

          public SAMv1Handler(SocketChannel s,
                              int verMajor,
                              int verMinor,
                              Properties i2cpProps,
                              SAMBridge parent)
                       throws SAMException,
                              IOException

      Create a new SAM version 1 handler. This constructor expects that the SAM HELLO message has been still answered (and stripped) from the socket input stream.
      Parameters:
        `s` - Socket attached to a SAM client
        `verMajor` - SAM major version to manage (should be 1)
        `verMinor` - SAM minor version to manage
        `i2cpProps` - properties to configure the I2CP connection (host, port, etc)
      Throws:
        `SAMException`
        `IOException`

    - #### SAMv1Handler

          public SAMv1Handler(SocketChannel s,
                              int verMajor,
                              int verMinor,
                              SAMBridge parent)
                       throws SAMException,
                              IOException

      Create a new SAM version 1 handler. This constructor expects that the SAM HELLO message has been still answered (and stripped) from the socket input stream.
      Parameters:
        `s` - Socket attached to a SAM client
        `verMajor` - SAM major version to manage (should be 1)
        `verMinor` - SAM minor version to manage
      Throws:
        `SAMException`
        `IOException`

  - ### Method Detail

    - #### createMessageString

          protected static String createMessageString(String msg)

      Create a string to be appended to a status.
      Parameters:
        `msg` - may be null
      Returns:
        non-null, "" if msg is null, MESSAGE=msg or MESSAGE="msg a b c" with leading space if msg is non-null

    - #### execDatagramMessage

          protected boolean execDatagramMessage(String opcode,
                                                Properties props)

    - #### execDestMessage

          protected boolean execDestMessage(String opcode,
                                            Properties props)

    - #### execNamingMessage

          protected boolean execNamingMessage(String opcode,
                                              Properties props)

    - #### execRawMessage

          protected boolean execRawMessage(String opcode,
                                           Properties props)

    - #### execSessionMessage

          protected boolean execSessionMessage(String opcode,
                                               Properties props)

    - #### execStreamClose

          protected boolean execStreamClose(Properties props)

    - #### execStreamConnect

          protected boolean execStreamConnect(Properties props)

    - #### execStreamMessage

          protected boolean execStreamMessage(String opcode,
                                              Properties props)

    - #### execStreamSend

          protected boolean execStreamSend(Properties props)

    - #### getDatagramSession

          protected final SAMMessageSess getDatagramSession()

    - #### getRawSession

          protected final SAMMessageSess getRawSession()

    - #### getStreamSession

          protected final SAMStreamSession getStreamSession()

    - #### handle

          public void handle()

      Description copied from class: `SAMHandler`
      Actually handle the SAM protocol.
      Specified by:
        `handle` in class `SAMHandler`

    - #### notifyStreamDisconnection

          public void notifyStreamDisconnection(int id,
                                                String result,
                                                String msg)
                                         throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Notify that a connection has been closed FIXME: this interface should be cleaner
      Specified by:
        `notifyStreamDisconnection` in interface `SAMStreamReceiver`
      Parameters:
        `msg` - may be null
        `id` - Connection id
        `result` - Disconnection reason ("OK" or something else)
      Throws:
        `IOException`

    - #### notifyStreamIncomingConnection

          public void notifyStreamIncomingConnection(int id,
                                                     Destination d)
                                              throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Notify about a new incoming connection
      Specified by:
        `notifyStreamIncomingConnection` in interface `SAMStreamReceiver`
      Parameters:
        `id` - New connection id
        `d` - Destination
      Throws:
        `IOException`

    - #### notifyStreamOutgoingConnection

          public void notifyStreamOutgoingConnection(int id,
                                                     String result,
                                                     String msg)
                                              throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Notify about a new outgoing connection
      Specified by:
        `notifyStreamOutgoingConnection` in interface `SAMStreamReceiver`
      Parameters:
        `msg` - may be null
        `id` - New connection id
        `result` - message result
      Throws:
        `IOException`

    - #### notifyStreamSendBufferFree

          public void notifyStreamSendBufferFree(int id)
                                          throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Notifies that the outwards buffer is free for writing
      Specified by:
        `notifyStreamSendBufferFree` in interface `SAMStreamReceiver`
      Parameters:
        `id` - stream ID
      Throws:
        `IOException`

    - #### 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`

    - #### 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`

    - #### receiveStreamBytes

          public void receiveStreamBytes(int id,
                                         ByteBuffer data)
                                  throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Transmit a byte array from I2P to a SAM client.
      Specified by:
        `receiveStreamBytes` in interface `SAMStreamReceiver`
      Parameters:
        `id` - Connection id
        `data` - Byte array to be received
      Throws:
        `IOException`

    - #### stopDatagramReceiving

          public void stopDatagramReceiving()

      Description copied from interface: `SAMDatagramReceiver`
      Stop receiving data.
      Specified by:
        `stopDatagramReceiving` in interface `SAMDatagramReceiver`

    - #### stopRawReceiving

          public void stopRawReceiving()

      Description copied from interface: `SAMRawReceiver`
      Stop receiving data.
      Specified by:
        `stopRawReceiving` in interface `SAMRawReceiver`

    - #### stopStreamReceiving

          public void stopStreamReceiving()

      Description copied from interface: `SAMStreamReceiver`
      Stop receiving data.
      Specified by:
        `stopStreamReceiving` in interface `SAMStreamReceiver`

    - #### streamSendAnswer

          public void streamSendAnswer(int id,
                                       String result,
                                       String bufferState)
                                throws IOException

      Description copied from interface: `SAMStreamReceiver`
      Sends the result of a stream send operation
      Specified by:
        `streamSendAnswer` in interface `SAMStreamReceiver`
      Parameters:
        `id` - Stream ID
        `result` - information
        `bufferState` - state of the buffer
      Throws:
        `IOException`

    - #### verifVersion

          public boolean verifVersion()

    - #### writeString

          protected boolean writeString(String s,
                                        String msg)

      Write a string and message, escaping the message. Writes s + createMessageString(msg) + \n
      Parameters:
        `s` - The string, non-null