GetFileTitleW-Funktion (commdlg.h)

Artikel
08/22/2023

Ruft den Namen der angegebenen Datei ab.

Syntax

short GetFileTitleW(
  [in]  LPCWSTR unnamedParam1,
  [out] LPWSTR  Buf,
  [in]  WORD    cchSize
);

Parameter

[in] unnamedParam1

Typ: LPCTSTR

Name und Speicherort einer Datei.

[out] Buf

Typ: LPTSTR

Der Puffer, der den Namen der Datei empfängt.

[in] cchSize

Typ: WORD

Die Länge des Puffers in Zeichen, auf den der lpszTitle-Parameter verweist.

Rückgabewert

Typ: short

Wenn die Funktion erfolgreich ist, ist der Rückgabewert „0“.

Wenn der Dateiname ungültig ist, ist der Rückgabewert unbekannt. Wenn ein Fehler auftritt, ist der Rückgabewert eine negative Zahl.

Wenn der Puffer, auf den der lpszTitle-Parameter verweist, zu klein ist, ist der Rückgabewert eine positive ganze Zahl, die die erforderliche Puffergröße in Zeichen angibt. Die erforderliche Puffergröße enthält das abschließende NULL-Zeichen.

Hinweise

GetFileTitle sollte nur mit gesetzlichen Dateinamen aufgerufen werden. Die Verwendung eines unzulässigen Dateinamens führt zu einem undefinierten Ergebnis.

Um die für den Namen einer Datei erforderliche Puffergröße abzurufen, rufen Sie die Funktion auf, wobei lpszTitle auf NULL und cchSize auf Null festgelegt ist. Die Funktion gibt die erforderliche Größe zurück.

GetFileTitle gibt die Zeichenfolge zurück, die das System zum Anzeigen des Dateinamens für den Benutzer verwenden würde. Der Anzeigename enthält nur eine Erweiterung, wenn dies die Präferenz des Benutzers für die Anzeige von Dateinamen ist. Dies bedeutet, dass die zurückgegebene Zeichenfolge die Datei möglicherweise nicht genau identifiziert, wenn sie in Aufrufen von Dateisystemfunktionen verwendet wird.

Wenn der puffer lpszTitle zu klein ist, gibt GetFileTitle die größe zurück, die für den Anzeigenamen erforderlich ist. Es gibt jedoch keine garantierte Beziehung zwischen der erforderlichen Größe und den Zeichen, die ursprünglich im lpszFile-Puffer angegeben wurden. Rufen Sie beispielsweise nicht GetFileTitle auf, wobei lpszTitle auf NULL und cchSize auf Null festgelegt ist, und versuchen Sie dann, den Rückgabewert als Index in der lpszFile-Zeichenfolge zu verwenden. Mit C-Laufzeitbibliotheksfunktionen wie strrchr, wcsrchr und _mbsrchr können Sie in der Regel ähnliche Ergebnisse (und überlegene Leistung) erzielen.

Hinweis

Der commdlg.h-Header definiert GetFileTitle als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	commdlg.h (windows.h einschließen)
Bibliothek	Comdlg32.lib
DLL	Comdlg32.dll
APIs	ext-ms-win-shell-comdlg32-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)