GetFileTitleA-Funktion (commdlg.h)

  • Artikel

Ruft den Namen der angegebenen Datei ab.

Syntax

short GetFileTitleA(
  [in]  LPCSTR unnamedParam1,
  [out] LPSTR  Buf,
  [in]  WORD   cchSize
);

Parameter

[in] unnamedParam1

Typ: LPCTSTR

Der 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: kurz

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 beendende NULL-Zeichen.

Hinweise

GetFileTitle sollte nur mit legalen Dateinamen aufgerufen werden. Die Verwendung eines ungültigen Dateinamens führt zu einem nicht definierten 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 Einstellung 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 lpszTitle-Puffer zu klein ist, gibt GetFileTitle die Größe zurück, die zum Speichern des Anzeigenamens 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 GetFileTitle nicht auf, wenn 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 nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek Comdlg32.lib
DLL Comdlg32.dll
APIs ext-ms-win-shell-comdlg32-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)

Weitere Informationen

Allgemeine Dialogfeldbibliothek

Konzept

GetOpenFileName

GetSaveFileName

Referenz