INFO: README for Win32 Software Development Kit, Part 2 of 2

• Microsoft Visual C++, 32-bit Editions, version 5.0

SUMMARY

This is part 2 of 2, of the Win32 Software Development Kit (SDK) readme that is compatible with the SDK that was included with Visual C++ 5.0. This article includes the original text of the readme. This document contains references to directories that are on the CD the SDK originally shipped on, not the Visual C++ CD.

                 Microsoft Win32 SDK for Microsoft Windows
                              August, 1996

Contents:

     Sections 1 through 6 can be found in the article titled,

        "README for the Win32 Software Development Kit, Part 1 of 2"

     7. RPC and MIDL
     8. OLE
     9. Known Issues

MORE INFORMATION

7. RPC and MIDL

7.1 RPC Run Time

Support for Banyan Vines SPP transport: The RPC run time includes support for the Banyan Vines SPP transport protocol on Windows NT 4.0 clients and servers, and on MS-DOS and Windows 3.x clients. Support on Windows NT requires the Windows NT edition of Banyan Enterprise Client version 5.56 [30] or newer. Please contact Banyan Systems, Inc., for questions relating to the Banyan software. For more information on using the transport protocol, see the online SDK topics "ncacn_vns_spp" in the MIDL Language Reference, and "String Bindings" in the RPC Reference.

New run time support for port restrictions and selective binding to NICs: A new RPC data type and a set of Extended RpcServerUseProtseq functions let you restrict port allocation for dynamic ports and allow multihomed computers to selectively bind to Network Interface Cards. For more information, see the online SDK topic "RPC_POLICY" in the RPC Reference.

DCE pipes are supported on all transport protocols on 32-bit Windows platforms. For more information, see the "Pipes" overview in the RPC Reference.

7.2. MIDL Compiler

New default mode for MIDL compiler: The /ms_ext and /c_ext modes for the MIDL compiler are now the default mode. It is not necessary to specify these two switches when you compile an IDL script that includes Microsoft extensions to the OSF-DCE IDL. A new compiler option, /osf, is available to force strict compatibility with OSF-DCE. For more information, see the online SDK topic "/osf" in the MIDL Command-Line Reference.

Compiler options /Oic and /Oif offer interpreted methods for marshaling stub code between client and server. For more information, see the online SDK topic "/Oi" in the MIDL Command-line Reference.

Pipe support: The new MIDL compiler and the RPC run time support DCE pipes to pass large or incrementally produced quantities of data in remote procedure calls. This release has some restrictions related to pipe types and non-pipe arguments in pipe calls. For more information see the online SDK topic "pipe" in the MIDL Language Reference and the "Pipes" overview in the Overviews node of the RPC documentation.

Performance attributes for data marshaling: Two new attributes, [wire_marshal] and [user_marshal], permit faster, more efficient marshaling of datatypes that are difficult to remote. For more information see the online SDK topics "The wire_marshal Attribute" and "The user_marshal Attribute" in the RPC documentation, and the topics "wire_marshal" and "user_marshal" in the MIDL Language Reference.

Array attributes accept multiple parameters: You can use this feature to specify a sized array of pointers or a multidimensional section of a multidimensional array. For more information on this, and on how to use [out, size_is] to allow the server to return a dynamically sized array, see the online SDK topics "size_is" in the MIDL Language Reference, "Multiple Levels of Pointers" in the RPC documentation, and the sample programs "dynout" and "strout" in the \mstools\samples\rpc directory of the Win32 SDK CD.

Support for international characters: Where appropriate, the MIDL compiler now accepts the entire ANSI character set in the input file.

Floating-point constants: The MIDL 3.0 compiler supports floating-point constants in IDL and ACF files.

32-bit int: The MIDL compiler recognizes the int data type as a 32-bit remoteable element on 32-bit platforms.

Object interface methods return type: Nonlocal object interface member functions must have a return type of HRESULT or SCODE. Earlier versions of MIDL allowed member functions to have a return type of void. For more information, see the online SDK topic "object" in the MIDL Language Reference.

Version control: To guard against using MIDL features that are not supported on older platforms, the MIDL compiler generates target macros that facilitate compatibility checking during C compilation. For more information, see "Targetting Stubs for Specific 32-Bit Platforms" in the MIDL Programmer's Reference.

7.3. Known Problems

