Power GUI Programming with VisualAge C++/powergui.iso/trialva/ibmcppw/sdk/readme.txt

Text File | 1995-07-11 | 24.9 KB | 675 lines

                Microsoft Win32 SDK for Microsoft Windows
                            August, 1995


---------------
1. Introduction
---------------

Welcome to the Microsoft Win32 SDK for Microsoft Windows.  This release of the
SDK provides the tools and information necessary to build retail applications
for Windows 95 and for Windows NT 3.51.

Most of the utilities, headers, libraries, documentation, and sample code in
the SDK are useful when building applications for both Windows 95 and Windows
NT 3.51.  Platform specific files are located in appropriately named
subdirectories, i.e. WIN95 and WINNT.  When the SDK is installed, it detects
the host operating system and installs any binaries specific to that OS.  All
of the headers and libraries are installed, so that either operating system
can host development targeting the other.  If the SDK is installed on a RISC
platform, samples that will run only on Windows 95 are not installed.

This release of the Win32 SDK contains new technology for viewing the on-line
documentation.  The familiar MSDN browser is now installed with the SDK, and
all of the core documentation is provided in this format.  The new browser
offers a unified window containing both the table of contents and the topic
page.  It also offers the ability to print multiple pages at one time.  Like
earlier versions of the SDK documentation, most reference pages include a
QuickInfo popup with platform specifics as well as Group and Overview links
to help move between related pages.



-----------
2. Compiler
-----------

There is no compiler, linker, lib utility, or make utility provided for x86,
MIPS, or Alpha platforms. You must have Microsoft Visual C++ version 2.x or
a compatible 32-bit compiler.

The SDK does include a compiler, linker, lib utility, and make utility for the
PowerPC platform.  The compiler will display a banner each time it is run.
The banner contains a phone number to be used for registering the compiler.
Registration is free and relatively easy.  Once the compiler is registered,
it will not expire.  However, a compiler that is not registered will cease
working 30 days after it is first used.  To register the compiler, call the
phone number listed in the banner, provide the people on the phone the "code"
in the banner and receive an "access code" in return.  Run register.exe with
the access code as the single command line parameter, e.g.
register <access_code>.

Visual C++ provides structured exception handling though the use of catch and
throw.  Although one of the SDK samples uses this technique (oleapt), the
PowerPC compiler will not support it.  There will be no catch/throw support
until Microsoft Visual C++ provides a compiler for PowerPC.



----------------------
3. Guide to Components
----------------------

For a general introduction to the Win32 SDK, including many of the tools,
see the "Getting Started" help file, i.e \MSTOOLS\HELP\SDKSTART.HLP.

Windows 95 and Windows NT both have fully compatible 32-bit implementations
of OLE.  For specific OLE information, see \MSTOOLS\SAMPLES\OLE\OLEREL.WRI.

Windows 95 and Windows NT both have fully compatible 32-bit implementations
of RPC.  For specific RPC information, see \MSTOOLS\SAMPLES\RPC\RPCREAD.ME.

The x86 version of MAPI is supported on both Windows 95 and Windows NT.  The
32-bit MAPI headers, libraries, documentation, tools, and sample code are
integrated into the Win32 SDK.  However, it is necessary to install the
Exchange client on Windows 95 or the MAPI run-time on Windows NT before
successfully running most of the MAPI executables (including the sample code).
See \MSTOOLS\MAPI\README.WRI for more information.

Win32s is a technology that will allow a 32-bit application to run on Windows
3.x.  Version 1.3 of Win32s is available in the \MSTOOLS\WIN32S directory.
This release contains the new Windows 95 common controls including richedit.
It also contains the new 4.0 winhelp with full text search.  For more
information, see \MSTOOLS\WIN32S\README.TXT.

This version of the Win32 SDK provides two setup toolkits.  See
\MSTOOLS\ISHIELD and \MSTOOLS\MSSETUP.  You are encouraged to evaluate
both and chose the one that best meets your setup needs.



