IPortableDevice：：Open 方法 (portabledeviceapi.h)

项目
03/13/2024

Open 方法打开应用程序与设备之间的连接。

语法

HRESULT Open(
  [in] LPCWSTR               pszPnPDeviceID,
  [in] IPortableDeviceValues *pClientInfo
);

参数

[in] pszPnPDeviceID

指向以 null 结尾的字符串的指针，该字符串包含设备的即插即用 ID 字符串。可以通过调用 IPortableDeviceManager：：GetDevices 来获取此字符串。

[in] pClientInfo

指向 IPortableDeviceValues 接口的指针，该接口包含标识设备应用程序的信息。此接口包含尝试唯一标识应用程序的 PROPERTYKEY/值对。尽管需要存在 CoCreated 接口，但应用程序不需要发送任何键/值对。但是，发送数据可能会提高性能。典型的键/值对包括应用程序名称、主要和次要版本以及内部版本号。

请参阅属性部分中以“WPD_CLIENT_”开头的属性。

返回值

该方法返回 HRESULT。可能的值包括（但并不限于）下表中的项。

返回代码	说明
S_OK	方法成功。
E_WPD_DEVICE_ALREADY_OPENED	设备连接已打开。
E_POINTER	至少有一个参数是 NULL 指针。

注解

必须先打开设备，然后才能对该设备调用任何方法。 (请注意， IPortableDeviceManager 方法不需要在调用任何 methods.) 但通常不需要调用 Close。

管理员可以将便携式设备的访问限制为在网络上运行的计算机。例如，管理员可以将所有来宾用户限制为只读访问权限，而经过身份验证的用户则获得读/写访问权限。

由于这些安全问题，如果应用程序不会执行写入操作，它应调用 Open 方法，并通过指定它在 pClientInfo 参数中提供的 WPD_CLIENT_DESIRED_ACCESS 属性的GENERIC_READ来请求只读访问权限。

如果应用程序需要写入操作，则应调用 Open 方法，如以下示例代码所示。第一次，它应通过传递 pClientInfo 参数中的默认 WPD_CLIENT_DESIRED_ACCESS 属性来请求读/写访问权限。如果第一次调用失败并返回E_ACCESSDENIED，则应用程序应再次调用 Open 方法，并通过为它在 pClientInfo 参数中提供的 WPD_CLIENT_DESIRED_ACCESS 属性指定GENERIC_READ来请求只读访问权限。

位于单线程单元中的应用程序应使用 CLSID_PortableDeviceFTM，因为这样可以消除接口指针封送的开销。旧版应用程序仍支持CLSID_PortableDevice。

示例


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

HRESULT OpenDevice(LPCWSTR wszPnPDeviceID, IPortableDevice** ppDevice)
{
    HRESULT                hr                 = S_OK;
    IPortableDeviceValues* pClientInformation = NULL;
    IPortableDevice*       pDevice            = NULL;

    if ((wszPnPDeviceID == NULL) || (ppDevice == NULL))
    {
        hr = E_INVALIDARG;
        return hr;
    }

    // CoCreate an IPortableDeviceValues interface to hold the client information.
    hr = CoCreateInstance(CLSID_PortableDeviceValues,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IPortableDeviceValues,
                          (VOID**) &pClientInformation);
    if (SUCCEEDED(hr))
    {
        HRESULT ClientInfoHR = S_OK;

        // Attempt to set all properties for client information. If we fail to set
        // any of the properties below it is OK. Failing to set a property in the
        // client information isn't a fatal error.
        ClientInfoHR = pClientInformation->SetStringValue(WPD_CLIENT_NAME, CLIENT_NAME);
        if (FAILED(ClientInfoHR))
        {
           // Failed to set WPD_CLIENT_NAME
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MAJOR_VERSION, CLIENT_MAJOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MAJOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MINOR_VERSION, CLIENT_MINOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MINOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_REVISION, CLIENT_REVISION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_REVISION
        }
    }
    else
    {
        // Failed to CoCreateInstance CLSID_PortableDeviceValues for client information
    }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE, SECURITY_IMPERSONATION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE
        }

    if (SUCCEEDED(hr))
    {
        // CoCreate an IPortableDevice interface
        hr = CoCreateInstance(CLSID_PortableDeviceFTM,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IPortableDevice,
                              (VOID**) &pDevice);

        if (SUCCEEDED(hr))
        {
            // Attempt to open the device using the PnPDeviceID string given
            // to this function and the newly created client information.
            // Note that we're attempting to open the device the first 
            // time using the default (read/write) access. If this fails
            // with E_ACCESSDENIED, we'll attempt to open a second time
            // with read-only access.
            hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            if (hr == E_ACCESSDENIED)
            {
                 // Attempt to open for read-only access
                 pClientInformation->SetUnsignedIntegerValue(
                       WPD_CLIENT_DESIRED_ACCESS,
                       GENERIC_READ);
                 hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            }
            if (SUCCEEDED(hr))
            {
                // The device successfully opened, obtain an instance of the Device into
                // ppDevice so the caller can be returned an opened IPortableDevice.
                hr = pDevice->QueryInterface(IID_IPortableDevice, (VOID**)ppDevice);
                if (FAILED(hr))
                {
                    // Failed to QueryInterface the opened IPortableDevice
                }
            }
        }
        else
        {
            // Failed to CoCreateInstance CLSID_PortableDevice
        }
    }

    // Release the IPortableDevice when finished
    if (pDevice != NULL)
    {
        pDevice->Release();
        pDevice = NULL;
    }

    // Release the IPortableDeviceValues that contains the client information when finished
    if (pClientInformation != NULL)
    {
        pClientInformation->Release();
        pClientInformation = NULL;
    }

    return hr;
}