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