System software Win32 file API

Document directory

• Createfile

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

ThelpFileName
Can be set to an absolute or relative path,
And has a maximum lengthMAX_PATH
.

ThedwDesiredAccess
Can be setGENERIC_READ
And/orGENERIC_WRITE
.

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

ThedwCreationDistribution
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

ThedwFlagsAndAttributes
Specifies file attributes as
Combination

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
Service ''flags specified! Security permissions may also be set
Over and above those of the DOS file system.

IfCreateFile
Succeeds, it will return a handle to
Open file. There are invalid circumstances in which it might fail
(Such as creating an existing fileCREATE_NEW

Specified ).
On failureINVALID_HANDLE_VALUE
Is returned.
More information on errors is available byGetLastError()
Call.

Deletefile

The deletefile function deletes an existing file.

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

Closehandle

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

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

Closes any open object.

Readfile

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 readlpNumberOfBytesRead
.
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
Time of the read operation.

Writefile

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
}

File Information

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
}

Use of these functions

When should you use these low-level functions? Only when you have.
In general
Use the High-level functions. There will be available 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
Guest SS Windows platforms, not to other operating systems.

Createfilethis function is a multi-purpose function that can be used to control
All sorts of situations

• 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