===================================================================
SIP User Agent README 
====================================================================
Vovida SIP User Agent (ua)
Release 1.4.0
May 16, 2001


====================================================================
LICENSE AND COPYRIGHT 
====================================================================
For information about licensing, please see the LICENSE file in this
directory, or http://www.vovida.org/license.html .

====================================================================
INTRODUCTION 
====================================================================
This directory contains source code for the SIP User Agent (ua). The
SIP User Agent is an implementation of the Vovida SIP stack that 
supports SIP call initiation, setup, and teardown.  You can
make a basic SIP call between two SIP user agents or from a user
agent to a proxy server.


====================================================================
NEW FEATURES AND FUNCTIONALITY IN THIS RELEASE 
====================================================================

Changes since 1.3.0:

-- Persistent TCP connection support.
-- Limited NAT traversal.
-- New Linux sound card device.

Changes since 1.2.0:

-- Added support for direct entry of a URL to dial to Sound Card,
   NullHardware and QuickNet devices in Linux. Note that direct
   URL entry does not work in Windows.

This release implements these new features and functionality:

-- Support for Open Sound System (OSS) compatible sound cards
-- Improved registration support
-- A multitude of bug fixes


====================================================================
KNOWN BUGS OR LIMITATIONS
====================================================================
These bugs or limitations are known to exist:

1. Due to API changes within the sip/base source code, some of the
   ua's functionality has been compromised.  Things that have been
   broken prior to this release are:
   -- consultation and blind transfer
   -- call waiting

2. The ua assumes the codec type is always PCM u-law.

3. The ua does not handle message retransmit timeout.

4. The ua does not do complete SDP negotiation.

5. There is a known problem when using the INTERNAL_IP_DIAL(3) speed
   dial option.  Workaround: Use the new more flexible URL dialing.

6. There is no real implementation of single-line hold.  If
   Ua_Xfer_Mode is set to 'Off', then a flashhook during a call will
   have no effect.  Setting this parameter to 'Transfer' will
   put the far end on hold, but the local ua will then play a
   dialtone and wait for a second connection to be initiated.
   A flashhook or onhook at this point will take the initial
   call off hold, but this is different than stand-alone hold
   functionality.

7. Waiting too long at the URL dial prompt causes the call to time out.
   Workaround: Increase the Initial_Digit_Timeout and Inter_Digit_Timeout
   timer in configuration (ua.cfg) file.

8. Direct URL entry does not work in Windows and requires restarting
   the ua to reset the console input.

9. Early media (18x with SDP) does not work with QuickNet device
   and requires restarting the ua to reset the card.

====================================================================
FIXED LIMITATIONS
====================================================================
These limitations have been fixed:

Changes since 1.3.0:

-- UA now will respond to a 407 on a REGISTER or an INVITE.  It should
   also respond to a 401 on a REGISTER or an INVITE, but that have not
   been tested.
-- Suppress SIP SNMP agent in WIN32.
-- Change size of WIN32 dummy include files to non-zero for Winzip.
-- Eliminate unnecessary error message when turn on a two way RTP
   session by turing on the receiving part first.

Changes since 1.2.0:

-- The SDP message in the ACK message is now checked.
-- QuickNet device is working again RedHat 7.1 and RedHat 7.2.


====================================================================
OTHER IMPLEMENTATION ISSUES
====================================================================
Please see the FAQ for more information.


====================================================================
GETTING STARTED
====================================================================

PLATFORM SUPPORT
--------------------------------------------------------------------
The SIP User Agent will compile and run on Linux and Solaris
operating systems. We have tested the SIP User Agent on:
-- RedHat Linux 6.2 with gcc 2.91.66 (egcs-1.1.2 release)
   and glibc 2.1.3
-- RedHat Linux 7.1, 7.2 and 7.3 with gcc 2.96   
-- Sun Solaris with gcc/g++ 2.96 compiler or Workshop 6 update 1
-- Windows with MSVC++ 6.0, Service Pack 4

