ceph/src/boost/libs/winapi/doc/winapi.qbk

   1 [/
   2   Copyright (c) 2016 Andrey Semashev
   3
   4   Distributed under the Boost Software License,
   5   Version 1.0. (See accompanying file LICENSE_1_0.txt
   6   or copy at http://boost.org/LICENSE_1_0.txt)
   7 ]
   8
   9 [library Boost.WinAPI
  10   [quickbook 1.6]
  11   [id winapi]
  12   [copyright 2016 Andrey Semashev]
  13   [dirname winapi]
  14   [license Distributed under the [@http://boost.org/LICENSE_1_0.txt Boost Software License, Version 1.0].]
  15 ]
  16
  17 [section:intro Introduction]
  18
  19 The Boost.WinAPI library is an abstraction layer for Windows API intended to be used internally by other Boost libraries. Boost.WinAPI is not a public library for users of Boost.
  20
  21 The main advantages of using Boost.WinAPI instead of Windows API directly are:
  22
  23 * Avoid including `<windows.h>` or other Windows SDK headers in public headers of your library. Windows SDK headers are known to be dependent on a large number of configuration macros that have to be defined by the user. If your library depends on a particular API, you may not be able to rely on it being enabled by the user. On the other hand, your library cannot enforce particular Windows SDK configuration because (a) Windows SDK headers may be included before your library headers with a different set of config macros and (b) because your desired configuration may be incompatible with that of the user's code.
  24 * Avoid dealing with lots of macros defined by Windows SDK headers.
  25 * More fine grained control of the API you include in your headers.
  26 * Allow to select the target Windows version for Boost. This version can be different from the version user's code targets.
  27 * Better compatibility with different implementations of Windows SDK, like MinGW and MinGW-w64.
  28
  29 The implementation of Boost.WinAPI consists of a number of declarations of functions, types and constants mimicking the real declarations in Windows SDK. In some cases simple inline function wrappers are provided. As a result the runtime performance impact of Boost.WinAPI should be zero. Boost.WinAPI only depends on Boost.Config and Boost.Predef and is compatible with C++03 compilers.
  30
  31 [endsect]
  32
  33 [section:config Configuration]
  34
  35 Boost.WinAPI recognizes the following configuration macros:
  36
  37 [table Configuration macros
  38     [[Macro name]                               [Effect]]
  39     [[`BOOST_USE_WINAPI_VERSION`]               [If defined, designates the Windows API version to use. The version should be given as hexadecimal integer, same as the `_WIN32_WINNT` macro values. Some of the versions are given [@https://msdn.microsoft.com/en-us/library/aa383745(v=vs.100).aspx#macros_for_conditional_declarations here]. If the macro is not defined, the version is deduced from `_WIN32_WINNT` and `WINVER` macros, if they are defined, or the default version is chosen. The default version is currently Windows Vista/Server 2008 on compilers that support this version of SDK and Windows XP on others. The default may change in future releases.]]
  40     [[`BOOST_USE_WINDOWS_H`]                    [This macro is part of Boost.Config. If defined, Boost.WinAPI will include `<windows.h>` and any other headers from Windows SDK as needed. Otherwise Boost.WinAPI will provide its own declarations of the SDK components as needed without including SDK headers.]]
  41     [[`BOOST_NO_ANSI_APIS`]                     [This macro is defined by Boost.Config on platforms that do not support narrow-character versions of some APIs. Boost.WinAPI will not declare narrow-character APIs when this macro is defined.]]
  42 ]
  43
  44 User's code can include `<boost/detail/winapi/config.hpp>` to define a number of macros that can be useful. Including this header is recommended in any code that involves Windows API usage.
  45
  46 [table Defined configuration macros
  47     [[Macro name]                               [Effect]]
  48     [[`BOOST_USE_WINAPI_VERSION`]               [If not defined by user, this macro is defined by the header to the target Windows API version.]]
  49     [[`BOOST_WINAPI_VERSION_NT4`,[br]`BOOST_WINAPI_VERSION_WIN2K`,[br]`BOOST_WINAPI_VERSION_WINXP`,[br]`BOOST_WINAPI_VERSION_WS03`,[br]`BOOST_WINAPI_VERSION_WIN6`,[br]`BOOST_WINAPI_VERSION_VISTA`,[br]`BOOST_WINAPI_VERSION_WS08`,[br]`BOOST_WINAPI_VERSION_LONGHORN`,[br]`BOOST_WINAPI_VERSION_WIN7`,[br]`BOOST_WINAPI_VERSION_WIN8`,[br]`BOOST_WINAPI_VERSION_WINBLUE`,[br]`BOOST_WINAPI_VERSION_WINTHRESHOLD`,[br]`BOOST_WINAPI_VERSION_WIN10`]
  50                                                 [These macros expand to the constants designating the particular Windows versions and can be used together with `BOOST_USE_WINAPI_VERSION` in preprocessor version checks.]]
  51     [[`BOOST_WINAPI_IS_MINGW`]                  [Defined if Windows SDK is provided by [@http://mingw.org/ MinGW].]]
  52     [[`BOOST_WINAPI_IS_MINGW_W64`]              [Defined if Windows SDK is provided by [@http://mingw-w64.org MinGW-w64]. Note that is does not mean that the code is compiled for 64-bit Windows.]]
  53 ]
  54
  55 [endsect]
  56
  57 [section:usage Using Boost.WinAPI]
  58
  59 In order to use Boost.WinAPI you have to include one or several headers from the `boost/detail/winapi` directory. Each header there defines a portion of Windows API, the name of the header should be self-explanatory. Each Boost.WinAPI header may declare a number of symbols like functions and types in the global namespace, mimicking the Windows SDK, and the corresponding set of symbols in the `boost::detail::winapi` namespace. User's code is supposed to use the symbols from the `boost::detail::winapi` namespace only.
  60
  61 Most of the functions in the `boost::detail::winapi` have the same name and meaning as the corresponding Windows API functions. Types and constants have a trailing underscore ('_') in their name to avoid clashes with macros that are defined in Windows SDK.
  62
  63 [note Boost.WinAPI does not define function-name macros that expand to the `char` or `wchar_t` based functions depending on the `UNICODE` macro. Boost.WinAPI also does not support `_TCHAR` and related string types. Users have to explicitly use the `*A` or `*W` functions with appropriate argument types. Note however that `*A` functions may not be available if `BOOST_NO_ANSI_APIS` is defined.]
  64
  65 For example, here is how one would create and destroy a semaphore with Boost.WinAPI:
  66
  67     #include <limits>
  68     #include <boost/detail/winapi/handles.hpp>
  69     #include <boost/detail/winapi/semaphore.hpp>
  70
  71     boost::detail::winapi::HANDLE_ h = boost::detail::winapi::CreateSemaphoreExW(
  72         NULL,                                                        // security attributes
  73         0l,                                                          // initial count
  74         std::numeric_limits< boost::detail::winapi::LONG_ >::max(),  // max count
  75         L"Local\\MySemaphore",                                       // semaphore name
  76         0l,                                                          // flags
  77         boost::detail::winapi::SEMAPHORE_ALL_ACCESS_                 // access mode
  78     );
  79
  80     if (h)
  81         boost::detail::winapi::CloseHandle(h);
  82
  83 Refer to [@https://msdn.microsoft.com/library MSDN] for documentation on the particular functions, types and constants.
  84
  85 [endsect]