(dbgeng.h) IDebugControl：：ControlledOutput 方法

發行項
02/25/2024

ControlledOutput 方法會格式化字串，並將結果傳送至向某些引擎用戶端註冊的輸出回呼。

語法

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

參數

[in] OutputControl

指定輸出控件，決定哪些客戶端的輸出回呼將接收輸出。如需可能的值，請參閱 DEBUG_OUTCTL_XXX。如需輸出的詳細資訊，請參閱輸入和輸出。

[in] Mask

指定輸出類型位欄位。如需可能的值，請參閱DEBUG_OUTPUT_XXX 。

[in] Format

指定格式字串，如 printf 所示。一般而言，轉換字元的運作方式與 C 相同。如果是浮點轉換字元，除非使用 l 修飾詞，否則 64 位自變數會解譯為 32 位浮點數。

支援 %p 轉換字元，但它代表目標地址空間中的指標。它可能沒有任何修飾詞，而且會使用調試程式的內部位址格式。支援下列其他轉換字元。

字元	引數類型	引數	列印的文字
%p	ULONG64	地址空間中的指標。	指標的值。
%N	視主機的架構而定，DWORD_PTR (32 或 64 位)	主機虛擬位址空間中的指標。	指標的值。 (這相當於標準 C %p 字元。)
%I	ULONG64	任何 64 位值。	指定值。如果此值大於 0xFFFFFFFF，則會列印為64位值;否則，它會列印為32位值。
%ma	ULONG64	進程虛擬位址空間中 NULL 終止的 ASCII 字串位址。	指定的字串。
%mu	ULONG64	進程虛擬位址空間中 NULL 終止的 Unicode 字串位址。	指定的字串。
%msa	ULONG64	進程虛擬位址空間中ANSI_STRING結構的位址。	指定的字串。
%msu	ULONG64	進程虛擬位址空間中UNICODE_STRING結構的位址。	指定的字串。
%y	ULONG64	具有符號資訊之專案之進程虛擬位址空間中的位址。	包含指定符號名稱的字串，如果有任何) ，則為 (和位移。
%ly	ULONG64	具有符號資訊之專案之進程虛擬位址空間中的位址。	包含指定符號名稱的字串，如果有任何) ，以及任何可用的源行資訊，則為 (和位移。

%Y 格式規範可用來支援調試程式標記語言 (DML) 。如需詳細資訊，請參閱使用 DML 自定義調試程序輸出。

下表摘要說明 %Y 格式規範的使用方式。

字元	引數類型	引數	列印的文字
%Y{t}	String	文字	括號中的字串。如果輸出格式 (第一個自變數) 為 DML，則會將文字轉換成 DML。
%Y{T}	String	文字	括號中的字串。不論輸出格式為何，一律會將文字轉換成 DML。
%Y{s}	String	文字	未加上批註的字串。如果輸出格式 (第一個自變數) 為 DML，則會將文字轉換成 DML。
%Y{S}	String	文字	未加上批註的字串。不論輸出格式為何，一律會將文字轉換成 DML。
%Y{as}	ULONG64	調試程式格式化指標	加入空字串或 9 個字元的間距，以填補調試程式格式化指標欄位的高 32 位部分。額外的空格會輸出 9 個空格，其中包含前 8 個零加上 ' 字元。
%Y{ps}	ULONG64	調試程式格式化指標	加入空字串或 8 個字元的間距，以填補調試程式格式化指標欄位的高 32 位部分。
%Y{l}	ULONG64	調試程式格式化指標	位址做為源行資訊。

此代碼段說明如何使用 %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;

}

此範例程式代碼會產生下列輸出。

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]

...

指定其他參數，這些參數表示格式化期間要插入輸出中的值。