ctypes 原型参数冗余解析

本文旨在阐明 ctypes 库中函数原型参数规范中 DEFAULT_ZERO 标志的用途，并解释其与直接指定默认值的区别。通过示例代码，我们将演示如何正确使用 ctypes 定义 Windows API 函数，并避免常见的 TypeError 错误。此外，还将介绍使用 .argtypes 和 .restype 属性定义函数参数和返回值类型的替代方法，以提高代码的可读性和可维护性.

在 Python 中使用 ctypes 库与 C 动态链接库（DLL）进行交互时，理解函数原型参数的正确规范至关重要。特别是当涉及到参数的默认值时，ctypes 提供了一些选项，但如果不正确使用，可能会导致意外的行为和错误。

DEFAULT_ZERO 的特殊含义

ctypes 文档中提到，参数类型为 4（即 DEFAULT_ZERO）表示输入参数的默认值为整数零。然而，简单地在第三个元组元素中指定 0 似乎也能达到相同的效果。那么，DEFAULT_ZERO 的真正作用是什么？

实际上，DEFAULT_ZERO 标志的含义是“不要传递参数...使用默认值作为输入”。这意味着，当使用 DEFAULT_ZERO 标记参数时，调用函数时不能显式地传递该参数。这与指定默认值不同，后者允许在调用时选择性地覆盖默认值。

示例：WlanRegisterNotification 函数

考虑 Windows API 函数 WlanRegisterNotification。如果我们使用 DEFAULT_ZERO 为 pReserved 参数指定默认值，则在调用该函数时，不能显式地传递 pReserved 参数。否则，会引发 TypeError: call takes exactly N arguments (N+1 given) 错误。

以下代码演示了正确使用 DEFAULT_ZERO 的方法：

import ctypes
import ctypes.wintypes

PWLAN_NOTIFICATION_DATA = ctypes.c_void_p
WLAN_NOTIFICATION_CALLBACK = ctypes.WINFUNCTYPE(None, PWLAN_NOTIFICATION_DATA, ctypes.wintypes.LPVOID)

null_callback = WLAN_NOTIFICATION_CALLBACK()

# valid callback
@WLAN_NOTIFICATION_CALLBACK
def callback(param1, param2):
    print(param1, param2)

IN = 1
OUT = 2
DEFAULT_ZERO = 4

wlanapi = ctypes.WinDLL('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, 'funcCallback', null_callback),
        (IN, 'pCallbackContext', None),
        (IN | DEFAULT_ZERO, 'pReserved'),
        (OUT, 'pdwPrevNotifSource'),
    ),
)
fun.errcheck = lambda result, func, args: (result, args[5])
print(fun(0,0,0))
print(fun(0,0,0,callback))
print(fun(0,0,0,callback,None))
# print(fun(0,0,0,callback,None,None))  # this will fail. pReserved can't be passed.

在这个例子中，pReserved 参数使用了 DEFAULT_ZERO 标志。因此，在调用 fun 函数时，我们不能显式地传递 pReserved 参数。如果尝试传递，将会引发 TypeError 错误。

注意： 对于回调函数和 LPVOID 类型的参数，int(0) 通常不是有效的默认值。对于回调函数，可以使用 None 或空的回调函数实例作为默认值。对于 LPVOID，可以使用 None 作为默认值。

使用 .argtypes 和 .restype 的替代方法

除了使用 ctypes.WINFUNCTYPE 和参数标志外，还可以使用 .argtypes 和 .restype 属性来定义函数的参数类型和返回值类型。这种方法通常更简洁、更易读，并且可以避免一些与参数标志相关的陷阱。

以下代码演示了如何使用 .argtypes 和 .restype 定义 WlanRegisterNotification 函数：

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()

# valid callback
@WLAN_NOTIFICATION_CALLBACK
def callback(param1, param2):
    print(param1, param2)

wlanapi = ct.WinDLL('wlanapi')
wlanapi.WlanRegisterNotification.argtypes = w.HANDLE, w.DWORD, w.BOOL, WLAN_NOTIFICATION_CALLBACK, w.LPVOID, w.LPVOID, ct.POINTER(w.DWORD)
wlanapi.WlanRegisterNotification.restype = w.DWORD

def fun(h, src, ignore, cb=null_callback, context=None):
    prev = w.DWORD()
    result = wlanapi.WlanRegisterNotification(h, src, ignore, cb, context, None, ct.byref(prev))
    return result, prev.value

print(fun(0, 0, 0))
print(fun(0, 0, 0, callback))
print(fun(0, 0, 0, callback, None))
# print(fun(0, 0, 0, callback, None, None))  # this will fail. pReserved can't be passed.

在这个例子中，我们首先使用 wlanapi.WlanRegisterNotification.argtypes 属性定义了函数的参数类型，然后使用 wlanapi.WlanRegisterNotification.restype 属性定义了函数的返回值类型。最后，我们定义了一个包装函数 fun，该函数负责调用 WlanRegisterNotification 函数，并处理返回值。

总结：

• DEFAULT_ZERO 标志表示不传递参数，而是使用默认值。
• 使用 DEFAULT_ZERO 标记的参数不能在调用函数时显式地传递。
• 可以使用 .argtypes 和 .restype 属性来定义函数的参数类型和返回值类型，这通常更简洁、更易读。
• 在使用 ctypes 定义 Windows API 函数时，务必仔细阅读文档，并理解每个参数的含义和类型。
• 避免直接照搬问题原文，要融合、改写、优化表达。

通过理解 ctypes 中参数规范的细节，我们可以更有效地使用 ctypes 库与 C 动态链接库进行交互，并避免常见的错误。