Método IDebugControl::ControlledOutput (dbgeng.h)

Artigo
02/26/2024

O método ControlledOutput formata uma cadeia de caracteres e envia o resultado para retornos de chamada de saída que foram registrados com alguns dos clientes do mecanismo.

Sintaxe

HRESULT ControlledOutput(
  [in] ULONG OutputControl,
  [in] ULONG Mask,
  [in] PCSTR Format,
       ...   
);

Parâmetros

[in] OutputControl

Especifica um controle de saída que determina quais dos retornos de chamada de saída dos clientes receberão a saída. Para obter valores possíveis, consulte DEBUG_OUTCTL_XXX. Para obter mais informações sobre saída, consulte Entrada e Saída.

[in] Mask

Especifica o campo de bits do tipo saída. Consulte DEBUG_OUTPUT_XXX para obter valores possíveis.

[in] Format

Especifica a cadeia de caracteres de formato, como em printf. Normalmente, os caracteres de conversão funcionam exatamente como em C. Para os caracteres de conversão de ponto flutuante, o argumento de 64 bits é interpretado como um número de ponto flutuante de 32 bits, a menos que o modificador l seja usado.

Há suporte para o caractere de conversão %p , mas representa um ponteiro no espaço de endereço de um destino. Ele pode não ter modificadores e usa a formatação de endereço interno do depurador. Há suporte para os seguintes caracteres de conversão adicionais.

Caractere	Tipo de argumento	Argumento	Texto impresso
%p	ULONG64	Ponteiro em um espaço de endereço.	O valor do ponteiro.
%N	DWORD_PTR (32 ou 64 bits, dependendo da arquitetura do host)	Ponteiro no espaço de endereço virtual do host.	O valor do ponteiro. (Isso é equivalente ao caractere C %p padrão.)
%I	ULONG64	Qualquer valor de 64 bits.	O valor especificado. Se for maior que 0xFFFFFFFF, ele será impresso como um valor de 64 bits; caso contrário, ele será impresso como um valor de 32 bits.
%ma	ULONG64	Endereço de uma cadeia de caracteres ASCII terminada em NULL no espaço de endereço virtual do processo.	A cadeia de caracteres especificada.
%mu	ULONG64	Endereço de uma cadeia de caracteres Unicode terminada em NULL no espaço de endereço virtual do processo.	A cadeia de caracteres especificada.
%msa	ULONG64	Endereço de uma estrutura ANSI_STRING no espaço de endereço virtual do processo.	A cadeia de caracteres especificada.
%msu	ULONG64	Endereço de uma estrutura UNICODE_STRING no espaço de endereço virtual do processo.	A cadeia de caracteres especificada.
%y	ULONG64	Endereço no espaço de endereço virtual do processo de um item com informações de símbolo.	Cadeia de caracteres que contém o nome do símbolo especificado (e deslocamento, se houver).
%ly	ULONG64	Endereço no espaço de endereço virtual do processo de um item com informações de símbolo.	Cadeia de caracteres que contém o nome do símbolo especificado (e deslocamento, se houver), bem como qualquer informação de linha de origem disponível.

O especificador de formato %Y pode ser usado para dar suporte à DML (Linguagem de Marcação do Depurador). Para obter mais informações, consulte Personalizando a saída do depurador usando DML.

A tabela a seguir resume o uso do especificador de formato %Y.

Caractere	Tipo de argumento	Argumento	Texto impresso
%Y{t}	String	Texto	Cadeia de caracteres entre aspas. Converterá texto em DML se o formato de saída (primeiro arg) for DML.
%Y{T}	String	Texto	Cadeia de caracteres entre aspas. Sempre converterá texto em DML, independentemente do formato de saída.
%Y{s}	String	Texto	Cadeia de caracteres sem aspas. Converterá texto em DML se o formato de saída (primeiro arg) for DML.
%Y{S}	String	Texto	Cadeia de caracteres sem aspas. Sempre converterá texto em DML, independentemente do formato de saída.
%Y{as}	ULONG64	Ponteiro formatado do depurador	Adiciona uma cadeia de caracteres vazia ou 9 caracteres de espaçamento para preencher a parte alta de 32 bits dos campos de ponteiro formatados do depurador. O espaço extra gera 9 espaços que incluem os 8 zeros superiores mais o caractere .
%Y{ps}	ULONG64	Ponteiro formatado do depurador	Adiciona uma cadeia de caracteres vazia ou 8 caracteres de espaçamento para preencher a parte alta de 32 bits dos campos de ponteiro formatados do depurador.
%Y{l}	ULONG64	Ponteiro formatado do depurador	Endereço como informações de linha de origem.

Este snippet de código ilustra o uso do especificador de formato %Y.

HRESULT CALLBACK testout(_In_ PDEBUG_CLIENT pClient, _In_ PCWSTR /*pwszArgs*/)
{
    HRESULT hr = S_OK;

    ComPtr<IDebugControl4> spControl;
    IfFailedReturn(pClient->QueryInterface(IID_PPV_ARGS(&spControl)));

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{t}: %Y{t}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{T}: %Y{T}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{s}: %Y{s}\n", L"Hello <World>");
    spControl->ControlledOutputWide(0, DEBUG_OUTPUT_NORMAL, L"TEXT/NORMAL Y{S}: %Y{S}\n", L"Hello <World>");

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{a}: %Y{a}\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 64bit   : '%Y{as}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{as} 32value : '%Y{as}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 64bit   : '%Y{ps}'\n", (ULONG64)0x00007ffa7da163c0);
    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{ps} 32value : '%Y{ps}'\n", (ULONG64)0x1);

    spControl->ControlledOutputWide(DEBUG_OUTCTL_DML, DEBUG_OUTPUT_NORMAL, L"DML/NORMAL Y{l}: %Y{l}\n", (ULONG64)0x00007ffa7da163c0);

    return hr;

}

Esse código de exemplo geraria a saída a seguir.

0:004> !testout
DML/NORMAL Y{t}: "Hello <World>"
DML/NORMAL Y{T}: "Hello <World>"
DML/NORMAL Y{s}: Hello <World>
DML/NORMAL Y{S}: Hello <World>
TEXT/NORMAL Y{t}: "Hello <World>"
TEXT/NORMAL Y{T}: &quot;Hello <World>&quot;
TEXT/NORMAL Y{s}: Hello <World>
TEXT/NORMAL Y{S}: Hello <World>
DML/NORMAL Y{a}: 00007ffa`7da163c0
DML/NORMAL Y{as} 64bit   : '         '
DML/NORMAL Y{as} 32value : '         '
DML/NORMAL Y{ps} 64bit   : '        '
DML/NORMAL Y{ps} 32value : '        '
DML/NORMAL Y{l}: [d:\th\minkernel\kernelbase\debug.c @ 443]

...

Especifica parâmetros adicionais que representam valores a serem inseridos na saída durante a formatação.

Retornar valor

Esse método também pode retornar valores de erro. Consulte Valores retornados para obter mais detalhes.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.

Comentários

Ao gerar cadeias de caracteres de saída muito grandes, é possível atingir os limites do mecanismo de depurador ou do sistema operacional. Por exemplo, algumas versões do mecanismo de depurador têm um limite de caracteres de 16K para uma única saída. Se você achar que a saída muito grande está sendo truncada, talvez seja necessário dividir a saída em várias solicitações.