Funzione WdfPdoInitAddDeviceText (wdfpdo.h)

Articolo
02/27/2024

[Si applica solo a KMDF]

Il metodo WdfPdoInitAddDeviceText aggiunge una descrizione del dispositivo e la posizione del dispositivo a un dispositivo per le impostazioni locali specificate.

Sintassi

NTSTATUS WdfPdoInitAddDeviceText(
  [in] PWDFDEVICE_INIT  DeviceInit,
  [in] PCUNICODE_STRING DeviceDescription,
  [in] PCUNICODE_STRING DeviceLocation,
  [in] LCID             LocaleId
);

Parametri

[in] DeviceInit

Puntatore a una struttura WDFDEVICE_INIT .

[in] DeviceDescription

Puntatore a una struttura UNICODE_STRING che contiene una descrizione del dispositivo, formattata per le impostazioni locali specificate. Il driver può allocare il buffer della stringa dal pool di paging.

[in] DeviceLocation

Puntatore a una struttura UNICODE_STRING che contiene una descrizione della posizione del bus in cui il dispositivo padre ha trovato l'elemento figlio. Il driver può allocare il buffer della stringa dal pool di paging.

[in] LocaleId

Identificatore delle impostazioni locali (LCID) che rappresenta le impostazioni locali delle stringhe Unicode. Per altre informazioni, vedere Identificatori delle impostazioni locali.

Valore restituito

Se l'operazione ha esito positivo, il metodo restituisce STATUS_SUCCESS. I valori restituiti aggiuntivi includono:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Il driver sta inizializzando un fdO anziché un PDO.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare spazio al driver per archiviare le stringhe.

Il metodo potrebbe anche restituire altri valori NTSTATUS.

Commenti

Il framework archivia il testo del dispositivo specificato e lo passa al gestore PnP in risposta a una richiesta di IRP_MN_QUERY_DEVICE_TEXT . Il testo fornito dovrebbe aiutare l'utente a identificare il dispositivo. Il gestore PnP a volte visualizza il testo durante il tentativo di installare driver aggiuntivi per il dispositivo.

Puoi chiamare WdfPdoInitAddDeviceText più volte, aggiungendo testo del dispositivo per più impostazioni locali. Quando il sistema visualizza il testo, sceglie il testo corrispondente alle impostazioni locali correnti, se disponibile. In caso contrario, userà la stringa per le impostazioni locali predefinite. Il driver può specificare le impostazioni locali predefinite del driver chiamando WdfPdoInitSetDefaultLocale.

Il driver deve chiamare WdfPdoInitAddDeviceText prima di chiamare WdfDeviceCreate. Per altre informazioni sulla chiamata a WdfDeviceCreate, vedere Creazione di un oggetto dispositivo framework.

Esempio

L'esempio di codice seguente fornisce stringhe Unicode per la posizione e la descrizione di un dispositivo. La descrizione include un numero di istanza. Per un esempio completo che usa WdfPdoInitAddDeviceText, vedere il driver di esempio KbFiltr .

DECLARE_CONST_UNICODE_STRING(deviceLocation,L"Keyboard Filter\0" );
DECLARE_UNICODE_STRING_SIZE(buffer, MAX_ID_LEN);

status = RtlUnicodeStringPrintf(
                                &buffer,
                                L"Keyboard_Filter_%02d",
                                InstanceNo
                                );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}
status = WdfPdoInitAddDeviceText(
                                 pDeviceInit,
                                 &buffer,
                                 &deviceLocation,
                                 0x409
                                 );
if (!NT_SUCCESS(status)) {
    goto Cleanup;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfpdo.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	ChildDeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCallback(kmdf), InitFreeDeviceCreate(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCallback(kmdf), PdoInitFreeDeviceCreate(kmdf)

Vedi anche

WdfPdoInitSetDefaultLocale

Condividi tramite