訊息文字檔
訊息定義於訊息文本檔中。 訊息編譯程式會將數位指派給每個訊息,併產生 C/C++包含檔案,應用程式可用來使用符號常數存取訊息。
訊息文本檔中語句的一般語法如下:
關鍵詞=值
忽略等號周圍的空格,且值會以空格符分隔,而下一個關鍵詞/值組中的空格符(包括換行符)。 比較關鍵詞名稱時,會忽略大小寫。 值 部分可以是使用 C/C++ 語法的數值整數常數、遵循 C/C++ 識別符規則的符號名稱,或是不含句點的檔名。
如需範例訊息檔,請參閱 範例訊息文字檔。
評論
訊息文字文件中允許批注行。 分號 (;)開始批注,結尾為行尾。 遵循分號搭配 C/C++單行批注指標 (--),讓訊息編譯程式所產生的頭檔會在您的應用程式中編譯。
;// This is a single-line comment.
對於區塊批注,請以分號開始每一行,然後在第一行的分號後面放置 C/C++開啟區塊批註指標 (/*),並在最後一行的分號後面放置關閉區塊批注指標 (*/)。
;/* This is a block comment.
; It spans multiple lines.
;*/
標頭區段
訊息文本檔包含一個標頭,可定義名稱與語言標識符,以供檔案本文中的訊息定義使用。 標頭包含下列語句的零個或多個 。
語句語法 | 描述 |
---|---|
MessageIdTypedef=類型 | 在訊息定義中使用的類型,如下所示:#define 名稱(類型)0xnnnnnnnn) 類型必須夠大,才能容納整個訊息碼,例如 DWORD。 這個類型也可以是應用程式原始碼中定義的類型。 類型 的預設值是空的,因此不會使用類型轉換。 此語句可以在標頭中指定,而且訊息定義區段中會視需要指定。 |
SeverityNames=(name=number[:name]) | 訊息定義中允許嚴重性的名稱集。 與每個嚴重性名稱相關聯的數位是一個數位,當向左移 30 位時,會使用設備與訊息標識碼,將位模式提供給邏輯 OR,以形成訊息碼。 不符合 2 位的任何嚴重性值都是錯誤。 嚴重性代碼也可以指定符號名稱。默認值的定義如下:SeverityNames=( Success=0x0 Informational=0x1 Warning=0x2 Error=0x3) |
FacilityNames=(name=number[:name]) | 訊息定義中設備值允許的名稱集。 與每個設施名稱相關聯的數位,當向左移 16 位時,會將位模式提供給具有嚴重性和訊息標識碼值的邏輯 OR,以形成訊息碼。 不符合12位的任何設備值都是錯誤。 這允許 4096 設施代碼;前 256 個代碼會保留給系統使用。 設施代碼也可以指定符號名稱。預設值的定義如下:FacilityNames=(System=0x0FF Application=0xFFF) |
LanguageNames=(name=number:filename) | 訊息定義中語言值允許的名稱集。 此數位會作為資源數據表中的語言標識碼。 指定的檔案包含該語言的訊息。 它通常是訊息編譯程式所產生的.bin檔案。 範例值為:LanguageNames=(English=0x409:MSG00409) 如需語言識別碼的清單,請參閱 https://go.microsoft.com/fwlink/p/?linkid=190280。 |
OutputBase=數位 | 訊息編譯程式寫入頭檔之訊息常數的輸出基數。 如果存在,這個值會覆寫 -d 參數。 這個數位可以是 10 (十進位) 或 16 (十六進位)。 |
訊息定義
訊息文本檔包含標頭區段後面的零個或多個訊息定義。 下表描述訊息定義語句。 MessageId 語句會標示訊息定義的開頭。 [嚴重性] 和 [設施] 語句是選擇性的。
語句語法 | 描述 |
---|---|
MessageId=[number|+number] | 訊息的標識碼。 雖然這個值是選擇性的,但這是必要語句。 如果未指定任何值,則所使用的值會是設施的先前值,加上一個。 如果使用加號指定值,則所使用的值會是設施的先前值,加上加號之後的數位。 任何指定的值都必須符合16位。如需如何從嚴重性、設施及訊息標識符形成訊息值的詳細資訊,請參閱 Winerror.h 中的圖表。 此頭檔會定義系統的錯誤碼。 |
嚴重性=名稱 | 標頭中 SeverityNames 所指定的其中一個值。 這個語句是選擇性的。 如果未指定任何值,則所使用的值是訊息定義最後指定的值。 第一個訊息定義的預設值為 Severity=Success |
設備=名稱 | 標頭中 FacilityNames 所指定的其中一個值。 這個語句是選擇性的。 如果未指定任何值,則所使用的值是訊息定義最後指定的值。 第一個訊息定義的預設值為 Facility=Application |
SymbolicName=名稱 | 將 C/C++符號常數與訊息碼產生關聯。 它用於訊息定義,如下所示:#define 名稱 ((類型)0xnnnnnnnn) |
OutputBase={number} | 訊息編譯程式寫入頭檔之訊息常數的輸出基數。 如果存在,這個值會覆寫 -d 參數。 這個數位可以是 10 (十進位) 或 16 (十六進位)。 |
Language=名稱 | 標頭中 LanguageNames 所指定的其中一個值。 這個語句是選擇性的。 如果未指定任何值,則所使用的值是訊息定義最後指定的值。 第一個訊息定義的預設值如下:Language=English |
消息正文 | 訊息的文字。 它包含在訊息二進位檔中。 它也會包含在直接在訊息定義前面的批注區塊頭檔中。 |
. | 消息正文會由新行終止,該行的開頭包含單一句號。 |
如果訊息定義包含多個語言的訊息文字,則每個語言都需要自己的 Language 語句、消息正文,以及以句號終止新行。 例如:
MessageId=0x1
Severity=Error
Facility=Runtime
SymbolicName=MSG_BAD_COMMAND
Language=English
You have chosen an incorrect command.
.
Language=Japanese
<Japanese message string goes here>
.
您可以指定下列逸出序列來格式化事件查看器或應用程式所使用的消息正文。 百分比符號字元 (%) 會開始所有逸出序列。 在百分比符號之後的任何其他字元都會顯示,而不會顯示百分比符號。
-
% n[!format_specifier!]
-
描述插入。 每個插入都是 FormatMessage 函式中 Arguments 陣列中的專案。 n 的值可以是介於 1 到 99 之間的數位。 格式規範是選擇性的。 如果未指定任何值,則預設值為 !s!。 如需格式規範的相關信息,請參閱 wsprintf。
格式規範可以使用 * 來表示有效位數或寬度。 指定時,它們會取用 以 n+1 和 n n+2 編號的插入。
-
%0
-
終止消息正文行,而不使用尾端換行符。 這可以用來建置長行或終止提示訊息,而不需尾端換行符。
-
%。
-
產生單一期間。 這可以用來在行開頭顯示句點,否則會終止消息正文。
-
%!
-
產生單一驚嘆號。 這可用來在插入后立即指定驚嘆號。
-
%%
-
產生單一百分比符號。
-
%n
-
在行尾發生時,產生硬式換行符。 這可以搭配 FormatMessage 使用,以確保訊息符合特定寬度。
-
%b
-
產生空格符。 這可以用來確保一行上適當的尾端空格數目。
-
%r
-
產生不帶尾端換行符的硬式歸位字元。