User's Guide:i2p.sam

Module i2p.sam allows Python programs to access the SAM proxy.

With this module, a program can send stream data, datagrams, and raw packets across the I2P network.

Table of contents

1 Sockets 2 Tunnels 2.1 Tunnel Server 2.2 Tunnel Client 3 Errors 4 Constants

Sockets

socket(session, type, samaddr='127.0.0.1:7656', **kwargs)

 Create a new socket.  Argument session should be a session
 name -- if the name has not yet been used, an I2P
 Destination will be created for it, otherwise, the
 existing Destination will be re-used.  An empty session
 string causes a transient session to be created.  Argument
 type is one of SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.
 
 I2P configuration keyword arguments:
 
   * in_depth  - depth of incoming tunnel (default 2)
   * out_depth - depth of outgoing tunnel (default 2)
 
 A single session may be shared by more than one socket, if
 the sockets are the same type, and if the sockets are
 created within the same Python process.  The socket
 objects are multithread-safe.
 
 Examples:
   a = i2p.socket('Alice', i2p.SOCK_STREAM)
   b = i2p.socket('Bob',   i2p.SOCK_DGRAM, 
                  in_depth=2, out_depth=5)
 
 The created object behaves identically to a socket from
 module socket, with the following exceptions:
 
   * I2P Destinations are used as address arguments [1].
   * bind is a no-op: sockets are always bound.
   * send* methods send all data and are non-blocking.
 
 A given session name can only be open in a single Python
 program at a time.  If you need to overcome this
 limitation, consider patching I2P.
 
 [1]. Alternatively, a host name can be used as an address.
      It will be resolved using hosts.txt.
 
 For details on how to use socket objects, see
 http://www.python.org/doc/current/lib/socket-objects.html
 
 See the examples directory for code examples.

socket() object properties:

 dest    - Local I2P Destination of socket
 session - Session name
 type    - Socket type: SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW.

poll()

 Returns a polling object.  Works on SAM sockets and Python sockets.
 See select.poll() in the Python library for more information.

resolve(host, samaddr='127.0.0.1:7656')

 Resolve I2P host name --> I2P Destination.
 Returns the same string if host is already a Destination.

select(readlist, writelist, errlist, timeout=None)

 Performs a select call.  Works on SAM sockets and Python sockets.
 See select.select() in the Python library for more information.

Tunnels

Tunnels allow stream sockets to be joined, so that connections to a listening socket are relayed to one or more sending sockets. This allows an ordinary web server to be exposed as an I2P Destination, or an I2P Destination to be bound as a local port, and so on.

class Tunnel(self, receive, make_send, nconnect=-1, timeout=60.0)

 A Tunnel relays connections from a 'receive' socket to one
 or more 'send' sockets.  The receive socket must be bound
 and listening.  For each incoming connection, a new send
 socket is created by calling make_send().  Data is then
 exchanged between the created streams until one socket is
 closed.  nconnect is the maximum number of simultaneous
 connections (-1 for infinite), and timeout is the time that
 a single connection can last for (None allows a connection
 to last forever).
 
 Sockets must accept stream traffic and support the Python
 socket interface.  A separate daemonic thread is created to
 manage the tunnel.  For high performance, make_send() should
 make a socket and connect in non-blocking mode (you should
 catch and discard the sam.BlockError or socket.error due to
 executing connect on a non-blocking socket).
 
 Security Note:
 A firewall is needed to maintain the end user's anonymity.
 An attacker could keep a tunnel socket open by pinging it
 regularly.  The accepted sockets from 'receive' must prevent
 this by closing down eventually.
 
 Socket errors do not cause the Tunnel to shut down.

close()

 Close all connections made for this tunnel.

Tunnel Server

class TunnelServer(session, port, samaddr='127.0.0.1:7656', nconnect=-1, timeout=None, **kwargs)

 Tunnels incoming SAM streams --> localhost:port.
 
 nconnect and timeout are the maximum number of connections
 and maximum time per connection.  All other arguments are
 passed to sam.socket().  This call blocks until the tunnel
 is ready.

TunnelServer properties:

 dest       - I2P Destination of server. 
 session    - Session name for server.

Tunnel Client

class TunnelClient(session, port, dest, samaddr='127.0.0.1:7656', nconnect=-1, timeout=None, **kwargs)

 Derived from Tunnel.
 Tunnels localhost:port --> I2P Destination dest.
 
 A session named 'session' is created locally, for purposes
 of routing to 'dest'.  nconnect and timeout are the maximum
 number of connections and maximum time per connection.  All
 other arguments are passed to sam.socket().  This call blocks
 until the tunnel is ready.

TunnelClient properties:

 dest       - Local Destination used for routing.
 remotedest - Remote Destination.
 session    - Session name for local Destination.

Errors

class Error(i2p.Error)

 Base class for all SAM errors.

class BlockError(Error)

 Socket call would have blocked.

class ClosedError(Error)

 A command was used on a socket that closed gracefully.

class NetworkError(Error)

 Network error occurred within I2P.

 The error object is a 2-tuple: (errtag, errdesc).
 errtag is a SAM error string,
 errdesc is a human readable error description. 

Constants

Socket types

 SOCK_STREAM = 1
 SOCK_DGRAM = 2
 SOCK_RAW = 3

Packet sizes

 MAX_DGRAM = 31744        # Maximum size for datagram packet
 MAX_RAW = 32768          # Maximum size for raw packet

Flags for recv()

 MSG_DONTWAIT = 128       # Don't block 
 MSG_PEEK = 2             # Peek at incoming data
 MSG_WAITALL = 64         # Wait for all data or error

Polling flags

 POLLIN = 1
 POLLOUT = 4
 POLLERR = 8
 POLLHUP = 16
 POLLNVAL = 32
 POLLPRI = 1