Funzione vDbgPrintExWithPrefix (wdm.h)

Articolo
02/29/2024

La routine vDbgPrintExWithPrefix invia una stringa al debugger del kernel se vengono soddisfatte determinate condizioni specificate. Questa routine può aggiungere un prefisso all'output del debugger per organizzare i risultati del debug.

Sintassi

NTSYSAPI ULONG vDbgPrintExWithPrefix(
  [in] PCCH    Prefix,
  [in] ULONG   ComponentId,
  [in] ULONG   Level,
  [in] PCCH    Format,
  [in] va_list arglist
);

Parametri

[in] Prefix

Stringa aggiunta all'inizio dell'output del debugger. È possibile usare questa stringa per organizzare l'output del debugger aggiungendo un identificatore univoco.

Ad esempio, una routine specifica del componente può specificare il nome del componente quando chiama vDbgPrintExWithPrefix. Questa routine aggiunge automaticamente il nome del componente all'inizio di tutto l'output di debug passato alla routine di stampa di debug del componente.

[in] ComponentId

Componente che chiama questa routine. Questo parametro deve essere uno degli ID filtro dei nomi del componente definiti in Dpfilter.h. Per evitare di combinare l'output del driver con l'output dei componenti di Windows, è consigliabile usare solo i valori seguenti per ComponentId:

DPFLTR_IHVVIDEO_ID
DPFLTR_IHVAUDIO_ID
DPFLTR_IHVNETWORK_ID
DPFLTR_IHVSTREAMING_ID
DPFLTR_IHVBUS_ID
DPFLTR_IHVDRIVER_ID

[in] Level

Gravità del messaggio inviato. Questo parametro può essere qualsiasi intero a 32 bit. I valori compresi tra 0 e 31 (inclusi) vengono trattati in modo diverso rispetto ai valori compresi tra 32 e 0xFFFFFFFF. Per altre informazioni sulla modalità di gestione dei valori, vedere Lettura e filtro dei messaggi di debug.

[in] Format

Puntatore alla stringa di formato da stampare. La stringa formato supporta la maggior parte dei codici di formattazione in stile printf. Tuttavia, è possibile usare i codici di formato Unicode (%C, %S, %lc, %ls, %wc, %ws e %wZ) solo con IRQL = PASSIVE_LEVEL. La routine vDbgPrintExWithPrefix non supporta alcun tipo a virgola mobile (%f, %e, %E, %g, %G, %a o %A).

[in] arglist

Elenco di argomenti per la stringa di formato. La routine vDbgPrintExWithPrefix usa questo elenco nello stesso modo in cui vprintf esegue.

Valore restituito

vDbgPrintExWithPrefix restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questa routine restituisce il codice di errore appropriato.

Commenti

Solo i driver in modalità kernel possono chiamare la routine vDbgPrintExWithPrefix .

vDbgPrintExWithPrefix può essere chiamato in IRQL <= DIRQL. Tuttavia, è possibile usare codici di formato Unicode (%wc e %ws) solo in IRQL = PASSIVE_LEVEL. Inoltre, poiché il debugger usa interrupt interprocessi (IPI) per comunicare con altri processori, una chiamata a vDbgPrintExWithPrefix in IRQL > DIRQL può causare deadlock.

vDbgPrintExWithPrefix passa la stringa creata al debugger del kernel o non esegue alcuna operazione, a seconda dei valori di ComponentId, Level e delle maschere di filtro dei componenti corrispondenti. Per altre informazioni sulle operazioni di vDbgPrintEx , vedere Lettura e filtro dei messaggi di debug.

A meno che non sia assolutamente necessario, non è consigliabile ottenere una stringa dall'input dell'utente o da un altro processo e passarla a vDbgPrintExWithPrefix. Se si usa una stringa che non è stata creata, è necessario verificare che questa stringa sia una stringa di formato valida e che i codici di formato corrispondano all'elenco di argomenti di tipo e quantità. La procedura consigliata per la codifica è che tutte le stringhe di formato siano statiche e definite in fase di compilazione.

Non esiste alcun limite massimo per le dimensioni della stringa Format o il numero di argomenti nell'elenco arglist . Tuttavia, qualsiasi singola chiamata a vDbgPrintExWithPrefix trasmette solo 512 byte di informazioni.

Esiste anche un limite alla dimensione del buffer usata dal debugger. Per altre informazioni su questo limite, vedere Il buffer DbgPrint e il debugger.

Questa routine è definita in Wdm.h. Gli ID filtro dei componenti sono definiti in Dpfilter.h.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Microsoft Windows XP e versioni successive del sistema operativo.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Dpfilter.h, Wdm.h, Ntddk.h, Ndis.h)
Libreria	NtDll.lib (modalità utente); NtosKrnl.lib (modalità kernel)
DLL	NtDll.dll (modalità utente); NtosKrnl.exe (modalità kernel)
IRQL	<= DIRQL (vedere la sezione Commenti)

Vedi anche

DbgPrintEx

vDbgPrintEx

Condividi tramite