Método IDebugControl3::ControlledOutputVaList (dbgeng.h)

Artículo
02/26/2024

El método ControlledOutputVaList da formato a una cadena y envía el resultado a las devoluciones de llamada de salida registradas con algunos de los clientes del motor.

Sintaxis

HRESULT ControlledOutputVaList(
  [in] ULONG   OutputControl,
  [in] ULONG   Mask,
  [in] PCSTR   Format,
  [in] va_list Args
);

Parámetros

[in] OutputControl

Especifica un control de salida que determina las devoluciones de llamada de salida del cliente que recibirán la salida. Para conocer los valores posibles, consulte DEBUG_OUTCTL_XXX. Para obtener más información sobre la salida, consulte Entrada y salida.

[in] Mask

Especifica el campo de bits de tipo de salida. Consulte DEBUG_OUTPUT_XXX para conocer los valores posibles.

[in] Format

Especifica la cadena de formato, como en printf. Normalmente, los caracteres de conversión funcionan exactamente igual que en C. Para los caracteres de conversión de punto flotante, el argumento de 64 bits se interpreta como un número de punto flotante de 32 bits a menos que se use el modificador l .

Se admite el carácter de conversión %p , pero representa un puntero en el espacio de direcciones de un destino. Es posible que no tenga ningún modificador y use el formato de dirección interna del depurador. Se admiten los siguientes caracteres de conversión adicionales.

Carácter	Tipo de argumento	Argumento	Texto impreso
%p	ULONG64	Puntero en un espacio de direcciones.	Valor del puntero.
%N	DWORD_PTR (32 o 64 bits, según la arquitectura del host)	Puntero en el espacio de direcciones virtuales del host.	Valor del puntero. (Esto equivale al carácter C %p estándar).
%I	ULONG64	Cualquier valor de 64 bits.	Valor especificado. Si es mayor que 0xFFFFFFFF, se imprime como un valor de 64 bits; de lo contrario, se imprime como un valor de 32 bits.
%ma	ULONG64	Dirección de una cadena ASCII terminada en NULL en el espacio de direcciones virtuales del proceso.	Cadena especificada.
%mu	ULONG64	Dirección de una cadena Unicode terminada en NULL en el espacio de direcciones virtuales del proceso.	Cadena especificada.
%msa	ULONG64	Dirección de una estructura de ANSI_STRING en el espacio de direcciones virtuales del proceso.	Cadena especificada.
%msu	ULONG64	Dirección de una estructura de UNICODE_STRING en el espacio de direcciones virtuales del proceso.	Cadena especificada.
%y	ULONG64	Dirección en el espacio de direcciones virtuales del proceso de un elemento con información de símbolos.	Cadena que contiene el nombre del símbolo especificado (y desplazamiento, si existe).
%ly	ULONG64	Dirección en el espacio de direcciones virtuales del proceso de un elemento con información de símbolos.	Cadena que contiene el nombre del símbolo especificado (y desplazamiento, si existe), así como cualquier información de línea de origen disponible.

El especificador de formato %Y se puede usar para admitir el lenguaje de marcado del depurador (DML). Para obtener más información, consulte Personalización de la salida del depurador mediante DML.

En la tabla siguiente se resume el uso del especificador de formato %Y.

Carácter	Tipo de argumento	Argumento	Texto impreso
%Y{t}	String	Texto	Cadena entrecomillada. Convertirá texto a DML si el formato de salida (primer argumento) es DML.
%Y{T}	String	Texto	Cadena entrecomillada. Siempre convertirá texto a DML independientemente del formato de salida.
%Y{s}	String	Texto	Cadena sin comilla. Convertirá texto a DML si el formato de salida (primer argumento) es DML.
%Y{S}	String	Texto	Cadena sin comilla. Siempre convertirá texto a DML independientemente del formato de salida.
%Y{as}	ULONG64	Puntero con formato de depurador	Agrega una cadena vacía o 9 caracteres de espaciado para rellenar la parte de 32 bits alta de los campos de puntero con formato de depurador. El espacio adicional genera 9 espacios que incluyen los 8 ceros superiores más el carácter ' .
%Y{ps}	ULONG64	Puntero con formato de depurador	Agrega una cadena vacía o 8 caracteres de espaciado para rellenar la parte de 32 bits alta de los campos de puntero con formato de depurador.
%Y{l}	ULONG64	Puntero con formato de depurador	Dirección como información de línea de origen.

Este fragmento de código muestra el uso del 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;

}

Este código de ejemplo generaría la siguiente salida.

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]

[in] Args

Especifica parámetros adicionales que representan valores que se van a insertar en la salida durante el formato. Los argumentos se deben inicializar mediante va_start. Este método no llama a va_end.

Valor devuelto

Código devuelto	Descripción
S_OK	Método realizado correctamente.

Este método también puede devolver valores de error. Consulte Valores devueltos para obtener más detalles.

Comentarios

Al generar cadenas de salida muy grandes, es posible alcanzar los límites del motor del depurador o del sistema operativo. Por ejemplo, algunas versiones del motor del depurador tienen un límite de 16 000 caracteres para una única salida. Si observa que la salida muy grande se está truncando, es posible que tenga que dividir la salida en varias solicitudes.

Las macros va_list, va_start y va_end se definen en Stdarg.h.