readme.txt

a open source project in linux for peer to peer on seep

1. GENERAL
===============
SIP2P is a GPLed experimental implementation of the small part of the
SIP Protocol over Peer-To-Peer communication, without central proxy servers
for storing the user data.

2. USED LIBRARIES
=====================
It uses the KadC library (http://kadc.sourceforge.net) for storing and retreiving
data from the kademlia networtk, pthreadcc (http://www.ctie.monash.edu.au/SocketCC/PThreadCC.htm) 
and the socketcc library (http://sourceforge.net/projects/socketcc) for sockets communications.

3. SHORT DESCRIPTION OF SIP2P
================================
The ideal solution would be to design and implement a SIP client, which has this
functionality within. That SIP client would not have to use a SIP server, proxy
or whatever, but would retrieve the addresses of other users over kademlia
and SIP messages would be sent directly to the called party. But for the time
being SIP2P starts an UDP server on the specified port, and actually acts like a
SIP proxy. For testing the address and the port of SIP2P server should be entered as
a SIP proxy in a normal SIP Client (e.g x-Lite, Twinkle, etc.).

4. SUPPORTED CALL FLOWS
===========================
At the moment, only the REGISTER and INVITE messages are supported.
After a REGISTER message is received, the user data will be published
in the kademlia network.

And the processing of INVITE messages is also kept quite simple. When an INVITE message
is received, all lines will be copied, but only the one holding the name of the called
party will be changed. A search in the kademlia network will be started, and that
line will be replaced with name, ip and port number found in the kademlia network.
So prepared INVITE message will be sent to the callee. SIP2P then just forwards the
next few messages between the two parties (TRYING, RINGING, and OK) and then
its job is done.

For documentation on the source code, look for the comments in header files and in the source iself.

5. BUILDING THE PROJECT
==========================
After building the project with "make", an executable will be created in a subfolder called "dist".
So start the program by typing "dist/sip2p".
Optionally an argument can be supplied, with the name of the configuration file. If not
specified, the default name "sip2p.ini" will be used. If that or the specified file
does not exist, the program won't start.

6. CONFIGURATION
====================

The layout of the config file is pretty straight forward. It just uses key-value
pairs for the most important settings.

Below is a simple example, and then follows the explanation.


#--------------SAMPLE BEGIN----------------------
################################################
# INI FILE USED FOR STARTING THE SIP2P SERVER
################################################

###################
# IP and port
######################
S2P_SERVER_IP=<ip address>
S2P_SERVER_PORT=5060;

###################
# KadC conf file location
######################
KADC_INI_FILE=kadc.ini

###################
# Debug TRUE or FALSE
######################
DEBUG=FALSE

#####################
# Publish dummy users 
######################
DUMMY_PUBLISH=TRUE

#####################
# Fast search for dummy users 
######################
DUMMY_FAST_SEARCH=TRUE

#####################
# List of dummy users 
######################
[DUMMY_P2P_USERS]
localx=konj@<ip address>:5062
local=local@<ip address>:5063
#local=local@<ip address>
[DUMMY_P2P_USERS_END]
#--------------SAMPLE END------------------------


Comments start with a '#' sign. All lines starting with a hash key will be
ignored. Actually if a key name cannot be interpreted, the line containing
that key will also be ignored. Also be careful.

The most important settings which must be set for the daily use are
S2P_SERVER_IP and S2P_SERVER_PORT. They contain the ip address, (also the
ip address of the localhost) and the port under which the UDP Server will be
started. They always must be set. The rest is just used for debugging purposes.

The KADC_INI_FILE specifies location of the configuration file for KadCapi, the
library used in this project. It should be always kadc.ini, but for debugging purposes,
when running more then one process of sip2p, then different ports can be specified
for KadC to use in two different configuration files.

If DEBUG option is set to TRUE (it is case sensitive, so TRUE, true, or True... are actually FALSE),
then the program may behave different from normal mode. For details, please look into the source code.

Between the lines [DUMMY_P2P_USERS] and [DUMMY_P2P_USERS_END] you may put names of
some dummy users and their SIP URLs. Actually these may be real SIP accounts, which are just
not available in the kademlia. If preceded by an Hash key #, then theses
dummy users will also be ignored.

If the flag  DUMMY_PUBLISH is TRUE, then the dummy users will be published in the kademlia network.
And if the DUMMY_FAST_SEARCH is set to TRUE, then first the names from the configuration file will be searched,
and not kademlia. That way you may speed up the development process, without having to wait for kademlia searches,
if you are sure they work ok.


7. CLIENTS
=============

v.81 has been tested wtih x-lite v2 which for Windows is e.g. available from
http://www.freespeech.co.uk/downloads/X-Lite-2.0-freespeech.co.uk.exe

The following attributes need to be set:

System Settings -> SIP Proxy -> add a default proxy with
  IP being the sip2p address
  Direct Dial IP=yes

Advanced System Settings - SIP Settings
  Timeout SIP Messages=60000
  Resend SIP Messages=60000



E. Sinanovic (designer and developer) - [e-mail]
M. Alexander (project advisor) - [e-mail]