Метод IWDFDevice::RetrieveDeviceName (wudfddi.h)

Статья
02/07/2025

[ предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе Начало работы с UMDF.]

Метод RetrieveDeviceName извлекает имя базового устройства в режиме ядра.

Синтаксис

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

Параметры

[out] pDeviceName

Указатель на буфер, получающий NULL-завершенной строкой, представляющей имя базового устройства в режиме ядра, если буфер не являетсяNULL и RetrieveDeviceName выполнен успешно.

[in, out] pdwDeviceNameLength

Указатель на переменную, которая получает количество символов, включая символы, значение NULL в имени устройства.

Если буфер по адресу pDeviceNameNULL, значение, которое предоставляет драйвер, равно нулю. Затем платформа возвращает размер в символах, необходимых для строки имени устройства.

Если буфер в pDeviceName неNULL, платформа возвращает размер строки имени устройства в символах.

Возвращаемое значение

RetrieveDeviceName возвращает S_OK для следующих сценариев:

Буфер, на который указывает параметр pDeviceName, неNULL и достаточно большой для хранения строки имени, включая символ NULL, и платформа успешно скопировала строку в предоставленный буфер и задайте переменную, на которую указывает pdwDeviceNameLength число символов в строке.
Буфер в pDeviceName был NULL, драйвер предустановил переменную в pdwDeviceNameLength значение 0, а платформа установила переменную в pdwDeviceNameLength число символов, необходимых для строки.

RetrieveDeviceName возвращает HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), чтобы указать, что предоставленный буфер не былNULL и не содержал достаточно места для хранения имени устройства. Платформа задает переменную в pdwDeviceNameLength число символов, необходимых для строки.

RetrieveDeviceName также может возвращать другие значения HRESULT.

Замечания

Имя устройства не является именем физического объекта устройства (PDO). Вместо этого имя устройства — это имя отражателя. Драйвер должен нацелить все ввода-вывода на этот объект устройства.

Примеры

В следующем примере кода показано, как получить имя базового устройства в режиме ядра.

    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);

Требования

Требование	Ценность
завершение поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
целевая платформа	Настольный
минимальная версия UMDF	1.5
заголовка	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

См. также

IWDFDevice

Поделиться через