Share via

Specifying Client Information

  • Article

banner art

Previous Next

Specifying Client Information

The client information supplied in the second argument is used by some device drivers to optimize device performance. At a minimum, your application should provide a string containing its name, a major version number, a minor version number, and a revision number. These are the fields supplied by the sample application.

#define CLIENT_NAME         L"WPD Sample Application"
#define CLIENT_MAJOR_VER    1
#define CLIENT_MINOR_VER    0
#define CLIENT_REVISION     2

The GetClientInformation function in the sample application creates and populates an IPortableDeviceValues interface with client information. This function has two primary parts. The first part creates an instance of a portable device-values object by calling the CoCreateInstance function.

hr = CoCreateInstance(CLSID_PortableDeviceValues,
                     NULL,
                     CLSCTX_INPROC_SERVER,
                     IID_IPortableDeviceValues,
                     (VOID**) ppClientInformation);

The second part sets the client information in the portable device-values object.

if (SUCCEEDED(hr))
{
    if (ppClientInformation != NULL)
    {
        // Attempt to set all bits of client information
        hr = (*ppClientInformation)->SetStringValue(WPD_CLIENT_NAME, CLIENT_NAME);
        if (FAILED(hr))
        {
            printf("! Failed to set WPD_CLIENT_NAME, hr = 0x%lx\n",hr);
        }

        hr = (*ppClientInformation)->SetUnsignedIntegerValue(WPD_CLIENT_MAJOR_VERSION, CLIENT_MAJOR_VER);
        if (FAILED(hr))
        {
            printf("! Failed to set WPD_CLIENT_MAJOR_VERSION, hr = 0x%lx\n",hr);
        }

        hr = (*ppClientInformation)->SetUnsignedIntegerValue(WPD_CLIENT_MINOR_VERSION, CLIENT_MINOR_VER);
        if (FAILED(hr))
        {
            printf("! Failed to set WPD_CLIENT_MINOR_VERSION, hr = 0x%lx\n",hr);
        }

        hr = (*ppClientInformation)->SetUnsignedIntegerValue(WPD_CLIENT_REVISION, CLIENT_REVISION);
        if (FAILED(hr))
        {
            printf("! Failed to set WPD_CLIENT_REVISION, hr = 0x%lx\n",hr);
        }

        //  Some device drivers need to impersonate the caller in order to function correctly.  Since our application does not
        //  need to restrict its identity, specify SECURITY_IMPERSONATION so that we work with all devices.
        hr = (*ppClientInformation)->SetUnsignedIntegerValue(WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE, SECURITY_IMPERSONATION);
        if (FAILED(hr))
        {
            printf("! Failed to set WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE, hr = 0x%lx\n",hr);
        }
    }
    else
    {
        hr = E_UNEXPECTED;
        printf("! Failed to create client information because we were returned a NULL IPortableDeviceValues interface pointer, hr = 0x%lx\n",hr);
    }
}
else
{
    printf("! Failed to CoCreateInstance CLSID_PortableDeviceValues, hr = 0x%lx\n",hr);
}

See Also

Previous Next