README for sofsip-cli
=====================

This is a simple SIP VoIP/IM example client demonstrating 
how to use the Sofia-SIP libsofia-sip-ua library interfaces.

Features 
--------

* console mode user-interface (with readline support)
* registration to SIP networks (UDP/TCP/TLS)
* sending OPTIONS request to other SIP nodes
* making and receiving calls (either with dummy media, or 
  basic media support with the gstreamer, see below)
* call control; call transfers, hold
* sending and receiving instant messages
* publishing and subscribing to presence 

Dependencies
------------

Sofsip-cli requires the Sofia-SIP package to be installed. See 
http://sofia-sip.sf.net for more information.

For media support, sofsip-cli comes with multiple media implementations, 
each of which has different set of dependencies to external packages:

1. "--media-impl=fsgst" - GStreamer plus Farsight plugins (default)
    - The current default media implementation. Uses gstreamer-0.10
      elements, plus additional RTP plugins from the Farsight project, 
      to realize basic media support needed for voice calls.
    - deps: gstreamer-0.10, gst-plugins-base and gst-plugins-good, 
	    gst-plugins-farsight; note: known problems with some gst
	    versions, see gnome bugzilla items #348677 and #348675 at
	    http://bugzilla.gnome.org
    - codecs: G711

2. "--media-impl=gstreamer" -  Plain GStreamer
    - Simplified version of "fsgst", which only depends on plugins
      already included in the main gstreamer packages.
    - deps: gstreamer-0.10, gst-plugins-base and gst-plugins-good; see
      notes for "fsgst" above concerning problems with specific gst versions
    - limitations: Like 'fsgst', but no RTCP support, asymmetric RTP and 
      no jitterbuffering.
    - codecs: G711

3. "--media-impl=farsight" - Farsight media library 
    - Uses the libjingle library to provide P2P connectivity (do
      a web search on IETF ICE framework to get more information).
    - deps: farsight, plus all deps of 'fsgst'
    - limitations: does not work yet! (last update: 2006/Jul)
    - codecs: all codecs supported by GStreamer

4. "--media-impl=dummy"     
    - A dummy implementation for testing purposes (does not send
      any RTP packets and silently discards any packets received)
    - deps: no extra packages required
    - limitations: Only useful for testing SIP signaling.
    - codecs: dummy-G711

Sofsip-cli can optionally be compiled against the GNU readline
library (GPL licensed).

Documentation
-------------

Example of basic registration to network follows. You'll
need a SIP account from some provider (try a web search for free
SIP services).

  sh> ./sofsip_cli sip:first.surname@mysipprovider.net
  [ sofsip_cli starts ]
  UA> r
  [ registration is performed, you might get a prompt for password ]
  UA> k mypassword
  [ you should now be succesfully logged in ]

After you are registered, you can send instant messages, and
make calls as follows:

  UA> m sip:friend@otherprovider.net
  Enter message> hi there!
  [ message is sent ]

  UA> i sip:friend@otherprovider.net
  [ an outgoing call is made ]

If you can't, or don't want to, use SIP servers, you can also run
multiple SIP clients, and make calls and send messages directly:

  UA> i sip:192.168.0.1
  [ call to SIP client listening on 192.168.0.1:5060 ]
  UA> i sip:192.168.0.1:40000
  [ call to SIP client listening on non-default port 40000 ]

To select a specific transport protocol, or network protocol (IPv4 or
IPv6), etc, you can use SIP URI params:
 
  UA> ./sofsip_cli --contact="sip:*:5060;transport=tcp,udp"
  [ sofsip_cli will prefer TCP as the transport ]

If you want to explicitly define which SIP registrar to use, or to
use a SIP proxy for outgoing message, use the '--proxy=SIPURI' and
'--registrar=SIPURI' parameters.

If you are behind a NAT, you can use STUN (RFC3489) for NAT
traversal. You'll need an address of an STUN server (try a web
search for free STUN servers):

  sh> ./sofsip_cli --stun-server=stun.someprovider.com
  [ enables STUN support for signaling and media ]

To debug problems, set the "TPORT_LOG" variable to 1 in order to see 
all received and sent signaling messages:

  sh> export TPORT_LOG=1
  sh> ./sofsip_cli sip:foo@myprovider.com

See sofsip_cli(1) man page for more information.

Contact information
-------------------

If you have any questions, or comments, feel free to mail
the developer team to:

   sofia-sip-devel@lists.sourceforge.net

License
-------

LGPL. Note license of GNU readline (GPL), if support for it
is enabled. See file COPYING for full details.
