w32api/include/w32api.h.in

   1 /*
   2  * w32api.h
   3  *
   4  * Package version identification, operating system support level set up,
   5  * and "convenience" macros to be shared by all package header files.
   6  *
   7  * $Id$
   8  *
   9  * Written by Earnie Boyd  <earnie@users.sourceforge.net>
  10  * Copyright (C) 2001-2011, 2015, 2016, MinGW.org Project
  11  *
  12  *
  13  * Permission is hereby granted, free of charge, to any person obtaining a
  14  * copy of this software and associated documentation files (the "Software"),
  15  * to deal in the Software without restriction, including without limitation
  16  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  17  * and/or sell copies of the Software, and to permit persons to whom the
  18  * Software is furnished to do so, subject to the following conditions:
  19  *
  20  * The above copyright notice and this permission notice (including the next
  21  * paragraph) shall be included in all copies or substantial portions of the
  22  * Software.
  23  *
  24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  29  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  30  * DEALINGS IN THE SOFTWARE.
  31  *
  32  */
  33 #ifndef _W32API_H
  34 #define _W32API_H
  35 #pragma GCC system_header
  36
  37 /* Package version identification: formerly specified as a simple
  38  * dotted numeric pair representing major.minor, this doesn't adapt
  39  * well to the inclusion of the patch-level, since the dotted triplet
  40  * representation of major.minor.patch is not a valid representation
  41  * of a numeric entity.  Thus, from version 3.18 onwards we adopt a
  42  * representation which encodes the version as a long integer value,
  43  * expressing:
  44  *
  45  *   __W32API_VERSION = 1,000,000 * major + 1,000 * minor + patch
  46  *
  47  * DO NOT EDIT these package version assignments manually; they are
  48  * derived from the package version specification within configure.ac,
  49  * whence they are propagated automatically, at package build time.
  50  */
  51 #define __W32API_VERSION           %PACKAGE_VERSION_LONG%L
  52 #define __W32API_MAJOR_VERSION     %PACKAGE_VERSION_MAJOR%
  53 #define __W32API_MINOR_VERSION     %PACKAGE_VERSION_MINOR%
  54 #define __W32API_PATCHLEVEL        %PACKAGE_VERSION_PATCH%
  55
  56 /* The underlying operating system platform version, and its
  57  * identifying macros for application support, are established by:
  58  */
  59 #include <sdkddkver.h>
  60
  61 /* The following defines are for documentation purposes.  Although not used
  62  * within it, they were provided in earlier versions of the Win32 API, as a
  63  * convenience for users who wished to symbolically declare a minimum level
  64  * of required operating system and Internet Explorer version support, when
  65  * assigning WINVER, _WIN32_WINDOWS, _WIN32_WINNT, and _WIN32_IE values.
  66  *
  67  * Each of the following "old name" macros is now considered deprecated in
  68  * favour of manifest "preferred name" macro definitions from <sdkddkver.h>.
  69  * Hence, redefine each in terms of the appropriate "preferred name" macro;
  70  * new code should avoid the old names, and use the preferred name instead.
  71  *
  72  *
  73  * _WIN32_WINDOWS and/or WINVER may be set to any of the following manifest
  74  * values, to specify a minimum Win9x support level requirement:
  75  *
  76  *      Old Name        Preferred Name
  77  *      -------------   ------------------
  78  */
  79 #define Windows95       _WIN32_WINDOWS_95
  80 #define Windows98       _WIN32_WINDOWS_98
  81 #define WindowsME       _WIN32_WINDOWS_ME
  82
  83 /* _WIN32_WINNT and/or WINVER may be set to any of the following manifest
  84  * values, to specify a minimum WinNT support level requirement:
  85  *
  86  *      Old Name        Preferred Name
  87  *      -------------   ------------------
  88  */
  89 #define WindowsNT4      _WIN32_WINNT_NT4
  90 #define Windows2000     _WIN32_WINNT_WIN2K
  91 #define WindowsXP       _WIN32_WINNT_WINXP
  92 #define Windows2003     _WIN32_WINNT_WS03
  93 #define WindowsVista    _WIN32_WINNT_VISTA
  94
  95 /* _WIN32_IE may be set to any of the following manifest values, to
  96  * specify a minimum Internet Explorer support level requirement:
  97  *
  98  *      Old Name        Preferred Name
  99  *      -------------   ------------------
 100  */
 101 #define IE3             _WIN32_IE_IE30
 102 #define IE301           _WIN32_IE_IE301
 103 #define IE302           _WIN32_IE_IE302
 104 #define IE4             _WIN32_IE_IE40
 105 #define IE401           _WIN32_IE_IE401
 106 #define IE5             _WIN32_IE_IE50
 107 #define IE5a            _WIN32_IE_IE50
 108 #define IE5b            _WIN32_IE_IE50
 109 #define IE501           _WIN32_IE_IE501
 110 #define IE55            _WIN32_IE_IE55
 111 #define IE56            _WIN32_IE_IE56
 112 #define IE6             _WIN32_IE_IE60
 113 #define IE601           _WIN32_IE_IE60SP1
 114 #define IE602           _WIN32_IE_IE60SP2
 115 #define IE7             _WIN32_IE_IE70
 116
 117
 118 /* Only Microsoft could attempt to justify this insanity: when building
 119  * a UTF-16LE application -- apparently their understanding of Unicode is
 120  * limited to this -- the C/C++ runtime requires that the user must define
 121  * the _UNICODE macro, while to use the Windows API's UTF-16LE capabilities,
 122  * it is the UNICODE macro, (without the leading underscore), which must be
 123  * defined.  The (bogus) explanation appears to be that it is the C standard
 124  * which dictates the requirement for the leading underscore, to avoid any
 125  * possible conflict with a user defined symbol; (bogus because the macro
 126  * must be user defined anyway -- it is not a private symbol -- and in
 127  * any case, the Windows API already reserves the UNICODE symbol as
 128  * a user defined macro, with equivalent intent.
 129  *
 130  * The real explanation, of course, is that this is just another example
 131  * of Microsoft irrationality; in any event, there seems to be no sane
 132  * scenario in which defining one without the other would be required,
 133  * or indeed would not raise potential for internal inconsistency, so we
 134  * ensure that either both are, or neither is defined.
 135  */
 136 #if defined UNICODE && ! defined _UNICODE
 137 # define _UNICODE  UNICODE
 138 #elif defined _UNICODE && ! defined UNICODE
 139 # define UNICODE  _UNICODE
 140 #endif
 141 /* Related to the UNICODE macro definition, there are many functions in
 142  * the Win32 API with a generic name, which is mapped to a variant with
 143  * wchar_t UTF-16LE encoding of string arguments, in cases when UNICODE
 144  * is defined, as facilitated by the following macro...
 145  */
 146 #ifdef UNICODE
 147  /* ...by appending a "W" suffix to the generic function name...
 148   */
 149 # define __AW_SUFFIXED__(__NAME__)  __NAME__##W
 150 #else
 151  /* ...or by appending an "A" suffix, to select an ANSI variant with
 152   * char encoding of string arguments, when UNICODE is not defined.
 153   */
 154 # define __AW_SUFFIXED__(__NAME__)  __NAME__##A
 155 #endif
 156 /* Further related, the __AW_EXTENDED__ macro reproduces the effect of
 157  * __AW_SUFFIXED__, with the addition of a single underscore character
 158  * separating the base name from the appropriate suffix.
 159  */
 160 #define __AW_EXTENDED__(__NAME__)  __AW_SUFFIXED__(__NAME__##_)
 161
 162 /* __AW_EXTENDED__ may often be used to map manifest string constants.
 163  * The following triplet provide a convenient mechanism to derive the
 164  * UNICODE variant of the string from its ANSI definition; (note that
 165  * this requires a two stage expansion, to ensure that the "L" prefix
 166  * is attached to the expansion of the ANSI string definition, rather
 167  * than just to the defining macro name).
 168  */
 169 #define __AW_STRING_A__(__TEXT__)  __TEXT__
 170 #define __AW__WCHAR_T__(__TEXT__)  __AW_STRING_A__(L##__TEXT__)
 171 #define __AW_STRING_W__(__TEXT__)  __AW__WCHAR_T__(__TEXT__)
 172
 173 /* Further uses of __AW_SUFFIXED__ and __AW_EXTENDED__, encapsulated
 174  * within __AW_ALIAS__ and __AW_ALIAS_EX__; each provides a convenient
 175  * generic mapping for type names with alternative representations for
 176  * UNICODE and non-UNICODE usage.
 177  */
 178 #define __AW_ALIAS__(__NAME__)     __AW_SUFFIXED__(__NAME__) __NAME__
 179 #define __AW_ALIAS_EX__(__NAME__)  __AW_EXTENDED__(__NAME__) __NAME__
 180
 181 #ifdef __cplusplus
 182 /* When compiling C++ code, these macros provide a convenient notation
 183  * for designating those sections of system header files which declare
 184  * prototypes for API functions with "C" binding...
 185  */
 186 # define _EXTERN_C       extern "C"
 187 # define _BEGIN_C_DECLS  extern "C" {
 188 # define _END_C_DECLS    }
 189
 190 #else
 191 /* ...while remaining transparent, when compiling C code.
 192  */
 193 # define _EXTERN_C       extern
 194 # define _BEGIN_C_DECLS
 195 # define _END_C_DECLS
 196 #endif
 197
 198 #endif /* ! _W32API_H: $RCSfile$: end of file */