IPortableDevice ::Open, méthode (portabledeviceapi.h)

Article
03/01/2024

La méthode Open ouvre une connexion entre l’application et l’appareil.

Syntaxe

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

Paramètres

[in] pszPnPDeviceID

Pointeur vers une chaîne terminée par null qui contient la chaîne d’ID Plug-and-Play de l’appareil. Vous pouvez obtenir cette chaîne en appelant IPortableDeviceManager ::GetDevices.

[in] pClientInfo

Pointeur vers une interface IPortableDeviceValues qui contient des informations qui identifient l’application sur l’appareil. Cette interface contient des paires PROPERTYKEY/value qui tentent d’identifier une application de manière unique. Bien que la présence d’une interface CoCreated soit requise, l’application n’est pas tenue d’envoyer des paires clé/valeur. Toutefois, l’envoi de données peut améliorer les performances. Les paires clé/valeur classiques incluent le nom de l’application, la version principale et la version mineure et le numéro de build.

Consultez les propriétés commençant par « WPD_CLIENT_ » dans la section Propriétés .

Valeur retournée

Cette méthode retourne un code HRESULT. Les valeurs possibles sont notamment celles figurant dans le tableau suivant.

Code de retour	Description
S_OK	S_OK
E_WPD_DEVICE_ALREADY_OPENED	La connexion de l’appareil a déjà été ouverte.
E_POINTER	Au moins un des arguments était un pointeur NULL.

Remarques

Un appareil doit être ouvert avant que vous puissiez appeler des méthodes sur celui-ci. (Notez que les méthodes IPortableDeviceManager ne vous obligent pas à ouvrir un appareil avant d’appeler des méthodes.) Toutefois, vous n’avez généralement pas besoin d’appeler Close.

Les administrateurs peuvent restreindre l’accès des appareils portables aux ordinateurs exécutés sur un réseau. Par exemple, un administrateur peut restreindre tous les utilisateurs invités à l’accès en lecture seule, tandis que les utilisateurs authentifiés bénéficient d’un accès en lecture/écriture.

En raison de ces problèmes de sécurité, si votre application n’effectue pas d’opérations d’écriture, elle doit appeler la méthode Open et demander un accès en lecture seule en spécifiant GENERIC_READ pour la propriété WPD_CLIENT_DESIRED_ACCESS qu’elle fournit dans le paramètre pClientInfo .

Si votre application nécessite des opérations d’écriture, elle doit appeler la méthode Open comme indiqué dans l’exemple de code suivant. La première fois, il doit demander l’accès en lecture/écriture en passant la propriété de WPD_CLIENT_DESIRED_ACCESS par défaut dans le paramètre pClientInfo . Si ce premier appel échoue et retourne E_ACCESSDENIED, votre application doit appeler la méthode Open une deuxième fois et demander un accès en lecture seule en spécifiant GENERIC_READ pour la propriété WPD_CLIENT_DESIRED_ACCESS qu’elle fournit dans le paramètre pClientInfo .

Les applications qui vivent dans des appartements à thread unique doivent utiliser CLSID_PortableDeviceFTM, car cela élimine la surcharge du marshaling des pointeurs d’interface. CLSID_PortableDevice est toujours pris en charge pour les applications héritées.

Exemples


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