Freigeben über


OpenFileById-Funktion (winbase.h)

Öffnet die Datei, die mit dem angegebenen Bezeichner übereinstimmt.

Syntax

HANDLE OpenFileById(
  [in]           HANDLE                hVolumeHint,
  [in]           LPFILE_ID_DESCRIPTOR  lpFileId,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwFlagsAndAttributes
);

Parameter

[in] hVolumeHint

Ein Handle für jede Datei auf einem Volume oder einer Freigabe, auf der die zu öffnende Datei gespeichert ist.

[in] lpFileId

Ein Zeiger auf einen FILE_ID_DESCRIPTOR , der die zu öffnende Datei identifiziert.

[in] dwDesiredAccess

Der Zugriff auf das Objekt. Der Zugriff kann lese-, schreib- oder beides sein.

Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte. Sie können keinen Zugriffsmodus anfordern, der mit dem Freigabemodus in Konflikt steht, der in einer offenen Anforderung mit einem geöffneten Handle angegeben ist.

Wenn dieser Parameter null (0) ist, kann die Anwendung Datei- und Geräteattribute abfragen, ohne auf ein Gerät zuzugreifen. Dies ist nützlich für eine Anwendung, um die Größe eines Diskettenlaufwerks und die unterstützten Formate zu bestimmen, ohne dass eine Diskette in einem Laufwerk erforderlich ist. Es kann auch verwendet werden, um zu testen, ob eine Datei oder ein Verzeichnis vorhanden ist, ohne sie für Lese- oder Schreibzugriff zu öffnen.

[in] dwShareMode

Der Freigabemodus eines Objekts, der lese-, schreib-, beides- oder keines-Objekt sein kann.

Sie können keinen Freigabemodus anfordern, der mit dem Zugriffsmodus in Konflikt steht, der in einer offenen Anforderung mit einem geöffneten Handle angegeben ist, da dies zu der folgenden Freigabeverletzung führen würde: (ERROR_SHARING_VIOLATION). Weitere Informationen finden Sie unter Erstellen und Öffnen von Dateien.

Wenn dieser Parameter null (0) ist und OpenFileById erfolgreich ist, kann das Objekt nicht freigegeben werden und kann erst wieder geöffnet werden, wenn das Handle geschlossen ist. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

Die Freigabeoptionen bleiben wirksam, bis Sie das Handle für ein Objekt schließen.

Um einem Prozess die Freigabe eines Objekts zu ermöglichen, während das Objekt in einem anderen Prozess geöffnet ist, verwenden Sie eine Kombination aus mindestens einem der folgenden Werte, um den Zugriffsmodus anzugeben, den sie zum Öffnen des Objekts anfordern können.

Wert Bedeutung
FILE_SHARE_DELETE
0x00000004
Ermöglicht nachfolgende geöffnete Vorgänge für ein Objekt, um Löschzugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Löschzugriff anfordern.

Wenn dieses Flag nicht angegeben ist, aber das Objekt für den Löschzugriff geöffnet wurde, schlägt die Funktion fehl.

FILE_SHARE_READ
0x00000001
Ermöglicht nachfolgende geöffnete Vorgänge für ein Objekt, um Lesezugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Lesezugriff anfordern.

Wenn dieses Flag nicht angegeben ist, aber das Objekt für den Lesezugriff geöffnet wurde, schlägt die Funktion fehl.

FILE_SHARE_WRITE
0x00000002
Ermöglicht nachfolgende geöffnete Vorgänge für ein Objekt, um Schreibzugriff anzufordern.

Andernfalls können andere Prozesse das Objekt nicht öffnen, wenn sie Schreibzugriff anfordern.

Wenn dieses Flag nicht angegeben ist, das Objekt aber für den Schreibzugriff geöffnet wurde oder über eine Dateizuordnung mit Schreibzugriff verfügt, schlägt die Funktion fehl.

[in, optional] lpSecurityAttributes

Reserviert.

[in] dwFlagsAndAttributes

Die Dateiflags.

Wenn OpenFileById eine Datei öffnet, kombiniert es die Dateiflags mit vorhandenen Dateiattributen und ignoriert alle angegebenen Dateiattribute. Dieser Parameter kann eine beliebige Kombination der folgenden Flags enthalten.

