OpenFile-Funktion (winbase.h)

Artikel
08/27/2023

Erstellt eine Datei, öffnet sie, öffnet sie erneut oder löscht sie.

Hinweis Diese Funktion verfügt über begrenzte Funktionen und wird nicht empfohlen. Verwenden Sie für die Entwicklung neuer Anwendungen die CreateFile-Funktion .

Syntax

HFILE OpenFile(
  [in]  LPCSTR     lpFileName,
  [out] LPOFSTRUCT lpReOpenBuff,
  [in]  UINT       uStyle
);

Parameter

[in] lpFileName

Der Name der Datei.

Die Zeichenfolge muss aus Zeichen aus dem 8-Bit-Windows-Zeichensatz bestehen. Die OpenFile-Funktion unterstützt keine Unicode-Dateinamen oder das Öffnen von Named Pipes.

[out] lpReOpenBuff

Ein Zeiger auf die OFSTRUCT-Struktur , die Beim ersten Öffnen Informationen zu einer Datei empfängt.

Die Struktur kann in nachfolgenden Aufrufen der OpenFile-Funktion verwendet werden, um eine geöffnete Datei anzuzeigen.

Die OFSTRUCT-Struktur enthält einen Pfadzeichenfolgenmember mit einer Länge, die auf OFS_MAXPATHNAME Zeichen beschränkt ist, d. h. 128 Zeichen. Aus diesem Fall können Sie die OpenFile-Funktion nicht verwenden, um eine Datei mit einer Pfadlänge von mehr als 128 Zeichen zu öffnen. Die CreateFile-Funktion verfügt nicht über diese Pfadlängenbeschränkung.

[in] uStyle

Die zu ergreifende Aktion.

Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
OF_CANCEL 0x00000800	Ignoriert. Verwenden Sie OF_PROMPT, um ein Dialogfeld zu erstellen, das eine Schaltfläche Abbrechen enthält.
OF_CREATE 0x00001000	Erstellt eine neue Datei. Wenn die Datei vorhanden ist, wird sie auf die Länge 0 (0) abgeschnitten.
OF_DELETE 0x00000200	Löscht eine Datei.
OF_EXIST 0x00004000	Öffnet eine Datei und schließt sie dann. Verwenden Sie dies, um das Vorhandensein einer Datei zu testen.
OF_PARSE 0x00000100	Füllt die OFSTRUCT-Struktur aus, tut aber nichts anderes.
OF_PROMPT 0x00002000	Zeigt ein Dialogfeld an, wenn keine angeforderte Datei vorhanden ist. Ein Dialogfeld informiert einen Benutzer darüber, dass das System eine Datei nicht finden kann, und es enthält die Schaltflächen Wiederholen und Abbrechen . Die Schaltfläche Abbrechen weist OpenFile an, eine Fehlermeldung "Datei nicht gefunden" zurückzugeben.
OF_READ 0x00000000	Öffnet eine Datei nur zum Lesen.
OF_READWRITE 0x00000002	Öffnet eine Datei mit Lese-/Schreibberechtigungen.
OF_REOPEN 0x00008000	Öffnet eine Datei mithilfe von Informationen im Puffer "Erneut öffnen".
OF_SHARE_COMPAT 0x00000000	Öffnet bei MS-DOS-basierten Dateisystemen eine Datei mit Kompatibilitätsmodus, ermöglicht jedem Prozess auf einem angegebenen Computer, die Datei beliebig oft zu öffnen. Andere Versuche, eine Datei mit anderen Freigabemodi zu öffnen, schlagen fehl. Dieses Flag ist dem FILE_SHARE_READ\|FILE_SHARE_WRITE Flags der CreateFile-Funktion zugeordnet.
OF_SHARE_DENY_NONE 0x00000040	Öffnet eine Datei, ohne den Lese- oder Schreibzugriff auf andere Prozesse zu verweigern. Wenn die Datei auf MS-DOS-basierten Dateisystemen von einem anderen Prozess im Kompatibilitätsmodus geöffnet wurde, schlägt die Funktion fehl. Dieses Flag ist dem FILE_SHARE_READ\|FILE_SHARE_WRITE Flags der CreateFile-Funktion zugeordnet.
OF_SHARE_DENY_READ 0x00000030	Öffnet eine Datei und verweigert den Lesezugriff auf andere Prozesse. Wenn die Datei auf MS-DOS-basierten Dateisystemen im Kompatibilitätsmodus oder für den Lesezugriff durch einen anderen Prozess geöffnet wurde, schlägt die Funktion fehl. Dieses Flag ist dem FILE_SHARE_WRITE Flag der CreateFile-Funktion zugeordnet.
OF_SHARE_DENY_WRITE 0x00000020	Öffnet eine Datei und verweigert schreibzugriff auf andere Prozesse. Wenn auf MS-DOS-basierten Dateisystemen eine Datei im Kompatibilitätsmodus oder für den Schreibzugriff durch einen anderen Prozess geöffnet wurde, schlägt die Funktion fehl. Dieses Flag ist dem FILE_SHARE_READ Flag der CreateFile-Funktion zugeordnet.
OF_SHARE_EXCLUSIVE 0x00000010	Öffnet eine Datei im exklusiven Modus und verweigert sowohl Lese-/Schreibzugriff auf andere Prozesse. Wenn eine Datei in einem anderen Modus für den Lese-/Schreibzugriff geöffnet wurde, auch durch den aktuellen Prozess, schlägt die Funktion fehl.
OF_VERIFY	Überprüft, ob das Datum und die Uhrzeit einer Datei mit dem Zeitpunkt identisch sind, an dem sie zuvor geöffnet wurde. Dies ist nützlich als zusätzliche Überprüfung für schreibgeschützte Dateien.
OF_WRITE 0x00000001	Öffnet eine Datei nur für den Schreibzugriff.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt der Rückgabewert ein Dateihandle an, das beim Ausführen von Datei-E/A verwendet werden soll. Rufen Sie die CloseHandle-Funktion mithilfe dieses Handles auf, um die Datei zu schließen.

