net.i2p.sam

## Class SAMv1Handler

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

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

      public class SAMv1Handler
      extends SAMHandler
      implements SAMRawReceiver, SAMDatagramReceiver, SAMStreamReceiver

  Class able to handle a SAM version 1 client connections.
  Author:
    human

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static long` | `__id`
    `protected long` | `_id`
    `protected SAMDatagramSession` | `datagramSession`
    `protected SAMRawSession` | `rawSession`
    `protected SAMStreamSession` | `streamSession`
    `protected int` | `verMajorId`
    `protected int` | `verMinorId`

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

      `bridge, i2cpProps, socket, thread, verMajor, verMinor`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 SAMDatagramSession` | `getDatagramSession()`
    `protected SAMRawSession` | `getRawSession()`
    `protected SAMStreamSession` | `getStreamSession()`
    `void` | `handle()` Actually handle the SAM protocol.
    `(package private) SAMStreamSession` | `newSAMStreamSession(String destKeystream, String direction, Properties props)`
    `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)` Send a byte array to a SAM client.
    `void` | `receiveRawBytes(byte[] data)` 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()`

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

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

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

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

- - ### Field Detail

    - #### verMajorId

          protected int verMajorId

    - #### verMinorId

          protected int verMinorId

    - #### rawSession

          protected SAMRawSession rawSession

    - #### datagramSession

          protected SAMDatagramSession datagramSession

    - #### streamSession

          protected SAMStreamSession streamSession

    - #### _id

          protected long _id

    - #### __id

          protected static volatile long __id

  - ### Constructor Detail

    - #### SAMv1Handler

          public SAMv1Handler(SocketChannel s,
                      int verMajor,
                      int verMinor)
                       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`

    - #### SAMv1Handler

          public SAMv1Handler(SocketChannel s,
                      int verMajor,
                      int verMinor,
                      Properties i2cpProps)
                       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`

  - ### Method Detail

    - #### getRawSession

          protected SAMRawSession getRawSession()

    - #### getDatagramSession

          protected SAMDatagramSession getDatagramSession()

    - #### getStreamSession

          protected SAMStreamSession getStreamSession()

    - #### verifVersion

          public boolean verifVersion()

    - #### handle

          public void handle()

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

    - #### execSessionMessage

          protected boolean execSessionMessage(String opcode,
                                   Properties props)

    - #### newSAMStreamSession

          SAMStreamSession newSAMStreamSession(String destKeystream,
                                             String direction,
                                             Properties props)
                                         throws IOException,
                                                DataFormatException,
                                                SAMException

      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

    - #### execDestMessage

          protected boolean execDestMessage(String opcode,
                                Properties props)

    - #### execNamingMessage

          protected boolean execNamingMessage(String opcode,
                                  Properties props)

    - #### execDatagramMessage

          protected boolean execDatagramMessage(String opcode,
                                    Properties props)

    - #### execRawMessage

          protected boolean execRawMessage(String opcode,
                               Properties props)

    - #### execStreamMessage

          protected boolean execStreamMessage(String opcode,
                                  Properties props)

    - #### execStreamSend

          protected boolean execStreamSend(Properties props)

    - #### execStreamConnect

          protected boolean execStreamConnect(Properties props)

    - #### execStreamClose

          protected boolean execStreamClose(Properties props)

    - #### receiveRawBytes

          public void receiveRawBytes(byte[] data)
                               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
      Throws:
        `IOException`

    - #### stopRawReceiving

          public void stopRawReceiving()

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

    - #### receiveDatagramBytes

          public void receiveDatagramBytes(Destination sender,
                                  byte[] data)
                                    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
      Throws:
        `IOException`

    - #### stopDatagramReceiving

          public void stopDatagramReceiving()

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

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

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

    - #### 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:
        `id` - New connection id
        `result` - message result
        `msg` - Message
      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`

    - #### 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:
        `id` - Connection id
        `result` - Disconnection reason ("OK" or something else)
        `msg` - Error message, if any
      Throws:
        `IOException`

    - #### stopStreamReceiving

          public void stopStreamReceiving()

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