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.
[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 |
|---|---|
|
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. |
|
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:
Eine Anwendung kann eine Volumensektorgröße ermitteln, indem sie die GetDiskFreeSpace-Funktion aufruft. |
|
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. |
|
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. |
|
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. |
|
Auf eine Datei wird nach dem Zufallsprinzip zugegriffen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden. |
|
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. |
|
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. |