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

[Предупреждение: 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 , в имени устройства.

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

Если буфер в 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);

Требования

См. также раздел

IWDFDevice