共用方式為

IPortableDevice：：Open 方法 (portabledeviceapi.h)

  • 發行項

Open 方法會開啟應用程式與裝置之間的連線。

語法

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

參數

[in] pszPnPDeviceID

Null 終止字串的指標，其中包含裝置的 隨插即用 標識符字串。 您可以呼叫 IPortableDeviceManager：：GetDevices 來取得此字串。

[in] pClientInfo

IPortableDeviceValues 介面的指標，可保存識別應用程式至裝置的資訊。 此介面會保存嘗試唯一識別應用程式的 PROPERTYKEY/值組。 雖然需要 CoCreated 介面，但應用程式不需要傳送任何索引鍵/值組。 不過，傳送數據可能會改善效能。 典型的索引鍵/值組包括應用程式名稱、主要和次要版本，以及組建編號。

請參閱 Properties 一節的開頭為 「WPD_CLIENT_」 的屬性 。

傳回值

方法會傳回 HRESULT。 可能的值包括 (但不限於) 下表中的這些值。

傳回碼 描述
S_OK
 此方法已成功。
E_WPD_DEVICE_ALREADY_OPENED
 裝置連線已經開啟。
E_POINTER
 至少有一個自變數是 NULL 指標。

備註

必須先開啟裝置，才能在裝置上呼叫任何方法。 (請注意， IPortableDeviceManager 方法不需要在呼叫任何方法.) 之前開啟裝置，不過，您通常不需要呼叫 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來要求只讀存取。

位於單一線程 Apartment 中的應用程式應該使用 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;
}

規格需求

需求 值
目標平台 Windows
標頭 portabledeviceapi.h
程式庫 PortableDeviceGUIDs.lib

另請參閱

建立連線

IPortableDevice 介面

IPortableDevice：：Close