IWDFDevice：：RetrieveDeviceName 方法 (wudfddi.h)

[警告： UMDF 2 是最新版本的 UMDF，并取代 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 不会向 UMDF 1 添加任何新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 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) 名称 (物理设备对象。 相反，设备名称是反射器的名称。 驱动程序必须面向此设备对象的所有 I/O。

示例

下面的代码示例演示如何检索基础内核模式设备的名称。

    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 (包括 Wudfddi.h)
DLL	WUDFx.dll

另请参阅

IWDFDevice