CreateFile

Aus API-Wiki
Wechseln zu: Navigation, Suche

Diese Funktion öffnet oder erstellt eine Datei, oder einen Datenkanal. Kanäle können ein COM- oder LPT-Port, ein Gerät, ein Dienst oder eine Console sein.

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

Declare Function CreateFile Lib "kernel32" 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.[1]


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[2]


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[3]


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ückgabewert(e):

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 GetLastError ERROR_ALREADY_EXISTS zurück, obgleich die Funktion erfolgreich war. Wenn die Datei noch nicht vorhanden war, so gibt GetLastError 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.


Sonstige 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[4]


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