File System API Reference

This section details the Windows API functions and structures for interacting with the file system.

File and Directory Management

CreateFile

HANDLE CreateFile( LPCWSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile );

Opens or creates a file or device. This is a fundamental function for file system operations.

Parameters:

Parameter Type Description
lpFileName LPCWSTR The name of the file or device to be created or opened.
dwDesiredAccess DWORD The generic access rights for the file.
dwShareMode DWORD How to share the file or device with other threads.
dwCreationDisposition DWORD Action to take if the file exists or does not exist.

Return Value:

HANDLE A handle to the opened file or device. INVALID_HANDLE_VALUE on failure.
Always check the return value of CreateFile for INVALID_HANDLE_VALUE and use GetLastError to retrieve error information.

ReadFile

BOOL ReadFile( HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped );

Reads data from a file or device. Typically used after opening a handle with CreateFile.

Parameters:

Parameter Type Description
hFile HANDLE A handle to the file or device.
lpBuffer LPVOID A buffer that receives the data read from the file.
nNumberOfBytesToRead DWORD The maximum number of bytes to be read.
lpNumberOfBytesRead LPDWORD The number of bytes actually read.

Return Value:

BOOL TRUE on success, FALSE on failure.

WriteFile

BOOL WriteFile( HANDLE hFile, LPCVOID lpBuffer, DWORD nNumberOfBytesToWrite, LPDWORD lpNumberOfBytesWritten, LPOVERLAPPED lpOverlapped );

Writes data to a file or device.

Parameters:

Parameter Type Description
hFile HANDLE A handle to the file or device.
lpBuffer LPCVOID A buffer containing the data to be written.
nNumberOfBytesToWrite DWORD The number of bytes to write.
lpNumberOfBytesWritten LPDWORD The number of bytes actually written.

Return Value:

BOOL TRUE on success, FALSE on failure.

CloseHandle

BOOL CloseHandle( HANDLE hObject );

Closes an open object handle.

Parameters:

Parameter Type Description
hObject HANDLE A handle to an open object, such as a file, a process, or a thread.

Return Value:

BOOL TRUE on success, FALSE on failure.
It's crucial to close handles when they are no longer needed to free system resources and prevent leaks.

Directory Operations

CreateDirectory

BOOL CreateDirectory( LPCWSTR lpPathName, LPSECURITY_ATTRIBUTES lpAttribute );

Creates a new directory, including any necessary parent directories.

Parameters:

Parameter Type Description
lpPathName LPCWSTR The path of the directory to create.
lpAttribute LPSECURITY_ATTRIBUTES Security attributes for the directory. Can be NULL.

Return Value:

BOOL TRUE if the directory was created, FALSE otherwise.

RemoveDirectory

BOOL RemoveDirectory( LPCWSTR lpPathName );

Removes an existing directory. The directory must be empty.

Parameters:

Parameter Type Description
lpPathName LPCWSTR The path of the directory to remove.

Return Value:

BOOL TRUE if the directory was removed, FALSE otherwise.

File Attributes and Information

GetFileAttributes

DWORD GetFileAttributes( LPCWSTR lpFileName );

Retrieves the file system attributes for a specified file or directory.

Parameters:

Parameter Type Description
lpFileName LPCWSTR The name of the file or directory.

Return Value:

DWORD The file attributes. INVALID_FILE_ATTRIBUTES on failure.

Common attribute flags include:

  • FILE_ATTRIBUTE_ARCHIVE
  • FILE_ATTRIBUTE_DIRECTORY
  • FILE_ATTRIBUTE_HIDDEN
  • FILE_ATTRIBUTE_NORMAL
  • FILE_ATTRIBUTE_READONLY
  • FILE_ATTRIBUTE_SYSTEM
  • FILE_ATTRIBUTE_TEMPORARY