/*============================================================================*\
|                                                                              |
|                      SOA4D DPWSCore (C DPWS toolkit)                         |
|                                                                              |
|           ->>  Copyright 2004-2009 Schneider Electric SA  <<-                |
|                                                                              |
\*============================================================================*/

*****************
**   VERSION   **
*****************

Version 2.1.0, April 2009, 15th.


*********************
**  RELEASE NOTES  **
*********************

This version brings the following main features to the 2.0 toolkit:

* Improvements
- Hot configuration allow to modify devices configuration while they are online
  and without interruption.
- Discovery cache content control with definition of a filter and LRU.
- WS-Eventing subscription manager capacity control,
- Improved device discovery using a single lookup API performing several
  parallel "PROBE request".
- Full encapsulation of the gSOAP user runtime API.
  
* New
- Generic XML processing API (EPX) implemented on top of gSOAP runtime,
- Generic stub & skeleton based on EPX,
- XML file processing facilities,
- WS-Management pluggability support (header management & custom WS-Eventing
  subscription management plugin interface added),
- Configuration by an XML file,
- WS-Management implementations dispatcher,
- Dynamic deployment framework using the WS-Management protocol (not compliant
  with the whole specification however),
- IPv6 support,
- Multiple interface support,
- External HTTP server pluggability,
- TCP connection pool (avoids connection overhead and exhaustion),

* Build
- New code organization & build system.
- API parameters control macros that can be activated with stack build.
- Portability layers.


-> For a complete history of new features, bug fixes and known issues for all
   previous versions, please refer to module change log in the source tree:

- SRC/dpws/doc/change_log.txt for basic stack features.
- SRC/dyndepl/doc/change_log.txt for the dynamic deployement (and file
  configuration).


********************
**  INSTALLATION  **
********************

There is no automated installation of the DPWSCore SDK package. To use the
toolkit, one should:

1. Uncompress the archive somewhere on your host filesystem,

2. To be able to use code generators, the bin folder should be added to the
   execution path.

3. To be able to run DPWS applications, DPWSCore runtime shared libraries should
   belong to the library execution path:

  - on Windows, one could decide to modify the PATH or copy DLLs in PATH
    directories (including the working directory).
  - on Linux, either modify LD_LIBRARY_PATH or create a symbolic link in /usr/lib
    to so names of libraries (so names are the ones with 2 decimals e.g.
    libdcruntime.so.2.1) if you have administrator rights. 


*************************
**   GETTING STARTED   **
*************************

------------------
 Runtime overview
------------------

The DPWSCore toolkit package is made up of several executables file (shared
libraries) sorted hereafter by order of dependency:

- dcruntime:

  The basic DPWSCore stack that provides all DPWS basic features (WS-Discovery,
  WS-Addressing, WS-MetadatExchange, WS-Eventing). These are used in the
  'Lights', 'WashingMachine' & 'Home' samples.

Advanced features:

- dcxml:
  
  * EPX XML API and implementation on gSOAP,
  * XML file facilities,
  * Generic invocation.
  
- dcxmlconf:

  * Basic features of dynamic deployment,
  * File configuration relying on dynamic deployment features.
  
- wsman:

  * WS-Management dispatcher.
  
- dcdyndepl:
 
  * Dynamic deployment server relying on basic dynamic deployment features,
    WS-Management dispatcher and generic invocation. Note that the corresponding
    shared library also embeds dcxmlconf code so that one should use one or
    another.
     
- ddclient:

  * Dynamic deployment client helper based on generic invocation.
  
Most of these advanced features are demonstrated in the "DynHome" sample.

------------------------
 Documentation overview
------------------------

+ The DPWS user guide (doc/DPWSCore User Guide.pdf) should be read first
  to get an overview of the toolkit features and help on using them.
  
+ API reference (doc/api/) brings details API description generated using
  Doxygen on API header files.

+ gSOAP documentation (doc/soapdoc2.html) contains the documentation for
  the gSOAP web service used by this toolkit. Note that the user may still
  have to refer to it for details about code generation and XML data binding
  reference even if most DPWS features should be understood by anyone that
  read the DPWSCore user guide.
  
+ All samples are introduced in doc/samples.txt even if some may have a
  dedicated readme. Anyway, samples contain lots of comments and hints that
  almost make them tutorials.

+ In the source package (or on the SVN repository) documents are available
  for developers that may want to build DPWSCore, for instance to make an 
  embedded target port. doc/dev/DC Build Notes.html will:
  
  - describe the DPWSCore build system,
  - give hints for porting DPWS to custom targets (along with the portability
    layer reference guide.)


******************
**  COMPLIANCE  **
******************

This toolkit intends to be compliant with at least the minimal requirements
of the "Devices Profile for Web Services February 2006" specification from
Microsoft Corporation. This version is the one currently supported by the
new Windows Vista operating system.

***************
**  LICENSE  **
***************

1. The DPWSCore runtime is released under the LGPL license (see attached file).

2. The gSOAP runtime and the gSOAP compiler (soapcpp2) are released under one
   of the following three licenses:
   
   - GPL (see attached file),
   - the gSOAP public license (that unlike GPL, allows commercial use. see
     attached file),
   - the commercial license by Genivia Inc (write to contact@genivia.com or
     visit http://genivia.com/Products/gsoap/contract.html)

   This also applies to the code generated by the gSOAP compiler.

3. The gSOAP WSDL parser (wsdl2h) is released under one of the following two
   licenses:
   
   - GPL (see attached file),
   - the commercial license by Genivia Inc (write to contact@genivia.com or
     visit http://genivia.com/Products/gsoap/contract.html)
   
   This also applies to the code generated by the gSOAP WSDL parser.


NOTE:

Every source file comes with a banner telling under what license it is
available, especially because DPWSCore & gSOAP runtimes may be mixed,
in a very limited number of files however.

*******************************************
**  LIMITATIONS & POSSIBLE IMPROVEMENTS  **
*******************************************

- The modifications made on the gSOAP compiler only address C code generation.
  C++ generation is not supported for the time being.
- WSDL is returned only by location (URL) and not yet by reference (WS) or
  inclusion.
- Client metadata retrieval method is deterministic by section. ThisDevice,
  ThisModel and Relationship are expected inline while WSDL only by location.
- WS-Eventing : as authorized by the specification the DPWS toolkit only
  accepts relative time (duration) subscription expiration.

