核心分類架構
Win32 檔案系統 API 橫跨檔案/目錄管理、檔案 I/O、記憶體映射檔案、壓縮檔案、臨時檔案、磁碟資訊、檔案屬性/時間、版本資源、INI/登錄操作、檔案搜尋、路徑處理 等領域。本文依功能域系統整理，並標註關鍵使用情境與遷移建議。
一、檔案與目錄基礎操作
| API | 功能 | 備註/現代替代 |
|---|
CreateFile | 建立/開啟檔案、管道、通訊埠、裝置 | 核心 API，dwCreationDisposition 控制建立/開啟/覆寫/截斷語意 |
CloseHandle | 關閉核心物件 (檔案、對應、程序、執行緒、同步物件) | 通用關閉函數，必配對使用 |
ReadFile/WriteFile | 同步讀寫 | 搭配 OVERLAPPED 可非同步 |
ReadFileEx/WriteFileEx | 非同步讀寫 + 完成常式 | 僅支援非同步，需警示狀態執行緒 |
SetFilePointer/SetFilePointerEx | 移動檔案指標 | Ex 版支援 64-bit 位移 |
SetEndOfFile | 截斷/擴展檔案至目前指標 | |
FlushFileBuffers | 強制寫入磁碟 | 效能成本高，謹慎使用 |
CopyFile/CopyFileEx | 複製檔案 | Ex 版支援進度回呼、可取消 |
MoveFile/MoveFileEx | 移動/重命名 (跨磁碟自動複製+刪除) | Ex 版支援延遲至重開機、覆寫唯讀 |
DeleteFile | 刪除檔案 | 目錄用 RemoveDirectory |
CreateDirectory/CreateDirectoryEx | 建立目錄 (可指定安全性/模板) | |
RemoveDirectory | 刪除空目錄 | |
二、檔案屬性、時間與資訊查詢
| API | 功能 |
|---|
GetFileAttributes/SetFileAttributes | 取得/設定屬性 (唯讀、隱藏、系統、壓縮、加密、離線等) |
GetFileTime/SetFileTime | 建立/最後存取/最後寫入時間 (FILETIME 結構，UTC) |
GetFileSize/GetFileSizeEx | 取得檔案大小 (Ex 支援 64-bit) |
GetFileInformationByHandle | 一次取得屬性、時間、大小、連結數、檔案索引等完整資訊 |
GetFileType | 判斷檔案類型 (磁碟/字元/管道/遠端) |
GetCompressedFileSize | 取得壓縮檔實際磁碟佔用大小 |
GetBinaryType | 判斷是否可執行檔及子系統類型 |
時間格式轉換
| API | 轉換方向 |
|---|
FileTimeToSystemTime / SystemTimeToFileTime | FILETIME (UTC, 100ns) ↔ SYSTEMTIME (年月日時分秒毫秒) |
FileTimeToLocalFileTime / LocalFileTimeToFileTime | UTC FILETIME ↔ 本地時間 FILETIME |
DosDateTimeToFileTime / FileTimeToDosDateTime | DOS 日期/時間 (16-bit) ↔ FILETIME |
三、進階 I/O 與鎖定機制
| API | 功能 |
|---|
LockFile/LockFileEx | 鎖定檔案區塊 (Ex 支援共享/獨佔、非阻塞、長度 64-bit) |
UnlockFile/UnlockFileEx | 解除鎖定 |
DeviceIoControl | 裝置控制碼 (IOCTL) 直接控制驅動程式/檔案系統 |
GetOverlappedResult | 查詢非同步作業完成狀態 |
四、記憶體映射檔案 (共享記憶體/大檔案高效存取)
| 步驟 | API | 說明 |
|---|
| 1. 建立/開啟映射物件 | CreateFileMapping / OpenFileMapping | 指定分頁檔或現有檔案、大小、保護屬性、名稱 (跨程序共享) |
| 2. 映射視圖至位址空間 | MapViewOfFile / MapViewOfFileEx | 指定位移、大小、存取權限，傳回基底位址 |
| 3. 直接操作記憶體 | — | 指標讀寫，系統自動分頁管理 |
| 4. 釋放視圖 | UnmapViewOfFile | |
| 5. 關閉映射物件 | CloseHandle | |
| 同步寫入磁碟 | FlushViewOfFile | 指定基底位址與長度 |
五、目錄與磁碟管理
| API | 功能 |
|---|
GetCurrentDirectory/SetCurrentDirectory | 進程目前工作目錄 |
GetLogicalDrives/GetLogicalDriveStrings | 列舉磁碟機代號 |
GetDriveType | 判斷磁碟類型 (可移除/固定/網路/CD-ROM/RAM) |
GetDiskFreeSpace/GetDiskFreeSpaceEx | 取得磁碟空間資訊 (Ex 支援 64-bit、NTFS 壓縮/配額) |
GetVolumeInformation | 磁碟卷標、序號、檔案系統、旗標 (支援長檔名、壓縮、加密、配額等) |
SetVolumeLabel | 設定磁碟卷標 |
六、檔案搜尋與路徑處理
| API | 功能 |
|---|
FindFirstFile/FindFirstFileEx | 開始搜尋 (Ex 支援大檔案、層級搜尋、屬性過濾) |
FindNextFile | 繼續搜尋 |
FindClose | 關閉搜尋控制代碼 |
SearchPath | 在 PATH 環境變數中尋找檔案 |
GetFullPathName | 相對路徑轉絕對路徑 |
GetShortPathName/GetLongPathName | 8.3 短檔名 ↔ 長檔名轉換 |
GetTempPath/GetTempFileName | 取得/建立臨時檔案路徑 |
GetSystemDirectory/GetWindowsDirectory | 取得系統/Windows 目錄 |
七、壓縮檔案操作 (LZ 系列 — 舊版相容)
注意：LZ 系列 (LZOpenFile, LZRead, LZSeek, LZClose, LZCopy, LZInit) 為 16-bit 相容層，現代開發請改用 Zlib、LZMA SDK 或 Windows Compress API (CreateCompressor 等)。
八、檔案版本資源
| API | 功能 |
|---|
GetFileVersionInfoSize | 取得版本資源緩衝區大小 |
GetFileVersionInfo | 擷取版本資源至緩衝區 |
VerQueryValue | 從版本資源查詢特定值 (字串表、固定資訊、翻譯資訊) |
VerFindFile/VerInstallFile | 安裝程式判斷檔案目的地/執行安裝 |
VerLanguageName | 語言代碼轉語言名稱 |
九、INI 檔案操作 (傳統 — 建議改用登錄/XML/JSON)
| 範圍 | 讀取 | 寫入 |
|---|
系統 win.ini | GetProfileInt/GetProfileString/GetProfileSection | WriteProfileString/WriteProfileSection |
應用程式 .ini | GetPrivateProfileInt/GetPrivateProfileString/GetPrivateProfileSection | WritePrivateProfileString/WritePrivateProfileSection |
十、登錄操作 — 系統設定核心儲存
鍵值管理
| API | 功能 | 建議版本 |
|---|
| 開啟/建立鍵 | RegOpenKeyEx/RegCreateKeyEx | Ex 版 (支援安全性、選項、Disposition 回傳) |
| 關閉鍵 | RegCloseKey | |
| 刪除鍵/值 | RegDeleteKey/RegDeleteValue | |
| 列舉子鍵/值 | RegEnumKeyEx/RegEnumValue | Ex 版 (支援類別名稱、時間戳) |
| 查詢/設定值 | RegQueryValueEx/RegSetValueEx | 支援多種資料型別 (REG_SZ, REG_DWORD, REG_BINARY, REG_MULTI_SZ, REG_EXPAND_SZ...) |
| 查詢鍵資訊 | RegQueryInfoKey | 子鍵數、值數、最大名稱/資料長度、最後寫入時間、安全性描述項 |
進階登錄功能
| API | 功能 |
|---|
RegConnectRegistry | 連線遠端電腦登錄 |
RegFlushKey | 強制寫入磁碟 (通常不需呼叫) |
RegSaveKey/RegRestoreKey/RegReplaceKey | 鍵值備份/還原/替換 (需備份權限) |
RegLoadKey/RegUnLoadKey | 載入/卸載配置單元檔案 |
RegNotifyChangeKeyValue | 非同步監視鍵值變更 (配合事件物件) |
RegGetKeySecurity/RegSetKeySecurity | 存取控制 (ACL) 讀寫 |
十一、舊版檔案 I/O (16-bit 相容 — 勿用於新專案)
_lopen, _lcreat, _lread, _lwrite, _lclose, _llseek, _hread, _hwrite — 僅為相容 Win16 程式碼移植保留，功能受限 (無安全性、無 64-bit、無非同步)。
最佳實務總結
- 一律使用
CreateFile + ReadFile/WriteFile + CloseHandle 核心三件組
- 大檔案 (>4GB) 必須使用 Ex 版 API (
GetFileSizeEx, SetFilePointerEx, FindFirstFileEx)
- 非同步 I/O：
FILE_FLAG_OVERLAPPED + ReadFileEx/WriteFileEx + 完成常式 / I/O 完成埠 (IOCP)
- 共享記憶體/超大檔案：
CreateFileMapping + MapViewOfFile — 系統自動分頁，效能最佳
- 登錄：僅儲存小型設定資料；大量資料請用檔案/資料庫
- 錯誤處理：檢查傳回值，呼叫
GetLastError 取得詳細錯誤碼
