carb/CarbWindows.h

In directory: carb

Source file: carb/CarbWindows.h

Allow access to specific parts of Windows API without including Windows.h.

This file replaces #include <Windows.h> for header files. Windows.h is monolithic and defines some oft-used names like min, max, count, etc. Directives like NOMINMAX, WIN32_LEAN_AND_MEAN, and WIN32_EXTRA_LEAN can help, but still leave the global namespace much more polluted than is desired. Note that the MSVC CRT does not include Windows.h anywhere; instead special reserved naming conventions (such as _PrefixedUpper) exist to allow the CRT to define special functions that are called by the CRT, but the implementation of those functions (that utilize the Windows API) are hidden away in static or dynamic libraries. However, for Carbonite, since the goal is to not require additional linking for header utilities, there is no ability for carb header files to similarly hide Windows API usage in libraries.

Anything from the Windows API that Carbonite relies upon should be defined in this file, and should not conflict in the event that Windows.h is included.

Rules for adding things to this file:

  1. Do not #define anything that is defined in Windows.h. Instead, prefix the macro name with CARBWIN_ but give it the same value. This is to prevent errors if Windows.h is included since macros may not be defined more than once.

  2. Typedef’s should be specified exactly as in Windows.h

  3. Structs can be forward-declared only, otherwise definitions will conflict with Windows.h. If a struct definition is required, it should be prefixed with CARBWIN_ at the bottom of this file. TestCarbWindows.cpp should then static_assert that the size and member offsets are the same as the Windows.h version.

  4. Enums cannot be redefined. Therefore, enum values needed should be changed to #define and prefixed with CARBWIN_.

These rules will allow compilation units to #include <Windows.h> before or after this file.