Retrieving Part of an Instance

A partial-instance retrieval is when WMI retrieves only a subset of the properties of an instance. For example, WMI could retrieve only the Name and Key properties. The most common use of partial-instance retrieval is on large enumerations that have multiple properties.

Retrieving Part of an Instance Using VBScript

You can retrieve an individual property of an instance by using GetObject.

The following code example displays the volume serial number for an instance of the Win32_LogicalDisk class.

MsgBox (GetObject( _
    "WinMgmts:Win32_LogicalDisk='C:'").VolumeSerialNumber)

Retrieving Part of an Instance Using C++

The following procedure is used to request a partial-instance retrieval using C++.

Aa393247.wedge(en-us,VS.85).gifTo request a partial-instance retrieval using C++

  1. Create an IWbemContext object with a call to CoCreateInstance.

    A context object is an object that WMI uses to pass in more information to a WMI provider. In this case, you are using the IWbemContext object to instruct the provider to process a partial-instance retrieval.

  2. Add __GET_EXTENSIONS, __GET_EXT_CLIENT_REQUEST, and any other named values that describe the properties you want to retrieve to the IWbemContext object.

    The following table lists the different named values use in your retrieval call.

    Named valueDescription

    __GET_EXTENSIONS

    VT_BOOL set to VARIANT_TRUE. Used to signal that partial-instance retrieval operations are being used. This allows a quick, single check without having to enumerate the entire context object. If any of the other values are used, this one must be.

    __GET_EXT_PROPERTIES

    SAFEARRAY of strings listing the properties to be retrieved. Cannot be simultaneously specified with __GET_EXT_KEYS_ONLY.

    An asterisk "*" is an invalid property name for __GET_EXT_PROPERTIES.

    __GET_EXT_KEYS_ONLY

    VT_BOOL set to VARIANT_TRUE. Indicates that only keys should be provided in the returned object. Cannot be simultaneously specified with __GET_EXT_PROPERTIES. Instead, takes precedence over __GET_EXT_PROPERTIES.

    __GET_EXT_CLIENT_REQUEST

    VT_BOOL set to VARIANT_TRUE. Indicates that the caller was the one who wrote the value into the context object and that it was not propagated from another dependent operation.

     

  3. Pass the IWbemContext context object into any calls to IWbemServices::GetObject, IWbemServices::GetObjectAsync, IWbemServices::CreateInstanceEnum, or IWbemServices::CreateInstanceEnumAsync through the pCtx parameter.

    Passing the IWbemContext object instructs the provider to allow partial-instance retrievals. In a full-instance retrieval, you would set pCtx to a null value. If the provider does not support partial-instance retrieval, you will receive an error message.

If the provider cannot comply with the partial-instance operation, the provider either proceeds as if you did not enter the context object, or else returns WBEM_E_UNSUPPORTED_PARAMETER.

The following example describes how to perform a full instance retrieval of Win32_LogicalDisk, and then performs a partial-instance retrieval of the Win32_LogicalDisk.Caption property.


#include <stdio.h>
#define _WIN32_DCOM
#include <wbemidl.h>
# pragma comment(lib, "wbemuuid.lib")
#include <iostream>
using namespace std;
#include <comdef.h>