The problem is this: When an RPC application links to the static versions of the C run time libraries, and it uses the RpcSm package, it will have a heap that is separate from the one used by RPC run time and stubs. When this happens, the RPC application cannot free memory blocks that were allocated by the stubs, and the stubs cannot free blocks that were allocated by the RPC application. Because the stubs and the application operate on different heaps, these cross references cause an access violation in the memory package that is executing the free operation on a pointer. Note that this is a problem only if your application causes cross- referenced free operations as described earlier.

There are two ways to handle this problem:

1. If you must link to the static versions of the C run time libraries, use

The compiler doesn't generate correct mixed-mode (/Os) stubs for some cases with multidimensional array attributes. If this happens, use one of the interpreted modes (compiler option /Oi) instead.

When you define a coclass and a library in an IDL file, but you do not define an interface, MIDL fails to generate the .H and _I.C files. You need to use the /h compiler switch to generate these files.

8. OLE Release Notes for Windows NT 4.0

Applications that use OLE should note the following restrictions and features available in the Windows NT 4.0 Shell Update Release.

  * Availability of DCOM (Distributed COM)
      Changes from Windows NT 4.0 Beta 2/DCOM Preview
      MIDL/RPC/OLEAUT32.DLL provide marshaling support for VARIANTs
      Receiving OR_INVALID_OXID (0x80070776)
      Extensive Delays on Initial Remote Activation
      TreatAs on Remote Server
      Applications using CLSCTX_SERVER/CLSCTX_ALL do not run on
      Windows 95 or previous versions of Windows NT if compiled with
      _WIN32_DCOM or _WIN32_WINNT>=0x0400.
  * MkParseDisplayName enables <progid>:<string> syntax
  * Overriding the binding behavior of monikers: Class Moniker,
    IClassActivator, BINDOPTS2
  * New APIs Help Avoid Race Conditions in Multithreaded COM Servers
  * New CoRegisterPSClsid API enables proxy/stub usage without
    registration
  * New OleCreateXXXEx APIs avoid multiple launch and shutdown of servers
  * Property Set Interfaces Available
  * Compound File Optimization APIs Available as Redistributable
    Component for Windows 95, Windows NT 3.51 and Windows NT 4.0
  * Asynchronous Storage interfaces and functions available
  * Component Categories Manager available as redistributable component
  * OLEPRO32.DLL Available in Windows NT 4.0
  * OLE Tutorial Code Samples in mstools\samples\ole\com
  * Marshaling code for OLE Control and ITypeLib2/ITypeInfo2-Interfaces

Availability of DCOM (Distributed COM)

Changes from Windows NT 4.0 Beta 2/DCOM Preview

  * The COSERVERINFO structure has been changed as follows:
    typedef struct _COSERVERINFO {
        DWORD           dwReserved1;
        LPWSTR          pwszName;
        COAUTHINFO *    pAuthInfo;
        DWORD           dwReserved2;
    } COSERVERINFO;
    The dwSize member has been removed and the pszName member has been
    renamed to pwszName. The additional parameters are described in
    detail in the online SDK documentation. To obtain compatibility
    with Beta 2, the additional members have to be initialized to 0 and
    NULL, respectively.

  * CoInititializeEx can now be called with different COINIT flags from
    different threads, which supports the mixing of apartment-model and
    free-threaded objects.

  * CoInitializeSecurity now takes additional arguments which merge the
    functionality of CoRegisterAuthenticationServices, which has been
    removed. A call to CoInitializeSecurity(pSD, dwAuthnLevel,
    dwImpLevel, pReserved) can be replaced with a call to
    CoInitializeSecurity(pSD, -1, NULL, NULL, dwAuthnLevel, dwImpLevel,
    NULL, 0, pReserved).

  * Additional levels of impersonation and authentication are now
    supported by DCOM. The SECURE sample application
    (\mstools\samples\ole\dcom\secure) demonstrates the use of these
    security settings.

  * The OLECNFG command-line tool that supported configuring RunAs
    applications has been replaced with a graphical tool, DCOMCNFG,
    which displays information about and configures groups of classes
    packaged together (within the same executable [EXE] or library
    [DLL]) according to their APPID (see following). Run the DCOMCNFG tool
    directly from the command line or by clicking Run on the Start menu
    and typing DCOMCNFG in the Run dialog box.

  * The LaunchPermissions, AccessPermissions, RunAs, ActivateAtStorage,
    RemoteServerName, LocalService keys/values that were stored under
    each class's CLSID key (HKEY_CLASSES_ROOT\CLSID\{...}) are now all
    named values of a new key associated with the CLSID key known as an
    APPID. Each CLSID has a reference to its APPID key as a named value
    ("AppID") whose value is the stringized GUID that is their APPID.
    The APPID keys are kept under HKEY_CLASSES_ROOT\APPID\{...}, and their
    named values are the attributes and security settings for the
    collection of classes (possibly only one) associated with the APPID.
    This assures that a process exposing multiple class factories
    obtains the same security settings regardless of which CLSID is
    initially used to launch the process initially.

  * In the beta 1 preview release of DCOM, the security information
    associated with the LaunchPermissions and AccessPermissions keys was
    managed with the registry security APIs. These configuration entries
    are now named values that contain Win32 security descriptors. See
    the Win32 documentation for more information on manipulating security
    descriptors.

