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

===============================
== DPWS Module Release Notes ==
===============================

MODULE VERSION: 1.2.0

This file contains:

1. The module changelog,
2. Know issues.

********************************
**  CHANGE LOG & NEW FEATURES **
********************************


2.1.0

* API:

- A new object can now be configured, the subscription manager. It holds for
  example a maximum number of subscriptions, and a maximum duration for
  subscriptions that was moved from the registry to it.
- A DPWS_INT_MAX_SUBSC_DURATION attribute has been added to be able to set
  the maximum duration for subscriptions using an int. Note that
  DPWS_STR_MAX_SUBSC_DURATION cannot be used anymore for reading.
- New configuration parameter on the cache to specify a limit for the number
  of device proxies in the cache (DPWS_INT_MAX_DEVICE_PROXIES).
- A configuration parameter was added (DPWS_BOOL_BP1_1_COMPATIBILITY on
  DC_TOOLKIT_HANDLE) in order to turn off WS-Addressing headers use so that
  to enable WSI Basic Profile clients support, provided the WSDL was written
  using SOAP 1.1 bindings.
- dpws_join_network, added for cable unplugging management, allow the user
  to send Hello message when a network restoration has been detected.
  
* Multi-homed & IPv6 platforms support :

- dpws_init_ex modified for multi-homed platforms network interface
  configuration and DPWS version support. The user can now, for example, supply
  a sophisticated filter for interface selection while the simplified APIs
  dpws_init() or dpws_init6() will continue selecting (without conrol) one
  interface supporting a given protocol.
- dpws_server_init_ex adapted for listener configuration (most legacy
  configuration attributes where kept for compatibility reasons).
- dpws_get_transport_addresses was added to replace dpws_get_transport_address
  which was kept for backwards compatibility.
- A new WS-Eventing subscription API has been added (dpws_event_subscribe_ex)
  that allow local enpoint handles usage for notification sinks. This API
  performs automatic EPR selection and hides the multiple interface & protocol
  complexity.
- DPWS_STR_HTTP_ADDR toolkit parameter removed because it interfered with
  multiple address support.

* Other new features:

- HTTP server pluggability (see dc/dc_DpwsRequest.h) added & internal server
  replaced the gSOAP one.

* Bug fixes:

- In EPX, default namespace URI could not be retrieved.

* Stack configuration

- Stack build configuration macro renamed with a uniform naming (e.g. WSMAN
  renamed WITH_WSMAN).
- New build variable allow to turn on API parameters control (DC_API_PARAM_CONTROL).
- A user file can be used so that to set these settings: dc_config.h. Its
  inclusion is triggered by the DC_USER_CONFIG macro definition.

* Build System:

- A full Visual studio 2005 & 2008 build is now available that does not require
  Cygwin (that previously supplied Bison & Flex) nor GnuWin32 tools anymore, since
  Bison & Flex output is now provided along with VS projects for 'wsdl2h' and
  'soapcpp2'.

--------------------------------------------------------------------------------
2.1.M7

* API:

- dpws_server_shutdown added to be able to restart and reconfigure a server.
- dpws_malloc and dpws_fault added so that service implementation could use
  only DPWSCore API and no gSOAP APIs

* Runtime:

- The SOAP XML_STRICT flag is now used for all built-in web services
  (WS-Discovery, WS-MetadataExchange, WS-Eventing...) to avoid invalid messages
  to carry out server crash.
- Obsolete EPX_QNAME_EQUALS & EPX_QNAME_NOT_EQUALS removed (use QNAME_EQUALS
  instead).
- WS-Discovery compliance: RFC2396 match (used fo scope match) is now closest
  to the stricter interpretation of the specification sayin that
  'http://MyHost/seg1/' does not match 'http://MyHost/seg1/seg2' (whereas
  'http://MyHost/seg1' does) because ending '/' means that an empty segment is
  opened (and empty seg2).
- Memory exhaustion resilience added.
- Allocation macro facilities added to redefine allocators.
  
* Abstraction Layer (AL)

