WMI SDK README

This document provides the following information for the version 1.5 release of the Windowsâ Management Instrumentation (WMI) Software Development Kit (SDK):

· System requirements

· Installation instructions

· A description of known issues with the release

1.1 WMI and WBEM

The user may notice that the terms WMI (Windowsâ Management Instrumentation) and WBEM (Web-Based Enterprise Management) are used in a mixed fashion throughout the SDK documentation, samples and applications. WMI is based on the concepts and technology of the WBEM industry initiative and is the Windowsâ-based system implementation of WBEM. For the purpose of using this SDK, the user should treat these terms as more or less interchangeable (e.g., WMI CIM Studio and WBEM CIM Studio are one and the same application). Moving forward, all components associated with WMI on Windowsâ platforms will be renamed and referred to with the specific term “WMI” rather than the more generic “WBEM”.

2. SYSTEM REQUIREMENTS

The WMI SDK 1.5 release requires the following minimum configurations.

2.1 Operating System Requirements

The following operating systems are supported in this release of the WMI SDK.

Operating system Required

Microsoft Windowsâ NT version 4.0 Service Pack 5 or higher

Microsoft Windowsâ 2000

2.2 Hardware Requirements

Minimum computer configurations exist and are based on the Microsoft operating system used. For WMI SDK development purposes, it is recommended that a Win32 developer have a computer that consists of at least:

· Pentiumâ-class or Alpha (NT version 4.0 only) processor

· 32 MB RAM

· 40 MB of available hard disk space

· Video graphics card support for 256 colors at an 800 X 600 resolution

· Network card

3. UPGRADE INFORMATION

If you have previously installed a version of the WMI SDK, it is recommended you remove it before installing this release.

To remove a previous WMI SDK:

1. Remove the previous version using the Add/Remove Programs option from Control Panel or through the uninstall option found under the Start->WMI SDK menu.

2. After uninstalling any previous WMI SDK, the Microsoft Internet Explorer cache must be flushed. This can be done on Internet Explorer by deleting all files in “%SYSTEMROOT%\Downloaded Program Files” directory.

After removing the previous version of the WMI SDK, install the new release using the instructions in section 4, Installation.

4. INSTALLATION

To install the WMI SDK, run the Wmisdk.exe file and follow the prompts. Membership in the Administrators group is required to install the WMI SDK.

If you need to reinstall the SDK, it is recommended you first remove the current SDK installation. See the instructions in section 3, Upgrade Information. Then, run the Wmisdk.exe application.

To use the ActiveX components included in the WMI SDK, Microsoft Internet Explorer version 5.0 or higher must be installed. This product can be downloaded at no cost from the Microsoft Web site at http://www.microsoft.com/ie.

It should be noted that in previous releases of the WMI SDK, on systems where Internet Information Server (IIS) is installed, the SDK installer would put the WMI tools in the “InetPub\wwwroot\WMI” folder. The installer now places these files in the “Program Files\WMI\Applications” folder whether or not IIS is installed. No files will be placed in the “InetPub\wwwroot\WMI” folder. Previous installations where files were placed in this folder will be upgraded such that previous versions of these files are removed from “InetPub\wwwroot\WMI” and the new versions placed in “Program Files\WMI\Applications”.

5. SCHEMA.TXT FILE

The SCHEMA.TXT file contains information regarding the proper use and subclassing of the CIM and Win32 classes supported by the WMI SDK as proscribed by Microsoft and the DMTF. Please review this information carefully and be sure you understand the limitations it describes before designing your own classes. This file is installed in the License folder under the WMI SDK installation directory (typically, “%SYSTEMROOT%\system32\wbem”).

6. WEB BROWSER SUPPORT

The following Web browsers are supported by this version of the WMI SDK:

Operating system Browsers

Microsoft Windowsâ NT version 4.0 Internet Explorer 5.0

Microsoft Windowsâ 2000 Internet Explorer 5.0

Other combinations of operating systems and browsers not specified in the preceding table may also work, but are not formally supported by this version of the WMI SDK.

7. NETWORK CARD REQUIRED

WMI 1.5 requires a network card to start CIMOM as an NT service. If a network card is not present, CIMOM cannot be started as an NT service and applications will be unable to retrieve WMI information. In cases where a network card is not available, the CIMOM can be started as a standard executable manually by running WINMGMT.EXE in the WMI home directory.

