# BASIC Perl SAM Module
# created 2005 by postman (postman@i2pmail.org)


1. What does it do?

The SAM module is a little Perl add-on that  - on one side -
establishes communication with a I2P router's (http://www.i2p.net) SAM bridge
(Simple anonymous messaging ( http://www.i2p.net/sam)). On the
other side it exposes a simple socket like interface to the user.
Over this interface the user can send or receive datastreams from I2P 
destinations as if he would communicate with a normal IP socket.

The SAM module can be integrated into perl scripts that
want to communicate with I2P services.


2. Is this code usable?

This perl module should be considered as proof-of-concept
quality. It did surely work for me and my test setups, but
it might not work at all on your system. If you run into problems
you can contact me.


3. Does ist support DATAGRAM and RAW sessions?

No, at the moment the module only supports STREAM sessions.
Support for other session types might be added in the future.


4. How to install it?
Create a Subfolder called I2P  in your Perl Installation's Net Module 
folder (i.e. /usr/lib/perl5/5.8.4./Net/I2P ) and copy the module there.
You can now use it with use Net::I2P::SAM. 
The module only depends on Net::IO::Socket for operations. This
should be already installed.


5. How to debug?
You can switch on debugging with the constructor ( see below ).


6. How to use it?


$sam = new Net::I2P::SAM('127.0.0.1','7656',1);

# you can omit host/port - then the defult is assumed
# the 3rd argument is the debugging switch. If you switched it on
# there'll be a default debug in /tmp/sam-debug
# $sam will now either contain a object reference or 0
# if it's 0 then we coudl not talk to the SAM bridge at all ( connect failed)
# or we could not agree to a version

# next we can tune the tunnel settings we want for this session:
# The syntax is just like the one used on www.i2p.net/sam

$sam->change_settings("inbound.length=1,inbound.lenghVariance=0,outbound.length=1,outbound.lengthVariance=0,inbound.nickname=fun,outbound.nickname=fun");

# next we open a new session. 
# only stream is supported
# most of the time we use a transient destination
# otherwise state the hosts.txt name you want to use as in your session
# direction is most of the times both :)
# this cab return 1 for success or 0 for failure
$sam->create_session("STREAM","TRANSIENT","BOTH");


# now connect to our service
$sam->connect($sam->lookup("myservice.i2p"));

# or 

$sam->connect("I2PDESTINATIONKEY.....AAAA");

# if this returns 1 - we got a stream session and can now receive and send data
# otherwise consult the debug.



# Send data is just like the the raw perl send
# we send the data as scalar var and optional flags (most of the times 0)
$sam->send($data,0);


# receiving data is similar to the perl recv
# we define the mac number of bytes and optional flags

$indata = $sam->receive(512,0);

# close the session

$sam->close();

# that's the most important things to know.