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

Table of contents:

A. Introduction
  A.1 Lights
  A.2 WashingMachine
  A.3 Home
  A.4 DynHome
B. Requirements
C. Building
D. Running
E. Conventions


A. Introduction
---------------

A short description of each sample will be given hereafter. This list 
is ordered in growing complexity.

Note that the samples have been developed to demonstrate the various
features of the dpwscore stack.

If you look for a specific feature, the following table should help you to
find the right sample:

------------------------------------------------------------------
Feature                       | Lights | Washer | Home | DynHome |
------------------------------+--------+--------+------+---------|
Device discovery              |   X    |    X   |   X  |    X    |
Service invocation            |   X    |    X   |   X  |    X    |
Mono-thread listener          |   X    |        |      |         |
Multi-thread listener         |        |    X   |   X  |    X    |
Fault sending                 |        |    X   |   X  |    X    |
Simple device configuration   |   X    |    X   |      |         |
Multi-device configuration    |        |        |   X  |         |
XML file configuration        |        |        |      |    X    |
IPv6 support                  |        |    X   |      |         |
Multiple network support      |        |    X   |      |         |
WS-Eventing                   |        |    X   |   X  |    X    |
WS-Discovery listener         |        |    X   |   X  |    X    |
Client invocation in server   |        |        |   X  |    X    |
MTOM attachments              |        |        |   X  |    X    |
Dynamic deployment            |        |        |      |    X    |
------------------------------------------------------------------

A.1 Lights
----------

The simplest DPWS sample which consist in switching on or off a remote light.
It uses WS-Discovery to find the light device and  WS-Transfer to find the
service. It then demonstrate both one-way and two-way invocations.

This sample is made up of 2 components:

- The server which is the DPWS light device,
- The client that discovers and command the DPWS light.

Note: 
   Run the server first. You may use a scope diversifier to avoid conflicts on
   the local network by participating in building the scope of the device.
   Then run the client. If a diversifier was used to start the server, it should
   also be used when starting the client.
   
* Remarkable demonstrated features *

- Device discovery,
- Service invocation,
- Mono-thread listener,
- "Manual" device configuration.


A.2 WashingMachine
------------------

This sample implements a DPWS washing machine which demonstrates WS-Discovery
listening and WS-Eventing capabilities. New DPWS devices on the LAN are detected
by the client and printed. The cycle end is notified to the client using an
event.

This sample is made up of 2 components:

- The server which is the DPWS washing device,
- The client that discovers, command the DPWS washing device and prints events.

* Remarkable demonstrated features *

- IPv6 support,
- Multiple network interface support, 
- WS-Eventing subscription & notification,
- WS-Discovery listener (Hello & Byes),
- Fault sending in a service,
- Multi-thread listener (without any thread or memory pool !!!).


A.3 Home
--------

This sample is the "full" demonstration of the 'core' DPWS toolkit since it uses
most of its features among which the multi-device feature for gateways
implementation. The Home demonstrator embeds several lights devices already seen
in the 'light' sample (some augmented with dimming capabilities), a washing
machine previously exposed in the "WashingMachine" sample. A new video projector
device is also added to illustrate the MTOM attachment feature of the toolkit.

This sample is made up of 2 components:

- The server which hosts the home DPWS devices,
- The client that discovers, command the DPWS devices through interactive
  menus and prints events.

* Remarkable demonstrated features *

- Multi-device configuration (with device model use),
- Client invocation in service implementation (transparent local invocation),
- MTOM attachments.

A.4 DynHome
-----------

This sample is an adaptation of the 'Home' that uses all the new features
brought by the dynamic deployment DPWSCore extensions. Reading the 'Home'
readme is recommended before.

This sample is made up of 3 components:

- The client which is unchanged regarding the base 'Home' version. You will
  notice then than devices deployed or undeployed will be visible, device
  operation menus are not dynamic so they won't adapt to service deployement.
- The server was rewritten to provide the same applicative functional
  outline but with the features of dynamic deployment (file configuration,
  dynamic deployment and reference management). The initial configuration
  is available in the 'data' sub-directory.
- A new component named "manager" has been added to be able to deploy
  configuration objects remotely. Dynamic deployment object description
  are read from XML file provided in the 'data' sub-directory.

* Remarkable demonstrated features *

- XML file configuration,
- Dynamic deployment.

B. Requirements
---------------

Building on Windows requires either:

- MS Visual C++ 2005 or later with the provided project files.

Building on Linux requires:

- standard gcc & make tools.

and the DPWSCore package that should contain the present file.

C. Building
-----------

On a windows (vs2005 or vs2008) platform, open the .sln file and build all.

On a gnu platform, launch the "all" target of the supplied makefile. 

Building a sample will generate several executables in the sample directory.

D. Running
----------

Note that DPWSCore runtime libraries must have been installed first (i.e. put
in the system execution path).

Some samples may have a dedicated readme.txt file located in the doc folder of
the sample, however all executable can be used with the -? option. This will
display the common usage and optionally some explanations on the executable.

E. CONVENTIONS
---------------------

Samples generally produce output on the console. Specific strings will be
used in all samples.

'-->' means that the information is associated with an incoming message.
'<--' means that the information is associated with an outgoing message.
errors will be directed to stderr.

