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

********************************
** Frequently Asked Questions **
********************************

* Summary *

1. Sockets in TIME_WAIT state are accumulating on my device, is is a bug of the
   DPWSCore toolkit ?
2. I have more that one network adapter and DPWS discovery does not seem to work
   or maybe uses the wrong one. How can I control the interface used for device
   discovery ?
3. Under Linux, my DPWS application receives a SIGPIPE signal and exits. It is
   normal and how can I do to avoid this ?
4. Under Linux, device discovery doesn't work, what's wrong ?
5. My device seems slowed or blocked, what's going on ?
6. My Windows DPWS application is blocked without obvious reasons, what are the
   possible explanations ?

1.------------------------------------------------------------------------------

Q: Sockets in TIME_WAIT state are accumulating on my device, is is a bug of the
   DPWSCore toolkit ?

A: The TIME_WAIT state is a TCP feature that is hardly understood and generally
   ignored since it does not disturb usual client/server operations. Indeed, the
   TIME_WAIT state is defined by the TCP protocol to prevent wandering packets
   and "granted" to the peer that closes first the connection, usually the client
   in client-server architectures. In peer-to-peer architectures, for instance
   when events are sent using a high frequency, TIME_WAIT accumulation may also
   occur on the server side (device) and lead to socket resources exhaustion,
   especially in embedded constrained platforms.
   Since DPWS events can only be currently sent using HTTP (and then TCP), the
   only way to prevent such an inconvenience is to use the DPWSCore connection
   pool for sending events. Doing so also for frequent client invocations,
   especially on devices, is also recommended.


2.------------------------------------------------------------------------------

Q: I have more that one network adapter and DPWS discovery does not seem to work
   or maybe uses the wrong one. How can I control the interface used for device
   discovery ?
   
A: For compatibility reasons, the dpws_init() and dpws_init6() API functions
   select one interface for the toolkit, in fact the first retrieved from the
   system. To enable discovery on all available IP interfaces, the
   dpws_init_ex() API should be used instead. Note that 'WashingMachine' is the
   only delivered sample that uses the multiple interface feature.


3.------------------------------------------------------------------------------

Q: Under Linux, my DPWS application receives a SIGPIPE signal and exits. It is
   normal and how can I do to avoid this ?
   
A: If a connection is closed in a unpredictable manner (for instance a peer
   crash) and a DPWS program (or any other program) writes to a socket, Linux
   raises a SIGPIPE signal. The DPWSCore toolkit does not currently block this
   signal, letting the responsibility to the application programmer. One could
   decide to use a 'sigignore(SIGPIPE)' call to prevent untimely exits.


4.------------------------------------------------------------------------------

Q: Under Linux, device discovery doesn't work, what's wrong ?

A: On some versions of the Linux kernel or after changes of the network
   configuration, the route for multicast packets is not defined and should be
   done manually. The solution is then generally to use the
   'route add -net 224.0.0.0 netmask 240.0.0.0 dev eth0' command.


5.------------------------------------------------------------------------------

Q: My device seems slowed or blocked, what's going on ?

A: There may be many reasons for this, for instance applicative reasons (your
   implementation of a service for instance), but one frequent is related to TCP.
   Indeed, TCP may lead to long timeouts when the peer is not reachable at all
   (i.e. no IP stack alive). This may especially be the case when an event
   subscriber (event sink) suddenly disappears. Indeed a device may be blocked
   during its notification process, which obviously cannot be tolerated. To
   avoid such inconvenience, the use of user timeouts should be generalized (see
   User Guide).

6.------------------------------------------------------------------------------

Q: My Windows DPWS application is blocked without obvious reasons, what are the
   possible explanations ?
   
A: There may be several reasons for this among which:
   - You've developed your application under MS Visual Studio and you may face
   MSVCRT library concurrency problems. It can be the case for instance if you
   choose to link with DPWSCore static libraries that are linked with the
   multithread static version of MSVCRT and your application also uses this
   library. In this situation, some code in the gSOAP runtime may try to access
   to stdin (or stdout) using _setmode() while you main application function is
   for instance waiting for a user input on the console. This could be considered
   of bug that we did not fix yet because it may require a modification of gSOAP
   runtime code. This does not occur when you use  DLLs libraries since the
   DPWSCore DLLs use the static version of MSVCRT that does not seem to interfere
   with the one used by the application.
   - You use DPWS programs that were compiled using a debug version of DPWSCore
   libraries (compiled with the DPWS_DEBUG flag) in the same folder. As these
   special versions of the DPWSCore runtime produce log files in the working
   directory, you may face concurrency inconvenience like casual blockings. One
   simple solution is to run programs producing a trace in separate folders.