Função vDbgPrintExWithPrefix (wdm.h)
A rotina vDbgPrintExWithPrefix envia uma cadeia de caracteres para o depurador de kernel se determinadas condições especificadas forem atendidas. Essa rotina pode acrescentar um prefixo à saída do depurador para ajudar a organizar os resultados da depuração.
Sintaxe
NTSYSAPI ULONG vDbgPrintExWithPrefix(
[in] PCCH Prefix,
[in] ULONG ComponentId,
[in] ULONG Level,
[in] PCCH Format,
[in] va_list arglist
);
Parâmetros
[in] Prefix
Uma cadeia de caracteres que é acrescentada no início da saída do depurador. Você pode usar essa cadeia de caracteres para organizar a saída do depurador adicionando um identificador exclusivo.
Por exemplo, uma rotina específica do componente pode especificar o nome do componente ao chamar vDbgPrintExWithPrefix. Essa rotina adicionaria automaticamente o nome do componente ao início de toda a saída de depuração passada para a rotina de impressão de depuração do componente.
[in] ComponentId
O componente que está chamando essa rotina. Esse parâmetro deve ser uma das IDs de filtro de nome do componente definidas em Dpfilter.h. Para evitar misturar a saída do driver com a saída dos componentes do Windows, você deve usar apenas os seguintes valores para ComponentId:
- DPFLTR_IHVVIDEO_ID
- DPFLTR_IHVAUDIO_ID
- DPFLTR_IHVNETWORK_ID
- DPFLTR_IHVSTREAMING_ID
- DPFLTR_IHVBUS_ID
- DPFLTR_IHVDRIVER_ID
[in] Level
A gravidade da mensagem que está sendo enviada. Esse parâmetro pode ser qualquer inteiro de 32 bits. Os valores entre 0 e 31 (inclusivo) são tratados de forma diferente dos valores entre 32 e 0xFFFFFFFF. Para obter mais informações sobre como os valores são tratados, consulte Leitura e filtragem de mensagens de depuração.
[in] Format
Um ponteiro para a cadeia de caracteres de formato a ser impressa. A cadeia de caracteres Format dá suporte à maioria dos códigos de formatação no estilo printf. No entanto, você pode usar os códigos de formato Unicode (%C, %S, %lc, %ls, %wc, %ws e %wZ) somente com IRQL = PASSIVE_LEVEL. A rotina vDbgPrintExWithPrefix não dá suporte a nenhum dos tipos de ponto flutuante (%f, %e, %E, %g, %G, %a ou %A).
[in] arglist
Uma lista de argumentos para a cadeia de caracteres de formato. A rotina vDbgPrintExWithPrefix usa essa lista da mesma forma que vprintf .
Retornar valor
vDbgPrintExWithPrefix retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, essa rotina retornará o código de erro apropriado.
Comentários
Somente drivers de modo kernel podem chamar a rotina vDbgPrintExWithPrefix .
vDbgPrintExWithPrefix pode ser chamado em IRQL <= DIRQL. No entanto, você pode usar códigos de formato Unicode (%wc e %ws) somente em IRQL = PASSIVE_LEVEL. Além disso, como o depurador usa IPIs (interrupções entre processos) para se comunicar com outros processadores, uma chamada para vDbgPrintExWithPrefix no IRQL > DIRQL pode causar deadlocks.
vDbgPrintExWithPrefix passa a cadeia de caracteres que ele cria para o depurador de kernel ou não faz nada, dependendo dos valores de ComponentId, Level e as máscaras de filtro de componente correspondentes. Para obter mais informações sobre o que o vDbgPrintEx faz, consulte Leitura e filtragem de mensagens de depuração.
A menos que seja absolutamente necessário, você não deve obter uma cadeia de caracteres da entrada do usuário ou de outro processo e passá-la para vDbgPrintExWithPrefix. Se você usar uma cadeia de caracteres que não criou, deverá verificar se essa cadeia de caracteres é uma cadeia de caracteres de formato válida e se os códigos de formato correspondem à lista de argumentos no tipo e na quantidade. A melhor prática de codificação é que todas as cadeias de caracteres de formato sejam estáticas e definidas em tempo de compilação.
Não há limite superior para o tamanho da cadeia de caracteres Format ou o número de argumentos na lista arglist . No entanto, qualquer chamada única para vDbgPrintExWithPrefix transmite apenas 512 bytes de informações.
Também há um limite para o tamanho do buffer que o depurador usa. Para obter mais informações sobre esse limite, consulte O Buffer DbgPrint e o Depurador.
Essa rotina é definida em Wdm.h. As IDs de filtro de componente são definidas em Dpfilter.h.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Microsoft Windows XP e versões posteriores do sistema operacional. |
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (inclua Dpfilter.h, Wdm.h, Ntddk.h, Ndis.h) |
| Biblioteca | NtDll.lib (modo de usuário); NtosKrnl.lib (modo kernel) |
| DLL | NtDll.dll (modo de usuário); NtosKrnl.exe (modo kernel) |
| IRQL | <= DIRQL (consulte a seção Comentários) |