------------------------------
4. Late Breaking Documentation
------------------------------

4.1 SHFormatDrive
-----------------

DWORD WINAPI SHFormatDrive(HWND hwnd, UINT drive, UINT fmtID, UINT options);

  Displays the format dialog box used by the shell, permitting the user to
  format one or more disks in the specified drive. The dialog box requires
  user interaction to carry out the formatting operation, so you cannot use
  this function for unassisted disk formatting.

  Returns the physical format identifier of the last succesful format or one
  of these values:

    SHFMT_ERROR    Error on last format, drive may be formatable
    SHFMT_CANCEL    Last format was canceled
    SHFMT_NOFORMAT    Drive cannot be formatted

 hwnd
  Handle of the owner window for the the dialog box. This parameter must be a
  valid window handle; it must not be NULL.

 drive
  Zero-based number of the drive to format. Use 0 for drive A, 1 for B, and
  so on.

 fmtID
  Physical format type identifier. Can be one of these values:
  SHFMT_ID_DEFAULT    Default format.

 options
  Options. Can be one of these bit values:
  SHFMT_OPT_FULL
    Full format. By default, the dialog uses a quick formatting operation.
    This option permits formatting of unformatted disks.

  SHFMT_OPT_SYSONLY
    Copies system files only.

  If a physical format identifier is returned, you can use the low-order 16
  bits as the fmtID parameter in a subsequent call to the function.  You
  cannot subclass this dialog box or add custom controls to it. You cannot
  limit the number of diskettes the user can format.

  This API is implemented on Windows 95 only.

  #define SHFMT_ID_DEFAULT     0xFFFF
  #define SHFMT_OPT_FULL       0x0001
  #define SHFMT_OPT_SYSONLY    0x0002
  #define SHFMT_ERROR      0xFFFFFFFFL
  #define SHFMT_CANCEL     0xFFFFFFFEL
  #define SHFMT_NOFORMAT   0xFFFFFFFDL



4.2 WM_PENCTL submessages
-------------------------

The following two submessages of WM_PENCTL are missing from the Pen Services
documentation.  These submessages should appear in the Pen Application
Programming Interface Messages chapter or topic.  Note that these submessages
do not apply to the Japanese version.

HE_GETLENSTYPE
 Retrieves the type of writing lens tool opened from an hedit control when
 the CorrectWriting function is called. Submessage of WM_PENCTL.

 Parameters
 wParam:
  HE_GETLENSTYPE
 lParam:
  Not used; must be set to 0L.
 Return Value
  Returns the current CorrectWriting (CWR_) options.
 Comments
  This submessage is for single-line hedit controls only.
 See Also
  WM_PENCTL, HE_SETLENSTYPE


HE_SETLENSTYPE
 Sets the type of writing lens tool opened from an hedit control when the
 CorrectWriting function is called. Submessage of WM_PENCTL.

 Parameters
 wParam:
   HE_SETLENSTYPE
 lParam:
  The low-order word must contain either CWR_BOXES, to open a bedit-type lens
  control or CWR_KEYBOARD to open an onscreen keyboard. These can  be bitwise-
  OR'ed with other CWR_ constant values described in CorrectWriting. The high
  order word must be one of the CWRK_ values described in CorrectWriting to
  specify which onscreen keyboard to open, either directly, if CWR_KEYBOARD is
  in the low-order word, or when accessed through the bedit lens otherwise.
 Return Value
  Returns TRUE if successful; otherwise, returns FALSE.
 Comments
  This submessage is for single-line hedit controls only.
 See Also
  WM_PENCTL, HE_GETLENSTYPE


4.3 VALENT
----------

