CreateFile: Unterschied zwischen den Versionen

Aus API-Wiki
Wechseln zu: Navigation, Suche
 
(23 dazwischenliegende Versionen von 5 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
Diese Funktion ''öffnet'' oder ''erstellt''  eine Datei, oder einen Datenkanal. Kanäle können ein COM- oder LPT-Port, ein Gerät, einen Diest oder eine Console sein.
+
__NOTOC__
  
Sie '''gibt''' ein '''Handle zurück''', dass den Zugriff ermöglicht.
+
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.
  
<pre>
+
Sie gibt ein Handle zurück, welches den Zugriff ermöglicht.
Declare Function CreateFile Lib "kernel32" Alias "CreateFileA" ( _
+
 
 +
<syntaxhighlight lang="vb">
 +
Declare Function CreateFile Lib "kernel32.dll" Alias "CreateFileA" ( _
 
                             ByVal lpFileName As String, _
 
                             ByVal lpFileName As String, _
 
                             ByVal dwDesiredAccess As Long,  _
 
                             ByVal dwDesiredAccess As Long,  _
 
                             ByVal dwShareMode As Long,  _
 
                             ByVal dwShareMode As Long,  _
                             ByRef lpSecurityAttributes As SECURITY_ATTRIBUTES, _
+
                             ByVal lpSecurityAttributes As Long, _
 
                             ByVal dwCreationDisposition As Long, _
 
                             ByVal dwCreationDisposition As Long, _
 
                             ByVal dwFlagsAndAttributes As Long, _
 
                             ByVal dwFlagsAndAttributes As Long, _
 
                             ByVal hTemplateFile As Long) As Long
 
                             ByVal hTemplateFile As Long) As Long
</pre>
+
</syntaxhighlight>
  
  
'''Parameter:'''
+
==Parameter==
  
''lpFileName [übergabe]''
+
''lpFileName [Übergabe]''
 
          
 
          
Übergabe eines Pfades (maximale Länge "Const MAX_PATH = 260").
+
:Übergabe eines Pfades (maximale Länge meist Const [[MAX_PATH]] = 260).
Bei Zugriff auf das Com-Objekt wird nach dem Portnamen ein Doppelpunkt erwartet  
+
:Bei Zugriff auf einen COM-Anschluss wird nach dem Portnamen ein Doppelpunkt erwartet  
z.B.: ''COM1:''
+
:z.B.: ''COM1:''
  
  
''dwDesiredAccess [übergabe]''
+
''dwDesiredAccess [Übergabe]''
  
Übergabe der Zugriffsart.
+
:Übergabe der Zugriffsart.
GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE und Mischformen.
+
:[[GENERIC_READ]], [[GENERIC_WRITE]], [[GENERIC_EXECUTE]], weitere Flags und Mischformen.
  
  
''dwShareMode [übergabe]''
 
  
Gibt das Verhalten der Datei gegenüber anderen Zugriffen an.
+
''dwShareMode [Übergabe]''
FILE_SHARE_READ, FILE_SHARE_WRITE und Mischforen.
 
  
 +
:Gibt das Verhalten der Datei gegenüber anderen Zugriffen an.
 +
:[[FILE_SHARE_DELETE]], [[FILE_SHARE_READ]], [[FILE_SHARE_WRITE]] und Mischformen.
  
''lpSecurityAttributes [übergabe]''
 
  
Wird nicht benötigt. Übergabe daher ByVal 0&.
+
''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.
+
''dwCreationDisposition [Übergabe]''
  
Eine vollständige Liste der Flags findet sich in der MSDN[http://msdn2.microsoft.com/en-us/library/aa914735.aspx#]
+
: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.
+
''dwFlagsAndAttributes [Übergabe]''
''Standardwert ist: FILE_ATTRIBUTE_NORMAL.''
 
  
Eine vollständige Liste der Flags findet sich in der MSDN[http://msdn2.microsoft.com/en-us/library/aa914735.aspx#]
+
: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]''
 
  
Wird ignoriert. Die Übergabe ist daher "0".
+
''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 0 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'' "0" zurück.
+
==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  
 
Um festzustellen, ob ein Dateihandle gültig ist, empfielt sich ein Vergleich mit  
"Const INVALID_HANDLE_VALUE = -1" durchzuführen.
+
Const [[INVALID_HANDLE_VALUE]] As Long = -1 durchzuführen.
  
  
  
'''Sonstige Hinweise:'''
+
==Hinweise==
  
Um ein Objekthandle wieder zu schließen (und das Objekt damit ggf. freizugeben), ist die [[CloseHandle]] - Funktion zu verwenden.
+
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[http://msdn2.microsoft.com/en-us/library/aa914735.aspx#]
+
Weitere Hinweise, wie beispielsweise zur Verwendung mit [[FILE_FLAG_NO_BUFFERING]] finden sich in der MSDN Libary.
 +
<br><br>
  
 
+
===Beispiel:===
 
+
<syntaxhighlight lang="vb">
'''Beispiel:'''
 
<pre>
 
 
     FileHandle = CreateFile(Path, GENERIC_READ, FILE_SHARE_READ Or _
 
     FileHandle = CreateFile(Path, GENERIC_READ, FILE_SHARE_READ Or _
                             FILE_SHARE_WRITE, ByVal 0&, OPEN_EXISTING, _
+
                             FILE_SHARE_WRITE, 0, OPEN_EXISTING, _
 
                             FILE_FLAG_NO_BUFFERING, 0)
 
                             FILE_FLAG_NO_BUFFERING, 0)
 
      
 
      
     If Not FileHandle <> INVALID_HANDLE_VALUE Then
+
     If FileHandle = INVALID_HANDLE_VALUE Then
 
         'Fehler beim Zugriff
 
         'Fehler beim Zugriff
 
     End If
 
     End If
</pre>
+
</syntaxhighlight>
 +
<br>
 +
 
 +
==Verweise==
  
 +
[http://msdn2.microsoft.com/en-us/library/aa363858.aspx MSDN Libary: CreateFile]<br>
 +
[http://msdn2.microsoft.com/en-us/library/aa364399.aspx MSDN Libary: File Security and Access Rights]
  
 +
[[Kategorie:Dateien und Laufwerke]]
 
[[Kategorie:Kernel]]
 
[[Kategorie:Kernel]]
 +
[[Kategorie:Funktionen]]

Aktuelle Version vom 7. Oktober 2016, 21:22 Uhr


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