Método IWDFDevice::RetrieveDeviceName (wudfddi.h)

Artigo
02/07/2025

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda UMDF .]

O método RetrieveDeviceName recupera o nome de um dispositivo de modo kernel subjacente.

Sintaxe

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Parâmetros

[out] pDeviceName

Um ponteiro para um buffer que recebe um cadeia de caracteres nullterminada que representa o nome do dispositivo de modo kernel subjacente, se o buffer não for NULL e RetrieveDeviceName for bem-sucedido.

[in, out] pdwDeviceNameLength

Um ponteiro para uma variável que recebe o número de caracteres, incluindo o caractere NULL, no nome do dispositivo.

Se o buffer em pDeviceName for NULL, o valor fornecido pelo driver será zero. Em seguida, a estrutura retorna o tamanho, em caracteres, necessário para a cadeia de caracteres de nome do dispositivo.

Se o buffer em pDeviceName não forNULL, a estrutura retornará o tamanho, em caracteres, da cadeia de caracteres de nome do dispositivo.

Valor de retorno

RetrieveDeviceName retorna S_OK para os seguintes cenários:

O buffer que o parâmetro pDeviceName apontou era não NULL e grande o suficiente para manter a cadeia de caracteres de nome, incluindo o caractere NULL e a estrutura copiou com êxito a cadeia de caracteres para o buffer fornecido e definiu a variável que é apontada por pdwDeviceNameLength para o número de caracteres na cadeia de caracteres.
O buffer em pDeviceName foi NULL, o driver predefini a variável em pdwDeviceNameLength como 0 e a estrutura definiu a variável em pdwDeviceNameLength para o número de caracteres necessários para a cadeia de caracteres.

RetrieveDeviceName retorna HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) para indicar que o buffer fornecido não era NULL e não continha espaço suficiente para manter o nome do dispositivo. A estrutura define a variável em pdwDeviceNameLength para o número de caracteres necessários para a cadeia de caracteres.

retrieveDeviceName também pode retornar outros valores HRESULT.

Observações

O nome do dispositivo não é o nome do objeto de dispositivo físico (PDO). Em vez disso, o nome do dispositivo é o nome do refletor. O driver deve direcionar todas as E/Ss para este objeto de dispositivo.

Exemplos

O exemplo de código a seguir mostra como recuperar o nome de um dispositivo de modo kernel subjacente.

    PWSTR deviceName = NULL;
    DWORD deviceNameCch = 0;
    HRESULT hr;
    //
    // Get the length of the device name to allocate a buffer
    //
    hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
    //
    // Allocate the buffer
    //
    deviceName = new WCHAR[deviceNameCch];

    if (deviceName == NULL) {
        hr = E_OUTOFMEMORY;
        goto Exit1;
    }
    //
    // Get the device name
    //
    hr = m_FxDevice->RetrieveDeviceName(deviceName,
                                        &deviceNameCch);

    // Open the device and get the handle

    m_Handle = CreateFile(deviceName, 
                         (GENERIC_READ | GENERIC_WRITE), 
                         0, 
                         NULL, 
                         OPEN_EXISTING, 
                         FILE_FLAG_OVERLAPPED, 
                         NULL);

Requisitos

Requisito	Valor
fim do suporte	Indisponível no UMDF 2.0 e posterior.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.5
cabeçalho	wudfddi.h (inclua Wudfddi.h)
de DLL	WUDFx.dll

Consulte também

IWDFDevice

Compartilhar via