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 且 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