Program Development using Unix Win32 File API

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);

HANDLE CreateFile(
    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 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.

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_ARCHIVE
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

This 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.

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.

The DeleteFile function deletes an existing file.

BOOL DeleteFile(
    LPCTSTR lpFileName 	// pointer to name of file to delete  
   );	

This closes the handle to any object, including file handles:

BOOL CloseHandle(
    HANDLE hObject 	// handle to object to close  
   );

closes any open object.

BOOL ReadFile(
    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 
   );	

The function attepts to read a number of bytes into a buffer, setting the actual number read into 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.

BOOL WriteFile(
    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
   );	

Here is a file copy:

#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
}

The GetFileInformationByHandle function retrieves information about a specified file.

BOOL GetFileInformationByHandle(
    HANDLE hFile,     // handle of file 
    LPBY_HANDLE_FILE_INFORMATION lpFileInformation     // address of structure 
   );    

where

typedef struct _BY_HANDLE_FILE_INFORMATION { // bhfi  
    DWORD    dwFileAttributes; 
    FILETIME ftCreationTime; 
    FILETIME ftLastAccessTime; 
    FILETIME ftLastWriteTime; 
    DWORD    dwVolumeSerialNumber; 
    DWORD    nFileSizeHigh; 
    DWORD    nFileSizeLow; 
    DWORD    nNumberOfLinks; 
    DWORD    nFileIndexHigh; 
    DWORD    nFileIndexLow; 
} BY_HANDLE_FILE_INFORMATION; 

The following program extracts some of this:

#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
}

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