SHAnsiToUnicode-Funktion (shlwapi.h)

Artikel
08/26/2023

[Diese Funktion ist über Windows XP und Windows Server 2003 verfügbar. In nachfolgenden Versionen von Windows ist sie möglicherweise geändert oder nicht verfügbar.]

Konvertiert eine Zeichenfolge von der ANSI-Codepage in die Unicode-Codepage.

Syntax

int SHAnsiToUnicode(
  [in]  PCSTR pszSrc,
  [out] PWSTR pwszDst,
        int   cwchBuf
);

Parameter

[in] pszSrc

Typ: PCSTR

Ein Zeiger auf eine NULL-endende ANSI-Zeichenfolge, die in Unicode konvertiert werden soll.

[out] pwszDst

Typ: PWSTR

Ein Zeiger auf einen Puffer, der nach erfolgreicher Rückgabe dieser Funktion die von pszSrc angegebene Zeichenfolge empfängt, nachdem die ANSI-Zeichen in Unicode (WCHAR) konvertiert wurden. Der Puffer muss groß genug sein, um die Durch den cwchBuf-Parameter angegebene Anzahl von Unicode-Zeichen zu enthalten, einschließlich eines abschließenden NULL-Zeichens.

cwchBuf

Typ: int

Die Anzahl der Unicode-Zeichen, die der Puffer enthalten kann, auf den pwszDst verweist. Dieser Parameter muss größer als 0 (null) sein.

Rückgabewert

Typ: int

Gibt die Anzahl der Unicode-Zeichen zurück, die in pwszDst geschrieben wurden, einschließlich des abschließenden NULL-Zeichens. Gibt 0 zurück, wenn der Fehler nicht erfolgreich ist.

Hinweise

Sicherheitswarnung: Die falsche Verwendung dieser Funktion kann die Sicherheit Ihrer Anwendung beeinträchtigen. Wenn der pwszDst-Puffer beispielsweise nicht groß genug ist, um die von cwchBuf angegebene Anzahl von Zeichen zu enthalten, kann es zu einem Pufferüberlauf kommen. Pufferüberläufe können einen Denial-of-Service-Angriff auf eine Anwendung verursachen, wenn eine Zugriffsverletzung auftritt. Im schlimmsten Fall kann ein Pufferüberlauf es einem Angreifer ermöglichen, ausführbaren Code in Ihren Prozess einzufügen, insbesondere wenn pwszDst ein stapelbasierter Puffer ist. Beachten Sie beim Kopieren einer gesamten Zeichenfolge, dass sizeof die Anzahl von Bytes zurückgibt, was nicht der richtige Wert für den cwchBuf-Parameter ist. Verwenden Sie stattdessen sizeof(pwszDst)/sizeof(WCHAR). Beachten Sie, dass bei dieser Technik davon ausgegangen wird, dass pwszDst ein Array und kein Zeiger ist.

Wenn der pwszDst-Puffer nicht groß genug ist, um die gesamte konvertierte Ausgabezeichenfolge zu enthalten, wird die Zeichenfolge abgeschnitten, damit sie dem Puffer entspricht. Es gibt keine Möglichkeit, zu erkennen, dass die Rückgabezeichenfolge abgeschnitten wurde. Die Zeichenfolge ist immer NULL-beendet, auch wenn sie abgeschnitten wurde. Dadurch wird sichergestellt, dass nicht mehr als cwchBuf-Zeichen in pwszDst kopiert werden. Es wird nicht versucht, das Abschneiden der Zeichenfolge in der Mitte eines Unicode-Ersatzzeichenpaars zu vermeiden.

Wenn sich die Puffer pszSrc und pwszDst überlappen, ist das Verhalten der Funktion nicht definiert.

Hinweis Gehen Sie nicht davon aus, dass die Funktion keines der Zeichen im Ausgabepuffer geändert hat, die auf das abschließende NULL-Zeichen der Zeichenfolge folgen. Der Inhalt des Ausgabepuffers, der auf das abschließende NULL-Zeichen der Zeichenfolge folgt, ist undefiniert, bis und einschließlich des letzten Zeichens im Puffer.

SHAnsiToTChar ist als identisch mit SHAnsiToUnicode definiert.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server, Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlwapi.h
DLL	Shlwapi.dll (Version 5.0 oder höher)