Contents
CreateFile
DeleteFile
CloseHandle
ReadFile
WriteFile
File Information
Use of these functions
The Win32 API provides a set of functions to perform the general operations available on files. The functions include
HANDLE CreateFile(...);
BOOL DeleteFile(LPCWSTR lpFileName);
BOOL MoveFile(LPCWSTR lpExistingFileName, LPCWSTR lpNewFileName);
BOOL CloseHandle(HANDLE hObject);
BOOL ReadFile(...);
BOOL WriteFile(...);
DWORD SetFilePointer(...);
DWORD GetFileAttributes(LPCTSTR lpFileName);
BOOL GetFileInformationByHandle(HANDLE hFile,
LPBY_HANDLE_FILE_INFORMATION lpFileInformation);
BOOL SetFileAttributes(ileAttributesW(LPCWSTR lpFileName,
DWORD dwFileAttributes);
CreateFile
HANDLE CreateFile(The CreateFile function creates, opens, or truncates a file, pipe, mailslot, communications resource, disk device, or console. It returns a handle that can be used to access the object. It can also open and return a handle to a directory.
LPCTSTR lpFileName, // pointer to name of the file
DWORD dwDesiredAccess, // access (read-write) mode
DWORD dwShareMode, // share mode
LPSECURITY_ATTRIBUTES lpSecurityAttributes, // pointer to security descriptor
DWORD dwCreationDistribution, // how to create
DWORD dwFlagsAndAttributes, // file attributes
HANDLE hTemplateFile // handle to file with attributes to copy
);
The lpFileName
can be set to an absolute or relative path, and has a maximum length of MAX_PATH
.
The dwDesiredAccess
can be set to GENERIC_READ
and/or GENERIC_WRITE
.
The dwShareMode
can be set to allow no other proces to gain access while the file is open, or to grant read-share or write-share access.
The dwCreationDistribution
specifies behaviour to take on files that exist or do not exist, with values
-
CREATE_NEW
which fails if the file already exists -
CREATE_ALWAYS
which overwrites any existing file -
TRUNCATE_EXISTING
which fails of the file already exists
The dwFlagsAndAttributes
specifies file attributes as a combination of
FILE_ATTRIBUTE_ARCHIVEThis gets worse: if the file is a pipe, there may also be ``quality of service'' flags specified! Security permissions may also be set over and above those of the DOS file system.
FILE_ATTRIBUTE_COMPRESSED
FILE_ATTRIBUTE_HIDDEN
FILE_ATTRIBUTE_NORMAL
FILE_ATTRIBUTE_OFFLINE
FILE_ATTRIBUTE_READONLY
FILE_ATTRIBUTE_SYSTEM
FILE_ATTRIBUTE_TEMPORARY
FILE_FLAG_WRITE_THROUGH
FILE_FLAG_OVERLAPPED
FILE_FLAG_NO_BUFFERING
FILE_FLAG_RANDOM_ACCESS
FILE_FLAG_SEQUENTIAL_SCA
FILE_FLAG_DELETE_ON_CLOSE
FILE_FLAG_BACKUP_SEMANTICS
FILE_FLAG_POSIX_SEMANTICS
If CreateFile
succeeds, it will return a handle to the open file. There are many circumstances in which it might fail (such as creating an existing file with CREATE_NEW
specified). On failure INVALID_HANDLE_VALUE
is returned. More information on errors is available by the GetLastError()
call.
DeleteFile
BOOL DeleteFile(
LPCTSTR lpFileName // pointer to name of file to delete
);
CloseHandle
BOOL CloseHandle(closes any open object.
HANDLE hObject // handle to object to close
);
ReadFile
BOOL ReadFile(The function attepts to read a number of bytes into a buffer, setting the actual number read into
HANDLE hFile, // handle of file to read
LPVOID lpBuffer, // address of buffer that receives data
DWORD nNumberOfBytesToRead, // number of bytes to read
LPDWORD lpNumberOfBytesRead, // address of number of bytes read
LPOVERLAPPED lpOverlapped // address of structure for data
);
lpNumberOfBytesRead
. If the function succeeds, the return value is TRUE. If the return value is TRUE and the number of bytes read is zero, the file pointer was beyond the current end of the file at the time of the read operation.
WriteFile
BOOL WriteFile(Here is a file copy:
HANDLE hFile, // handle to file to write to
LPCVOID lpBuffer, // pointer to data to write to file
DWORD nNumberOfBytesToWrite, // number of bytes to write
LPDWORD lpNumberOfBytesWritten, // pointer to number of bytes written
LPOVERLAPPED lpOverlapped // pointer to structure needed for overlapped I/O
);
#include <iostream.h>
#include <windows.h>
const int BUF_SIZE = 1024;
int main(int argc, char *argv[])
{
HANDLE fileIn, fileOut;
char buf[BUF_SIZE];
char inName[MAX_PATH],
outName[MAX_PATH];
DWORD nread,nwrote;
cout << "Source file name:";
cin >> inName;
cout << "Destination file name:";
cin >> outName;
if ((fileIn = CreateFile(inName, GENERIC_READ,
0, 0, OPEN_EXISTING, 0, 0)) ==
INVALID_HANDLE_VALUE) {
cerr << "Error opening source: " <<
GetLastError() << endl;
exit(1);
}
if ((fileOut = CreateFile(outName, GENERIC_WRITE,
0, 0, CREATE_NEW, 0, 0)) ==
INVALID_HANDLE_VALUE) {
cerr << "Error opening destination: " <<
GetLastError() << endl;
exit(2);
}
while (ReadFile(fileIn, buf, BUF_SIZE,
&nread, NULL) && nread > 0) {
if ( ! WriteFile(fileOut, buf, nread,
&nwrote, NULL)) {
cerr << "Error writing" <<
GetLastError() << endl;
}
}
CloseHandle(fileIn);
CloseHandle(fileOut);
exit(0);
return 0; // never reached
}
File Information
BOOL GetFileInformationByHandle(where
HANDLE hFile, // handle of file
LPBY_HANDLE_FILE_INFORMATION lpFileInformation // address of structure
);
typedef struct _BY_HANDLE_FILE_INFORMATION { // bhfiThe following program extracts some of this:
DWORD dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
DWORD dwVolumeSerialNumber;
DWORD nFileSizeHigh;
DWORD nFileSizeLow;
DWORD nNumberOfLinks;
DWORD nFileIndexHigh;
DWORD nFileIndexLow;
} BY_HANDLE_FILE_INFORMATION;
#include <iostream.h>
#include <windows.h>
const int BUF_SIZE = 1024;
int main(int argc, char *argv[])
{
char inName[BUF_SIZE];
HANDLE fileIn;
BY_HANDLE_FILE_INFORMATION bhfi;
cout << "Source file name:";
cin >> inName;
if ((fileIn = CreateFile(inName, GENERIC_READ,
0, 0, OPEN_EXISTING, 0, 0)) ==
INVALID_HANDLE_VALUE) {
cerr << "Error opening source: " <<
GetLastError() << endl;
exit(1);
}
if (GetFileInformationByHandle(fileIn,
&bhfi)) {
cout << "Created: " <<
bhfi.ftCreationTime.dwLowDateTime <<
endl;
}
CloseHandle(fileIn);
exit(0);
return 0; // never reached
}
Use of these functions
When should you use these low-level functions? Only when you have to. In general use the high-level functions. There will be many times when you need finer control.
Note that these functions are specific to the Win32 API, and are not in Unix C, for example. So code written using these functions will only be portable across Windows platforms, not to other Operating Systems.
CreateFile
- It can set DOS and higher level access to files
- It can be used on pipes and other non-file devices
- It can be used on existing or new files
- It can open directories
- It can set sharing attributes
- It can set buffering attributes