前言
呼叫 Windows API (P/Invoke) 時,正確對應 C/C++ 型別至 C# 型別至關重要,錯誤會導致記憶體損毀、存取違規或邏輯錯誤。本表整理最常用的 Win32 型別對應,並說明關鍵陷阱。
基本整數與布林
| Win32 | C# | 備註 |
| BOOL | int / bool (需 [MarshalAs(UnmanagedType.Bool)]) | Win32 BOOL = 4 bytes,C# bool = 1 byte,建議用 int |
| BOOLEAN | byte | 1 byte |
| BYTE | byte | unsigned char |
| CHAR | sbyte | signed char |
| WORD | ushort | 16-bit unsigned |
| DWORD | uint | 32-bit unsigned |
| DWORD32 | uint | |
| DWORD64 / ULONGLONG | ulong | 64-bit unsigned |
| INT / INT32 / LONG / LONG32 | int | 32-bit signed |
| INT64 / LONG64 / LONGLONG | long | 64-bit signed |
| UINT / UINT32 / ULONG / ULONG32 | uint | 32-bit unsigned |
| UINT64 / ULONG64 | ulong | |
| SHORT | short | 16-bit signed |
| USHORT | ushort | |
指標與控制代碼 (Handle)
| Win32 | C# | 備註 |
| HANDLE / HWND / HMODULE / HINSTANCE / HICON / HBITMAP / HBRUSH / HPEN / HFONT / HDC / HKEY / HRGN / HMENU / HACCEL / HDWP / HDDEDATA / HDESK / HDROP / HENHMETAFILE / HFILE / HGDIOBJ / HGLOBAL / HHOOK / HIMAGELIST / HIMC / HLOCAL / HMETAFILE / HMONITOR / HPALETTE / HRSRC / HSZ / HWINSTA / SC_HANDLE / SC_LOCK | IntPtr | 平台相容 (32/64-bit 自動對應),絕對不可用 int/long |
| LPVOID / PVOID / LPCVOID | IntPtr | 通用指標 |
| LPSTR / LPCSTR / LPCTSTR / LPTSTR / LPCWSTR / LPWSTR / PSTR / PCSTR / PCTSTR / PCWSTR / PWSTR | string / StringBuilder | 字串參數用 string (In) 或 StringBuilder (Out),加 CharSet 指定 ANSI/Unicode |
| LPBOOL / LPBYTE / LPDWORD / LPINT / LPLONG / LPWORD / LPWSTR | ref / out / IntPtr + Marshal | 輸出參數用 ref/out,陣列用 [] 或 IntPtr + Marshal.Copy |
結構體對齊關鍵
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto, Pack = 1)] // Pack=1 依結構定義
public struct RECT
{
public int Left, Top, Right, Bottom;
}
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
public struct POINT
{
public int X, Y;
}
Pack:指定記憶體對齊邊界,Win32 結構通常為 4 或 8,預設 8 通常正確,但某些舊結構需 `Pack=1`。
CharSet.Auto:依執行平台自動選 ANSI/Unicode (Windows NT 系列為 Unicode)。
- 布林欄位在結構中用
int (4 bytes) 對應 `BOOL`,用 `byte` 對應 `BOOLEAN`。
常見 API 簽名範例
[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Auto)]
public static extern IntPtr FindWindow(string lpClassName, string lpWindowName);
[DllImport("user32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
[DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Auto)]
public static extern IntPtr LoadLibrary(string lpFileName);
[DllImport("kernel32.dll", SetLastError = true, ExactSpelling = true)]
public static extern IntPtr VirtualAllocEx(
IntPtr hProcess,
IntPtr lpAddress,
UIntPtr dwSize, // SIZE_T -> UIntPtr
uint flAllocationType,
uint flProtect);
避坑指南
- CharSet 不匹配:API 名稱尾碼 `A` (ANSI) / `W` (Unicode),C# 宣告加 `CharSet = CharSet.Auto` 並用 `string`,CLR 會自動轉換。
- 布林回傳值:Win32 `BOOL` 回傳非零即真,C# 簽名加 `[return: MarshalAs(UnmanagedType.Bool)]` 才能正確轉為 `bool`。
- 字串輸出緩衝區:`StringBuilder sb = new StringBuilder(260); GetWindowText(hWnd, sb, sb.Capacity);`
- 結構體大小:呼叫需 `cbSize = Marshal.SizeOf(typeof(MYSTRUCT))` 的 API 時,務必正確填寫。
- SetLastError:加上 `SetLastError = true`,失敗時可呼叫 `Marshal.GetLastWin32Error()` 取得錯誤碼。