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 成功，則為緩衝區的指標，這個字串會接收 NULL終止字串，代表基礎內核模式裝置的名稱。

[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，且未包含足夠的空間來保存裝置名稱。 架構會將位於 pdwDeviceNameLeng th 的變數設定為字串所需的字元數。

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