8. REMOTE ACCESS WITH WINDOWSâ 95/98

If Windowsâ 95 or Windowsâ 98 users have problems with remote access over DCOM, make sure to set the registry value in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\OLE\EnableRemoteConnect to "Y". You must restart the system for the change to take effect.

9. SECURITY

This release has not had all possible security issues tested. Do not rely on it for system security.

10. WMI CLIENTS LIMITATIONS USING AUTHENTICATION AND ENCRYPTION

WMI clients can specify that they require operations to be authenticated or encrypted when calling into WMI by using standard DCOM procedures (IClientSecurity). WMI Scripting clients can achieve the same effect by setting the SWbemSecurity properties on an object, or specifying the relevant security attributes in a moniker string.

In both cases, clients should be aware that when the requested operation is to be performed asynchronously, only the request is subject to the specified security settings. The asynchronous responses to the request will not be affected by the requested settings.

For example one can specify that IWbemServices.GetObject("MyBankBalance") and its response uses encryption over the wire, but one cannot specify that the responses to IWbemServices.GetObjectAsync("MyBankBalance") use encryption; only the request is guaranteed to do this.

11. DEBUG VERSION OF PROVIDER FRAMEWORK (FRAMEDYD)

The WMI SDK includes the debug version of the provider framework library (FRAMEDYD.LIB) and DLL (FRAMEDYD.DLL) to aid in debugging providers built upon the framework. Among other checks, the framework verifies that the variable types being passed to framework functions are valid for that particular function. In the release version of the framework library, as documented, if an invalid type is passed to one of the CInstance Get or Set functions, the function will return a FALSE, indicating the operation was not performed. In the debug version, the behavior is exactly the same except that an ASSERT will also be raised to notify the developer that an incorrect data type has been used before the function returns FALSE. This has been included to help developers identify subtle type bugs that may inadvertently get introduced into provider code during the development process. Note that these ASSERT’s will only be raised in the debug version of the framework code, not in the release version (FRAMEDYN.LIB) as they intended as an aid to developers only.

Below is a table of the acceptable CIM types that can be passed to the various CInstance Get and Set functions; passing types other than those specified to a function will result in the call failing to perform the requested action and, in the case of the debug framework library, and an ASSERT being raised.

CIM Data Type	CInstance
CIM Data Type	Get Functions	Set Functions
string	GetCHString GetVariant GetWCHAR GetCharSplat	SetCHString SetVariant SetWCHAR SetCharSplat
sint8	GetVariant	SetVariant
uint8	GetByte GetVariant	SetByte SetVariant
sint16	GetWBEMINT16 GetVariant	SetWBEMINT16 SetVariant
uint16	GetWORD GetDWORD GetVariant	SetWORD SetDWORD SetVariant
sint32	GetWORD GetDWORD GetVariant	SetWORD SetDWORD SetVariant
uint32	GetWORD GetDWORD GetVariant	SetWORD SetDWORD SetVariant
sint64	GetCHString GetWCHAR GetWBEMINT64 GetVariant	SetCHString SetWCHAR SetWBEMINT64 SetVariant
uint64	GetCHString GetWCHAR GetWBEMINT64 GetVariant	SetCHString SetWCHAR SetWBEMINT64 SetVariant
real32	GetVariant	SetVariant
real64	GetCHString GetDOUBLE GetVariant	SetCHString SetDOUBLE SetVariant
char16	GetVariant	SetVariant
datetime	GetCHString GetDateTime GetWCHAR GetVariant	SetCHString SetDateTime SetWCHAR SetVariant

12. USING THE NEW UNICODE PROVIDER FRAMEWORK

The previous WMI SDK provider framework was designed to support building providers that use and contain ANSI strings. Wide character strings could be passed to the previous framework without problems, but internally they would still be represented as ANSI strings and in general Unicode was not supported. Providers built with versions of the SDK before version 1.5 will not be compatible with the FRAMEDYN.DLL shipped with the version 1.5 WMI core components. Older providers will have to be modified using the information below and rebuilt in order to work with the version 1.5 FRAMEDYN.DLL code. Similarly, providers built with version 1.5 of the framework will not work correctly on previous versions of the core components.

