CreateFile Function

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

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

CreateFile creates or opens a console, communications resource, directory (can only open), disk devices (Windows NT, 2000 only), files, mailslots, and pipes. Obviously, files are the most common thing opened by the function. The object opened can then be read from or written to, as the access level allows. After your program is finished using the handle generated by the function, it must call CloseHandle to close the open object.

Return Value

If an error occured, the function returns -1 (use GetLastError to get the error code). If successful, the function returns a handle to the opened or created file or other object.

Visual Basic-Specific Issues

When passing 0 as the lpSecurityAttributes parameter, the expression ByVal CLng(0) must be used to pass the zero correctly. See the example for a demonstration.

Parameters

lpFileName

The name of the file or other allowed object to create or open.

dwDesiredAccess

A combination of the following flags (if any) specifying the amounts of read/write access to the file or other object:

GENERIC_READ: Allow the program to read data from the file or other object.
GENERIC_WRITE: Allow the program to write data to the file or other object.

dwShareMode

A combination of the following flags (if any) specifying the amounts of read/write access to grant other programs attempting to access the file or other object while your program still has it open:

FILE_SHARE_READ: Allow other programs to read data from the file or other object.
FILE_SHARE_WRITE: Allow other programs to write data to the file or other object.

lpSecurityAppributes

Windows NT, 2000: A SECURITY_ATTRIBUTES structure specifying the security attributes to give the created or opened file or other object. Windows 95, 98, CE: This parameter must be 0.

dwCreationDisposition

Exactly one of the following flags specifying how and when to create or open the file or other object depending if it already does or does not exist:

CREATE_ALWAYS: Create a new file or other object. Overwrite the file or other object (i.e., delete the old one first) if it already exists.
CREATE_NEW: Create a new file or other object. The function fails if the file or other object already exists.
OPEN_ALWAYS: Open an existing file or other object. If the file or other object does not exist, it will be created.
OPEN_EXISTING: Open an existing file or other object. The function fails if the file or other object does not exist.
TRUNCATE_EXISTING: Open an existing file or other object and delete its contents. The function fails if the file or other object does not exist.

dwFlagsAndAttributes

The combination of the following flags specifying both the file attributes of a newly created file and other options for creating or opening the file. One flag specifying the file attributes must be included.

FILE_ATTRIBUTE_ARCHIVE: An archive file (which most files are).
FILE_ATTRIBUTE_HIDDEN: A hidden file, not normally visible to the user.
FILE_ATTRIBUTE_NORMAL: An attribute-less file (cannot be combined with other attributes).
FILE_ATTRIBUTE_READONLY: A read-only file.
FILE_ATTRIBUTE_SYSTEM: A system file, used exclusively by the operating system.
FILE_FLAG_DELETE_ON_CLOSE: Delete the file once it is closed.
FILE_FLAG_NO_BUFFERING: Do not use any buffers or caches. If used, the following things must be done: access to the file must begin at whole number multiples of the disk's sector size; the amounts of data accessed must be a whole number multiple of the disk's sector size; and buffer addresses for I/O operations must be aligned on whole number multiples of the disk's sector size.
FILE_FLAG_OVERLAPPED: Allow asynchronous I/O; i.e., allow the file to be read from and written to simultaneously. If used, functions that read and write to the file must specify the OVERLAPPED structure identifying the file pointer. (Windows 95, 98, CE: Overlapped files are not supported, although other overlapped objects are.)
FILE_FLAG_POSIX_SEMANTICS: Allow file names to be case-sensitive.
FILE_FLAG_RANDOM_ACCESS: Optimize the file cache for random access (skipping around to various parts of the file).
FILE_FLAG_SEQUENTIAL_SCAN: Optimize the file cache for sequential access (starting at the beginning and continuing to the end of the file).
FILE_FLAG_WRITE_THROUGH: Bypass any disk cache and instead read and write directly to the file.

hTemplateFile

A handle to an open file to copy the attributes of, or 0 to not copy the attributes of any open file.

Constant Definitions

Const GENERIC_READ = &H80000000
Const GENERIC_WRITE = &H40000000
Const FILE_SHARE_READ = &H1
Const FILE_SHARE_WRITE = &H2
Const CREATE_ALWAYS = 2
Const CREATE_NEW = 1
Const OPEN_ALWAYS = 4
Const OPEN_EXISTING = 3
Const TRUNCATE_EXISTING = 5
Const FILE_ATTRIBUTE_ARCHIVE = &H20
Const FILE_ATTRIBUTE_HIDDEN = &H2
Const FILE_ATTRIBUTE_NORMAL = &H80
Const FILE_ATTRIBUTE_READONLY = &H1
Const FILE_ATTRIBUTE_SYSTEM = &H4
Const FILE_FLAG_DELETE_ON_CLOSE = &H4000000
Const FILE_FLAG_NO_BUFFERING = &H20000000
Const FILE_FLAG_OVERLAPPED = &H40000000
Const FILE_FLAG_POSIX_SEMANTICS = &H1000000
Const FILE_FLAG_RANDOM_ACCESS = &H10000000
Const FILE_FLAG_SEQUENTIAL_SCAN = &H8000000
Const FILE_FLAG_WRITE_THROUGH = &H80000000

Example

' This code is licensed according to the terms and conditions listed here.

' Display the date on which the file C:\MyApp\test.txt was
' created.  Note how the time zone conversion is necessary.
Dim hFile As Long  ' handle to the opened file
Dim ctime As FILETIME  ' receives time of creation
Dim atime As FILETIME  ' receives time of last access
Dim mtime As FILETIME  ' receives time of last modification
Dim thetime As SYSTEMTIME  ' used to manipulate the time
Dim retval As Long  ' return value

' First, open the file C:\MyApp\test.txt for read-level access.  Note the
' expression necessary to pass 0 as lpSecurityAttributes.
hFile = CreateFile("C:\MyApp\test.txt", GENERIC_READ, FILE_SHARE_READ, ByVal CLng(0), OPEN_EXISTING, FILE_ATTRIBUTE_ARCHIVE, 0)
If hFile = -1 Then
  Debug.Print "Could not open the file successfully -- aborting."
  End  ' terminate the program
End If

' Next, get the creation, last-access, and last-modification times.
retval = GetFileTime(hFile, ctime, atime, mtime)
' Convert the creation time to the local time zone.
retval = FileTimeToLocalFileTime(ctime, ctime)
' Convert the FILETIME format to the SYSTEMTIME format.
retval = FileTimeToSystemTime(ctime, thetime)

' Display the date of creation of the file to the user.
Debug.Print "The file was created on "; thetime.wMonth; "-"; thetime.wDay; "-"; thetime.wYear

' Close the file to free up resources.
retval = CloseHandle(hFile)