Wenn die Funktion fehlschlägt, wird der Rückgabewert HFILE_ERROR. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der lpFileName-Parameter nur einen Dateinamen und eine Erweiterung angibt, sucht diese Funktion nach einer übereinstimmenden Datei in den folgenden Verzeichnissen und der angezeigten Reihenfolge:

Das Verzeichnis, in dem eine Anwendung geladen wird.
Das aktuelle Verzeichnis.
Das Systemverzeichnis von Windows.
Verwenden Sie die GetSystemDirectory-Funktion , um den Pfad dieses Verzeichnisses abzurufen.
Das 16-Bit-Windows-Systemverzeichnis.
Es gibt keine Funktion, die den Pfad dieses Verzeichnisses abruft, aber sie wird durchsucht.
Das Windows-Verzeichnis.
Verwenden Sie die GetWindowsDirectory-Funktion , um den Pfad dieses Verzeichnisses abzurufen.
Die Verzeichnisse, die in der PATH-Umgebungsvariablen aufgeführt sind.

Der lpFileName-Parameter darf keine Feldhalterzeichen enthalten.

Die OpenFile-Funktion unterstützt nicht das OF_SEARCH-Flag , das die 16-Bit-Windows OpenFile-Funktion unterstützt. Das flag OF_SEARCH weist das System an, nach einer übereinstimmenden Datei zu suchen, auch wenn ein Dateiname einen vollständigen Pfad enthält. Verwenden Sie die SearchPath-Funktion , um nach einer Datei zu suchen.

Eine Freigabeverletzung tritt auf, wenn versucht wird, eine Datei oder ein Verzeichnis zum Löschen auf einem Remotecomputer zu öffnen, wenn der Wert des uStyle-Parameters das OF_DELETE Zugriffsflag ODER mit einem anderen Zugriffsflag ist und die Remotedatei oder das Remoteverzeichnis nicht mit FILE_SHARE_DELETE Freigabezugriff geöffnet wurde. Um den Verstoß gegen die Freigabe in diesem Szenario zu vermeiden, öffnen Sie die Remotedatei oder das Remoteverzeichnis nur mit OF_DELETE Zugriff, oder rufen Sie DeleteFile auf , ohne zuvor die Datei oder das Verzeichnis zum Löschen zu öffnen.

Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

CsvFs leiten E/A für komprimierte Dateien um.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll