IPortableDevice::Open-Methode (portabledeviceapi.h)

Artikel
03/01/2024

Die Open-Methode öffnet eine Verbindung zwischen der Anwendung und dem Gerät.

Syntax

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

Parameter

[in] pszPnPDeviceID

Ein Zeiger auf eine NULL-endende Zeichenfolge, die die Plug & Play-ID-Zeichenfolge für das Gerät enthält. Sie können diese Zeichenfolge abrufen, indem Sie IPortableDeviceManager::GetDevices aufrufen.

[in] pClientInfo

Ein Zeiger auf eine IPortableDeviceValues-Schnittstelle , die Informationen enthält, die die Anwendung für das Gerät identifizieren. Diese Schnittstelle enthält PROPERTYKEY-Wert-Paare, die versuchen, eine Anwendung eindeutig zu identifizieren. Obwohl das Vorhandensein einer CoCreated-Schnittstelle erforderlich ist, muss die Anwendung keine Schlüssel-Wert-Paare senden. Das Senden von Daten kann jedoch die Leistung verbessern. Typische Schlüssel-Wert-Paare umfassen den Anwendungsnamen, die Haupt- und Nebenversion sowie die Buildnummer.

Weitere Informationen finden Sie unter Eigenschaften ab "WPD_CLIENT_" im Abschnitt Eigenschaften .

Rückgabewert

Die Methode gibt ein HRESULT zurück. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.

Rückgabecode	BESCHREIBUNG
S_OK	Die Methode wurde erfolgreich ausgeführt.
E_WPD_DEVICE_ALREADY_OPENED	Die Geräteverbindung wurde bereits geöffnet.
E_POINTER	Mindestens eines der Argumente war ein NULL-Zeiger.

Hinweise

Ein Gerät muss geöffnet werden, bevor Sie methoden darauf aufrufen können. (Beachten Sie, dass die IPortableDeviceManager-Methoden nicht erfordern, dass Sie vor dem Aufrufen von Methoden ein Gerät öffnen.) In der Regel müssen Sie close jedoch nicht aufrufen.

Administratoren können den Zugriff von tragbaren Geräten auf Computer einschränken, die in einem Netzwerk ausgeführt werden. Beispielsweise kann ein Administrator alle Gastbenutzer auf schreibgeschützten Zugriff beschränken, während authentifizierten Benutzern Lese-/Schreibzugriff gewährt wird.

Wenn Ihre Anwendung aufgrund dieser Sicherheitsprobleme keine Schreibvorgänge ausführt, sollte sie die Open-Methode aufrufen und schreibgeschützten Zugriff anfordern, indem GENERIC_READ für die WPD_CLIENT_DESIRED_ACCESS-Eigenschaft angegeben wird, die sie im pClientInfo-Parameter bereitstellt.

Wenn Ihre Anwendung Schreibvorgänge erfordert, sollte sie die Open-Methode aufrufen, wie im folgenden Beispielcode gezeigt. Beim ersten Mal sollte lese-/schreibzugriff angefordert werden, indem die Standardeigenschaft WPD_CLIENT_DESIRED_ACCESS im pClientInfo-Parameter übergeben wird. Wenn dieser erste Aufruf fehlschlägt und E_ACCESSDENIED zurückgibt, sollte Ihre Anwendung die Open-Methode ein zweites Mal aufrufen und schreibgeschützten Zugriff anfordern, indem sie GENERIC_READ für die WPD_CLIENT_DESIRED_ACCESS-Eigenschaft angibt, die sie im pClientInfo-Parameter bereitstellt.

Anwendungen, die in Single Threaded Apartments leben, sollten CLSID_PortableDeviceFTM verwenden, da dadurch der Mehraufwand beim Marshallen von Schnittstellenzeigern entfällt. CLSID_PortableDevice wird weiterhin für Legacyanwendungen unterstützt.

Beispiele


#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;
}