The following reference page for the VALENT structure is new.
 VALENT
 typedef struct value_ent {
    LPTSTR   ve_valuename;
    DWORD ve_valuelen;
    DWORD ve_valueptr;
    DWORD ve_type;
 }VALENT;

 The VALENT structure contains information about a registry value. The
 RegQueryMultipleValues function uses this structure.

 MEMBERS

 ve_valuename
  Pointer to a null-terminated string. Before calling RegQueryMultipleValues,
  set this member to point to the name of a value to retrieve.

 ve_valuelen
  Specifies the size, in bytes, of the data pointed to by ve_valueptr.

 ve_valueptr
  Pointer to the data for the value entry. This is a pointer to the valueÆs
  data returned in the lpValueBuf buffer filled in by RegQueryMultipleValues.

 ve_type
  Specifies the type code for the value entry. The type code can be one of
  the following values:

 REG_BINARY
  Binary data in any form.

 REG_DWORD
  A 32-bit number.

 REG_DWORD_LITTLE_ENDIAN
  A 32-bit number in little-endian format (same as REG_DWORD). In little-
  endian format, the most significant byte of a word is the high-order word.
  This is the most common format for computers running Windows NT and
  Windows 95.

 REG_DWORD_BIG_ENDIAN
  A 32-bit number in big-endian format. In big-endian format, the most
  significant byte of a word is the low-order word.

 REG_EXPAND_SZ
  A null-terminated string that contains unexpanded references to environment
  variables (for example, %PATH%).  It will be a Unicode or ANSI string
  depending on whether you use the Unicode or ANSI functions.

 REG_LINK
  A Unicode symbolic link.

 REG_MULTI_SZ
  An array of null-terminated strings, terminated by two null characters.

 REG_NONE
  No defined value type.

 REG_RESOURCE_LIST
  A device-driver resource list.

 REG_SZ
  A null-terminated string. It will be a Unicode or ANSI string, depending on
  whether you use the Unicode or ANSI functions.

 See Also
  RegQueryMultipleValues


-----------------------
5. Documentation Errata
-----------------------

5.1 Functions
-------------

DocumentProperties
 The description of the pDevModeInput parameter should read as follows:
 pDevModeInput
  Pointer to a DEVMODE structure that the operating system uses to initialize
  the dialog box controls.  This parameter is only used if the DM_IN_BUFFER
  flag is set in the fMode parameter.  If DM_IN_BUFFER is not set, the
  operating system uses the printerÆs default DEVMODE.


DrawAnimatedRects
 The idAni parameter is now handled the same on Windows NT as on Windows 95.
 Its description should read as follows:
 idAni
  This parameter is reserved and must be zero.


FindResource
 The description of the hModule parameter should read as follows:
 hModule
  A handle to the module whose executable file contains the resource.
  A value of NULL specifies the module handle associated with the image
  file that the operating system used to create the current process.


FSCTL_DISMOUNT_VOLUME
 The syntax line for the lpchBytesReturned parameter should read as follows:
 lpcbBytesReturned;    // pointer to DWORD used by DeviceIoControl function

 The description for lpchBytesReturned should read as follows:
 lpcbBytesReturned
  Pointer to a DWORD. This value cannot be NULL. Although the
  FSCTL_DISMOUNT_VOLUME operation produces no output data, and lpvOutBuffer
  should be NULL, the DeviceIoControl function uses the variable pointed to
  by lpcbBytesReturned. After the operation, the value of this variable is
  without meaning.


FSCTL_LOCK_VOLUME
 The syntax line for the lpchBytesReturned parameter should read as follows:
 lpcbBytesReturned;    // pointer to DWORD used by DeviceIoControl function

 The description for lpchBytesReturned should read as follows:
 lpcbBytesReturned
  Pointer to a DWORD. This value cannot be NULL. Although the FSCTL_LOCK_VOLUME
  operation produces no output data, and lpvOutBuffer should be NULL, the
  DeviceIoControl function uses the variable pointed to by lpcbBytesReturned.
  After the operation, the value of this variable is without meaning.


