共用方式為

函式原型的慣例

  • 發行項

Windows SDK 提供泛型、Windows 代碼頁和 Unicode 版本的函式原型。 原型可以編譯成產生 Windows 代碼頁原型或 Unicode 原型。 本主題會討論這三個原型，並透過 SetWindowText 函式的程式碼範例來說明。

以下是泛型原型的範例。

BOOL SetWindowText(
  HWND hwnd,
  LPCTSTR lpText
);

標頭檔提供實作為巨集的泛型函式名稱。

#ifdef UNICODE
#define SetWindowText SetWindowTextW
#else
#define SetWindowText SetWindowTextA
#endif // !UNICODE

預處理器會將巨集展開至 Windows 代碼頁或 Unicode 函式名稱。 字母 “A” 或 “W” （Unicode） 會適當地新增在泛型函式名稱的結尾。 頭文件接著會提供兩個特定的原型，一個用於 Windows 代碼頁，另一個用於 Unicode，如下列範例所示。

BOOL SetWindowTextA(
  HWND hwnd,
  LPCSTR lpText
);

BOOL SetWindowTextW(
  HWND hwnd,
  LPCWSTR lpText
);

如 適用於字串的 Windows 數據類型中所述，泛型函式原型會使用文字參數的數據類型 LPCTSTR。 不過，Windows 代碼頁原型會使用 LPCSTR 類型，而 Unicode 原型則使用 LPCWSTR。

對於具有文字自變數的所有函式，應用程式通常應該使用泛型函式原型。 如果應用程式在頭檔 #include 語句之前或編譯期間定義 「UNICODE」，語句就會編譯成 Unicode 函式。

注意

新的 Windows 應用程式應該使用 Unicode 來避免不同代碼頁的不一致，並方便當地語系化。 它們應該使用泛型函式撰寫，並應定義 UNICODE，將函式編譯成 Unicode 函式。 在應用程式必須使用8位字元資料的地方，它可以明確使用Windows代碼頁的函式。

 

您的應用程式應該一律使用泛型函式原型搭配泛型字串和字元類型。 以大寫 「W」 結尾的所有函式名稱都會採用 Unicode，也就是寬字元、參數。 某些函式只存在於 Unicode 版本中，而且只能與適當的數據類型搭配使用。 例如，LCIDToLocaleName 和 LocaleNameToLCID 只有 Unicode 版本。

每個 Unicode 和字元集函式的參考檔中的 [需求] 區段提供受支援作系統所實作之函式版本的相關信息。 如果包含以 「Unicode」 開頭的一行，函式就會有個別的 Unicode 和 Windows 代碼頁版本。

注意

當函式具有字元字串的 length 參數時，長度應該記錄為字串中的 TCHAR 值計數。 此數據類型是指函式的 Windows 代碼頁版本的位元組，或 Unicode 版本的 16 位字組。 不過，需要或傳回不具類型記憶體區塊指標的函式，例如 GlobalAlloc 函式，一般會採用位元元大小，而不論所使用的原型為何。 如果不具類型的記憶體配置是針對字串，則應用程式必須將字元數目乘以sizeof（TCHAR）。 如需詳細資訊，請參閱使用泛型數據類型 。

 

在 Windows API 中 Unicode