MIDL/RPC/OLEAUT32.DLL Provide Marshaling Support for VARIANTs

It is important to realize that the wire representation used by proxy/stubs is part of the interface contract and cannot be changed without changing the interface identifier. Before Distributed COM, this has not been of practical concern, since updating the proxy on a machine forcibly updated the corresponding stub. Any proxy/stub that is installed on a DCOM-enabled system (Windows NT 4.0) effectively freezes the wire format for this interface. For designers of new interfaces, this leaves several options in dealing with VARIANTs:

  * Use hand-coded proxy/stubs on Windows NT 3.51 and Windows NT 4.0: this
    will preclude any future use of MIDL/RPC's VARIANT marshaling.

  * Use MIDL generated proxy/stubs on Windows NT 4.0 and hand-coded
    proxy/stubs on Windows NT 3.51: installation programs have to guarantee
    that no Windows NT 3.51 proxy is ever installed on a DCOM-enabled
    machine. When upgrading a system from Windows NT 3.51 for Windows NT
    4.0, the hand-coded proxies must fail, requiring a new installation of
    the application.
  * Use intelligent proxy/stubs that test for the presence of the new

    flexible but most complicated option.

Receiving OR_INVALID_OXID (0x80070776)

This failure can occur when a machine has been configured with TCP/IP as well as another network transport, such as IPX/SPX, or NetBeui, but the TCP/IP configuration is improperly configured. For example, it may be configured to be dynamically assigned an IP address using DHCP, yet a DHCP server may not be available, so it has no IP address. The solution is to properly configure TCP/IP networking.

Extensive Delays on Initial Remote Activation

DCOM attempts remote activation using one protocol at a time. If a protocol indicates a failure, DCOM uses the next configured protocol. If a machine is configured to use TCP/IP and IPX/SPX for DCOM, with TCP/IP being the primary transport, a faulty TCP/IP configuration (missing DHCP server, for example) will not prevent the object from being activated, but the activation will succeed only after the TCP/IP transport's time-out of approximately 30 seconds.

To solve this problem, you must either correct the configuration of the primary transport or remove the protocol by using the Network Control Panel.

TreatAs on Remote Server

Applications using CLSCTX_SERVER/CLSCTX_ALL do not run on Windows 95 or previous versions of Windows NT if compiled with _WIN32_DCOM or _WIN32_WINNT>=0x0400. The new definitions of CLSCTX_SERVER and CLSCTX_ALL include CLSCTX_REMOTE_SERVER. Applications using these flags will not run on Windows 95 or previous versions of Windows NT when compiled with the header files included in this SDK. Previous versions of COM/OLE validate the flags passed to CoCreateInstance/CoGetClassObject and fail with E_INVALIDARG when CLSCTX_REMOTE_SERVER is specified. When targeting both Windows NT 4.0 and Windows 95 or previous versions of Windows NT, you need to make sure the _WIN32_WINNT preprocessor symbol is defined to be less than 0x0400 and the _WIN32_DCOM preprocessor symbol is not defined.

MkParseDisplayName enables <progid>:<string> syntax

Class Moniker, IClassActivator, BINDOPTS2

The File Moniker does this by calling IMoniker::BindtoObject on the moniker to its left. If this object exposes IClassActivator, the file moniker calls IClassActivator::GetClassObject to obtain the uninitialized instance. Otherwise, if the object exposes IClassFactory, the file moniker calls IClassFactory::CreateInstance. If the object exposes neither, the bind operation fails.

Custom monikers should be changed to enable this kind of extensibility, where applicable. Typically, this mechanism does not apply for monikers that already require or support a moniker to their left, like Item Monikers.

The new Class Moniker for Windows NT 4.0 uses this extensibility mechanism. It can be composed with a file moniker to override the CLSID. The Class Moniker can be created using the new CreateClassMonikerAPI, using CoCreateInstance (..., CLSID_ClassMoniker, ..., IID_IParseDisplayName) or through MkParseDisplayName with a display name of the form "clsid:xxxxxxxx- xxxx-xxxx-xxxx-xxxxxxxx".

