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 - all end to end encryption is done transparently within the client's I2PSession itself. 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 occation 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 up a Hash
 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 details
 boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, java.util.Set tagsSent)
           
 boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, java.util.Set tagsSent, int proto, int fromport, int toport)
          See I2PSessionMuxedImpl for details
 boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, java.util.Set tagsSent, long expire)
           
 boolean sendMessage(Destination dest, byte[] payload, int offset, int size, SessionKey keyUsed, java.util.Set tagsSent, long expire, int proto, int fromport, int toport)
          See I2PSessionMuxedImpl for details
 boolean sendMessage(Destination dest, byte[] payload, SessionKey keyUsed, java.util.Set tagsSent)
          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
 

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 details

Throws:
I2PSessionException

sendMessage

boolean sendMessage(Destination dest,
                    byte[] payload,
                    SessionKey keyUsed,
                    java.util.Set tagsSent)
                    throws I2PSessionException
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 - 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 - 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,
                    java.util.Set tagsSent)
                    throws I2PSessionException
Throws:
I2PSessionException

sendMessage

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

sendMessage

boolean sendMessage(Destination dest,
                    byte[] payload,
                    int offset,
                    int size,
                    SessionKey keyUsed,
                    java.util.Set tagsSent,
                    int proto,
                    int fromport,
                    int toport)
                    throws I2PSessionException
See I2PSessionMuxedImpl for details

Throws:
I2PSessionException

sendMessage

boolean sendMessage(Destination dest,
                    byte[] payload,
                    int offset,
                    int size,
                    SessionKey keyUsed,
                    java.util.Set tagsSent,
                    long expire,
                    int proto,
                    int fromport,
                    int toport)
                    throws I2PSessionException
See I2PSessionMuxedImpl for details

Throws:
I2PSessionException

receiveMessage

byte[] receiveMessage(int msgId)
                      throws I2PSessionException
Receive a message that the router has notified the client about, returning the payload.

Parameters:
msgId - message to fetch
Returns:
unencrypted body of the message
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.

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 up a Hash

Throws:
I2PSessionException

bandwidthLimits

int[] bandwidthLimits()
                      throws I2PSessionException
Get the current bandwidth limits

Throws:
I2PSessionException

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