The SIP User Agent has been compiled and tested on other
distributions in the past, and should be distribution independent.
Please consult the SIP mailing list as other developers may have
tested the SIP stack and User Agent on other Linux distributions.

SOUND CARD SUPPORT
--------------------------------------------------------------------
Open Sound System (OSS) compatible sound cards should work with the
ua.  We have tested the SIP User Agent with Creative Labs 
SoundBlaster Live! sound card using the emu10k1 driver available at
http://opensource.creative.com/

QUICKNET SUPPORT
--------------------------------------------------------------------
The SIP User Agent can be used with the following 
Quicknet Cards:
-- Internet PhoneJACK Card
-- Internet LineJACK Card
-- Internet PhoneCARD (PCMCIA)

You can connect an analog phone to Internet PhoneJACK or LineJACK card
and initiate a call from the analog phone.  The ua requires the 1.0.0
version of the Quicknet drivers.  

The drivers, and instructions for installing them, are available from

	http://www.openh323.org/driver/build.html

To use the Internet PhoneCard (PCMCIA), connect a headset
(microphone/headset) and use the keyboard to initiate, answer, or
hangup a call.

Quicknet Driver Support
-----------------------

In order to use the Quicknet cards in a Linux machine, you must
install Quicknet Linux drivers.  We have used the 1.0.0 drivers, from 

	http://www.openh323.org/driver/build.html

In our tests, the drivers which come with Redhat 7.1 do NOT work.
Please contact RedHat with support issues with kernels from them, or
upgrade to the 1.0.0 drivers as outlined on the web page above.


COMPILING THE USER AGENT
--------------------------------------------------------------------
To compile the user agent, type:
	make


====================================================================
USING THE USER AGENT
====================================================================
You can make a simple SIP call between two User Agents.  There are
two options supported:
-- SIP signalling without voice path
-- SIP signalling with voice path
   -- using non-PMCIA Quicknet Card
   -- using sound card or Quicknet Internet PhoneCard (PMCIA)

If you want to test SIP signalling without voice (Null Hardware
Option):
--------------------------------------------------------------------
1. Install and compile the SIP stack and SIP User Agent on each    
   machine.
2. Copy and modify the ua.cfg file for each User Agent.
3. Run the User Agent by typing: ua -f ua.cfg. Refer to the "User
   Agent Options" section for more information on other options.
3. Press the 'a' key to go offhook (lift handset).
4. Using the keypad, press the digits keys to dial a number. Or, enter
   a SIP URL.
5. Press the 'z' key to go onhook (hangup). 

If you want to make a voice call with non-PMCIA Quicknet Cards:
--------------------------------------------------------------------
1. Install and compile the SIP stack and SIP User Agent on each    
   machine.
2. Install a Quicknet card and Linux Quicknet drivers on each 
   machine. Connect your phone to the Quicknet card.
3. Copy and Modify the ua.cfg file for each User Agent.
4. Run the User Agent by typing: ua -q -f ua.cfg. Refer to the "User
   Agent Options" section for more information on other options.
5. Using the phone, dial a number. Or, using the keyboard, enter
   a SIP URL.

If you want to make a voice call using a sound card or the Quicknet 
Internet PhoneCARD (PMCIA):
-------------------------------------------------------------------
1. Install and compile the SIP stack and SIP User Agent on each    
   machine.
2. Install the Quicknet Internet PhoneCARD (PMCIA) or sound card.
3. Attach the headset/microphone to your Quicknet card or sound card.
3. Copy and modify the ua.cfg file for each User Agent
4. Run the User Agent by typing: ua -s -f ua.cfg. Refer to the "User Agent
   Options" section for more information on other options, including
   the -s option for sound cards.
5. Press the 'a' key to go offhook (lift handset).
6. Using the keypad, press the digits keys to dial a number. Or, enter
   a SIP URL.
7. Press the 'z' key to go onhook (hangup).

