SHUnicodeToAnsi-Funktion (shlwapi.h)

Artikel
08/26/2023

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

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

Syntax

int SHUnicodeToAnsi(
  [in]  PCWSTR pwszSrc,
  [out] PSTR   pszDst,
        int    cchBuf
);

Parameter

[in] pwszSrc

Typ: PCWSTR

Ein Zeiger auf die Unicode-Zeichenfolge mit NULL-Beendigung, die in ANSI konvertiert werden soll.

[out] pszDst

Typ: PSTR

Ein Zeiger auf einen Puffer, der bei erfolgreicher Rückgabe dieser Funktion die konvertierten Zeichen empfängt. Der Puffer muss groß genug sein, um die Anzahl von CHAR-Zeichen zu enthalten, die durch den cchBuf-Parameter angegeben werden, einschließlich des Raums für ein beendendes NULL-Zeichen.

cchBuf

Typ: int

Die Anzahl der CHAR-Werte , die vom Puffer enthalten sein können, auf den pszDst verweist. Der dem Parameter zugewiesene Wert muss größer als 0 sein.

Rückgabewert

Typ: int

Gibt die Anzahl der CHAR-Werte zurück, die in den Ausgabepuffer geschrieben wurden, einschließlich des beendenden NULL-Zeichens. Gibt 0 zurück, wenn der Fehler nicht erfolgreich ist.

Hinweise

Sicherheitswarnung: Die falsche Verwendung dieser Funktion kann die Sicherheit Ihrer Anwendung gefährden. Wenn der pszDst-Puffer beispielsweise nicht groß genug ist, um die von cchBuf 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 es sich bei pszDst um einen stapelbasierten Puffer handelt. Darüber hinaus wird die Ausgabezeichenfolge unbeaufsichtigt abgeschnitten, wenn sie für den Puffer zu groß ist. Dies kann zu Kanonisierungen oder anderen Sicherheitsrisiken führen.

Wenn der pszDst-Puffer nicht groß genug ist, um die gesamte konvertierte Ausgabezeichenfolge zu enthalten, wird die Zeichenfolge abgeschnitten, um dem Puffer zu entsprechen. Es gibt keine Möglichkeit, zu erkennen, dass die Rückgabezeichenfolge abgeschnitten wurde. Die Zeichenfolge ist immer null-beendet, auch wenn sie abgeschnitten wurde. Diese Funktion achte darauf, dass zwischen den Lead- und Trailbytes eines DBCS-Zeichenpaars nicht abgeschnitten wird. In diesem Fall werden nur cchBuf-1-Zeichen zurückgegeben.

Wenn sich die Puffer pwszSrc und pszDst überschneiden, 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 dem beendenden NULL-Zeichen der Zeichenfolge folgen. Der Inhalt des Ausgabepuffers, der dem beendenden NULL-Zeichen der Zeichenfolge folgt, ist nicht definiert, bis und einschließlich des letzten Zeichens im Puffer.

SHTCharToAnsi ist mit SHUnicodeToAnsi identisch.

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)