- AL includes are not required anymore for the user of the DC API.
- al_ip_init & al_ip_shutdown not required anymore by the runtime (could be
  removed from AL).

* New experimental features:

- IPv6 support. To enable IPv6, use dpws_init6() instead of dpws_init().

* Bug fixes:

- dpws_lookup_ex and cache filters did not work properly with multiple filters
  (only the first was considered).
- cache filtering crashed receiving Vista Hellos (no scope tag).
- several defensive code snippets added to support unexpected hellos & byes.
- SOA4D #35, #41, #44, #50, #64


--------------------------------------------------------------------------------
2.1.M6 (refactoring):


* API:

- get_system_time helper removed since provided by the abstraction layer (AL).
- The DPWS_STR_ADDRESS can now also be set on the device (was for service ports
  only) to be able to specify an alternate transport address.
- dpws_init_ex() API added to be able to select a network interface for the
  toolkit.
- xmlduration2time and time2xmlduration removed since based on absolute time
  API not necessarily available on the platform.
- The undocumented out_ip_addr dpws structure member has been moved and is now
  set by default to the IP address set for the toolkit. This allows to force
  multicast messages to use a specific network interface.
- A filter can now be set on the device cache to select what devices should be
  cached (see DPWS_PTR_CACHE_FILTER attribute on DC_CACHE_HANDLE).
- dpws_lookup_ex & dpws_probe_address_ex have been updated to use the filter
  structure created for the cache filter. Old prototypes can still be used by
  compiling with the DC_LEGACY_API macro.
- DPWS_PTR_CALLBACK_HELLO & DPWS_PTR_CALLBACK_BYE attributes must now be set
  on the DC_CACHE_HANDLE object.
- The uncomplete and somewhat incorrect dpws_check_device_type API is replaced
  by dpws_device_proxy_match.
- New connection pool feature for client invocations using the HTTP keep-alive
  feature (see dc_ConnPool.h). No user documentation scheduled yet.
- dpws_recv_empty_response added to generation and removed from public API
  because not using it leads to multiple issues.
  
* Runtime:

- Unused gSOAP runtime functions removed (soap_accept).
- WITH_UDP, SOCKET_CLOSE_ON_EXEC gSOAP macros related code removed.

* Ports:

- Abstraction layer making ports easier.
- Previous existing ports reset.
- Already available :  Win32, Linux (+ mingw, cygwin).

* Bug fixes:

- Corrupted WS-Discovery message robustness (detected by automated test).
- Memory corruption and leaks detected using Valgrind fixed.


--------------------------------------------------------------------------------
2.1.M5 :

* EPX:

- New ATTRIBUTE event and event scheme to optimize EXI future implementation and
  limit the number of typed value access APIs. Position attribute access API are
  kept for compatibility reasons but may be removed in DPWSCore v3.
  To continue to work, legacy programs should:
    1. ignore the new ATTRIBUTE event.
    2. consider the new order for START_ELEMENT, PREFIX_DEFINITION, and ATTRIBUTE
       for serialization.
- Typed API first row (to be continued).
- epx_get_uri_prefix API added (retrieves a prefix for a namespace URI).
- Missing epx_delete_serializer added.
  
* Fixes:

- SOA4D bug fixes: #7,#10,#11.
- APP_MAX_DELAY changed to 2500ms like did Microsoft (contrary to the DPWS
  specification) to be able to pass Windows personal firewall.
- Bug in xmlduration2duration(tool.c) could lead to memory corruption. Used for
  WS-Eventing.
  

--------------------------------------------------------------------------------
2.1.M4 :

* New features:

- API EPX (Pull-parsing API over gSOAP runtime), SUN (persistency layer), FileX
  (gSOAP file input/outputs) and Generic (generic stub and skeleton using EPX)
  are now part of the DPWSCore runtime.
- Configuration API dpws_get_ptr_att_count added.
- dpws_create_XXX_device APIs enhanced to be able to generate random UUID for
  device (needed for dynamic deployment).

* API changes (recompilation and little code change may be required):

- EPX API added to set options during parsing (epx_set_parsing_options &
  epx_get_parsing_options.)