FSCTL_SET_COMPRESSION
 The syntax line for the lpchBytesReturned parameter should read as follows:
 lpcbBytesReturned;    // pointer to DWORD used by DeviceIoControl function

 The description for lpchBytesReturned should read as follows:
 lpcbBytesReturned
  Pointer to a DWORD. This value cannot be NULL. Although the
  FSCTL_SET_COMPRESSION operation produces no output data, and lpvOutBuffer
  should be NULL, the DeviceIoControl function uses the variable pointed to
  by lpcbBytesReturned. After the operation, the value of this variable is
  without meaning.


FSCTL_UNLOCK_VOLUME
 The syntax line for the lpchBytesReturned parameter should read as follows:
 lpcbBytesReturned;    // pointer to DWORD used by DeviceIoControl function

 The description for lpchBytesReturned should read as follows:
 lpcbBytesReturned
  Pointer to a DWORD. This value cannot be NULL. Although the
  FSCTL_UNLOCK_VOLUME operation produces no output data, and lpvOutBuffer
  should be NULL, the DeviceIoControl function uses the variable pointed to
  by lpcbBytesReturned. After the operation, the value of this variable is
  without meaning.


GetDeviceCaps
 The descriptions of the nIndex constants PHYSICALWIDTH, PHYSICALHEIGHT,
 PHYSICALOFFSETX, and PHYSICALOFFSETY should read as follows:

 PHYSICALWIDTH
  For printing devices: the width of the physical page, in device units.  For
  example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical
  width value of 5100 device units. Note that the physical page is almost
  always greater than the printable area of the page, and never smaller.

 PHYSICALHEIGHT
  For printing devices: the height of the physical page, in device units. For
  example, a printer set to print at 600 dpi on 8.5"x11" paper has a physical
  height value of 6600 device units. Note that the physical page is almost
  always greater than the printable area of the page, and never smaller.

 PHYSICALOFFSETX
  For printing devices: the distance  from the left edge of the physical page
  to the left edge of the printable area, in device units. For example, a
  printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the
  leftmost 0.25" of paper, has a horizontal physical offset of 150 device
  units.

 PHYSICALOFFSETY
  For printing devices: the distance  from the top edge of the physical page
  to the top edge of the printable area, in device units. For example, a
  printer set to print at 600 dpi on 8.5"x11" paper, that cannot print on the
  topmost 0.5" of paper, has a vertical physical offset of 300 device units.

 The following nIndex constants and descriptions should be removed.
 SCALINGFACTORX
  For printing devices: the scaling factor along the horizontal axis.

 SCALINGFACTORY
  For printing devices: the scaling factor along the vertical axis.


GetICMProfile
 The type, name, and definition of this functionÆs second parameter
 (DWORD cbName) has been changed to the following:
 LPDWORD  lpcbName,

 The description for the lpcbName parameter should read as follows:
 lpcbName
  Pointer to a DWORD that contains the size, in bytes or characters, of the
  buffer that receives the filename, depending on whether the ANSI or Unicode
  version of the function is used.  If the buffer is too small, the function
  fails, and sets the DWORD pointed to by lpcbName to the minimum required
  buffer size.


GetShortPathName
 The following paragraph should be appended to the Remarks section of the
 GetShortPathName reference page:
  You can obtain the long name of a file from the short name by calling the
  FindFirstFile function.


GetSystemMetrics
 The following values are defined and should be added to the table for the
 nIndex parameter in the Parameters section:

 SM_CYDRAG
  Windows 95 only: Width and height, in pixels, of a rectangle centered on a
  drag point to allow for limited movement of the mouse pointer before a drag
  operation begins. This allows the user to click and release the mouse button
  easily without unintentionally starting a drag operation.

 SM_CYEDGE
  Windows 95 only: Dimensions of a 3D border, in pixels. These are the
  counterparts of SM_CXBORDER and SM_CYBORDER.

 SM_CYMIN
  Minimum width and height of a window.