The file moniker also accepts a new BINDOPTS2 structure, an extension of the current BINDOPT structure. Clients can use this new structure to IBindCtx::SetBindOptions to request additional behavior for a bind operation.

Note: Currently, only File Moniker uses the new bind options. COM's new Class Moniker does not currently support the pServerInfo flag. pServerInfo and the pointers included in pServerInfo are not copied when IBindCtx::SetBindOptions is invoked. Thus, these pointers need to be kept valid until the last release to the bind context.

See the online SDK documentation for more details on any of these new mechanisms.

New APIs Help Avoid Race Conditions in Multithreaded COM Servers

To facilitate this, applications can use the new COM APIs CoAddRefServerProcess, CoReleaseServerProcess, CoSuspendClassObjects and CoResumeClassObjects. See the online SDK documentation for details.

New CoRegisterPSClsid API Enables Proxy/Stub Usage Without Registration

New OleCreateXXXEx APIs Avoid Multiple Launch/Shutdown of Servers

Extended versions of these creation functions solve this problem. See the online SDK documentation for details on OleCreateEx, OleCreateFromFileEx, OleCreateFromDataEx, OleCreateLinkEx, OleCreateLinkToFileEx, and OleCreateLinkFromDataEx.

Property Set Interfaces Available

Compound File Optimization APIs Available as Redistributable Component

The tool's primary use is in conjunction with asynchronous storage (see following), where it allows applications to do optimal progressive rendering while a file is being downloaded asynchronously. An optimized file also provides performance advantages in standard network access and even local access scenarios as it minimizes seek operations and takes advantage of read-ahead caching. Access on compact discs or other storage media with high seek latency also benefit greatly from an optimized file layout.

The tool provides a simple, dialog-based UI that allows the user to select multiple Compound Files that are to be optimized. When the user clicks the Optimize button, the tool will obtain the CLSID from each Compound File, launch the associated application (using CoCreateInstance) and initialize it using IPersistStorage. The tool monitors the activity of the application and writes an optimized Compound File based on this activity.

The tool uses the following Layout Optimization interfaces and APIs that are implemented in DFLAYOUT.DLL.

  * StgOpenLayoutDocfile

  * ILayoutStorage

Please refer to the online SDK documentation for more information on the layout optimization interfaces and APIs. The DFLAYOUT.DLL is NOT part of Windows NT 4.0. Instead it is provided in the Win32 SDK as redistributable code in the form of a self-extracting executable DFLAYDLL.EXE. It is ONLY redistributable through the use of this executable (MSTOOLS\BIN\<platform>\DFLAYDLL.EXE for Windows 95, Windows NT 4.0, and Windows NT 3.51). See details on redistribution rights in REDIST.TXT in the \License directory.

Asynchronous Storage Interfaces/APIs Available

  * StgOpenAsyncDocfileOnIFillLockBytes

  * StgGetIFillLockBytesOnILockBytes

  * StgGetIFillLockBytesOnFile

  * IFillLockBytes

  * IProgressNotify

Component Categories Manager Available as Redistributable Component

The Component Categories Manager is an in-process COM-object (COMCAT.DLL) that exposes the ICatInformation and ICatRegister interfaces. See the ActiveX SDK for a description of these interfaces and for header files (COMCAT.IDL/H).

The Component Categories Manager is provided as a self-extracting, self- registering executable. It is ONLY redistributable through the use of this executable (MSTOOLS\BIN\<platform>\CCDIST.EXE for Windows 95 and Windows NT 4.0, MSTOOLS\BIN\<platform>\CCDIST35.EXE for Windows NT 3.51). For details on redistribution rights see the REDIST.TXT file in \License.

OLEPRO32.DLL Available in Windows NT 4.0

OLE Tutorial Code Samples in mstools\samples\ole\com

Marshaling Code for OLE Control and ITypeLib2/ITypeInfo2 Interfaces

1. regsvr32 oleaut32.dll (regsvr32 is provided in the Win32 SDK).

