IPortableDevice::Open メソッド (portabledeviceapi.h)

[アーティクル]
03/15/2023

Open メソッドは、アプリケーションとデバイス間の接続を開きます。

構文

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

パラメーター

[in] pszPnPDeviceID

デバイスのプラグアンドプレイ ID 文字列を含む null で終わる文字列へのポインター。この文字列を取得するには、 IPortableDeviceManager::GetDevices を呼び出します。

[in] pClientInfo

デバイスへのアプリケーションを識別する情報を保持する IPortableDeviceValues インターフェイスへのポインター。このインターフェイスは、アプリケーションを一意に識別しようとする PROPERTYKEY/値ペアを保持します。 CoCreated インターフェイスが存在する必要がありますが、アプリケーションはキーと値のペアを送信する必要はありません。ただし、データを送信するとパフォーマンスが向上する可能性があります。一般的なキーと値のペアには、アプリケーション名、メジャーバージョンとマイナーバージョン、ビルド番号が含まれます。

「プロパティ」セクションの「WPD_CLIENT_」で始まるプロパティを参照してください。

戻り値

このメソッドは HRESULT を返します。有効な値を次の表に示しますが、これ以外にもあります。

リターンコード	説明
S_OK	メソッドが成功しました。
E_WPD_DEVICE_ALREADY_OPENED	デバイス接続は既に開かれています。
E_POINTER	引数の少なくとも 1 つが NULL ポインターでした。

注釈

デバイス上の任意のメソッドを呼び出す前に、デバイスを開く必要があります。 ( IPortableDeviceManager メソッドでは、メソッドを呼び出す前にデバイスを開く必要はありません。ただし、通常は Close を呼び出す必要はありません。

管理者は、ネットワーク上で実行されているコンピューターにポータブルデバイスのアクセスを制限できます。たとえば、管理者はすべてのゲストユーザーに読み取り専用アクセスを制限し、認証済みユーザーには読み取り/書き込みアクセス権が付与される場合があります。

これらのセキュリティの問題により、アプリケーションが書き込み操作を実行しない場合は、 Open メソッドを呼び出し、 pClientInfo パラメーターで指定するWPD_CLIENT_DESIRED_ACCESS プロパティのGENERIC_READを指定して読み取り専用アクセスを要求する必要があります。

アプリケーションで書き込み操作が必要な場合は、次のコード例に示すように Open メソッドを呼び出す必要があります。初めて、 pClientInfo パラメーターに既定の WPD_CLIENT_DESIRED_ACCESS プロパティを渡すことで、読み取り/書き込みアクセスを要求する必要があります。この最初の呼び出しが失敗し、E_ACCESSDENIEDを返す場合、アプリケーションは Open メソッドを 2 回目に呼び出し、 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;
}