Metodo IWDFDevice::RetrieveDeviceName (wudfddi.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedi Introduzione a UMDF.]

Il metodo RetrieveDeviceName recupera il nome di un dispositivo in modalità kernel sottostante.

Sintassi

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Parametri

[out] pDeviceName

Puntatore a un buffer che riceve un NULLstringa con terminazione che rappresenta il nome del dispositivo in modalità kernel sottostante, se il buffer non è NULL e RetrieveDeviceName ha esito positivo.

[in, out] pdwDeviceNameLength

Puntatore a una variabile che riceve il numero di caratteri, incluso il carattere NULL, nel nome del dispositivo.

Se il buffer in corrispondenza pDeviceName è NULL, il valore fornito dal driver è zero. Il framework restituisce quindi le dimensioni, in caratteri, necessarie per la stringa del nome del dispositivo.

Se il buffer in corrispondenza pDeviceName non èNULL, il framework restituisce le dimensioni, in caratteri, della stringa del nome del dispositivo.

Valore restituito

RetrieveDeviceName restituisce S_OK per gli scenari seguenti:

Il buffer a cui punta il parametro pDeviceName non era NULL e sufficientemente grande da contenere la stringa del nome, incluso il carattere NULL e il framework ha copiato correttamente la stringa nel buffer fornito e impostare la variabile a cui punta pdwDeviceNameLength al numero di caratteri nella stringa.
Il buffer in corrispondenza pDeviceName è stato NULL, il driver imposta la variabile in pdwDeviceNameLength su 0 e il framework imposta la variabile in pdwDeviceNameLength sul numero di caratteri necessari per la stringa.

RetrieveDeviceName restituisce HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) per indicare che il buffer fornito non era NULL e non contiene spazio sufficiente per contenere il nome del dispositivo. Il framework imposta la variabile in pdwDeviceNameLength sul numero di caratteri necessari per la stringa.

RetrieveDeviceName potrebbe restituire anche altri valori HRESULT.

Osservazioni

Il nome del dispositivo non è il nome dell'oggetto dispositivo fisico (PDO). Il nome del dispositivo è invece il nome del riflettore. Il driver deve avere come destinazione tutti gli I/O a questo oggetto dispositivo.

Esempi

L'esempio di codice seguente illustra come recuperare il nome di un dispositivo in modalità kernel sottostante.

    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);

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.5
intestazione	wudfddi.h (include Wudfddi.h)
dll	WUDFx.dll

Vedere anche

IWDFDevice

Condividi tramite