====================================================================
Feature Server README
====================================================================
Feature Server
Release 1.2.0
March 15, 2001

====================================================================
LICENSE AND COPYRIGHT 
====================================================================
The Vovida Software License, Version 1.0 
Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. The names "VOCAL", "Vovida Open Communication Application Library",
   and "Vovida Open Communication Application Library (VOCAL)" must
   not be used to endorse or promote products derived from this
   software without prior written permission. For written
   permission, please contact vocal@vovida.org.

4. Products derived from this software may not be called "VOCAL", nor
   may "VOCAL" appear in their name, without prior written
   permission of Vovida Networks, Inc.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
--------------------------------------------------------------------
All third party licenses and copyright notices and other required
legends also need to be complied with as well.

====================================================================
INTRODUCTION 
====================================================================
The Feature Server is a SIP proxy in the VOCAL system that executes
one of the features enabled from Vocal Provisioning.   The Feature 
Server supports the following CPL scripts generated from Vocal 
Provisioning:

      Calling Features                   Called Features 
      ================                   ===============
    - 900/976 Blocking                 - Call Return     
    - Caller ID Blocking               - Call Screening 
                                       - Call Forward All Calls
                                       - Call Forward No Answer/Busy 
                             

====================================================================
NEW FEATURES AND FUNCTIONS IN THIS RELEASE 
====================================================================
None 

====================================================================
BUG FIXES 
====================================================================
Query the Bugzilla database on http://www.vovida.org for the
most up-to-date information. 


====================================================================
KNOWN LIMITATIONS
====================================================================
The Feature Server currently supports CPL draft 0.1
(draft-ietf-iptel-cpl-01.ps).  

CPL scripts that are not generated by the Vocal Provisioning are not 
supported.

Bug 194 from Bugzilla remains.  A user cannot use *69 if they have 
both Call Return and Caller ID Blocking enabled.   A user should
disable Caller ID Blocking for *69 to work. 

Bug 331 from Bugzilla remains.  Consultation transfers do not
work with Caller ID Blocking.  A user should disable Caller ID
Blocking for transfer to work.

Call Blocking only screens North American dialing plan numbers
(e.g. 1+(xxx) XXX-XXXX).  If your system requires an external 
access code to reach the PSTN (e.g. 9+xxx+xxxx), you must enter
"9" in the Prefix field when enabling the Call Blocking feature
in Vocal Provisioning.

Call Blocking does not block 1-800 calls.  Unfortunately,
the CPL script also allows long-distance numbers with an area code
that begins with 8 (e.g. 1-8xx-XXX-XXXX) to be established too.

Call Screening works by matching the incoming phone number with
the digits entered in Vocal Provisioning.  The digits must be 
found in the beginning of the phone number.  For example, if 
the incoming number was (408) 555-1000, call screening will block
this number if 4085551000 was entered.  Entering 5551000 will
not screen the incoming call.  Entering 408 as a Call Screening
number will block all incoming calls where the phone number begins
with 408. 

For call-return feature to work, an entry needs to be added in the 
phone dial plan. The entry looks like
   Key: ^sip:\*69
   Value: sip:$USER@CallReturnFeatureServerIp:SipPort
thus when user dials *69, the RS redirect the call to the feature server
which then resolves *69 to actual destination.

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

SOFTWARE DEPENDENCIES
--------------------------------------------------------------------
The Feature Server requires libxml (see 
ftp://rpmfind.net/pub/veillard/libxml/).  Libxml is found in the 
vocal/contrib directory.  The Makefile shows other required Vocal 
software. 


COMPILE INSTRUCTIONS
--------------------------------------------------------------------
When compiling  the Feature Server executable for the first time, do:
a)  cd <your_path_to_software>/vocal/
    make fs

All subsequent compiles can be done by:  
b)  cd <your_path_to_software>/vocal/proxies/fs/base/
    make 


USING THE SOFTWARE
--------------------------------------------------------------------
Usage:  fs [OPTIONS]  PSERVER HOST:PORT 
                      REDUNDANT PSERVER HOST:PORT
                      SIPPORT

        Options: -d   Do not run in daemon mode
                 -f <logfile>  Log to this filename
                 -r   Retransmission off
                 -v <LOG_LEVEL>  Display messages at this level and 
                                 higher urgency. 
                    LOG_LEVEL = LOG_EMERG     (highest urgency)
                                LOG_ALERT
                                LOG_CRIT
                                LOG_ERR
                                LOG_WARNING
                                LOG_NOTICE
                                LOG_INFO
                                LOG_DEBUG
                                LOG_DEBUG_STACK
                                LOG_DEBUG_OPER
                                LOG_DEBUG_HB  (lowest urgency) 


