439 lines
14 KiB
Plaintext
439 lines
14 KiB
Plaintext
|
|
=======================================================================
|
|
Custom View OCX's for WMI Applications
|
|
=======================================================================
|
|
|
|
|
|
This file contains a description of the custom view OCXs for WMI and the
|
|
corresponding automation interface. Custom views provide non-generic
|
|
views of objects contained in the WMI database. The WMI CIM Studio,
|
|
Object Browser, and other programs may use these custom views to display application
|
|
specific views of WMI objects. For example, a custom view of a disk drive
|
|
might show the amount of free space in a bar chart, and so on.
|
|
|
|
Any number of views can be defined for each class stored in the
|
|
WMI database. To add a custom view to the WMI database, it is necessary
|
|
to create a new instance of the "ClassView" class. Below is an example
|
|
of a mof file that can be compiled to define a custom view for the
|
|
Win32LogicalDisk class. In this MOF file, the "id" property takes the form
|
|
of "ClassName.ViewName", so that custom views can be uniquely identified and
|
|
easily recognized.
|
|
|
|
The WMI CIM Studio and Object Browser applications determine what custom views are
|
|
available for a given class by querying for all instances of "ClassView" such
|
|
that the "ClassName" property is equal to the current class being displayed.
|
|
|
|
|
|
#pragma namespace("\\\\.\\root\\cimv2")
|
|
|
|
|
|
class ClassView
|
|
{
|
|
[key] string id;
|
|
string title;
|
|
string ClassName;
|
|
string classid;
|
|
string codebase;
|
|
string version;
|
|
};
|
|
|
|
|
|
instance of ClassView
|
|
{
|
|
id = "Win32_LogicalDisk.View1";
|
|
title = "Custom View of Win32_LogicalDisk";
|
|
ClassName = "Win32_LogicalDisk";
|
|
classid = "{D5FF1886-0191-11D2-853D-00C04FD7BB08}";
|
|
codebase = "";
|
|
version = "1.0";
|
|
};
|
|
|
|
|
|
To see a sample custom view in the WMI CIM Studio follow these steps:
|
|
|
|
1. Build the sample found in the WMI SDK directory under samples\vc\customviews
|
|
|
|
2. Use regsvr32 to register the resulting Win32LogicalDisk.ocx as shown below:
|
|
|
|
regsvr32 Win32LogicalDisk.ocx
|
|
|
|
3. Start the WMI CIM Studio application
|
|
|
|
4. Use the MOF Compiler Wizard in WMI CIM Studio to compile the "CustomView.mof"
|
|
MOF file that is included with the sample
|
|
|
|
5. In WMI CIM Studio, select the Win32_LogicalDisk class in the class tree.
|
|
|
|
6. In the Object Viewer (right pane), click the "Instances" button to display all
|
|
instances of "Win32_LogicalDisk" on your local machine
|
|
|
|
7. Double-click one of the instances to go to the single object view for
|
|
that instance. At this point, the custom view available for instances of this
|
|
class is recognized and the "Views" menu-option under the "Views" button
|
|
becomes enabled.
|
|
|
|
8. Click the "Views" button and select "Views..." in the menu.
|
|
A dialog is displayed with a list of the available views for this object.
|
|
One of them is the "Custom View of Win32_LogicalDisk" which is implemented by
|
|
our sample ocx. Selecting this option and clicking "OK" displays the custom view
|
|
showing (in this example) the total vs free disk space on the current disk object.
|
|
|
|
|
|
----------------
|
|
TROUBLESHOOTING:
|
|
----------------
|
|
|
|
If you do not see the custom view title listed among the views or if the
|
|
"Views..." menu option is not enabled under the "Views" button in the Object Viewer,
|
|
please check the following :
|
|
|
|
1. Check to make sure that you have an instance (not the class) of
|
|
"Win32_LogicalDisk" selected in the WMI CIM Studio Object Viewer.
|
|
|
|
2. Verify that you registered the "Win32LogicalDisk.ocx" custom view control.
|
|
|
|
3. Verify that you compiled the "CustomView.mof" file.
|
|
|
|
|
|
|
|
Win32LogicalDisk.ocx is a minimal implementation of a custom view. It displays the
|
|
object path passed to it from the container along with the size/free-space bar chart.
|
|
The control uses the object path to get the WMI object and extract the required
|
|
property values for building the bar chart. Real-world custom views would probably
|
|
use the WMI interface to get similar and more in-depth information for display.
|
|
|
|
Custom views need not be limited to information contained in the selected class.
|
|
For example, a class view for a disk drive may provide information about how the
|
|
space is being consumed, etc. The custom view control can use the full power of WMI
|
|
including associations, queries and events, for a more sophisticated and object-specific
|
|
display.
|
|
|
|
|
|
|
|
=======================================================================
|
|
Automation interface for the WMI custom object view OCXs
|
|
(Note : this information is also available in the .odl file that is
|
|
included with this sample)
|
|
=======================================================================
|
|
|
|
//****************************************************************
|
|
// DEFINITIONS
|
|
//****************************************************************
|
|
Context Handles:
|
|
Containers that use WMI custom views typically will want to
|
|
take a snapshot of the state of the custom view so that it is
|
|
possible to go back to that state at a later time. The container
|
|
is only aware of context handles that the custom view returns to
|
|
the container. The container only sees context handles as long
|
|
integers, thus custom views are free to define their own implementation
|
|
of context saving.
|
|
|
|
|
|
//****************************************************************
|
|
// Automation Properties
|
|
//****************************************************************
|
|
LPCTSTR NameSpace
|
|
|
|
|
|
//****************************************************************
|
|
// Automation Methods.
|
|
//****************************************************************
|
|
long QueryNeedsSave();
|
|
long AddContextRef(long lCtxtHandle);
|
|
long GetContext(long FAR* plCtxthandle);
|
|
long GetEditMode();
|
|
void ExternInstanceCreated(BSTR szObjectPath);
|
|
void ExternInstanceDeleted(BSTR szObjectPath);
|
|
long RefreshView();
|
|
long ReleaseContext(long lCtxtHandle);
|
|
long RestoreContext(long lCtxtHandle);
|
|
long SaveData();
|
|
void SetEditMode(long bCanEdit);
|
|
long SelectObjectByPath(BSTR szObjectPath);
|
|
|
|
|
|
|
|
//*****************************************************************
|
|
// Events that custom views can fire.
|
|
//*****************************************************************
|
|
void FireJumpToMultipleInstanceView(LPCTSTR szTitle, const VARIANT FAR& varPathArray);
|
|
void FireNotifyContextChanged();
|
|
void FireNotifySaveRequired();
|
|
void FireNotifyViewModified();
|
|
void FireGetIWbemServices(BSTR szNamespace, VARIANT FAR* pvarUpdatePointer, VARIANT FAR* pvarServices, VARIANT FAR* pvarSc, VARIANT FAR* pvarUserCancel)
|
|
|
|
|
|
///////////////////////////////////////////////////////////////
|
|
// METHOD AND EVENT INTERFACE DESCRIPTIONS
|
|
///////////////////////////////////////////////////////////////
|
|
|
|
|
|
//**************************************************************
|
|
// QueryNeedsSave
|
|
//
|
|
// The container calls this method prior to destroying this
|
|
// custom view.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// TRUE (1) if the selected object has been modified and needs to be
|
|
// saved, FALSE (0) otherwise.
|
|
//
|
|
//
|
|
//**************************************************************
|
|
// AddContextRef
|
|
//
|
|
// This method is called to increment the reference count of the
|
|
// specified context handle.
|
|
//
|
|
// Parameters:
|
|
// [in] long lCtxtHandle
|
|
// The context handle who's reference count should be
|
|
// incremented.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// Always returns S_OK.
|
|
//
|
|
//
|
|
//**************************************************************
|
|
// GetContext
|
|
//
|
|
// This method causes the custom view to save its current state
|
|
// in a "context" and return a handle to it. The definition of
|
|
// the "context" is left to the custom view.
|
|
//
|
|
// Parameters:
|
|
// [out] long FAR* plCtxthandle
|
|
// A pointer to the place to return the context handle.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// S_OK if successful, otherwise E_FAIL.
|
|
//
|
|
//
|
|
//**************************************************************
|
|
// CWbemViewCtrl::GetEditMode
|
|
//
|
|
// The container calls this method to get the current edit mode.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// TRUE if the object can be edited, FALSE otherwise.
|
|
//
|
|
//**************************************************************
|
|
// ExternInstanceCreated
|
|
//
|
|
// The container calls this method to inform the custom view that
|
|
// it created a WMI object.
|
|
// is created.
|
|
//
|
|
// Parameters:
|
|
// [in] BSTR szObjectPath
|
|
// The object path of the object created.
|
|
//
|
|
// Returns:
|
|
// None.
|
|
//
|
|
//**************************************************************
|
|
// ExternInstanceDeleted
|
|
//
|
|
// The container calls this method to inform the custom view that
|
|
// it deleted a WMI object.
|
|
//
|
|
// Parameters:
|
|
// [in] BSTR szObjectPath
|
|
// The path of the object that was deleted.
|
|
//
|
|
// Returns:
|
|
// None.
|
|
//
|
|
//**************************************************************
|
|
// RefreshView
|
|
//
|
|
// The container calls this method when it believes that the custom
|
|
// view needs to refresh its data. For example, this may be necessary
|
|
// if the container is notified that the WMI database has been
|
|
// modified by another view.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// S_OK if the view was refreshed, E_FAIL otherwise.
|
|
//
|
|
//**************************************************************
|
|
// ReleaseContext
|
|
//
|
|
// Decrement the reference count on the specified context handle.
|
|
// The context may be destroyed when the reference count goes to
|
|
// zero.
|
|
//
|
|
// Parameters:
|
|
// [in] long lCtxtHandle
|
|
// The context handle.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// S_OK if the reference count was decremented, E_FAIL
|
|
// otherwise.
|
|
//
|
|
//**************************************************************
|
|
// RestoreContext
|
|
//
|
|
// Restore the custom view to the state specified by the given
|
|
// context handle.
|
|
//
|
|
// Parameters:
|
|
// [in] long lCtxtHandle
|
|
// The context handle.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// S_OK if the state was restored, E_FAIL
|
|
// otherwise.
|
|
//
|
|
//**************************************************************
|
|
// SaveData
|
|
//
|
|
// The container calls this method when it wants the custom
|
|
// view to perform a "save". For example, CIM Studio will
|
|
// call this method when the "save" button is clicked if QueryNeedsSave
|
|
// returned TRUE.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
//
|
|
// Returns:
|
|
// SCODE
|
|
// S_OK if the save was successful, E_FAIL
|
|
// otherwise.
|
|
//
|
|
//**************************************************************
|
|
// SetEditMode
|
|
//
|
|
// Set the edit mode.
|
|
//
|
|
// Parameters:
|
|
// [in] long bCanEdit
|
|
// TRUE if it is OK to edit the object, FALSE otherwise.
|
|
//
|
|
// Returns:
|
|
// Nothing.
|
|
//
|
|
//**************************************************************
|
|
// SelectObjectByPath
|
|
//
|
|
// Select the specified WMI object.
|
|
//
|
|
// Parameters:
|
|
// [in] BSTR szObjectPath
|
|
// The WMI path to the object to select.
|
|
//
|
|
// Returns:
|
|
// long
|
|
// S_OK if the object was selected, E_FAIL
|
|
// otherwise.
|
|
//
|
|
//**************************************************************
|
|
|
|
|
|
|
|
|
|
=================================================================
|
|
EVENTS FIRED FROM CUSTOM VIEWS
|
|
=================================================================
|
|
|
|
//**************************************************************
|
|
// FireJumpToMultipleInstanceView
|
|
//
|
|
// Custom views can fire this event to cause the container to
|
|
// jump to a multiple instance view.
|
|
//
|
|
// Parameters:
|
|
// BSTR szTitle
|
|
// The view title.
|
|
//
|
|
// const VARIANT FAR& varPathArray
|
|
// An array of WMI object paths.
|
|
//
|
|
// Returns:
|
|
// void.
|
|
//
|
|
//
|
|
//**************************************************************
|
|
// FireNotifyContextChanged
|
|
//
|
|
// Custom views should fire this event when its context has changed.
|
|
// This allows the container to get an updated context handle for
|
|
// the custom view.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
|
|
//
|
|
// Returns:
|
|
// void.
|
|
//
|
|
//**************************************************************
|
|
// FireNotifySaveRequired
|
|
//
|
|
// Custom views should fire this event when the selected object's data
|
|
// has been modifed and a save is required.
|
|
//
|
|
// Parameters:
|
|
// None.
|
|
//
|
|
// Returns:
|
|
// void.
|
|
//
|
|
//**************************************************************
|
|
// FireGetIWbemServices
|
|
//
|
|
// Parameters:
|
|
// BSTR szNamespace
|
|
// The namespace to connect to.
|
|
//
|
|
// VARIANT FAR* pvarUpdatePointer
|
|
// This is a flag to indicate whether the container should returned a cached
|
|
// IWbemServices pointer for the namespace or get a new one (and put up the
|
|
// login dialog, etc.) The variant that this parameter points to should be of
|
|
// type VT_I4. The value of the variant should be TRUE (non-zero) to request
|
|
// a fresh pointer, or FALSE (zero) to request the cached pointer. If IWbemServices
|
|
// pointer for the namespace is not in the cache and the value is FALSE then
|
|
// the container will attempt to get a fresh pointer by performing a login if
|
|
// necessary.
|
|
//
|
|
//
|
|
// VARIANT FAR* pvarServices
|
|
// The services pointer is returned in the variant that this parameter points to.
|
|
//
|
|
// VARIANT FAR* pvarSc
|
|
// The status code is returned to the custom view via this parameter. If the container
|
|
// catches and handles this event the type of pvarSc will be set to VT_I4 and the status
|
|
// code will be returned in the lVal member.
|
|
//
|
|
//
|
|
// VARIANT FAR* pvarUserCancel
|
|
// A flag indicating whether or not the user cancelled the login dialog is returned
|
|
// via this parameter. Its type will be set to VT_BOOL and the boolVal member will
|
|
// be set to TRUE if the user cancelled the login, and FALSE if the user completed
|
|
// the login.
|
|
//
|
|
//******************************************************************************************
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|