Wert Bedeutung
FILE_FLAG_BACKUP_SEMANTICS
0x02000000
Eine Datei wird für einen Sicherungs- oder Wiederherstellungsvorgang geöffnet. Das System stellt sicher, dass der aufrufende Prozess Dateisicherheitsprüfungen außer Kraft setzt, wenn der Prozess über SE_BACKUP_NAME - und SE_RESTORE_NAME-Berechtigungen verfügt. Weitere Informationen finden Sie unter Ändern von Berechtigungen in einem Token.

Sie müssen dieses Flag festlegen, um ein Handle für ein Verzeichnis abzurufen. Ein Verzeichnishandle kann anstelle eines Dateihandles an einige Funktionen übergeben werden. Weitere Informationen finden Sie unter Verzeichnishandles.

FILE_FLAG_NO_BUFFERING
0x20000000
Das System öffnet eine Datei ohne Systemzwischenspeicherung. Dieses Flag wirkt sich nicht auf die Zwischenspeicherung von Festplatten aus. In Kombination mit FILE_FLAG_OVERLAPPED sorgt das Flag für maximale asynchrone Leistung, da die E/A-Vorgänge nicht von den synchronen Vorgängen des Speicher-Managers abhängig sind. Einige E/A-Vorgänge nehmen jedoch mehr Zeit in Anspruch, da die Daten nicht im Cache gespeichert werden. Außerdem können die Dateimetadaten weiterhin zwischengespeichert werden. Verwenden Sie die Funktion FlushFileBuffers, um die Metadaten auf den Datenträger zu leeren.

Eine Anwendung muss bestimmte Anforderungen erfüllen, wenn Sie mit Dateien arbeiten, die mit FILE_FLAG_NO_BUFFERING geöffnet werden:

  • Der Dateizugriff muss bei Byteoffsets innerhalb einer Datei beginnen, die ganzzahlige Vielfache der Volumensektorgröße sind.
  • Der Dateizugriff muss für die Anzahl von Bytes gelten, die ganzzahlige Vielfache der Volumensektorgröße sind. Wenn die Sektorgröße beispielsweise 512 Bytes beträgt, kann eine Anwendung Lese- und Schreibvorgänge von 512, 1024, 1536 oder 2048 Bytes anfordern, aber nicht von 335, 981 oder 7171 Bytes.
  • Pufferadressen für Lese- und Schreibvorgänge sollten sektorseitig ausgerichtet sein, was bedeutet, dass sie an Adressen im Arbeitsspeicher ausgerichtet sind, die ganzzahlige Vielfache der Volumensektorgröße sind. Je nach Datenträger kann diese Anforderung nicht erzwungen werden.
Eine Möglichkeit zum Ausrichten von Puffern auf ganzzahligen Vielfachen der Volumesektorgröße besteht darin , VirtualAlloc zum Zuweisen der Puffer zu verwenden. Es ordnet Arbeitsspeicher zu, der an Adressen ausgerichtet ist, die ganzzahlige Vielfache der Größe der Arbeitsspeicherseiten des Betriebssystems sind. Da sowohl die Größe des Speicherseiten- als auch des Volumesektors 2 beträgt, wird dieser Arbeitsspeicher auch an Adressen ausgerichtet, die ganzzahlige Vielfache einer Volumesektorgröße sind. Speicherseiten sind 4-8 KB groß; Sektoren sind 512 Bytes (Festplatten) oder 2048 Bytes (CD), daher dürfen Volumesektoren niemals größer als Speicherseiten sein.

Eine Anwendung kann eine Volumensektorgröße ermitteln, indem sie die GetDiskFreeSpace-Funktion aufruft.

FILE_FLAG_OPEN_NO_RECALL
0x00100000
Die Dateidaten werden angefordert, sollten sich aber weiterhin im Remotespeicher befinden. Es sollte nicht zurück in den lokalen Speicher transportiert werden. Dieses Flag ist für die Verwendung durch Remotespeichersysteme vorgesehen.
FILE_FLAG_OPEN_REPARSE_POINT
0x00200000
Wenn dieses Flag verwendet wird, wird die normale Analysepunktverarbeitung nicht ausgeführt, und OpenFileById versucht, den Analysepunkt zu öffnen. Wenn eine Datei geöffnet wird, wird ein Dateihandle zurückgegeben, unabhängig davon, ob der Filter, der den Analysepunkt steuert, betriebsbereit ist. Dieses Flag kann nicht mit dem CREATE_ALWAYS-Flag verwendet werden. Wenn die Datei kein Analysepunkt ist, wird dieses Flag ignoriert.
FILE_FLAG_OVERLAPPED
0x40000000
Die Datei wird geöffnet oder für asynchrone E/A erstellt. Wenn der Vorgang abgeschlossen ist, wird das für den Aufruf in der OVERLAPPED-Struktur angegebene Ereignis auf den signalierten Zustand festgelegt. Vorgänge, bei denen die Verarbeitung viel Zeit in Anspruch nimmt, geben ERROR_IO_PENDING zurück.

