Método IPortableDevice::Open (portabledeviceapi.h)

Artigo
03/01/2024

O método Open abre uma conexão entre o aplicativo e o dispositivo.

Sintaxe

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

Parâmetros

[in] pszPnPDeviceID

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém a cadeia de caracteres de ID Plug and Play para o dispositivo. Você pode obter essa cadeia de caracteres chamando IPortableDeviceManager::GetDevices.

[in] pClientInfo

Um ponteiro para uma interface IPortableDeviceValues que contém informações que identificam o aplicativo para o dispositivo. Essa interface contém pares PROPERTYKEY/value que tentam identificar um aplicativo exclusivamente. Embora a presença de uma interface CoCreated seja necessária, o aplicativo não é necessário para enviar pares chave/valor. No entanto, o envio de dados pode melhorar o desempenho. Os pares chave/valor típicos incluem o nome do aplicativo, a versão principal e secundária e o número de build.

Confira as propriedades que começam com "WPD_CLIENT_" na seção Propriedades .

Retornar valor

O método retorna um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
E_WPD_DEVICE_ALREADY_OPENED	A conexão do dispositivo já foi aberta.
E_POINTER	Pelo menos um dos argumentos era um ponteiro NULL.

Comentários

Um dispositivo deve ser aberto antes que você possa chamar qualquer método nele. (Observe que os métodos IPortableDeviceManager não exigem que você abra um dispositivo antes de chamar nenhum método.) No entanto, geralmente você não precisa chamar Close.

Os administradores podem restringir o acesso de dispositivos portáteis a computadores em execução em uma rede. Por exemplo, um administrador pode restringir todos os usuários convidados ao acesso somente leitura, enquanto os usuários autenticados recebem acesso de leitura/gravação.

Devido a esses problemas de segurança, se o aplicativo não executar operações de gravação, ele deverá chamar o método Open e solicitar acesso somente leitura especificando GENERIC_READ para a propriedade WPD_CLIENT_DESIRED_ACCESS que ele fornece no parâmetro pClientInfo .

Se o aplicativo exigir operações de gravação, ele deverá chamar o método Open , conforme mostrado no código de exemplo a seguir. Na primeira vez, ele deve solicitar acesso de leitura/gravação passando a propriedade padrão WPD_CLIENT_DESIRED_ACCESS no parâmetro pClientInfo . Se essa primeira chamada falhar e retornar E_ACCESSDENIED, seu aplicativo deverá chamar o método Open uma segunda vez e solicitar acesso somente leitura especificando GENERIC_READ para a propriedade WPD_CLIENT_DESIRED_ACCESS que ele fornece no parâmetro pClientInfo .

Os aplicativos que residem em apartamentos de thread único devem usar CLSID_PortableDeviceFTM, pois isso elimina a sobrecarga do marshaling de ponteiro de interface. CLSID_PortableDevice ainda tem suporte para aplicativos herdados.

Exemplos


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