Win32 File Management API

Overview

The Win32 File Management API provides a comprehensive set of functions for interacting with the file system on Windows. This includes creating, reading, writing, deleting, and managing files and directories, as well as controlling access permissions and retrieving file attributes.

Core Functions

CreateFile

Description: Creates or opens a file or I/O device. It is the primary function for accessing files.

HANDLE CreateFile( _In_ LPCTSTR lpFileName, _In_ DWORD dwDesiredAccess, _In_ DWORD dwShareMode, _In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes, _In_ DWORD dwCreationDisposition, _In_ DWORD dwFlagsAndAttributes, _In_opt_ HANDLE hTemplateFile );
Parameters:
  • lpFileName: The name of the file or device to be created or opened.
  • dwDesiredAccess: The generic access rights to the file.
  • dwShareMode: How the file can be shared by the calling process with other processes.
  • lpSecurityAttributes: A SECURITY_ATTRIBUTES structure that contains information about the security descriptor for the file.
  • dwCreationDisposition: An action to take if the file already exists or does not exist.
  • dwFlagsAndAttributes: The file system attributes and flags for the file.
  • hTemplateFile: A handle to a template file with the attributes and extended attributes that are to be copied to the file being created.
Return Value: If the function succeeds, the return value is an open handle to the specified file or device. If the function fails, the return value is INVALID_HANDLE_VALUE.
See Also:

ReadFile

Description: Reads data from a file or I/O device. It fills a buffer with data read from the specified file or device.

BOOL ReadFile( _In_ HANDLE hFile, _Out_ LPVOID lpBuffer, _In_ DWORD nNumberOfBytesToRead, _Out_opt_ LPDWORD lpNumberOfBytesRead, _Inout_opt_ LPOVERLAPPED lpOverlapped );
Parameters:
  • hFile: A handle to the file or device that is to be read.
  • lpBuffer: A pointer to the buffer that receives the data read from the file or device.
  • nNumberOfBytesToRead: The maximum number of bytes to be read.
  • lpNumberOfBytesRead: A pointer to a variable that receives the number of bytes read.
  • lpOverlapped: A pointer to an OVERLAPPED structure.
Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.
See Also:

WriteFile

Description: Writes data to a file or I/O device. It writes data starting from the position indicated by the file pointer.

BOOL WriteFile( _In_ HANDLE hFile, _In_ LPCVOID lpBuffer, _In_ DWORD nNumberOfBytesToWrite, _Out_opt_ LPDWORD lpNumberOfBytesWritten, _Inout_opt_ LPOVERLAPPED lpOverlapped );
Parameters:
  • hFile: A handle to the file or device that is to be written to.
  • lpBuffer: A pointer to a buffer containing the data to be written.
  • nNumberOfBytesToWrite: The number of bytes to be written to the file or device.
  • lpNumberOfBytesWritten: A pointer to a variable that receives the number of bytes written.
  • lpOverlapped: A pointer to an OVERLAPPED structure.
Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.
See Also:

CloseHandle

Description: Closes an open object handle. A handle is a required parameter for most other Win32 API functions that operate on objects.

BOOL CloseHandle( _In_ HANDLE hObject );
Parameters:
  • hObject: A handle to an open object.
Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.
See Also:

GetFileSizeEx

Description: Retrieves the size of the specified file. This function is Unicode and ANSI compatible.

BOOL GetFileSizeEx( _In_ HANDLE hFile, _Out_ PLARGE_INTEGER lpFileSize );
Parameters:
  • hFile: A handle to the file.
  • lpFileSize: A pointer to a LARGE_INTEGER variable that receives the file size, in bytes.
Return Value: Returns TRUE if successful, FALSE otherwise.
See Also:

Directory Management

CreateDirectory

Description: Creates a new directory. If the parent directory does not exist, the function fails.

BOOL CreateDirectory( _In_ LPCTSTR lpPathName, _In_opt_ LPSECURITY_ATTRIBUTES lpAttribute );
Parameters:
  • lpPathName: The path of the directory to create.
  • lpAttribute: Security attributes.
Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

RemoveDirectory

Description: Deletes an existing empty directory. The directory must be empty to be removed.

BOOL RemoveDirectory( _In_ LPCTSTR lpPathName );
Parameters:
  • lpPathName: A pointer to a null-terminated string that names the directory to be deleted.
Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

FindFirstFile

Description: Searches a directory for a file or subdirectory with a name matching a specified string and returns the handle of a search. This handle can be used to retrieve other information about the file or directory.

HANDLE FindFirstFile( _In_ LPCTSTR lpFileName, _Out_ LPWIN32_FIND_DATAW lpFindFileData );
Parameters:
  • lpFileName: The root directory and the default path and file name mask to search for.
  • lpFindFileData: A pointer to a WIN32_FIND_DATA structure that receives information about a found file or directory.
Return Value: If the function succeeds, the return value is a search handle identifying the directory containing the specified files. If the function fails, the return value is INVALID_HANDLE_VALUE.
See Also: