Reading Device Properties

Applications use a device's IWiaPropertyStorage interface to read and write device properties. IWiaPropertyStorage inherits all of the methods of the Component Object Model (COM) interface IPropertyStorage.

Device properties include information about a device that describe the device's capabilities and settings. For a list of these properties, see Device Properties.

Among the device properties that are read using IWiaPropertyStorage is the device ID, that is then used to create a Windows Image Acquisition (WIA) device. For more information, see IWiaDevMgr::CreateDevice (or IWiaDevMgr2::CreateDevice).

The following example reads the device ID, the device name, and the device description from the array of device properties, and prints these properties to the console.

    HRESULT ReadSomeWiaProperties( IWiaPropertyStorage *pWiaPropertyStorage )
    {
        //
        // Validate arguments
        //
        if (NULL == pWiaPropertyStorage)
        {
            return E_INVALIDARG;
        }

        //
        // Declare PROPSPECs and PROPVARIANTs, and initialize them to zero.
        //
        PROPSPEC PropSpec[3] = {0};
        PROPVARIANT PropVar[3] = {0};

        //
        // How many properties are you querying for?
        //
        const ULONG c_nPropertyCount = sizeof(PropSpec)/sizeof(PropSpec[0]);

        //
        // Define which properties you want to read:
        // Device ID.  This is what you would use to create
        // the device.
        //
        PropSpec[0].ulKind = PRSPEC_PROPID;
        PropSpec[0].propid = WIA_DIP_DEV_ID;

        //
        // Device Name
        //
        PropSpec[1].ulKind = PRSPEC_PROPID;
        PropSpec[1].propid = WIA_DIP_DEV_NAME;

        //
        // Device description
        //
        PropSpec[2].ulKind = PRSPEC_PROPID;
        PropSpec[2].propid = WIA_DIP_DEV_DESC;

        //
        // Ask for the property values
        //
        HRESULT hr = pWiaPropertyStorage->ReadMultiple( c_nPropertyCount, PropSpec, PropVar );
        if (SUCCEEDED(hr))
        {
            //
            // IWiaPropertyStorage::ReadMultiple will return S_FALSE if some
            // properties could not be read, so you have to check the return
            // types for each requested item.
            //

            //
            // Check the return type for the device ID
            //
            if (VT_BSTR == PropVar[0].vt)
            {
                //
                // Do something with the device ID
                //
                _tprintf( TEXT("WIA_DIP_DEV_ID: %ws\n"), PropVar[0].bstrVal );
            }

            //
            // Check the return type for the device name
            //
            if (VT_BSTR == PropVar[1].vt)
            {
                //
                // Do something with the device name
                //
                _tprintf( TEXT("WIA_DIP_DEV_NAME: %ws\n"), PropVar[1].bstrVal );
            }

            //
            // Check the return type for the device description
            //
            if (VT_BSTR == PropVar[2].vt)
            {
                //
                // Do something with the device description
                //
                _tprintf( TEXT("WIA_DIP_DEV_DESC: %ws\n"), PropVar[2].bstrVal );
            }

            //
            // Free the returned PROPVARIANTs
            //
            FreePropVariantArray( c_nPropertyCount, PropVar );
        }

        //
        // Return the result of reading the properties
        //
        return hr;
    }

In this example, the application sets up PROPVARIANT arrays (PropSpec and PropVar, respectively) to hold property information. These arrays are passed as parameters in the call to IPropertyStorage::ReadMultiple method of the IWiaPropertyStorage pointer pIWiaPropStg. Each element of the PropSpec array contains the type and name of a device property. Upon return, each element of the PropVar contains the value of the device property represented by the corresponding element of the PropSpec array.

The application then calls IPropertyStorage::ReadMultiple property of the IWiaPropertyStorage pointer pWiaPropertyStorage to retrieve the property information.

The technique used to read and set device properties is the same as that for item properties, the only difference is the type of the WIA item on which you call the appropriate methods. For a list of item properties, see Item Properties.