2. Call the DllRegisterServer() entrypoint in oleaut32.dll directly (this

   HMODULE hmodule;   FARPROC pfn;   hmodule =
LoadLibraryA("oleaut32.dll");   pfn = GetProcAddress(hmodule,
"DllRegisterServer");   pfn();      // call the DllRegisterServer routine

   FreeLibrary(hmodule);

   and to their remoting code.

OLE Automation for Windows NT 3.51

9. Known Issues

In order to put the Win32 SDK headers, libraries, and tools first on the search path, the INCLUDE, LIB, and PATH environment variables are modified. Doing this on Windows 95 may overflow the environment space of COMMAND.COM. To work around this, either add the following line to CONFIG.SYS:

    SHELL=c:\command.com c:\ /e:2048 /p

APIMON is a new tool in the Win32 SDK that will run only on Windows NT 4.0. It is provided as a replacement for the old WAP and LOGGER32 tools. APIMON provides an easy to use, graphical interface for gathering information on API calls and page faults. It is documented in apimon.hlp.

On the MIPS processor, the values listed in the time column of the API Counters window are invalid. Selecting the graph button when a graph is already displayed causes APIMON to fail.

The Z*.DLL files (e.g. zernel32, zser32, zdi32, ...) that were provided on previous releases of the SDK were to support the WAP and LOGGER32 tools. These DLL files are no longer present since the WAP and LOGGER32 tools have been replaced by APIMON. The apfcvt and apf32cvt tools are still provided for use with FERNEL32.DLL and the FIOSAP tool (see the online SDK documentation for more information). The apf32cvt tool will not work correctly on Windows 95.

The MIB compiler (MIBCC.EXE) requires MGMTAPI.DLL in order to run. This DLL is distributed with the operating system, and will be installed when you install the SNMP service on your machine. See the "Network" item in the Control Panel for more information.

The message compiler (mc.exe) does not compile Japanese-language strings correctly when run on the Japanese version of Windows 95. The recommended work-around is to use the Japanese version of Windows NT.

The \MSTOOLS\SAMPLES\MAPI\DOCFILE.MS sample does not compile correctly with Microsoft Visual C++ version 4.1 or version 4.0a for RISC. This is a recognized limitation in that version of the VC++ compiler, and it is fixed in version 4.2 and later.

Win32s has been removed from the Win32 SDK. It is available on another Microsoft Developer Network compact disc.

The WINDBG debugger no longer supports Win32s.

The mssetup environment variables are no longer registered by default. To build the mssetup sample and other code that uses the mssetup toolkit, run \mstools\mssetup\setenv.bat first. Notice that there is now a \mstools\include\setupapi.h header file that is different than the older \mstools\mssetup\include\setupapi.h header with the same name. If you are building code that uses mssetup, be sure that you use the older file. Some of the sample code in the Win32 SDK requires LIBCMT.LIB in order to build. This library is distributed with Microsoft Visual C++, but it is not installed by the minimum installation. If your code will not build because the linker is not able to locate this library, either grab it from the VC++ distribution media or reinstall VC++ making sure that this library is included.

The documentation indicates that the szKey member of the String and StringTable structures located in version resources can use the decimal value 1200 to indicate the Unicode character set. This is not correct. You should use the hexadecimal value 04b0 to indicate the Unicode character set. See the BLOCK string in the version resources of \mstools\samples\win32\deb\deb.rc for one example.

There, online documentation includes references to "ActiveX." This should not be confused with the ActiveX SDK that is available on the internet and that will be provided to MSDN customers later this year.

As in previous releases of the Win32 SDK, the DBG symbols for some of the Windows NT system components are provided on the SDK compact disc, in \SUPPORT\DEBUG\*. The Win32 SDK setup logic has been changed slightly so that if you run setup on a machine with a build number that matches the build of the DBG symbols, you will not be prompted for the location of the symbols. If you set up the SDK on a machine with a build number that does not match, you will be prompted, as has been the case in the past, for the location of the correct DBG symbols.

To fit all of the new material on a single compact disc, the debug symbols and the libraries have been compressed on the compact disc. The regular SDK setup will expand these files automatically as part of setup. If you copy the debug symbols or the libraries without using SDK setup, you will need to run EXPAND.EXE to decompress the files. The EXPAND utility is built into Windows NT, and is provided in the SDK for Windows 95.

The install batch file for the Software Compatibility Test (SCT) has been significantly changed to make it easier to debug 16-bit applications on Windows NT. See \SCT\SCT.HLP for additional information on using install, setdebug, and nondebug utilities. Note that SCT installation now requires you to reboot at the end of the process.

The client dynamic-link libraries for the licensing API (LSAPI32.DLL and MSLSP32.DLL) are still beta code. They are provided here for development purposes only. They are not redistributable. The interfaces may change in the future, requiring applications to be recompiled.