SHAnsiToAnsi-Funktion (shlwapi.h)

Artikel
03/06/2024

[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.]

Kopiert eine ANSI-Zeichenfolge.

Syntax

int SHAnsiToAnsi(
  [in]  PCSTR pszSrc,
  [out] PSTR  pszDst,
        int   cchBuf
);

Parameter

[in] pszSrc

Typ: LPCSTR

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

[out] pszDst

Typ: LPWSTR

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

cchBuf

Typ: int

Die Anzahl der Zeichen, die vom Puffer enthalten sein können, auf den pszDst verweist. Dieser Parameter muss größer als 0 (null) sein.

Rückgabewert

Typ: int

Gibt die Anzahl von Zeichen zurück, die in pszDst 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. Beachten Sie, dass die Ausgabezeichenfolge unbeaufsichtigt abgeschnitten wird, wenn der Puffer nicht groß genug ist. Dies kann zu Kanonisierung 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 pszSrc 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.

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)