MoveFileEx
 The first paragraph of the reference page for the MoveFileEx function should
 read as follows:
  The MoveFileEx function renames an existing file or directory.

 The descriptions for lpExistingFileName and lpNewFileName should read as
 follows:
 lpExistingFileName
  Points to a null-terminated string that names an existing file or directory.

 lpNewFileName
  Points to a null-terminated string that specifies the new name of
  lpExistingFileName. When moving a file, the destination can be on a different
  file system or drive. When moving a directory, the destination must be on the
  same drive.
  Windows NT only:
  If dwFlags specifies MOVEFILE_DELAY_UNTIL_REBOOT, lpNewFileName can be NULL.
  In this case, the function registers the lpExistingFileName file to be
  deleted when the system reboots.

 In the Remarks section of this reference page, the Windows NT only note should
 read as follows:
 Windows NT only:
  If the dwFlags parameter specifies MOVEFILE_DELAY_UNTIL_REBOOT, the function
  stores entries under the following registry key:
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
    Control\Session Manager\FileRenameOperations
  The system uses these registry entries to complete the operation at reboot.
  For example, on Windows NT, the following code fragment creates registry
  entries that delete szDstFile and rename szSrcFile to be szDstFile at reboot:
    MoveFileEx(szDstFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
    MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

 Windows 95 only:
  The MOVEFILE_DELAY_UNTIL_REBOOT flag is not supported.  To rename or delete
  a file at reboot on a Windows 95 system, place an entry in the WININIT.INI
  file in the Windows directory.  For example, on Windows 95, the following
  code fragment creates WININIT.INI entries that delete szDstFile and rename
  szSrcFile to be szDstFile at reboot:
    GetWindowsDirectory(szWinInitFile, uSize);
    lstrcat(szWinInitFile, "\\WININIT.INI");
    WritePrivateProfileString("Rename", "NUL", szDstFile, szWinInitFile);
    WritePrivateProfileString("Rename", szDstFile, szSrcFile, szWinInitFile);


NetServerEnum
 The description of the resume_handle parameter should read as follows:
 resume_handle
  Reserved. Set to NULL.


RegQueryMultipleValues
 The descriptions for the val_list, num_vals, lpValueBuf, and ldwTotsize
 parameters should read as follows:
 val_list
  Address of an array of VALENT structures that describe one or more value
  entries. On input, the ve_valuename member of each structure must contain
  a pointer to the name of a value to retrieve. The function fails if any of
  the specified values do not exist in the specified key.
  If the function succeeds, each element of the array contains the information
  for the specified value.

 num_vals
  Specifies the number of elements in the val_list array.
 lpValueBuf
  Pointer to a buffer. If the function succeeds, the buffer receives the data
  for each value.
  If lpValueBuf is NULL, the function returns success, and ldwTotsize returns
  the required size, in bytes, of the buffer.
 ldwTotsize
  Pointer to a value that specifies the size, in bytes, of the buffer pointed
  to by the lpValueBuf parameter. If the function succeeds, ldwTotsize returns
  the number of bytes copied to the buffer. If the function fails because the
  buffer is too small, ldwTotsize receives the required size, in bytes.

 The Return Value section should read as follows:
 Return Value
  If the function succeeds, the return value is ERROR_SUCCESS.
  If the function fails, the return value is an error value that can be one of
  the following:

 ERROR_CANTREAD
  RegQueryMultipleValues cannot instantiate or access the provider of the
  dynamic key.

 ERROR_MORE_DATA
  The buffer pointed to by lpValueBuf was too small. In this case, ldwTotsize
  returns the required buffer size.

 ERROR_TRANSFER_TOO_LONG
  The total length of the requested data (size of the val_list array +
  ldwTotSize) is more than the system limit of one megabyte.


RegSetValue
 The description of the chData parameter should read as follows:
 cbData
  Specifies the length, in bytes, of the string pointed to by the lpData
  parameter, not including the terminating null character.


SystemParametersInfo
 The Meaning column describing the uiAction parameter should include a second
 paragraph, as follows:
 SPI_SETDRAGWIDTH
  Windows 95 only: Sets the width, in pixels, of the rectangle used to detect
  the start of a drag operation.
  See SM_CXDRAG and SM_CYDRAG in the table under the nIndex parameter of
  GetSystemMetrics.


TranslateAccelerator
 The first paragraph in the Remarks section of this reference page should
 read as follows:
  To differentiate the message that this function sends from messages sent
  by menus or controls, the high-order word of the wParam parameter of the
  WM_COMMAND_win32_WM_COMMAND or WM_SYSCOMMAND_win32_WM_SYSCOMMAND message
  contains the value 1.


5.2 Messages
------------

BN_CLICKED
 The first sentence of the reference page for BN_CLICKED should read as
 follows:
  The BN_CLICKED notification message is sent when the user clicks a button.


WM_PAINT
 The syntax for WM_PAINT should read as follows:
 WM_PAINT
  hdc = (HDC) wParam; // the device context to draw in

 The following hdc parameter description should be added:
 hdc
  Identifies the device context to draw in. If this parameter is NULL, use
  the default DC. This parameter is used by common controls to enable drawing
  in a DC other than the default DC. Other windows can safely ignore this
  parameter.

 The following paragraph should be added to the end of the Remarks section of
 the WM_PAINT reference page:
  For common controls, the default WM_PAINT message processing checks the
  wParam parameter. If wParam is non-NULL, the control assumes that the value
  is an HDC and paints using that device context.


 The following sentence should be added at the end of each WM_PAINT entry in
 the Default Message Processing sections of many of the common controls
 overviews.
  If the wParam parameter is non-NULL, the control assumes that the value is
  an HDC and paints using that device context.

 The overviews affected are:
  Header Controls
  List View Controls
  Progress Bars
  Status Windows
  Tab Controls
  Toolbars
  Trackbars
  Tree-View Controls
  Up-Down Controls


5.3 Structures
--------------

HD_ITEM
 The description of the fmt member should read as follows:
 fmt
  A set of bit flags that specify the itemÆs format.
  This member can include one of the following text justification or
  right-to-left reading order bit flags:

 HDF_CENTER
  Centers the contents of the item.

 HDF_LEFT
  Left aligns the contents of the item.

 HDF_RIGHT
  Right aligns the contents of the item.

 HDF_RTLREADING
  Windows 95 only: Displays text using right-to-left reading order on
  Hebrew or Arabic systems.

 The preceding value is combined with one of the following values:

 HDF_BITMAP
  The item displays a bitmap.

 HDF_OWNERDRAW
  The owner window of the header control draws the item.

 HDF_STRING
  The item displays a string.

 You can use the HDF_JUSTIFYMASK mask to isolate the text justification
 portion of the fmt member.


PRINTER_INFO_2
 The descriptions for the StartTime and UntilTime members should read as
 follows:
 StartTime
  Specifies the earliest time at which the printer will print a job.
  This value is expressed as minutes elapsed since 12:00 A.M. GMT
  (Greenwich Mean Time).
 UntilTime
  Specifies the latest time at which the printer will print a job.
  This value is expressed as minutes elapsed since 12:00 A.M. GMT
  (Greenwich Mean Time).


RASPPPNBF
 The following paragraph should be appended to the description of the
 dwNetBiosError member.
 Windows 95: This member is undefined.


SYSTEM_INFO
 The description of the wProcessorArchitecture should include the following
 additional flag:
 PROCESSOR_ARCHITECTURE_UNKNOWN


5.4 Tools
---------

Windbg
 It is not possible to use the windbg kernel debugger extensions (i.e.
 windbg -KD) under Windows 95.

 It is not possible to attach to a running process with windbg under
 Windows 95.


LOGGER32
 The LOGGER32 system relies on Z*.DLLs provided in \MSTOOLS\BIN\LOGGER32.
 Not all of the new Windows NT 3.51 entry points have been added to these
 libraries.  Therefore some applications which call the new entry points will
 not work with the LOGGER32 system.  For example, after using apfcvt on
 \MSTOOLS\SAMPLES\FRMWORK\GDIDIB, executing the program will popup an error
 which explains that RegisterClassExA could not be located in zser32.dll.