深入理解 ctypes 函数原型中的 DEFAULT_ZERO 与参数处理

DWORD WlanRegisterNotification(
  HANDLE                    hClientHandle,
  DWORD                     dwNotifSource,
  BOOL                      bIgnoreDuplicate,
  WLAN_NOTIFICATION_CALLBACK funcCallback,
  PVOID                     pCallbackContext,
  PVOID                     pReserved,
  PDWORD                    pdwPrevNotifSource
);

import ctypes
import ctypes.wintypes

# 假设已定义 WLAN_NOTIFICATION_CALLBACK, IN, OUT, DEFAULT_ZERO, wlanapi
# ... (代码省略，详见下文完整示例)

proto = ctypes.WINFUNCTYPE(
    ctypes.wintypes.DWORD,
    ctypes.wintypes.HANDLE,
    ctypes.wintypes.DWORD,
    ctypes.wintypes.BOOL,
    WLAN_NOTIFICATION_CALLBACK,
    ctypes.wintypes.LPVOID,
    ctypes.wintypes.LPVOID,
    ctypes.POINTER(ctypes.wintypes.DWORD),
)

fun = proto(
    ('WlanRegisterNotification', wlanapi),
    (
        (IN, 'hClientHandle'),
        (IN, 'dwNotifSource'),
        (IN, 'bIgnoreDuplicate'),
        (IN | DEFAULT_ZERO, 'funcCallback'),   # 错误使用
        (IN | DEFAULT_ZERO, 'pCallbackContext'), # 错误使用
        (IN | DEFAULT_ZERO, 'pReserved'),      # 正确使用场景
        (OUT, 'pdwPrevNotifSource'),
    ),
)

import ctypes
import ctypes.wintypes

# 定义回调函数类型和常量
PWLAN_NOTIFICATION_DATA = ctypes.c_void_p
WLAN_NOTIFICATION_CALLBACK = ctypes.WINFUNCTYPE(None, PWLAN_NOTIFICATION_DATA, ctypes.wintypes.LPVOID)

# 定义一个空的或默认的WLAN_NOTIFICATION_CALLBACK实例
null_callback = WLAN_NOTIFICATION_CALLBACK()

# 定义一个示例回调函数
@WLAN_NOTIFICATION_CALLBACK
def callback(param1, param2):
    print(f"Callback invoked: {param1}, {param2}")

# 定义方向标志
IN = 1
OUT = 2
DEFAULT_ZERO = 4 # 仅用于pReserved

# 加载wlanapi库
wlanapi = ctypes.WinDLL('wlanapi')

# 定义函数原型
proto = ctypes.WINFUNCTYPE(
    ctypes.wintypes.DWORD, # 返回类型
    ctypes.wintypes.HANDLE, # hClientHandle
    ctypes.wintypes.DWORD, # dwNotifSource
    ctypes.wintypes.BOOL, # bIgnoreDuplicate
    WLAN_NOTIFICATION_CALLBACK, # funcCallback
    ctypes.wintypes.LPVOID, # pCallbackContext
    ctypes.wintypes.LPVOID, # pReserved
    ctypes.POINTER(ctypes.wintypes.DWORD), # pdwPrevNotifSource
)

# 绑定函数并指定参数信息
fun = proto(
    ('WlanRegisterNotification', wlanapi),
    (
        (IN, 'hClientHandle'),
        (IN, 'dwNotifSource'),
        (IN, 'bIgnoreDuplicate'),
        (IN, 'funcCallback', null_callback), # 显式提供默认值，允许覆盖
        (IN, 'pCallbackContext', None),      # 显式提供默认值，允许覆盖
        (IN | DEFAULT_ZERO, 'pReserved'),    # 使用DEFAULT_ZERO，表示不传递此参数
        (OUT, 'pdwPrevNotifSource'),
    ),
)

# 设置错误检查函数，方便调试
fun.errcheck = lambda result, func, args: (result, args[5]) # 假设 args[5] 是 pdwPrevNotifSource

# 各种调用方式
print("--- Using prototype with explicit defaults ---")
print(fun(0, 0, 0)) # 所有可选参数使用默认值
print(fun(0, 0, 0, callback)) # 提供 funcCallback
print(fun(0, 0, 0, callback, None)) # 提供 funcCallback 和 pCallbackContext (None)

# 尝试传递 pReserved 会失败，因为它是 DEFAULT_ZERO
try:
    print(fun(0, 0, 0, callback, None, None))
except TypeError as e:
    print(f"Error as expected: {e}") # TypeError: call takes exactly 5 arguments (6 given)

import ctypes as ct
import ctypes.wintypes as w

# 定义回调函数类型和常量 (同上)
PWLAN_NOTIFICATION_DATA = ct.c_void_p
WLAN_NOTIFICATION_CALLBACK = ct.WINFUNCTYPE(None, PWLAN_NOTIFICATION_DATA, w.LPVOID)
null_callback = WLAN_NOTIFICATION_CALLBACK()

@WLAN_NOTIFICATION_CALLBACK
def callback(param1, param2):
    print(f"Callback invoked: {param1}, {param2}")

# 加载wlanapi库
wlanapi = ct.WinDLL('wlanapi')

# 使用 .argtypes 和 .restype 定义C函数签名
wlanapi.WlanRegisterNotification.argtypes = (
    w.HANDLE,                     # hClientHandle
    w.DWORD,                      # dwNotifSource
    w.BOOL,                       # bIgnoreDuplicate
    WLAN_NOTIFICATION_CALLBACK,   # funcCallback
    w.LPVOID,                     # pCallbackContext
    w.LPVOID,                     # pReserved (C函数内部处理，通常为NULL)
    ct.POINTER(w.DWORD)           # pdwPrevNotifSource (输出参数)
)
wlanapi.WlanRegisterNotification.restype = w.DWORD # 返回类型

# 编写Python包装函数
def register_wlan_notification(hClientHandle, dwNotifSource, bIgnoreDuplicate,
                               funcCallback=null_callback, pCallbackContext=None):
    """
    Python wrapper for WlanRegisterNotification.
    Handles default values and extracts output parameter.
    """
    prev_notif_source = w.DWORD() # 用于接收输出参数

    # 调用C函数，pReserved 始终传递 None (对应C的NULL)
    result = wlanapi.WlanRegisterNotification(
        hClientHandle,
        dwNotifSource,
        bIgnoreDuplicate,
        funcCallback,
        pCallbackContext,
        None, # pReserved 始终为 None，由C函数内部处理
        ct.byref(prev_notif_source) # 传递输出参数的引用
    )

    return result, prev_notif_source.value

# 各种调用方式
print("\n--- Using .argtypes and Python wrapper ---")
print(register_wlan_notification(0, 0, 0)) # 所有可选参数使用默认值
print(register_wlan_notification(0, 0, 0, funcCallback=callback)) # 提供 funcCallback
print(register_wlan_notification(0, 0, 0, funcCallback=callback, pCallbackContext=None)) # 提供 funcCallback 和 pCallbackContext (None)

# 尝试传递 pReserved 会失败，因为Python wrapper中没有暴露此参数
try:
    # 这里的错误是Python层面的，因为 wrapper 函数没有定义第6个参数
    print(register_wlan_notification(0, 0, 0, callback, None, None))
except TypeError as e:
    print(f"Error as expected: {e}") # TypeError: register_wlan_notification() takes from 3 to 5 positional arguments but 6 were given