
 A. About Win32Inc

   Win32Inc is a set of ASM include files in MASM syntax to create Win32
   applications and dlls. Furthermore, there are module definition files
   supplied to create the standard Win32 import libraries.

   Some samples in the SAMPLES directory illustrate how to use Win32Inc.


 B. Requirements

   Assemblers which are able to digest the Win32Inc include files are

    - MASM
    - JWASM (http://www.japheth.de/JWasm.html)
    - POASM (partially)

   which gives a quite large range of possible tool chains for Win32
   development in MASM-like assembly:

   - include files:   Win32Inc
   - assembler:       JWASM, MS MASM or POASM
   - linker:          WLINK, MS LINK or POLINK
   - resource comp:   WRC,   MS RC   or PORC
   - librarian [opt]: WLIB,  MS LIB  or POLIB

   WLINK, WRC and WLIB are included in Open Watcom, POASM, POLINK, PORC
   and POLIB are included in PellesC. Both Open Watcom and PellesC are
   free.


 C. Creating Win32 Libraries

   a) Standard Win32 libs

   When creating Win32 binaries the link step will require import libraries
   to resolve the references to the Win32 API. One may get these libraries
   from the MS PSDK for free, but another very simple approach is supplied
   with Win32Inc: create the import libs with tool POLIB and some .DEF files
   supplied in sub directory DEF. Just run Def\MAKELIBS.BAT to create the
   libraries.
   
   a) UUID.LIB
   
   Regretably not all Win32 libraries are just import libraries which can 
   be created by POLIB. Some contain static code. One of those - which is
   crucial for COM - is UUID.LIB. The file UUID.LIB contained in Lib subdir
   is not a fully functional version of this lib. It is created by tool
   UUID\mkguids.exe and contains just the very minimum of GUIDs. If you need
   additional GUIDs in your binary, either get a version of UUID.LIB from
   other sources (PSDK for example) or add the missing GUIDS to file
   UUID\uuid and rerun UUID\makeuuid.bat.

   Thanks to Vortex and his (free) LIB2DEF utility, which has been used to
   create the .DEF files.


 D. Include Files Overview

   There might exist - rare - conditions where it is necessary to recreate
   one of the include files supplied with Win32Inc. In this case the 
   following information might be helpful:

   
  a) Some files were not generated by h2incx. These are:

   1. Files with no C counterpart

    - WINASM.INC: this file is manually created

   2. Files that will not be translated

    - PSHPACK1.INC: these files do control structure alignment
    - PSHPACK2.INC
    - PSHPACK4.INC
    - PSHPACK8.INC
    - POPPACK.INC

   3. Files not translated yet (currently manually created)

    - OBJBASE.INC: COM base include


  b) Modified Include Files

  These were the adjustments done after conversion with h2incx:

  COMMCTRL.INC   some pointers to unknown structures modified [POASM]

  DDRAW.INC      Underscore added to methods
                 - CreatePalette, GetPixelFormat, GetDC, ReleaseDC
                 because these names are valid win32 base functions

  DINPUT.INC      Underscore added to methods
                 - Escape
                 because these names are valid win32 base functions

  GL.INC         GLvoid typedef was invalid

  IMAGEHLP.INC   STACKFRAME.BOOL field changed to STACKFRAME.Far_

  MSXML.INC      Add an underscore to methods       
                 - send
                 because these names are valid base functions

  OAIDL.INC      wireSAFEARRAY wrong
                 tagVARIANT structure should be renamed to VARIANT
                 wType parameter in Invoke_ prototypes should be changed
                 from WORD to DWORD

  OBJIDL.INC     Underscore added to methods
                 - RevertToSelf
                 - GetObject
                 - ReleaseMutex
                 because these names are valid windows base functions

  OCIDL.INC      type SIZE has to be changed to SIZE_
                 Underscore added to methods
                 - GetClassInfo
                 - GetCapture
                 - SetCapture
                 - GetFocus
                 - SetFocus
                 - GetDC
                 - ReleaseDC
                 - TranslateAccelerator (3*)
                 because these names are valid win32 base functions

  OLEAUTO.INC    WORD parameter types in VariantChangeType(Ex) should be
                 changed to DWORD
                 VARTYPE parameter types should be changed to DWORD

  OLEIDL.INC     Underscore added to methods
                 - EnumObjects (2*)
                 - GetObject
                 - TranslateAccelerator (2*)
                 - SetMenu
                 - GetClipboardData
                 - GetWindow (5*)
                 because these names are valid win32 base functions

  PROPIDL.INC    rename tagPROPVARIANT to PROPVARIANT
                 inline function PropVariantInit must be changed to a macro

  PRSHT.INC      some pointers to unknown structures modified [POASM]

  RICHEDIT.INC   _WPAD type padding members must be deactivated

  RPCDCE.INC     several occurences of ":ptr unsigned" changed to ":ptr"

  RPCNDR.INC     2* changed __int64 to QWORD
                 several occurences of ":ptr unsigned" changed to ":ptr"
                 some prototypes with variable arguments missed C
                 qualifier

  SHOBJIDL.INC   underscore added to methods
                 - EnumObjects (2*)
                 - GetPath (2*)

  SQLEXT.INC     equate SQL_ODBC_KEYWORDS commented out ("line too long")

  SQLTYPES.INC   typedef PTR deleted
                 "unsigned" removed in 2 typedefs

  URLMON.INC     Underscore added to methods
                 - GetWindow
                 because these names are valid windows base functions

  WINBASE.INC    parameters of type ATOM should be changed to DWORD
                 to avoid MASM invoke bug
                 some "ptr volatile" changed to "ptr" (bug in h2incx) [POASM]
                 some pointers to unknown structures modified [POASM]

  WINCRYPT.INC   - Type_ changed to Type__ in struct KEY_TYPE_SUBTYPE               
                 - ifndef CONST deactivated

  WINDEF.INC     CONST is defined in this file, which is invalid for MASM
                 NULL equate is wrong
                 HFILE_ERROR equate is wrong
                 SIZE structure is translated to SIZE_ but some pointers
                 to this structure are generated wrong

  WINERROR.INC   the error handling macros (MAKE_HRESULT, MAKE_SCODE,...)
                 have to be adjusted! 

  WINIOCTL.INC   Prefetch member changed to Prefetch_.
                 macro IsRecognizedPartition deleted (line too long!)

  WINNT.INC      macros for 64bit processing not translated
                 DECLARE_HANDLE() macro wrong
                 TokenSource member invalid
                 NtCurrentTeb, GetCurrentFiber, GetFiberData must be
                 converted to macros
                 bitfield in IMPORT_OBJECT_HEADER wrong (invalid name)
                 prototypes Int64ShllMod32,... where defined twice
                 ifdef __POASM__ added for "Short" member
                 some "ptr _<name>" changed to "ptr <name>" [POASM]

  WINUSER.INC    prototype FlashWindow isn't created correctly
                 2 definitions are in C++ syntax
                 MASM bug: MAKEINTRESOURCE() should be a macro such as
                 MAKEINTRESOURCEA(). If defined as equate it may cause MASM
                 to produce error "line too long"!?!
                 MENUTEMPLATEA + W: typedef changed to BYTE [POASM]
                 some pointers to unknown structures modified [POASM]

  Additionally the following common problem was fixed:

  MSXML.INC      h2incx can now translate C headers generated by MIDL.
  OAIDL.INC      But there are 2 common errors in the created includes:
  OCIDL.INC      1. interface forward declarations are created wrong and
  OLEIDL.INC        should be deleted (cured since version 0.97)
  SERVPROV.INC   2. prototypes "MIDL_user_allocate" + "MIDL_user_free" 
  UNKNWN.INC        should be deleted. This is a MASM bug: prototypes 
  URLMON.INC        occuring more than once in an assembly unit may cause
  OBJIDL.INC        an (unresolved) external.
  OLECTL.INC


  c) Non-Win32 includes (C header files, used by windows.h)

  The following files for MS VC are included as well, since they are used
  by the Win32 includes:

  - CTYPE.INC
  - EXCPT.INC
  - FLOAT.INC
  - LIMITS.INC
  - MATH.INC
  - STDARG.INC
  - STDLIB.INC
  - STRING.INC

  STDIO.INC has been added as well, since it comes in handy. However, some
  of the stream functions might need to distinguish between the static and
  the dynamic CRT library. Add the "-D_ML" option to assembler's command line
  if the static CRT library is to be used (this is similiar to the /ML switch
  for MS VC).


 E. History

  09/02/2009 V1.3.5

  - DDraw2 sample added.
  - SockHttp sample changed, MSVCRT.DLL is no longer used.
  - added entry for GetVDMCurrentDirectories to WINBASE.DEF
  - TLHelp32.DEF added.
  - WINNT.INC, WTYPES.INC: type SHORT deactivated. In WINASM.INC
    option nokeyword:<short> removed.
  - some duplicated entries in WINGDI.DEF and WINUSER.DEF removed.
  - ntdll.inc added, contains a prototype for RtlUnwind().
  - sspi.inc and secur32.def added.

  01/24/2009 V1.3.4

  - SHELLAPI.INC replaced by file generated from C header versions
    dated 2001 (previously 1998).
  - WINASM.INC: equate ('wstr EQU parms') commented out.
  - SHLOBJ.INC: order of bits in record SHELLFLAGSTATE corrected.
  - RPCNDR.INC: order of bits in record MIDL_STUB_MESSAGE_R0 corrected.
  - WINGDI.INC: structs TEXTMETRICA/NEWTEXTMETRICA got a DWORD alignment
    parameter.

  11/22/2008 V1.3.3

  - bugfix in SHLOBJ:INC, structs NT_CONSOLE_PROPS and NT_FE_CONSOLE_PROPS
    contained a wrong member declaration of type DATABLOCK_HEADER.
  - GUIDs IQueryInfo, IDockingWindowSite, IDockingWindowFrame
    added to UUID.LIB

  09/13/2008 V1.3.2

  - WSOCK32.DEF and VERSION.DEF added.
  - some GUIDs concerning active scripting added to UUID.LIB
  - GUIDs IErrorInfo, IFontDisp, IDispatchEx, IDispError, IViewObjectEx
    added to UUID.LIB
  - some GUIDs of MSHTMHST.H added to UUID.LIB

  07/21/2008 V1.3.1

  - bugfix: WINBASE.INC: WIN32_FIND_DATAA needed an alignment parameter.
  - bugfix: WINIOCTL.INC: PARTITION_INFORMATION alignment parameter 8 added.
  - VWIN32.INC added.
  - RECORD definitions in WINNT.INC and WINBASE.INC adjusted.
  - modules for UUID.LIB now assembled with JWasm to reduce size.
  - WINSVC.DEF and MSWSOCK.DEF added.

  04/30/2008 V1.3

  - Win32Inc compatible with the new JWasm.
  - bugfix: OCIDL.INC: CONTROLINFO struct needed an alignment parameter.
  - bugfix: WINGDI.INC: BITMAPCOREINFO now aligned to DWORD.
  - bugfix: WINBASE.INC: COMMCONFIG+COMMPROP structures needed dword alignment.
  - bugfix: removed some entries in WINGDI.DEF, which belonged to OpenGl32.
  - IMAGEHLP.DEF and MPR.DEF added.

  02/12/2008 V1.2.5

  - bugfix: structures DISK_INT13_INFO and DISK_EX_INT13_INFO needed
    an alignment parameter.
  - WINNLS.DEF added.

  01/04/2008 V1.2.4

  - EXDISPID.INC added.
  - MSHTMDID.INC added.
  - OLEDB.INC added.
  - DCIDDI.INC, DCIMAN.INC added.
  - DINPUT.INC updated (methods "Escape" changed to "Escape_")
  - some GUIDs added for UUID.LIB
  - bugs fixed in WINIOCTL.INC
  - VDDSVC.INC, NT_VDD.INC added
  - NTVDM.DEF added

  10/05/2007 V1.2.3

  - some more GUIDs added for UUID.LIB
  - WINSPOOL.DEF added
  - bugfix: URL_COMPONENTS structure needed DWORD alignment

  08/12/2007 V1.2.2

  - STDIO.H: definition for stdin, stdout, stderr adjusted to account
    for some slight differences when using the static or dynamic C runtime.
  - WinINet sample made POASM compatible.  
  - OpenGL1 sample made POASM compatible.  
  - bugfix in GL.INC: GLvoid typedef adjusted
  - some more GUIDs added for UUID.LIB
  - some missing exports added for SHELL32.LIB
  - UnpackDDElParam, ReuseDDElParam exports added for USER32.LIB

  02/27/2007 V1.2.1

  - bugfix: DSound1 sample contained "include macros.inc",
    WinGUI1 sample was unable to load menu.
  - bugfix: mkguids.asm contained crt.inc (changed to stdio.inc
    and stdlib.inc)
  - bugfix: mkguids tool caused a GPF if file parameter wasn't an existing 
    file.
  - names of samples reorganized
  - sample SockHttp added
  - winsock.inc made compatible with POASM
  - DSOUND.DEF, OPENGL32.DEF, GLU32.DEF added

  02/23/2007 V1.2

  - WININET.DEF, SHLWAPI.DEF, RPCRT4.DEF and ODBC32.DEF added
  - SQL.INC, SQLTYPES.INC, SQLEXT.INC, SQLUCODE.INC added
  - samples ODBCSample and WinINet added

  01/21/2007 V1.1.9

  - a call of PORC added to GUISample2
  - sample SimplSvr updated
  - CRTDLL.DEF updated
  - MSVCRT.DEF added
  - WinMM.def added
  - WS2_32.DEF added
  - ordinals added to OLEAUT32.DEF 
  - RPC* includes updated with newer versions (PSDK 2001)
  - ADOSample was damaged in previous versions
  - Rtl* functions missing in winbase.def
  - shell GUIDs added to uuid\uuid

  01/17/2007 V1.1.8

  - missing GUID_NULL definition added to uuid\uuid
  - bugfix: underscore prefix removed in "_wsprintf" lines in Def\winuser.def

  01/15/2007 V1.1.7

  - some more .DEF files added: OLE32.DEF, OLEAUT32.DEF, COMDLG32.DEF
  - LIB\UUID.LIB, UUID\* and TOOLS\mkguids.asm added 
  - added to WINBASE.DEF: MultiByteToWideChar and WideCharToMultiByte
    exports.

  07/31/2006 V1.1.6

  - DEF subdir added to supply a simple method creating Win32 libraries
  - winioctl.inc added
  - prototypes in OBJBASE.INC changed to use @DefProto macro
  - SetConsoleTextAttribute second parameter changed from type WORD to DWORD
  - changes to make it POASM compatible:
    - create a WINASMP.INC for POASM (MASM still uses WINASM.INC)
    - POASM is much stricter with pointer types. It doesn't accept pointers
      to unknown structures. This had to be adjusted in the includes.

  03/18/2006 V1.1.5

  - bugfix: MAKEINTRESOURCE() didn't work in version 1.1.4. Thanks to
    Chun Sejin!

  02/25/2006 V1.1.4

  - bugfix: macros FD_SET, FD_CLR, FD_ISSET and FD_ZERO
    adjusted in WINSOCK.INC and WINSOCK2.INC. FD_SET typedef commented out.
  - bugfix: WSADATA structure needed a dword alignment parameter.
  - WAVEFORMATEX structure added to tools STRUCSIZ/STRUCSIC.
  - bugfix: 2 macros in MMSYSTEM.INC contained C style numbers
  - bugfix: ImageHlp.inc: struct STACKFRAME contained a field
    named "BOOL" (C name is "Far").
  - MSACM.INC, MMREG.INC, GUIDDEF.INC, TVOUT.INC, REASON.INC 
    WINTRUST.INC added.
  - WINNT.INC, WINBASE.INC, WINCON.INC, WINREG.INC, WINGDI.INC,
    WINUSER.INC replaced by files generated from C header versions
    dated 2001 (previously 1998). So most WinXP features should be
    covered by these includes.
  - _WIN32_WCE + _WIN32_FUSION added to WINASM.INC  

  12/29/2005 V1.1.3

  - DirectSound sample added.

  11/25/2005 V1.1.2

  - GL\GL.INC, GL\GLU.INC, GL\GLAUX.INC added
  - OpenGL sample added.

  10/21/2005 V1.1.1

  - DINPUT.INC + DSOUND.INC added

  08/28/2005 V1.1.0

  - DDRAW.INC: added underscore to methods CreatePalette,
    GetPixelFormat (GDI32 function name alias) , GetDC, ReleaseDC
    (USER32 function name alias).

  04/23/2005 V1.0.9

  - OBJBASE.INC: macros SUCCEEDED() and FAILED() had a severe bug.

  03/12/2005 V1.0.8

  - WINNT.INC: macro __TEXT() works now (required for
    constants such as SE_BACKUP_NAME)
  - MSWSOCK.INC: @DefProto macro used for prototypes
  - EXCPT.INC: prototype _exception_code commented out

  02/25/2005 V1.0.7.2

  - sample "Win32 console app" added

  02/24/2005 V1.0.7.1

  - bugfix: ADO sample used include file "macros.inc",
    which is not part of win32inc.zip

  02/23/2005 V1.0.7

  - OAIDL.INC replaced by newer version (old version
    missed IPropertyBag). MSXML.INC replaced by newer version.
  - ADOINT.INC added. Sample for ADO DB access added.

  02/20/2005 V1.0.6

  - ASPTLB.INC, IDISPIDS.INC added.
  - OAIDL.INC, OBJIDL.INC, OLEIDL.INC, OCIDL.INC, SHLDISP.INC,
    SHOBJIDL.INC replaced by versions using STDMETHOD macro.

  02/17/2005 V1.0.5.1

  - HTTPEXT.INC added

  02/17/2005 V1.0.5

  - FLOAT.INC replaced by versions using @DefProto macro
  - STDIO.INC: stdin and stdout macros for _DLL branch didn't work
  - WINSOCK.INC, WINSOCK2.INC and WININET.INC replaced.

  02/15/2005 V1.0.4

  - STRING.INC replaced by versions using @DefProto macro
  - bugfix: COMMCTRL.INC: ListView_SetItemState macro didn't work.

  02/14/2005 V1.0.3

  - WINNT.INC, WINBASE.INC, WINCON.INC, WINREG.INC,
  - WINGDI.INC, WINUSER.INC, STDIO.INC, STDLIB.INC replaced by
    versions using @DefProto macro.
  - equate ISOLATION_AWARE_ENABLED defined in winasm.inc.
  - COMMDLG.INC + PRSHT.INC replaced by newer versions (2001).
  - IMAGEHLP.INC added.

  02/04/2005 V1.0.2

  - some test tools added.
  - WINDOWSX.INC added.
  - COMMCTRL.INC: message cracker macros adjusted. 
  - WINASM.INC: SNDMSG() macro added.

  02/03/2005 V1.0.1

  - bugfix OBJIDL.INC: alignment 4 for FORMATETC
  - bugfix OAIDL.INC: alignment 4 for some structures
  - bugfix OAIDL.INC: PARAMDESCEX should have alignment 8,
    but this doesn't work for MASM 6/7. So a "filler" DWORD
    was added.
  - bugfix STDLIB.INC: some prototypes were wrong and externdefs
    missed "c" qualifier.
  - WINASM.INC: L() macro defined.

  02/01/2005 V1.0:

  - Win32 includes extracted from h2incx and shell includes added.


 F. Copyright

  I don't preserve any copyrights on the Win32 ASM include files. They are
  public domain. The 'copyright' string in the include files refers to tool
  h2incx, not to the include files themselves.

  Japheth