- Configuration API change (recompilation required): DPWS_STR_MODEL_NAME,
  DPWS_STR_MANUFACTURER and DPWS_STR_FRIENDLY_NAME attributes are now
  multivalued and no more simple strings but "localized string" in order
  to support DPWS metadata localization.
- Callback added to registry for metadata version change.
- TOOLKIT_HANDLE macro renamed DPWSCORE_REGISTRY_HANDLE.
- API constants changed.

* Fixes:

- Robustness of multicast WS-Discovery datagram reception improved. All kind of
  not understandable messages are now ignored (non-XML messages included).
- Management headers could not be received by the server in WS-Eventing
  operations since the WS-Management namespaces had not been added to the
  overridden 'send' namespace table.
- Makefiles cleaned for OSS publication on SOA4D and other improvements.
- Runtime modified to add support for custom fault action. Only supported
  currently by the generic skeleton and not by the code generation.
- MDM files removed from SVN (not used anymore).
- EPX bug processing empty tags fixed.


--------------------------------------------------------------------------------
2.1.M3 :

- EPX over gSOAP bug fix. Ghost attributes appeared in certain circumstances.
- my_stdsoap files split to separate the pure gSOAP runtime extensions from
  DPWS so that EPX over gSOAP only depends on gSOAP.
- Multicast client interface selection Windows hack: use the dpws->out_ip_addr
  field before lookup to select the network interface used for discovery. Just
  pass a local ip address attached to the interface. NULL let the OS choose the
  interface.


--------------------------------------------------------------------------------
2.1.M2 :

- Support for namespace context in WS-Management Fragment Transfer header
  added. This required to change the internal DPWS runtime processing for
  QNames (full normalized form and not gSOAP tag form anymore).
- Generic API was augmented with the ability to define prefixes at the root
  of messages.
- Slight change in EPX fragment parsing. All applicable prefix definitions
  (from the root of the document to the root of the fragment) can now listed
  in a row when starting to parse the fragment in order to provide all the
  information available.
- No need to define the WSMAN macro since it is forced in the dpws.h file
  because it was error prone (when the application forgot to use the macro).
- management.h (renamed plugin.h): create_subsc changed in WS-Eventing
  subscription manager plugin to avoid dependencies from internal types
  (dyn_array). See prototype for more information.
- Better modularization (no need to include tools.h). Plugin APIs is defined
  in plugin.h. This API is less stable user API since it is a publication of
  DPWS runtime internals decided for the development of specific extensions
  like WS-Management.

  
--------------------------------------------------------------------------------
2.1.M1 :

- Hot configuration
- Event source are now service endpoints and not ports.
- MDM removed since WS-Management implemented.
- WS-Management header support added (enabled when WSMAN macro is used).
- Pluggable WS-Eventing support added (enabled when WSMAN macro is used).
- Helper code added:
	+ generic XML parsing API (EPX),
	+ generic invocation and serving,
	+ XML file parsing and serialization.


--------------------------------------------------------------------------------
2.0.M11.5 :

- extern 'C' missing in _dpws.h added.
- gSOAP compiler patched to avoid generating empty structs (not tolerated by some
  C compilers) when SOAP message bodies are empty. Samples have been retrofit not
  to use dummy elements anymore.


--------------------------------------------------------------------------------
2.0.M11.4 :

- Bug fixes (C/Java/Vista final version interop tests):
  + major compatibility issues 
  	- old WS-Eventing filter dialect URI was used.
  	- RelatesTo was missing in probe match messages (worked with Vista RC).
  + minor compatibility issues 
  	- default MATCH timeout was shorter than recommended (and then too quick).
- Compilation issues on GNU environments (conflicting macro definitions)
- API improvement:
  + dpws_get_default_endpoint_reference & dpws_get_endpoint_references were
    renamed dpws_get_default_endpoint_ref & dpws_get_endpoint_refs for
    consistency but a macro has been defined to ensure backward compatibility.
- gSOAP compiler:
  + "-u" option advertized in the command-line help.