With this release of the WMI core components and SDK, however, the framework has moved to a Unicode-only model on all platforms. We have compiled a list of suggested practices to follow that will aid in migrating your previous code to the new Unicode framework model.

In order to simplify the Unicode transition, the following "best practices" are suggested:

· Wherever CHString's were used before, supply a wide-character version instead. Where strings are directly specified (e.g., "Hello"), precede them with an "L" to define them as wide-character strings (e.g., L"Hello" ). When defining variables, use wide-character versions such as WCHAR, LPWSTR, LPCWSTR, etc. Wide-character strings are required for all CHStrings.

· Do not use the TSTR string definitions (_T, LPTSTR, etc.) as these are intended for use when supporting the same source code in both an ANSI and a Unicode environment. In the new framework, all framework providers are required to use Unicode when dealing with the framework functions so this mixed model does not really apply.

· If you need to provide an ANSI only function with an ANSI string, you should first convert the CHString to ANSI using a function like bstr_t().

13. REDISTRIBUTION CHANGES

In order to ensure that when the WMI SDK ActiveX controls are redistributed they are correctly and consistently installed on systems, the REDIST.TXT file has been updated. Redistribution is now only allowed for the WBEMTOOL.CAB file which contains all the SDK ActiveX controls and their associated DLL’s. In addition, standard procedures for the controls and DLL’s are defined to make sure they are safely added or upgraded in environments where multiple products may be using them. A new redistributable utility, CabExtract.exe, has been added to the SDK to simplify extracting the controls properly from the CAB file.

In addition, the MIB and MOF files that support the WMI SNMP provider have been added to the list of items that can be redistributed.

14. KNOWN ISSUES

These are items known to be issues in the WMI SDK and suggested workarounds:

· On Windows 2000 systems, when building binary MOF files for use with WMI for WDM device drivers, the syntax check feature for these files in MOFCOMP.EXE and in the WMI SDK MOF Compiler Wizard will not work because the file WMIMOFCK.EXE is not installed on the system. This file is available in the Windows 2000 DDK distribution. Once the Windows 2000 DDK is installed, this file can be copied from the \NTDDK\BIN directory to the %SYSTEMROOT%\SYSTEM32\WBEM directory. Once this is complete, both MOFCOMP.EXE and the WMI SDK MOF Compiler Wizard should work as expected with regard to WMI for WDM binary MOF files.

· Because they are hosted in Internet Explorer, most of the WMI SDK tools will automatically detect if an ActiveX control has been deleted and automatically extract the control from the WBEMTOOL.CAB file. The WMI Event Viewer tool is a standalone application, however, and does not support this functionality. If, for example, the Namespace Picker control (wbemnspicker.ocx) is deleted from the system, WMI Event Viewer will not extract this file from the CAB and will therefore fail to work properly. To fix this sort of problem, simply run one of the Internet Explorer-based tools (e.g., WMI CIM Studio) once the missing files will be restored automatically. In general, however, this problem should rarely occur and only when a control is inadvertently deleted manually or by a poorly written application.

· Instrumentation issues – In some cases, particular WMI properties and methods return correct results but the behavior may not be what the user expects. The following list is the set of properties and methods that are known to exhibit such behavior:

1. Win32_NetworkLoginProfile.BadPasswordCount – Depending upon the network configuration, this property can return a count that is twice the number of login attempts that have failed. This can occur in situations where both Kerberos and NTLM authentication are enabled. If the login fails to be authenticated by Kerberos, the system will try NTLM authentication next. For each of these failures, the count of bad login attempts will be incremented even though to the user it appears they only attempted to log in once. The Win32_NetworkLoginProfile.BadPasswordCount property is only reporting what the underlying API indicates is the correct value of failed login attempts.

2. CIM_DataFile – On some laptops, if the floppy drive is removed after the system has been booted and already used the floppy, enumerating the CIM_DataFile class may cause error messages to be displayed by the operating system asking the user to check the floppy drive and ensure it is ready. This is caused by the laptop hardware not indicating to the operating system that the floppy drive has been removed, which is normally expected. This has been known to occur on Toshiba Tecra 8000 laptop systems.