## net.i2p.client
Interface I2PSession

All Known Implementing Classes:
  I2PSessionImpl, I2PSessionImpl2, I2PSessionMuxedImpl, I2PSimpleSession

    public interface I2PSession

Define the standard means of sending and receiving messages on the I2P network by using the I2CP (the client protocol). This is done over a bidirectional TCP socket and never sends any private keys. End to end encryption in I2PSession was disabled in release 0.6. Periodically the router will ask the client to authorize a new set of tunnels to be allocated to the client, which the client can accept by sending a `LeaseSet` signed by the `Destination`. In addition, the router may on occasion provide the client with an updated clock offset so that the client can stay in sync with the network (even if the host computer's clock is off).

Field Summary
`static int` `PORT_ANY`
`static int` `PORT_UNSPECIFIED`
`static int` `PROTO_ANY`
`static int` `PROTO_DATAGRAM`
`static int` `PROTO_STREAMING`
`static int` `PROTO_UNSPECIFIED`

Method Summary
`void` `addMuxedSessionListener(I2PSessionMuxedListener l, int proto, int port)` See I2PSessionMuxedImpl for details
`void` `addSessionListener(I2PSessionListener lsnr, int proto, int port)` See I2PSessionMuxedImpl for details
`int[]` `bandwidthLimits()` Get the current bandwidth limits.
`void` `connect()` Actually connect the session and start receiving/sending messages
`void` `destroySession()` Tear down the session and release any resources.
`PrivateKey` `getDecryptionKey()` Retrieve the decryption PrivateKey associated with the Destination
`Destination` `getMyDestination()` Retrieve the Destination this session serves as the endpoint for.
`SigningPrivateKey` `getPrivateKey()` Retrieve the signing SigningPrivateKey associated with the Destination
`boolean` `isClosed()` Have we closed the session?
`Destination` `lookupDest(Hash h)` Lookup a Destination by Hash.
`Destination` `lookupDest(Hash h, long maxWait)` Blocking.
`byte[]` `receiveMessage(int msgId)` Receive a message that the router has notified the client about, returning the payload.
`void` `removeListener(int proto, int port)` See I2PSessionMuxedImpl for details
`void` `reportAbuse(int msgId, int severity)` Instruct the router that the message received was abusive (including how abusive on a 1-100 scale) in the hopes the router can do something to minimize receiving abusive messages like that in the future.
`boolean` `sendMessage(Destination dest, byte[] payload)` Send a new message to the given destination, containing the specified payload, returning true if the router feels confident that the message was delivered.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size)`
`boolean` `sendMessage(Destination dest, byte[] payload, int proto, int fromport, int toport)` See I2PSessionMuxedImpl for proto/port details.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set tagsSent)` End-to-End Crypto is disabled, tags and keys are ignored.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set tagsSent, int proto, int fromport, int toport)` See I2PSessionMuxedImpl for proto/port details.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set tagsSent, long expire)` End-to-End Crypto is disabled, tags and keys are ignored.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set tagsSent, long expire, int proto, int fromport, int toport)` See I2PSessionMuxedImpl for proto/port details.
`boolean` `sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, Set tagsSent, long expire, int proto, int fromport, int toport, int flags)` See I2PSessionMuxedImpl for proto/port details.
`boolean` `sendMessage(Destination dest, byte[] payload, SessionKey keyUsed, Set tagsSent)` End-to-End Crypto is disabled, tags and keys are ignored! Like sendMessage above, except the key used and the tags sent are exposed to the application.
`void` `setSessionListener(I2PSessionListener lsnr)` Instruct the I2PSession where it should send event notifications
`void` `updateOptions(Properties options)` Does not remove properties previously present but missing from this options parameter.

Field Detail

### PORT_ANY

    static final int PORT_ANY

See Also:
  Constant Field Values

### PORT_UNSPECIFIED

    static final int PORT_UNSPECIFIED

See Also:
  Constant Field Values

### PROTO_ANY

    static final int PROTO_ANY

See Also:
  Constant Field Values

### PROTO_UNSPECIFIED

    static final int PROTO_UNSPECIFIED

See Also:
  Constant Field Values

### PROTO_STREAMING

    static final int PROTO_STREAMING

See Also:
  Constant Field Values

### PROTO_DATAGRAM

    static final int PROTO_DATAGRAM

See Also:
  Constant Field Values

Method Detail

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload)
                        throws I2PSessionException

  Send a new message to the given destination, containing the specified payload, returning true if the router feels confident that the message was delivered.

  Parameters:
    `dest` - location to send the message
    `payload` - body of the message to be sent (unencrypted)
  Returns:
    whether it was accepted by the router for delivery or not
  Throws:
    `I2PSessionException`

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size)
                        throws I2PSessionException

  Throws:
    `I2PSessionException`

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int proto,
                        int fromport,
                        int toport)
                        throws I2PSessionException

  See I2PSessionMuxedImpl for proto/port details.

  Throws:
    `I2PSessionException`
  Since:
    0.7.1

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        SessionKey keyUsed,
                        Set tagsSent)
                        throws I2PSessionException

  End-to-End Crypto is disabled, tags and keys are ignored! Like sendMessage above, except the key used and the tags sent are exposed to the application.

  If some application layer message delivery confirmation is used, rather than i2p's (slow) built in confirmation via guaranteed delivery mode, the application can update the SessionKeyManager, ala:

         SessionKeyManager.getInstance().tagsDelivered(dest.getPublicKey(), keyUsed, tagsSent);

  If an application is using guaranteed delivery mode, this is not useful, but for applications using best effort delivery mode, if they can know with certainty that a message was delivered and can update the SessionKeyManager appropriately, a significant performance boost will occur (subsequent message encryption and decryption will be done via AES and a SessionTag, rather than ElGamal+AES, which is 1000x slower).

  Parameters:
    `dest` - location to send the message
    `payload` - body of the message to be sent (unencrypted)
    `keyUsed` - UNUSED, IGNORED. Session key delivered to the destination for association with the tags sent. This is essentially an output parameter - keyUsed.getData() is ignored during this call, but after the call completes, it will be filled with the bytes of the session key delivered. Typically the key delivered is the same one as the key encrypted with, but not always. If this is null then the key data will not be exposed.
    `tagsSent` - UNUSED, IGNORED. Set of tags delivered to the peer and associated with the keyUsed. This is also an output parameter - the contents of the set is ignored during the call, but afterwards it contains a set of SessionTag objects that were sent along side the given keyUsed.
  Throws:
    `I2PSessionException`

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size,
                        SessionKey keyUsed,
                        Set tagsSent)
                        throws I2PSessionException

  End-to-End Crypto is disabled, tags and keys are ignored.

  Parameters:
    `keyUsed` - UNUSED, IGNORED.
    `tagsSent` - UNUSED, IGNORED.
  Throws:
    `I2PSessionException`

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size,
                        SessionKey keyUsed,
                        Set tagsSent,
                        long expire)
                        throws I2PSessionException

  End-to-End Crypto is disabled, tags and keys are ignored.

  Parameters:
    `keyUsed` - UNUSED, IGNORED.
    `tagsSent` - UNUSED, IGNORED.
  Throws:
    `I2PSessionException`
  Since:
    0.7.1

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size,
                        SessionKey keyUsed,
                        Set tagsSent,
                        int proto,
                        int fromport,
                        int toport)
                        throws I2PSessionException

  See I2PSessionMuxedImpl for proto/port details. End-to-End Crypto is disabled, tags and keys are ignored.

  Parameters:
    `keyUsed` - UNUSED, IGNORED.
    `tagsSent` - UNUSED, IGNORED.
  Throws:
    `I2PSessionException`
  Since:
    0.7.1

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size,
                        SessionKey keyUsed,
                        Set tagsSent,
                        long expire,
                        int proto,
                        int fromport,
                        int toport)
                        throws I2PSessionException

  See I2PSessionMuxedImpl for proto/port details. End-to-End Crypto is disabled, tags and keys are ignored.

  Parameters:
    `keyUsed` - UNUSED, IGNORED.
    `tagsSent` - UNUSED, IGNORED.
  Throws:
    `I2PSessionException`
  Since:
    0.7.1

### sendMessage

    boolean sendMessage(Destination dest,
                        byte[] payload,
                        int offset,
                        int size,
                        SessionKey keyUsed,
                        Set tagsSent,
                        long expire,
                        int proto,
                        int fromport,
                        int toport,
                        int flags)
                        throws I2PSessionException

  See I2PSessionMuxedImpl for proto/port details. End-to-End Crypto is disabled, tags and keys are ignored.

  Parameters:
    `keyUsed` - UNUSED, IGNORED.
    `tagsSent` - UNUSED, IGNORED.
  Throws:
    `I2PSessionException`
  Since:
    0.8.4

### receiveMessage

    byte[] receiveMessage(int msgId)
                          throws I2PSessionException

  Receive a message that the router has notified the client about, returning the payload. This may only be called once for a given msgId (until the counter wraps)

  Parameters:
    `msgId` - message to fetch
  Returns:
    unencrypted body of the message, or null if not found
  Throws:
    `I2PSessionException`

### reportAbuse

    void reportAbuse(int msgId,
                     int severity)
                     throws I2PSessionException

  Instruct the router that the message received was abusive (including how abusive on a 1-100 scale) in the hopes the router can do something to minimize receiving abusive messages like that in the future. Unused. Not fully implemented.

  Parameters:
    `msgId` - message that was abusive (or -1 for not message related)
    `severity` - how abusive
  Throws:
    `I2PSessionException`

### setSessionListener

    void setSessionListener(I2PSessionListener lsnr)

  Instruct the I2PSession where it should send event notifications

  Parameters:
    `lsnr` - listener to retrieve events

### destroySession

    void destroySession()
                        throws I2PSessionException

  Tear down the session and release any resources.

  Throws:
    `I2PSessionException`

### connect

    void connect()
                 throws I2PSessionException

  Actually connect the session and start receiving/sending messages

  Throws:
    `I2PSessionException`

### isClosed

    boolean isClosed()

  Have we closed the session?

  Returns:
    true if the session is closed

### getMyDestination

    Destination getMyDestination()

  Retrieve the Destination this session serves as the endpoint for. Returns null if no destination is available.

### getDecryptionKey

    PrivateKey getDecryptionKey()

  Retrieve the decryption PrivateKey associated with the Destination

### getPrivateKey

    SigningPrivateKey getPrivateKey()

  Retrieve the signing SigningPrivateKey associated with the Destination

### lookupDest

    Destination lookupDest(Hash h)
                           throws I2PSessionException

  Lookup a Destination by Hash. Blocking. Waits a max of 10 seconds by default.

  Throws:
    `I2PSessionException`

### lookupDest

    Destination lookupDest(Hash h,
                           long maxWait)
                           throws I2PSessionException

  Blocking.

  Parameters:
    `maxWait` - ms
  Returns:
    null on failure
  Throws:
    `I2PSessionException`
  Since:
    0.8.3

### updateOptions

    void updateOptions(Properties options)

  Does not remove properties previously present but missing from this options parameter.

  Parameters:
    `options` - non-null
  Since:
    0.8.4

### bandwidthLimits

    int[] bandwidthLimits()
                          throws I2PSessionException

  Get the current bandwidth limits. Blocking.

  Throws:
    `I2PSessionException`
  Since:
    0.8.3

### addSessionListener

    void addSessionListener(I2PSessionListener lsnr,
                            int proto,
                            int port)

  See I2PSessionMuxedImpl for details

### addMuxedSessionListener

    void addMuxedSessionListener(I2PSessionMuxedListener l,
                                 int proto,
                                 int port)

  See I2PSessionMuxedImpl for details

### removeListener

    void removeListener(int proto,
                        int port)

  See I2PSessionMuxedImpl for details