include/openssl: don't include <windows.h> in public headers.

If application uses any of Windows-specific interfaces, make it
application developer's respondibility to include <windows.h>.
Rationale is that <windows.h> is quite "toxic" and is sensitive
to inclusion order (most notably in relation to <winsock2.h>).
It's only natural to give complete control to the application developer.

Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>

4 files changed, 44 insertions, 0 deletions

diff --git a/doc/crypto/ASYNC_WAIT_CTX_new.pod b/doc/crypto/ASYNC_WAIT_CTX_new.pod
index 364cbb4e30..de1bd5777d 100644
--- a/doc/crypto/ASYNC_WAIT_CTX_new.pod
+++ b/doc/crypto/ASYNC_WAIT_CTX_new.pod
@@ -112,6 +112,15 @@ ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
 success or 0 on error.
 
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
 =head1 SEE ALSO
 
 L<crypto(3)>, L<ASYNC_start_job(3)>
diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod
index 20bc1ad2aa..eb12da8cb9 100644
--- a/doc/crypto/ASYNC_start_job.pod
+++ b/doc/crypto/ASYNC_start_job.pod
@@ -161,10 +161,22 @@ ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
 ASYNC_is_capable() returns 1 if the current platform is async capable or 0
 otherwise.
 
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
 =head1 EXAMPLE
 
 The following example demonstrates how to use most of the core async APIs:
 
+ #ifdef _WIN32
+ # include <windows.h>
+ #endif
  #include <stdio.h>
  #include <unistd.h>
  #include <openssl/async.h>
diff --git a/doc/crypto/CRYPTO_THREAD_run_once.pod b/doc/crypto/CRYPTO_THREAD_run_once.pod
index 37671b90eb..7795a04477 100644
--- a/doc/crypto/CRYPTO_THREAD_run_once.pod
+++ b/doc/crypto/CRYPTO_THREAD_run_once.pod
@@ -79,10 +79,23 @@ CRYPTO_THREAD_lock_frees() returns no value.
 
 The other functions return 1 on success or 0 on error.
 
+=head1 NOTES
+
+On Windows platforms the CRYPTO_THREAD_* types and functions in the
+openssl/crypto.h header are dependent on some of the types customarily
+made available by including windows.h. The application developer is
+likely to require control over when the latter is included, commonly as
+one of the first included headers. Therefore it is defined as an
+application developer's responsibility to include windows.h prior to
+crypto.h where use of CRYPTO_THREAD_* types and functions is required.
+
 =head1 EXAMPLE
 
 This example safely initializes and uses a lock.
 
+  #ifdef _WIN32
+  # include <windows.h>
+  #endif
   #include <openssl/crypto.h>
 
   static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT;
diff --git a/doc/ssl/SSL_get_all_async_fds.pod b/doc/ssl/SSL_get_all_async_fds.pod
index deb81e1fdf..636f765508 100644
--- a/doc/ssl/SSL_get_all_async_fds.pod
+++ b/doc/ssl/SSL_get_all_async_fds.pod
@@ -7,6 +7,7 @@ asynchronous operations
 
 =head1 SYNOPSIS
 
+ #include <openssl/async.h>
  #include <openssl/ssl.h>
 
  int SSL_waiting_for_async(SSL *s);
@@ -53,6 +54,15 @@ for an async operation to complete and 0 otherwise.
 SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or
 0 on error.
 
+=head1 NOTES
+
+On Windows platforms the openssl/async.h header is dependent on some
+of the types customarily made available by including windows.h. The
+application developer is likely to require control over when the latter
+is included, commonly as one of the first included headers. Therefore
+it is defined as an application developer's responsibility to include
+windows.h prior to async.h.
+
 =head1 SEE ALSO
 
 L<SSL_get_error(3)>, L<SSL_CTX_set_mode(3)>