CreateFile

Aus API-Wiki
Wechseln zu: Navigation, Suche


Diese Funktion öffnet oder erstellt eine Datei, oder einen Datenkanal. Kanäle können zu einem Port der seriellen (COMx), sowie parallelen (LPTx) Schnittstelle, einem Gerät, einem Dienst oder einer Console bestehen.

Sie gibt ein Handle zurück, welches den Zugriff ermöglicht.

Declare Function CreateFile Lib "kernel32.dll" Alias "CreateFileA" ( _
                            ByVal lpFileName As String, _
                            ByVal dwDesiredAccess As Long,  _
                            ByVal dwShareMode As Long,  _
                            ByVal lpSecurityAttributes As Long, _
                            ByVal dwCreationDisposition As Long, _
                            ByVal dwFlagsAndAttributes As Long, _
                            ByVal hTemplateFile As Long) As Long


Parameter

lpFileName [Übergabe]

Übergabe eines Pfades (maximale Länge meist Const MAX_PATH = 260).
Bei Zugriff auf einen COM-Anschluss wird nach dem Portnamen ein Doppelpunkt erwartet
z.B.: COM1:


dwDesiredAccess [Übergabe]

Übergabe der Zugriffsart.
GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE, weitere Flags und Mischformen.


dwShareMode [Übergabe]

Gibt das Verhalten der Datei gegenüber anderen Zugriffen an.
FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE und Mischformen.


lpSecurityAttributes [Übergabe]

Sicherheitsattribute der neu erstellten Datei. Meist wird ein Nullzeiger übergeben, dann wird ein Standard-Sicherheitsdeskriptor verwendet.


dwCreationDisposition [Übergabe]

Gibt an, wie sich CreateFile bei verschiedenen Situationen verhält. Ist die
Datei beispielsweise bereits vorhanden, so wird bei gesetztem Flag CREATE_ALWAYS die Datei
überschrieben.
Eine vollständige Liste der Flags findet sich in der MSDN Library.


dwFlagsAndAttributes [Übergabe]

Gibt an, mit welchen Dateiattributen die Datei erstellt werden soll. Gibt außerdem weitere Flags an.
Eine vollständige Liste der Flags findet sich in der MSDN Library.


hTemplateFile [Übergabe]

Ein Handle auf eine geöffnete Vorlagendatei, aus der die Dateiattribute kopiert werden. In den meisten Fällen wird ein Nullzeiger übergeben.


Rückgaben

Ein Dateihandle ungleich INVALID_HANDLE_VALUE ist ein Zeichen für den erfolgreichen Zugriff. Wenn die Datei hingegen schon vor dem Zugriff existiert hat, und der Flag CREATE_ALWAYS / OPEN_ALWAYS gesetzt wurde, so gibt Err.LastDLLError ERROR_ALREADY_EXISTS zurück, obgleich die Funktion erfolgreich war. Wenn die Datei noch nicht vorhanden war, so gibt Err.LastDLLError ERROR_SUCCESS zurück.

Um festzustellen, ob ein Dateihandle gültig ist, empfielt sich ein Vergleich mit Const INVALID_HANDLE_VALUE As Long = -1 durchzuführen.


Hinweise

Um ein Objekthandle wieder zu schließen (und das Objekt damit ggf. freizugeben), ist die CloseHandle-Funktion zu verwenden.

Weitere Hinweise, wie beispielsweise zur Verwendung mit FILE_FLAG_NO_BUFFERING finden sich in der MSDN Libary.

Beispiel:

    FileHandle = CreateFile(Path, GENERIC_READ, FILE_SHARE_READ Or _
                            FILE_SHARE_WRITE, 0, OPEN_EXISTING, _
                            FILE_FLAG_NO_BUFFERING, 0)
    
    If FileHandle = INVALID_HANDLE_VALUE Then
        'Fehler beim Zugriff
    End If


Verweise

MSDN Libary: CreateFile
MSDN Libary: File Security and Access Rights