getStringScripts 函式 (winnls.h)

  • 發行項

提供指定 Unicode 字串中使用的文稿清單。

語法

int GetStringScripts(
  [in]            DWORD   dwFlags,
  [in]            LPCWSTR lpString,
  [in]            int     cchString,
  [out, optional] LPWSTR  lpScripts,
  [in]            int     cchScripts
);

參數

[in] dwFlags

指定文稿擷取選項的旗標。

值 意義
GSS_ALLOW_INHERITED_COMMON
 擷取 「Qaii」 (INHERITED) 和 “Zyyy” (COMMON) 腳本資訊。 此旗標不會影響未指派字元的處理。 輸入字串中的這些字元一律會導致 「Zzzz」 (UNASSIGNED 腳本) 出現在腳本字串中。
 
注意 根據預設， GetStringScripts 會忽略 lpString 所指示之輸入字串中的任何繼承或通用字元。 如果未設定GSS_ALLOW_INHERITED_COMMON，即使輸入字串包含這類字元，“Qaii” 或 “Zyyy” 也不會出現在腳本字串中。 如果已設定GSS_ALLOW_INHERITED_COMMON，而且如果輸入字串包含繼承和/或通用字元，則分別會出現在腳本字串中，“Qaii” 和/或 “Zyyy”。 請參閱＜備註＞一節。
 

[in] lpString

要分析之 Unicode 字串的指標。

[in] cchString

以字元為單位的 Unicode 字串大小，以 lpString 表示。 如果 Unicode 字串為 Null 終止，則應用程式會將此參數設定為 -1。 如果應用程式將此參數設定為 0，函式會在 lpScripts 中擷取 null Unicode 字串 (L“\0”) ，並傳回 1。

[out, optional] lpScripts

緩衝區的指標，此函式會使用 ISO 15924 中使用的 4 個字元表示法，擷取代表腳本清單的 Null 終止字串。 每個腳本名稱都包含四個拉丁字元，並以字母順序擷取名稱。 每個名稱，包括最後一個名稱，後面接著分號。

或者，如果 cchScripts 設定為 0，此參數會包含 NULL。 在此情況下，函式會傳回腳本緩衝區的必要大小。

[in] cchScripts

大小，以字元為單位，以 lpScripts 表示的腳本緩衝區。

或者，應用程式可以將此參數設定為 0。 在此情況下，函式會在 lpScripts 中擷取 NULL，並傳回腳本緩衝區所需的大小。

傳回值

傳回輸出緩衝區中擷取的字元數，包括終止的 Null 字元，如果成功且 cchScripts 設定為非零值。 函式會傳回 1，表示找不到任何腳本，例如，當輸入字串只包含 COMMON 或 INHERITED 字元且未設定GSS_ALLOW_INHERITED_COMMON時。 假設每個找到的腳本都會 (四個字元 + 分隔符) 新增五個字元，簡單的數學運算會將腳本計數提供 (return_code - 1) / 5。

如果函式成功且 cchScripts 的值為 0，則函式會傳回腳本緩衝區所需的大小，包括終止 Null 字元的字元。 腳本計數如上所述。

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

  • ERROR_BADDB。 函式無法存取數據。 這種情況通常不應該發生，通常表示安裝不正確、磁碟問題或類似。
  • ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 NULL 不正確。
  • ERROR_INVALID_FLAGS。 為旗標的值無效。
  • ERROR_INVALID_PARAMETER。 任何參數值都無效。

備註

此函式在策略中很有用，可降低 與國際化域名相關的安全性問題， (IDN) 。

腳本判斷是以 中 http://www.unicode.org/Public/4.1.0/ucd/Scripts.txtUnicode 聯盟所發佈的腳本值為基礎，不同之處在於未指派字元的值為 “Zzzz” (UNASSIGNED) ，而不是 “Zyyy” (COMMON) 。

以下是此函式行為的一些範例：

輸入字串 dwFlags lpScripts 指令碼
Microsoft.com 0 Latn; 拉丁文
Microsoft.com GSS_ALLOW_INHERITED_COMMON Latn;Zyyy; 拉丁文 + 通用
現象 004E 0069 0241 006F GSS_ALLOW_INHERITED_COMMON Latn; 拉丁文
使用 LATIN SMALL LETTER N WITH TILDE
現象 004E 0069 006E 0303 006F GSS_ALLOW_INHERITED_COMMON Latn;Qaii; 拉丁文 + 繼承
使用 COMBINING TILDE
Spооf 0053 0070 043e 043e 0066 0 Latn;Cyrl; 拉丁文 + 斯拉夫文
使用 CYRILLIC SMALL LETTER O
U+f000 0 Zzzz; 未指定
U+f000 GSS_ALLOW_INHERITED_COMMON Zzzz; 未指定

規格需求

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

另請參閱

DownlevelGetStringScripts

處理國際化域名 (IDN)

國家語言支援

國家語言支援函式

VerifyScripts