Metodo IWDFDevice::RetrieveDeviceName (wudfddi.h)

Articolo
03/05/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta 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, vedere Introduzione con 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 una stringa con terminazione NULL 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 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 pDeviceName è diverso da 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 puntava il parametro pDeviceName era diverso da NULL e abbastanza grande per contenere la stringa del nome, incluso il carattere NULL e il framework copiava correttamente la stringa nel buffer fornito e imposta la variabile a cui punta pdwDeviceNameLength al numero di caratteri nella stringa.
Il buffer in pDeviceName è 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 era non 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.

Commenti

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

Esempio

Nell'esempio di codice seguente viene illustrato 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);

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Vedi anche

IWDFDevice

Condividi tramite