getStringTypeW 函式 (stringapiset.h)

發行項
03/02/2024

擷取指定 Unicode 來源字串中字元的字元類型資訊。針對字串中的每個字元，函式會在輸出數位的對應16位元素中設定一或多個位。每個位都會識別指定的字元類型，例如字母、數位或兩者皆未識別。

謹慎不正確使用 GetStringTypeW 函式可能會危害應用程式的安全性。若要避免緩衝區溢位，應用程式必須正確設定輸出緩衝區大小。如需詳細資訊，請參閱安全性考慮：Windows 用戶介面。

語法

BOOL GetStringTypeW(
  [in]  DWORD                         dwInfoType,
  [in]  _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]  int                           cchSrc,
  [out] LPWORD                        lpCharType
);

參數

[in] dwInfoType

指定要擷取之字元類型資訊的旗標。此參數可以有下列值。字元類型分成不同的層級，如一節中所述。

旗標	意義
CT_CTYPE1	擷取字元類型資訊。
CT_CTYPE2	擷取雙向配置資訊。
CT_CTYPE3	擷取文字處理資訊。

[in] lpSrcStr

要擷取字元類型的 Unicode 字串指標。如果 cchSrc 設定為任何負值，則字串假設為 null 終止。

[in] cchSrc

大小，以字元為單位，以 lpSrcStr 表示的字串。如果大小包含終止的 Null 字元，函式會擷取該字元的字元類型資訊。如果應用程式將大小設定為任何負整數，則來源字元串會假設為 Null 終止，且函式會自動計算大小，並針對 Null 終止使用額外的字元來計算大小。

[out] lpCharType

16 位值的陣列指標。這個陣列的長度必須夠大，才能接收來源字串中每個字元的一個16位值。如果 cchSrc 不是負數， lpCharType 應該是具有 cchSrc 元素的單字陣列。如果 cchSrc 設定為負數， lpCharType 是具有 lpSrcStr + 1 元素的單字數位。當函式傳回時，此陣列會包含一個對應至來源字串中每個字元的單字。

傳回值

如果成功，則傳回非零值，否則傳回 0。若要取得擴充的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：

ERROR_INVALID_FLAGS。為旗標的值無效。
ERROR_INVALID_PARAMETER。任何參數值都無效。

備註

如需使用字串函式的概觀，請參閱 Strings。

lpSrcStr 和 lpCharType 參數的值不得相同。如果兩者相同，函式會因為ERROR_INVALID_PARAMETER而失敗。

這個函式不會使用對應 GetStringTypeA 函式所使用的 Locale 參數。由於參數差異，應用程式無法透過使用 #define UNICODE 參數，自動叫用適當的 ANSI 或 Unicode 版本的 GetStringType* 函式。應用程式可以使用 GetStringTypeEx 來規避這項限制，這是建議的函式。

支援的字元類型

字元類型位分成數個層級。單一呼叫此函式可以擷取一個層級的資訊。每個層級限制為16位的資訊，讓其他對應函式，每個字元只能有16位的表示法，也可以傳回字元類型資訊。

Ctype 1

這些類型支援 ANSI C 和 POSIX (LC_CTYPE) 字元輸入函式。 當 dwInfoType 設定為 CT_CTYPE1 時，輸出緩衝區中的陣列中會擷取這些值的位 OR。針對 DBCS 地區設定，類型屬性會同時套用至窄字元和寬字元。日文平假名和片假名字符，以及漢字語意字元全都有C1_ALPHA屬性。

名稱	值	意義
C1_UPPER	0x0001	大寫
C1_LOWER	0x0002	小寫
C1_DIGIT	0x0004	十進位數字
C1_SPACE	0x0008	空格符
C1_PUNCT	0x0010	標點符號
C1_CNTRL	0x0020	控制字元
C1_BLANK	0x0040	空白字元
C1_XDIGIT	0x0080	十六進位數位
C1_ALPHA	0x0100	任何語言字元：字母、音節或語意
C1_DEFINED	0x0200	已定義的字元，但不是另一個C1_* 類型

下列字元類型是基本類型的常數或可計算，而且不需要由此函式支援。

類型	Description
英數字元	字母字元和數位 (C1_ALPHA 和C1_DIGIT)
可列印	圖形字元和空白 (除了C1_CNTRL) 以外的所有C1_* 類型

Ctype 2

這些類型支援正確配置 Unicode 文字。針對 DBCS 地區設定，字元類型同時適用於窄字元和寬字元。指派方向屬性，讓 Unicode 標準化的雙向配置演算法會產生精確的結果。這些類型互斥。如需使用這些屬性的詳細資訊，請參閱 Unicode 標準。

名稱	值	意義
強式
C2_LEFTTORIGHT	0x0001	由左至右
C2_RIGHTTOLEFT	0x0002	由右至左
弱
C2_EUROPENUMBER	0x0003	歐洲數位、歐洲數位
C2_EUROPESEPARATOR	0x0004	歐洲數位分隔符
C2_EUROPETERMINATOR	0x0005	歐洲數值終止符
C2_ARABICNUMBER	0x0006	阿拉伯數位
C2_COMMONSEPARATOR	0x0007	一般數值分隔符
中性
C2_BLOCKSEPARATOR	0x0008	區塊分隔符
C2_SEGMENTSEPARATOR	0x0009	區段分隔符
C2_WHITESPACE	0x000A	空白字元
C2_OTHERNEUTRAL	0x000B	其他中性
不適用
C2_NOTAPPLICABLE	0x0000	例如，控件程式代碼) 沒有隱含方向性 (

Ctype 3

這些類型是一般文字處理或標準 C 連結庫函式所需之 POSIX 類型延伸的佔位元。 當 dwInfoType 設定為 CT_CTYPE3 時，會擷取這些值的位 OR。針對 DBCS 地區設定，Ctype 3 屬性同時適用於窄字元和寬字元。日文平假名和片假名字符，以及漢字語意字元全都有C3_ALPHA屬性。

名稱	值	意義
C3_NONSPACING	0x0001	非步調標記
C3_DIACRITIC	0x0002	讀音符號非步調標記
C3_VOWELMARK	0x0004	Vowel 非步調標記
C3_SYMBOL	0x0008	符號
C3_KATAKANA	0x0010	片假名字符
C3_HIRAGANA	0x0020	平假名字符
C3_HALFWIDTH	0x0040	半角 (窄) 字元
C3_FULLWIDTH	0x0080	全角 (寬) 字元
C3_IDEOGRAPH	0x0100	表意字元
C3_KASHIDA	0x0200	阿拉伯文 kashida 字元
C3_LEXICAL	0x0400	標點符號會算為 kashida、連字元、feminine/masculine 序數指標、等號等字 (的一部分，以此類推)
C3_ALPHA	0x8000	所有語言字元 (字母、音節和語意)
C3_HIGHSURROGATE	0x0800	Windows Vista：高代理程式代碼單位
C3_LOWSURROGATE	0x1000	Windows Vista：低代理程式代碼單位
不適用
C3_NOTAPPLICABLE	0x0000	不適用

C3_HIGHSURROGATE和C3_LOWSURROGATE只會列出完整性，且絕對不應該提供給此函式。它們只與 Unicode 相關。

從 Windows 8 開始：GetStringTypeW 會在 Stringapiset.h 中宣告。在 Windows 8 之前，它會在 Winnls.h 中宣告。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	stringapiset.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

getStringTypeW 函式 (stringapiset.h)

語法

參數

傳回值

備註

規格需求

另請參閱

意見反應

意見反應

其他資源