The license applies to all software incorporated in the "Vovida
Open Communication Application Library" except for those portions
incorporating third party software specifically identified as being
licensed under separate license.

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.

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

This software consists of voluntary contributions made by Vovida
Networks, Inc. and many individuals on behalf of Vovida Networks,
Inc.  For more information on Vovida Networks, Inc., please see
<http://www.vovida.org/>.


All third party licenses and copyright notices and other required
legends also need to be complied with as well.





This README is obsolete.  It is included for historical purposes only.


README: 

PURPOSE of common:

The library contains common C++ utility objects that can be used by psLib 
and pserver.  Notably, the Http URI(s) used to identify the types of PS
 requests, the database Request object, database Result object and the 
classes that support the PS protocol: Xml database content encapsulated 
in a Http header.


CLASS DESCRIPTION:

PSCommon - contains PS protocol specific string constants and enums.

PSDBRequest - container class for storing information for a Provisioning
              database request.  Information for a Get* request is
              kept in a list, myFieldList, whereas, infomation for a
              Set* request is stored in a keyword/value table, myTable.

PSDBResult - container class for storing info for the database response
             from the Provisioning Server.  It also contains a set of
             data manipulation/conversion methods given a field's value.

PSMessage: parent class to PSDBRequest and PSDBResult

PSProtocolService: helper class for PSHttpXMLInterface.  This is a
                   singleton as there's only need for one object per
                   client/application.  This class hides the 
                   implementation details for building (see 
                   build*Req() methods) and parsing (see parseRequest()
                   and parseResponse()) PS protocol message.  It uses 
                   other helper classes:
                   HttpMessage, PSReqXmlContentHandlers and 
                   PSRspXmlContentHandlers.  
              N.B. This class can be extended to build a set of
                   build*Rsp() for Provisioning Server to build a
                   complete set PS responses too.

PSReqXmlContentHandlers: Xml data handler class for building and
                         parsing a provisioning request.  To keep it
                         simple, we build the Xml content via string
                         concatenation (see build*Req() methods). It
                         uses Xerces's SAX parser to decode the Xml
                         body.  (See test/testPSXML.cxx for an 
                         alternative of buiding an Xml document
                         via Libxml.)

PSRspXmlContentHandlers: Xml data handler class for building and
                         parsing a provisioning response.  Like 
                         PSReqXmlContentHandlers, it builds the
                         Xml content via string concatenation (see
                         build*Rsp() methods), and it uses Xerces'
                         SAX parser to decode the Xml content.

XmlContent: contains StrX helper class that provides convenience
            in converting XMLCh data to char* for display.  This
            class is borrowed from the Xerces' sample test programs.


SAMPLE USAGE:

1) Using PSProtocolService to build a PS message, e.g. GetRecordsInDomain
   request:

   #include "PSProtocolService.hxx"
   #include "HttpMessage.hxx"

   using namespace Vocal;

   string domain = "Accounts";
   string filter = "uid=200*";

   list<string> myFieldList;
   myFieldList.push_back("uid");
   myFieldList.push_back("phone");
   myFieldList.push_back("foo");
   myFieldList.push_back("bar");

   try {
       PSProtocolService& proto = PSProtocolService::getInstance();
       Sptr< Http::Message > req = proto.buildGetRecordsInDomainReq(
                               domain, filter, myFieldList );

       // to access the raw http string:
       const string& rawHttpMsg = req.encode();

       ..........   
   }
   catch (VException& e)
   {
       ............
   }

2) To parse the Xml content from a Http message:

   #include "PSProtocolService.hxx"
   #include "HttpMessage.hxx"
   #include "PSDBRequest.hxx"
   #include "PSMessage.hxx"

   using namespace Vocal;

   try {

       // assuming the Http message is a GetRecordsInDomain request:
       Sptr< Http::Message > req = ..........;

       PSProtocolService& proto = PSProtocolService::getInstance();
   
       const string& xmlBody = req->body();   // get the xml content
       Sptr<PSDBRequest> myRequest = proto.parseRequest(
                       PSMessage::GET_RECORDS_IN_DOMAIN_REQ, xmlBody );
   }
   catch (VException& e)
   {
       ........
   }

   // now can access members in PSDBRequest object.

// End of File

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

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.2.2.2 2003/03/28 05:25:52 bko Exp $