MODIFYING THE UA CONFIGURATION FILE -- ./SampleConfigFiles/ua.cfg
--------------------------------------------------------------------
The ua.cfg is a configuration file for the User Agent. 
You must copy and modify the ua.cfg for each ua.

A sample configuration file, ua.cfg, is include in the ua/SampleConfigFiles/
directory.
The ua.cfg file provides comments that will help you modify the file.  

To make a simple User Agent to User Agent call 
without a proxy server, registration, authentication, 
or other features modify these fields:

1. Specify the a phone number for the User Agent in User_Name. 
2. Add a # before Proxy_Server to disable this option.
3. Turn off registration by changing the Register_On field to False.
4. Add the proper entries to the Speed Dial section, or use the new
   direct entry of a URL.

USER AGENT OPTIONS
-------------------------------------------------------------------
To use the User Agent type:
        ./ua [options]

where options are:
-d   	Run in daemon mode (DO NOT USE.)
-h   	Prints "ua [-dhqr] [-v[<log-level>]] [-f <config-file>]"
-q   	Use a Quicknet card for speech path.
-s   	Use an OSS driver enabled sound card for speech path.
	Note: -s & -q are mutually exclusive.
-r    	Run with retransmission of SIP messages off 
	(Note. This option is not used. Currently retransmission
	is always off. DO NOT USE.)

-f <config-file>Configuration file

-v[<log-level>] This option allows you to operate in debug mode and
		debug comments will appear on your screen. 

		The most commonly used log levels are LOG_DEBUG and
		LOG_DEBUG_STACK.  When emailing the SIP list with
		questions about the ua, we suggest including a ua
		log using -vLOG_DEBUG_STACK. Generally, "debug mode"
		indicates a level of LOG_DEBUG or LOG_DEBUG_STACK.

                  Levels:
                  - LOG_EMERG
                  - LOG_ALERT
                  - LOG_CRIT
                  - LOG_ERR
                  - LOG_WARNING (default)
                  - LOG_NOTICE
                  - LOG_INFO
                  - LOG_DEBUG
                  - LOG_DEBUG_STACK

Note: that there is no space between -v and the log level. For
example, -vLOG_DEBUG, would turn on application level debug messages.

QuickNet Card DIAL OPTIONS
-------------------------------------------------------------------
When initiating a call using your keyboard, this option is supported
after the phone is off-hook:

Key	Action
---     ------
u       Direct entry of a SIP URL

NULL HARDWARE and Sound Card DIAL OPTIONS
-------------------------------------------------------------------
When initiating or receiving a call using your keyboard, these
options are supported:

Key	Action
---     ------
a       Go offhook (lift handset)
z       Go onhook (hangup)
f       Flashook
u       Direct entry of a SIP URL
1-9,#,*	Equivalent buttons on the phone.

DIAL TONES
-------------------------------------------------------------------
Dial tones and ring back tones are generated locally using tone files.  
To enable these tones, copy the directory ua/Tone into the same
directory from where you will run the ua.  The directory must have
proper read permissions.


====================================================================
CONTRIBUTORS 
====================================================================  
This software consists of voluntary contributions made by Vovida
Networks, Inc., Cisco Systems, Inc., and many individuals including:

Luan Dang
Jeff Gao
Cullent Jennings
Sunitha Kumar
Mahesh Shankar
Mitch Zollinger


====================================================================
CONTACT INFORMATION AND WEBSITE
====================================================================
We welcome your feedback, suggestions and contributions. Contact us 
via email if you have questions, feedback, code submissions, and
bug reports.

For general inquiries - info@vovida.org

We have mailing lists for the VOCAL applications and protocol stacks: 
VOCAL - vocal@vovida.org
COPS - cops@vovida.org
MGCP - mgcp@vovida.org
RADIUS - radius@vovida.org
RTP - rtp@vovida.org
SIP - sip@vovida.org
TRIP - trip@vovida.org
You can subscribe to the mailing lists on www.vovida.org. 