void main(void)
{
    HRESULT hr;
    _bstr_t bstrNamespace;
    IWbemLocator *pWbemLocator = NULL;
    IWbemServices *pServices = NULL;
    IWbemClassObject *pDrive = NULL;
    

    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    hr = CoInitializeSecurity(NULL, -1, NULL, NULL,
                         RPC_C_AUTHN_LEVEL_CONNECT,
                         RPC_C_IMP_LEVEL_IMPERSONATE,
                         NULL, EOAC_NONE, 0);
 
    if (FAILED(hr))
    {
       CoUninitialize();
       cout << "Failed to initialize security. Error code = 0x" 
            << hex << hr << endl;
       return;
    }

    hr = CoCreateInstance(CLSID_WbemLocator, NULL, 
                          CLSCTX_INPROC_SERVER, IID_IWbemLocator, 
                          (void**) &pWbemLocator);
    if( FAILED(hr) ) 
    {
        CoUninitialize();
        printf("failed CoCreateInstance\n");
        return;
    }
    
    bstrNamespace = L"root\\cimv2";
    hr = pWbemLocator->ConnectServer(bstrNamespace, 
              NULL, NULL, NULL, 0, NULL, NULL, &pServices);
    if( FAILED(hr) ) 
    {
        pWbemLocator->Release();
        CoUninitialize();
        printf("failed ConnectServer\n");
        return;
    }
    pWbemLocator->Release();
    printf("Successfully connected to namespace.\n");

    
    BSTR bstrPath = 
         SysAllocString(L"Win32_LogicalDisk.DeviceID=\"C:\"");
   // *******************************************************//
   // Perform a full-instance retrieval. 
   // *******************************************************//
    hr = pServices->GetObject(bstrPath,
                              0,0, &pDrive, 0);
    if( FAILED(hr) )
    { 
        pServices->Release();
        CoUninitialize();
        printf("failed GetObject\n");
        return;
    }    
    // Display the object
    BSTR  bstrDriveObj;
    hr = pDrive->GetObjectText(0, &bstrDriveObj);
    printf("%S\n\n", bstrDriveObj);

    pDrive->Release();
    pDrive = NULL;

   // *****************************************************//
   // Perform a partial-instance retrieval. 
   // *****************************************************//
    
    IWbemContext  *pctxDrive; // Create context object
    hr = CoCreateInstance(CLSID_WbemContext, NULL, 
                          CLSCTX_INPROC_SERVER, IID_IWbemContext, 
                          (void**) &pctxDrive);
    if (FAILED(hr))
    {
        pServices->Release();
        pDrive->Release();    
        CoUninitialize();
        printf("create instance failed for context object.\n");
        return;
    }
    
    VARIANT  vExtensions;
    VARIANT  vClient;
    VARIANT  vPropertyList;
    VARIANT  vProperty;
    SAFEARRAY  *psaProperties;
    SAFEARRAYBOUND saBounds;
    LONG  lArrayIndex = 0;
    
    // Add named values to the context object. 
    VariantInit(&vExtensions);
    V_VT(&vExtensions) = VT_BOOL;
    V_BOOL(&vExtensions) = VARIANT_TRUE;
    hr = pctxDrive->SetValue(_bstr_t(L"__GET_EXTENSIONS"), 
        0, &vExtensions);
    VariantClear(&vExtensions);

    VariantInit(&vClient);
    V_VT(&vClient) = VT_BOOL;
    V_BOOL(&vClient) = VARIANT_TRUE;
    hr = pctxDrive->SetValue(_bstr_t(L"__GET_EXT_CLIENT_REQUEST"), 
       0, &vClient);
    VariantClear(&vClient);
    // Create an array of properties to return.
    saBounds.cElements = 1;
    saBounds.lLbound = 0;
    psaProperties = SafeArrayCreate(VT_BSTR, 1, &saBounds);

    // Add the Caption property to the array.
    VariantInit(&vProperty);
    V_VT(&vProperty) = VT_BSTR;
    V_BSTR(&vProperty) = _bstr_t(L"Caption");
    SafeArrayPutElement(psaProperties, &lArrayIndex, 
       V_BSTR(&vProperty));
    VariantClear(&vProperty);
    
    VariantInit(&vPropertyList);
    V_VT(&vPropertyList) = VT_ARRAY | VT_BSTR;
    V_ARRAY(&vPropertyList) = psaProperties;
    // Put the array in the named value __GET_EXT_PROPERTIES.
    hr = pctxDrive->SetValue(_bstr_t(L"__GET_EXT_PROPERTIES"), 
        0, &vPropertyList);
    VariantClear(&vPropertyList);
    SafeArrayDestroy(psaProperties);

    // Pass the context object as the pCtx parameter of GetObject.
    hr = pServices->GetObject(bstrPath, 0, pctxDrive, &pDrive, 0);
    if( FAILED(hr) )
    { 
        pServices->Release();
        CoUninitialize();
        printf("failed property GetObject\n");
        return;
    }    
    // Display the object
    hr = pDrive->GetObjectText(0, &bstrDriveObj);
    printf("%S\n\n", bstrDriveObj);

    SysFreeString(bstrPath);

    VARIANT vFileSystem;
    // Attempt to get a property that was not requested.
    // The following should return a NULL property if
    // the partial-instance retrieval succeeded.

    hr = pDrive->Get(_bstr_t(L"FileSystem"), 0,
                       &vFileSystem, NULL, NULL);

    if( FAILED(hr) )
    { 
        pServices->Release();
        pDrive->Release();    
        CoUninitialize();
        printf("failed get for file system\n");
        return;
    }    
 
    if (V_VT(&vFileSystem) == VT_NULL)
        printf("file system variable is null - expected\n");
    else
        printf("FileSystem = %S\n", V_BSTR(&vFileSystem));
    
    VariantClear(&vFileSystem);

    pDrive->Release();    
    pctxDrive->Release();
    pServices->Release();
    pServices = NULL;    // MUST be set to NULL
    CoUninitialize();
    return;  // -- program successfully completed
};


When executed, the previous code example writes the following information. The first object description is from the full-instance retrieval. The second object description is from the partial-instance retrieval. The last section shows that you receive a null value if you request a property that was not requested in the original GetObject call.

Successfully connected to namespace

instance of Win32_LogicalDisk
{
        Caption = "C:";
        Compressed = FALSE;
        CreationClassName = "Win32_LogicalDisk";
        Description = "Local Fixed Disk";
        DeviceID = "C:";
        DriveType = 3;
        FileSystem = "NTFS";
        FreeSpace = "3085668352";
        MaximumComponentLength = 255;
        MediaType = 12;
        Name = "C:";
        Size = "4581445632";
        SupportsFileBasedCompression = TRUE;
        SystemCreationClassName = "Win32_ComputerSystem";
        SystemName = "TITUS";
        VolumeName = "titus-c";
        VolumeSerialNumber = "7CB4B90E";
};

instance of Win32_LogicalDisk
{
        Caption = "C:";
        CreationClassName = "Win32_LogicalDisk";
        Description = "Local Fixed Disk";
        DeviceID = "C:";
        DriveType = 3;
        MediaType = 12;
        Name = "C:";
        SystemCreationClassName = "Win32_ComputerSystem";
        SystemName = "MySystem";
};

The following output is generated by the previous example.

file system variable is null - expected
Press any key to continue

 

 

Show:
© 2014 Microsoft