RtlAnsiStringToUnicodeString 函式 (wdm.h)

發行項
02/27/2024

RtlAnsiStringToUnicodeString 會將指定的 ANSI 來源字串轉換成 Unicode 字串。

語法

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

參數

[in, out] DestinationString

要保存已轉換 Unicode 字串 之UNICODE_STRING 結構的指標。如果 AllocateDestinationString 為 TRUE，則例程會配置新的緩衝區來保存字串數據，並更新 DestinationString 的 Buffer 成員以指向新的緩衝區。否則，例程會使用目前指定的緩衝區來保存字串。

[in] SourceString

要轉換成 Unicode 的 ANSI 字串指標。

[in] AllocateDestinationString

指定這個例程是否應該配置目的地字串的緩衝區空間。如果這樣做，呼叫端必須呼叫 RtlFreeUnicodeString 來解除分配緩衝區。

傳回值

如果轉換成功， RtlAnsiStringToUnicodeString 會傳回STATUS_SUCCESS。失敗時，例程不會配置任何記憶體。

備註

翻譯符合目前的系統地區設定資訊。

如果呼叫端將AllocateDestinationString 設定為TRUE，例程會將 DestinationString 的 Buffer 成員取代為其配置的緩衝區指標。即使例程傳回錯誤狀態代碼，也可以覆寫舊的值。

此例程不會在頭檔中宣告。不過，您可以將下列宣告複製到原始程式碼：

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

您可以使用下列例程，將單一位元組和雙位元組字元轉換成 Unicode 字元：

如需這些和其他字串處理例程的詳細資訊，請參閱運行時間連結庫 (RTL) 例程。

RtlAnsiCharToUnicodeChar 具有安全性缺點。請考慮改用 RtlAnsiStringToUnicodeString 例程。

如果輸入時，*SourceCharacter 指向一個字節緩衝區，其中包含雙位元組字元碼的第一個字節， 則 RtlAnsiCharToUnicodeChar 會在嘗試讀取第二個字節時覆寫緩衝區。

在系統啟動時，作業系統會從地區設定判斷用戶語言，並安裝適當的系統 ANSI 代碼頁。 RtlAnsiCharToUnicodeChar 使用此代碼頁，將單一位元組或雙位元組字元轉換成對應的 Unicode 字元。

如果系統 ANSI 代碼頁定義單一位元組字元集 (，則 ANSI 字元集) RtlAnsiCharToUnicodeChar 只要將範圍中的 ANSI 字元 0x00以0x7f 產生對應的 Unicode 字元，即可加速轉換作業。例程會將 ANSI 值0x5c轉換成反斜杠字元 (“\”) ，即使單一位元組代碼頁將此字元定義為簽章也一樣。

如果輸入時，*SourceCharacter 指向無效的字元碼， RtlAnsiCharToUnicodeChar 會傳回 Unicode 空格字元代碼，0x0020。下列清單顯示無效字元碼的範例：