/**	@file	dk3sock.h	Socket functions.
The dk3sock module is a wrapper around BSD socket API functions and
WinSock functions. In addition to the original functions it provides
error reporting with the dk3_app_t data type and error code setting.

In contrast to the dktcpip module from dktools 2.x.x this module
is closer to the original API and provides functions for both client
and server.

The file size increased significantly compared against the former
dktcpip module for the following reasons:

- Support for IPv6 was added. With IPv6 new functions like getaddrinfo()
  were introduced, allowing to retrieve both IPv4 and IPv6 addresses for
  hosts. But we also want to support legacy systems with pure IPv4
  without these functions, so we use conditional compilation to choose
  the best function.

- For some functions processing text (like host names) we have both a
  version for char strings and a version for dkChar strings.
  Domain names and host names are not longer restricted to the ASCII
  character set so we must be able to process non-ASCII names.

You networking code should be enclosed in dk3socket_up() and dk3socket_down().
These functions bring the WinSock DLL up and down on Windows systems,
on other systems they always indicate success.
@code
  void my_networking_function(dk3_app_t *app)
  {
    int		errorCode = DK3_ERROR_NONE;
    if(dk3socket_up(&errorCode, app)) {
      run_all_networking_operations();
      dk3socket_down(&errorCode, app);
    }
  }
@endcode
Both arguments - pointer to error code variable and dk3_app_t pointer -
may be NULL.

There is one main difference between the original functions from the
BSD socket API and the wrapper functions in the dk3sock module:
The original functions bind(), connect(), accept(), sendto(), recvfrom()
use either int on some systems
or socklen_t on other systems to specify the length of a socket address.
The wrapper functions in this module always use size_t.

The dk3socket_open(), dk3socket_bind()... functions call the
dk3socket_error_socket(), dk3socket_error_bind()... functions on errors.

The dk3socket_open_net_stream_client() and
dk3socket_dkchar_open_net_stream_client()
functions only report an error status on errors, no detailed information.
The dk3socket_listeners() function does not report failures to bind
addresses.
If multiple addresses are found for the host to connect to and the
connection attempt fails for the first address and succeeds for a later one
the program would issue error messages even on success. Users might
be irritated by these error messages.
*/