- Updated readmes especially for samples.
- Build process cleaned though always 'manual' and limited to cygwin.


--------------------------------------------------------------------------------
2.0.M11.3 :

- API improvement:
  + dpws_get_service was renamed dpws_get_services but a macro has been defined
    to ensure backward compatibility.
  + dpws_get_proxy_type has been added to be able to set what metadata API must
    be used after retrieving service proxies (among which may be devices).

- Bug fixes:
  + wsdl was always null in device metadata retrieval.
  + eventing notification now tolerates to pass the handle reference of a
    service endpoint instead of only a service port. The ability to provide
    a service port may be removed in the next major version.
  + Add a control on proxy type in metadata APIs to block the improper use
    of the wrong API.
  + Handle was not hold correctly in lookup APIs so a call to dpws_release_proxy
    could lead to a fatal error.


--------------------------------------------------------------------------------
2.0.M11.2 :

- Compilation:
  + A misprint, invisible with some compilers has been removed in the
  device_metadata structure defined in dpws.h.

- API improvement:
  + dpws_release_proxies has been removed since it is now done automatically
    during dpws_end.
     
- Bug fixes:
  + dpws_get_device metadata/dpws_get_service_metadata. Memory corruption when
    retrieving service info.
  + dpws_cache_get_device_transport_addresses. Memory corruption.

- Improvements:
  + dpws_lookup_by_id: now tolerates uuid with "urn:uuid:", "uuid:" or no prefix.
  + dpws_release_proxy: does not crash anymore if href is negative avoiding to
    perform a test is a previous API returned a dummy href.


--------------------------------------------------------------------------------
2.0.M11.1 :

- The support of the "Vista" version induced some noticeable changes of the
  DPWS data model and then of the API. Note that:
  
  + On the server side, the changes is limited if the simple API (dpws_create_device)
    is used. In fact, the concept of service port has been added and features a
    physical address (# an endpoint reference) on which a service is bound.
    This object can also be created and bound manually using new APIs. Note also
    than WS-Eventing notification has been simplified so that the handle of the
    service port featuring the event source can directly be supplied to the
    notify function instead of an endpoint reference structure, which is more
    convenient.
  + On the client side, the concept of "proxy" has been added to feature a device
    or a service, since now, a service can feature multiple endpoint references. The
    API user will receive handles on proxies to emulate an object-like behavior.
    This means than the results of discovery API should be released instead of freed.
    When a proxy is to be used for invokation, some new API should be used to retrieve
    an endpoint reference so that the invokation can be proceeded like before.
    
The use of the new API is rather well illustrated in the delivery samples.


--------------------------------------------------------------------------------
2.0.M10 :

- Error API changed and error management improved impacting slightly the
  whole API.
- WARNING ! the dpws_init() API call is now also required even for Windows platforms.
- Bug fixes.


--------------------------------------------------------------------------------
2.0.M2 :

- Conformity to the last DPWS specification (May 2005) and Interop Workshop
  (Oct 2005):
  + Endpoints: device and hosted services endpoint changed,
  + New metadata format,
  + WS-Discovery: (especially new probe semantics, directed probes),
  + MTOM attachements,
  + One-way message response : HTTP 202,
  + ...
- New API : especially the 'object' configuration API,
- Upgrade of gSOAP (from 2.6.2 to 2.7.6),
- Documentation updated,
- API reference is now generated from the source code using doxygen,
- Internal code modularized to make easier reactivity to specification changes.


--------------------------------------------------------------------------------
2.0.M1 :

- Toolkit reingeneering for the support of multi-device.


******************
** KNOWN ISSUES **
******************

- On multiple network interface systems, especially Windows Vista which has several
  virtual adapters, WS-Discovery multicast packets may stray from the right interface.
- Custom WS-Addressing reference parameters & properties not supported.
- RFC2396 match algorithm used for WS-Discovery scope matching implemented in a too
  "lax" way...
- WS-Discovery message parsing is currently too strict and ignores message containing
  unsupported extensibility.
- See SOA4D bug trackers for issues detected by the community.