Example:  fs -dr -v LOG_DEBUG -f fs.log ps1.my.com:6005 ps2.my.com:6005 5070
  This runs the Feature Server in foreground mode, displaying all LOG_DEBUG
  messages and higher.  The log messages are stored in fs.log.  The Feature
  Server uses port 5070 to send and receive.  The Feature Server communicates
  with provisioning servers ps1 and ps2.

Example:  fs -v LOG_ERR  ps1.my.com:6005 ps1.my.com:6005 5071
  This runs the Feature Server in daemon mode, displaying only LOG_ERR
  messages and higher.  The log messages are printed to screen.  The Feature
  Server uses port 5071 to send and receive.  The provisioning servers 
  are defined the same because there is no redundancy provisioning server. 

TESTING THE SOFTWARE
--------------------------------------------------------------------
Useful debugging tips:

To test if your own CPL script parses: 
1)  Uncomment #TESTPROGRAMS += cplTest001.cxx in the Makefile
2)  make
3)  bin.debug.<your OS>/cplTest001 <your script name>.cpl

To manually insert your own script:
1)  From Vocal Provisioning, enable a feature for a user.  
    A Called feature should be enabled if your script is to be
    done by the called party.  A Calling feature should be 
    enabled if your script is to be executed for the calling
    party.   Feature interaction is shown under "INTRODUCTION."
2)  On your Provisioning host (including redundancy if using it),
    search the provisioning data for the CPL script that was
    generated for the user.
    E.g:
    /usr/local/vocal/provisioning_data/AAA/Features_<IP_PORT>/5000.cpl.xml
3)  Replace the contents of this script with your new script.
4)  Run or restart the Feature Server executable.

To debug a script in the Feature Server:
1)  Run Feature Server in debug mode (see "USING THE SOFTWARE.")
2)  Try to activate your feature (i.e.  Make a call).
3)  If you captured your debug messages in a log, do the following
    to see Feature Server-only messages (no SIP messages): 
    grep --regexp="Fs" --regexp="CPL" <log_file>
    NOTE:  The "Fs" and "CPL" tags are unavailable on Solaris. 

    Search for "<<< Configured users begin >>>" to check if your 
    script owner was included.   If not, an error occurred 
    during parsing.  

    Look at the CPLxxxx.cxx messages to see if the expected
    operators and states were traversed. 

    Lastly, use ipgrab or tcpdump to determine if the expected
    SIP messages arrive or depart from the Feature Server. 

====================================================================
SOURCE CODE INFORMATION
====================================================================

Generating Feature Server Documentation using Doc++
----------------------------------------------
You can use Doc++ to generate API documentation. 
Doc++ generates an alphabetical and hierarchical index of 
classes, functions, and variables. To use Doc++: 

1. Download Doc++ from http://www.zib.de/Visual/software/doc++/
2. Untar the file.
3. Locate the doc++ and docify files. These files should be in
   the /bin directory.
4. Copy the doc++ and docify files to directory where the source
   code is located.
5. Type: make doc 
6. Doc++ generated documentation will be saved in a html directory.
7. Select index.html from the html directory.

====================================================================
DIRECTORY STRUCTURE 
====================================================================  
Two important components of the Feature Server are the SIP stack
and the basic proxy:
  <your_software_location>/vocal/sip/sipstack 
  <your_software_location>/vocal/sip/base 

The Feature Server code is in
  <your_software_location>/vocal/sip/proxies/fs/base 
  <your_software_location>/vocal/sip/proxies/fs/cpl 

Examples of the scripts generated by Vocal Provisioning are in:
  <your_software_location>/vocal/sip/proxies/fs/cpl/cplScripts/features


FsProvisioning.cxx communicates with provisioning
(see /vocal/provisioning/psLib) to retrieve CPL scripts and other
system data. 

FSBuilder.cxx (1) processes the incoming SIP messages, (2) gets 
the feature and the data structures associated with the call, 
and (3) passes the message to the CPL operators 
(see /vocal/proxies/fs/cpl).

FsUsers.cxx keep track of the users that are provisioned for 
the feature.

fs.cxx contains the main(). 

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

====================================================================
CONTACT INFORMATION AND WEB SITE
====================================================================
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. 

You can submit bug, patches, software contributions, and feature 
requests using Bugzilla.  Access Bugzilla from www.vovida.org. 

====================================================================
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.5.2.1 2003/03/28 05:25:54 bko Exp $
