前言
Windows SDK 提供豐富的檔案操作 API，涵蓋建立/讀寫、屬性查詢、目錄管理、記憶體映射、壓縮、鎖定等層面。本文分類整理最常用的 API，附帶關鍵參數與使用情境，供開發快速查閱。
一、基礎檔案 I/O (Handle-Based)
| API | 用途 | 關鍵參數/備註 |
|---|
CreateFile | 開啟/建立檔案，取得 Handle | 首選 API，支援 GENERIC_READ/WRITE、FILE_SHARE_*、OPEN_EXISTING/CREATE_ALWAYS 等 |
ReadFile | 同步讀取位元組 | 需搭配 OVERLAPPED 實作非同步 I/O |
WriteFile | 同步寫入位元組 | 同上 |
CloseHandle | 關閉 Handle | 務必配對呼叫，避免洩漏 |
GetFileSize / GetFileSizeEx | 取得檔案大小 | Ex 版本支援 64-bit (LARGE_INTEGER) |
GetFileTime | 取得建立/存取/寫入時間 | 回傳 FILETIME 結構 |
SetFilePointer / SetFilePointerEx | 移動檔案指標 | 隨機存取關鍵 |
SetEndOfFile | 截斷/擴展檔案 | 配合 SetFilePointer 使用 |
二、檔案屬性與資訊
| API | 用途 | 備註 |
|---|
GetFileAttributes / GetFileAttributesEx | 取得屬性 (唯讀、隱藏、系統、封存...) | Ex 版本回傳 WIN32_FILE_ATTRIBUTE_DATA 含時間/大小 |
SetFileAttributes | 設定屬性 | 不可修改目錄屬性 |
GetFileInformationByHandle | 一次取得完整資訊 | 含檔案索引、連結數、卷標序號等唯一識別資訊 |
GetFullPathName | 轉換為完整路徑 | 僅對當前目錄相對路徑正確；絕對路徑建議用 GetModuleFileName |
三、檔案/目錄管理
| API | 用途 | 備註 |
|---|
CopyFile / CopyFileEx | 複製檔案 | Ex 支援進度回呼、可取消；無法複製目錄 |
MoveFile / MoveFileEx | 移動/重命名檔案或目錄 | Ex 支援 MOVEFILE_REPLACE_EXISTING、MOVEFILE_COPY_ALLOWED (跨磁碟) |
DeleteFile | 刪除檔案 | 目錄請用 RemoveDirectory |
CreateDirectory / CreateDirectoryEx | 建立目錄 | Ex 可複製安全屬性 |
RemoveDirectory | 刪除空目錄 | 非空目錄需遞迴刪除內容 |
FindFirstFile / FindNextFile | 列舉目錄內容 | 配合 WIN32_FIND_DATA |
GetTempPath | 取得暫存目錄路徑 | 通常 %TEMP% |
GetTempFileName | 建立唯一暫存檔 | 自動產生檔名，避免衝突 |
四、檔案鎖定 (同步/共享控制)
| API | 用途 |
|---|
LockFile / LockFileEx | 鎖定檔案區間 (獨佔/共享) |
UnlockFile / UnlockFileEx | 解除鎖定 |
應用場景：多行程/多執行緒同時存取同一檔案不同區塊，或實作簡易記錄鎖定機制。
五、檔案壓縮 (LZ 擴展庫)
| API | 用途 |
|---|
LZOpenFile | 開啟壓縮檔讀取 |
LZRead / LZSeek | 讀取/定位壓縮檔 |
LZClose | 關閉壓縮檔 |
LZCopy | 複製並解壓縮 |
GetExpandedName | 取得壓縮檔原始檔名 |
註：需連結 LZ32.lib，壓縮檔通常由 compress.exe 產生 (.gz/.lz 格式)。現代專案建議改用 zlib 或 Windows Compression API (MSZIP/LZX)。
六、記憶體映射檔案 (大檔案/共享記憶體首選)
| API | 用途 |
|---|
CreateFileMapping | 建立/開啟檔案映射物件 |
MapViewOfFile / MapViewOfFileEx | 將映射檢視對應至進程位址空間 |
UnmapViewOfFile | 解除對應 |
FlushViewOfFile | 強制寫回磁碟 |
優勢：系統自動分頁管理，隨機存取效能極佳，亦可作為行程間共享記憶體 (命名映射)。
七、實務建議清單
- 一律檢查回傳值為
INVALID_HANDLE_VALUE / FALSE / 0，並呼叫 GetLastError() 診斷。
- 大於 4GB 檔案務必使用
GetFileSizeEx、SetFilePointerEx、LARGE_INTEGER。
- 非同步 I/O 需配合
FILE_FLAG_OVERLAPPED、OVERLAPPED 結構與 GetOverlappedResult/IOCP。
- 共享模式 (
FILE_SHARE_READ/WRITE/DELETE) 謹慎設定，避免鎖死被其他程序存取。
- 路徑長度超過 MAX_PATH (260) 時，使用
\\?\ 前綴 (如 \\?\C:\Very\Long\Path) 支援 32,767 字元。
結語
熟練掌握上述 API 分類與關鍵參數，能應對 90% 以上的檔案操作需求。現代 C++ 專案建議封裝為 RAII 型別 (如 unique_handle、file_view)，或直接使用 C++17 std::filesystem、std::fstream 簡化跨平台開發；但在需要精細控制共享模式、記憶體映射、非同步 I/O 等進階場景時，原生 Win32 API 仍是不可替代的工具。