Wenn dieses Flag angegeben ist, kann die Datei für gleichzeitige Lese- und Schreibvorgänge verwendet werden. Das System behält den Dateizeiger nicht bei, daher müssen Sie die Dateiposition an die Lese- und Schreibfunktionen in der OVERLAPPED-Struktur übergeben oder den Dateizeiger aktualisieren.

Wenn dieses Flag nicht angegeben ist, werden E/A-Vorgänge serialisiert, auch wenn die Aufrufe der Lese- und Schreibfunktionen eine OVERLAPPED-Struktur angeben.

FILE_FLAG_RANDOM_ACCESS
0x10000000
Auf eine Datei wird nach dem Zufallsprinzip zugegriffen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden.
FILE_FLAG_SEQUENTIAL_SCAN
0x08000000
Auf eine Datei wird sequenziell (vom Anfang zum Ende) zugegriffen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden. Wenn eine Anwendung den Dateizeiger für den zufälligen Zugriff verschiebt, erfolgt möglicherweise keine optimale Zwischenspeicherung. Der korrekte Betrieb ist jedoch weiterhin gewährleistet.

Das Angeben dieses Flags kann die Leistung für Anwendungen erhöhen, die große Dateien mithilfe des sequenziellen Zugriffs lesen. Noch deutlicher kann die Leistung bei Anwendungen sein, die große Dateien meist sequenziell lesen, aber gelegentlich kleine Bytebereiche überspringen.

FILE_FLAG_WRITE_THROUGH
0x80000000
Das System schreibt durch jeden Zwischencache und wechselt direkt zum Datenträger.

Wenn nicht auch FILE_FLAG_NO_BUFFERING angegeben ist, sodass die Systemzwischenspeicherung wirksam ist, werden die Daten in den Systemcache geschrieben, aber ohne Verzögerung auf den Datenträger geleert.

Wenn auch FILE_FLAG_NO_BUFFERING angegeben ist, sodass die Systemzwischenspeicherung nicht wirksam ist, werden die Daten sofort auf den Datenträger geleert, ohne den Systemcache zu durchlaufen. Das Betriebssystem fordert auch einen Schreibvorgang für den Festplattencache auf persistente Medien an. Diese Schreibzugriffsfunktion wird jedoch nicht von der gesamten Hardware unterstützt.

Rückgabewert

Wenn die Funktion erfolgreich ausgeführt wurde, ist der Rückgabewert ein offenes Handle zu einer angegebenen Datei.

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

Hinweise

Verwenden Sie die CloseHandle-Funktion , um ein Objekthandle zu schließen, das OpenFileById zurückgibt.

Wenn Sie OpenFileById für eine Datei aufrufen, die aufgrund eines vorherigen Aufrufs von DeleteFile gelöscht wird, schlägt die Funktion fehl. Das Betriebssystem verzögert das Löschen von Dateien, bis alle Handles für die Datei geschlossen sind. GetLastError gibt ERROR_ACCESS_DENIED zurück.

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) No
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) No
Dateisystem mit freigegebenen Clustervolumes (CsvFS) Ja
Robustes Dateisystem (Resilient File System, ReFS) Ja

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winbase.h (Windows.h einschließen)
Bibliothek Kernel32.lib; FileExtd.lib unter Windows Server 2003 und Windows XP
DLL Kernel32.dll
Verteilbare Komponente Windows SDK unter Windows Server 2003 und Windows XP.

Weitere Informationen

ACCESS_MASK

CloseHandle

CreateFile

DeleteFile

FILE_ID_DESCRIPTOR

Dateiverwaltungsfunktionen

GetFileInformationByHandleEx

GetOverlappedResult

OVERLAPPED

OpenFile

ReadFile

WriteFile