Go语言调用Windows DLL：SCard API参数传递与常见陷阱解析

package main

import (
    "fmt"
    "syscall"
    "unicode/utf16"
    "unsafe"
)

// 定义DLL句柄和函数地址
var (
    WinSCard, _                  = syscall.LoadLibrary(`C:\windows\system32\WinSCard.dll`)
    procSCardEstablishContext, _ = syscall.GetProcAddress(WinSCard, "SCardEstablishContext")
    procSCardReleaseContext, _   = syscall.GetProcAddress(WinSCard, "SCardReleaseContext")
    // 注意：这里使用 "SCardListReadersW" 而不是 "SCardListReaders"
    procSCardListReaders, _      = syscall.GetProcAddress(WinSCard, "SCardListReadersW")
)

// 定义SCard API常量
const (
    SCARD_SCOPE_USER   = 0 // 用户上下文
    SCARD_SCOPE_SYSTEM = 2 // 系统上下文

    SCARD_ALL_READERS     = "SCard$AllReaders"     // 所有读卡器组
    SCARD_DEFAULT_READERS = "SCard$DefaultReaders" // 默认读卡器组
)

// SCardListReadersW 的 Go 封装
// hContext: 智能卡资源管理器的上下文句柄
// mszGroups: 读卡器组名称，UTF-16编码，多字符串列表
// mszReaders: 输出缓冲区，用于接收读卡器名称，UTF-16编码，多字符串列表
// pcchReaders: 输入/输出参数，指定/返回 mszReaders 缓冲区的大小（字符数）
func SCardListReaders(hContext syscall.Handle, mszGroups *uint16, mszReaders *uint16, pcchReaders *uint32) (retval error) {
    r0, _, _ := syscall.Syscall6(
        uintptr(procSCardListReaders),
        4, // 参数数量
        uintptr(hContext),
        uintptr(unsafe.Pointer(mszGroups)),
        uintptr(unsafe.Pointer(mszReaders)),
        uintptr(unsafe.Pointer(pcchReaders)),
        0,
        0,
    )
    if r0 != 0 {
        retval = syscall.Errno(r0)
    }
    return
}

// SCardReleaseContext 的 Go 封装
// hContext: 智能卡资源管理器的上下文句柄
func SCardReleaseContext(hContext syscall.Handle) (retval error) {
    r0, _, _ := syscall.Syscall(
        uintptr(procSCardReleaseContext),
        1, // 参数数量
        uintptr(hContext),
        0,
        0,
    )
    if r0 != 0 {
        retval = syscall.Errno(r0)
    }
    return
}

// SCardEstablishContext 的 Go 封装
// dwScope: 上下文范围
// pvReserved1, pvReserved2: 保留参数，通常为0
// phContext: 输出参数，接收智能卡资源管理器的上下文句柄
func SCardEstablishContext(dwScope uint32, pvReserved1 uintptr, pvReserved2 uintptr, phContext *syscall.Handle) (retval error) {
    r0, _, _ := syscall.Syscall6(
        uintptr(procSCardEstablishContext),
        4, // 参数数量
        uintptr(dwScope),
        uintptr(pvReserved1),
        uintptr(pvReserved2),
        uintptr(unsafe.Pointer(phContext)), // 传递 phContext 变量的地址
        0,
        0,
    )
    if r0 != 0 {
        retval = syscall.Errno(r0)
    }
    return
}

// 将错误转换为 uint32 类型的错误码
func ReturnValue(err error) uint32 {
    rv, ok := err.(syscall.Errno)
    if !ok {
        rv = 0 // 如果不是 syscall.Errno 类型，则返回0
    }
    return uint32(rv)
}

// 将 UTF-16 编码的多字符串列表 (以双空字符结束) 转换为 Go 的 []string
func UTF16ToStrings(ls []uint16) []string {
    var ss []string
    if len(ls) == 0 {
        return ss
    }
    // 确保切片以双空字符结束，以便正确解析
    if ls[len(ls)-1] != 0 {
        ls = append(ls, 0)
    }
    i := 0
    for j, cu := range ls {
        if cu == 0 { // 遇到空字符，表示一个字符串结束
            if j >= 1 && ls[j-1] == 0 { // 遇到双空字符，表示列表结束
                break
            }
            if j-i > 0 { // 如果当前字符串非空，则解码并添加
                ss = append(ss, string(utf16.Decode(ls[i:j])))
            }
            i = j + 1 // 移动到下一个字符串的起始位置
            continue
        }
    }
    return ss
}

func main() {
    var (
        context  syscall.Handle // 智能卡上下文句柄
        scope    uint32         // 上下文范围
        groups   *uint16        // 读卡器组名称指针
        cReaders uint32         // 读卡器名称缓冲区大小
    )

    // 确保在程序退出时释放DLL
    defer syscall.FreeLibrary(WinSCard)

    // --- 尝试列出读卡器（在建立上下文之前，某些系统可能无法列出所有读卡器） ---
    // 初始化 context 为0，表示不使用已建立的上下文
    context = 0
    // 将 Go 字符串转换为 UTF-16 指针
    groups, err := syscall.UTF16PtrFromString(SCARD_ALL_READERS)
    if err != nil {
        fmt.Println("Reader Group conversion error: ", err)
        return
    }

    // 第一次调用 SCardListReaders 获取所需缓冲区大小
    // mszReaders 传入 nil，pcchReaders 接收所需大小
    err = SCardListReaders(context, groups, nil, &cReaders)
    if err != nil {
        // 如果返回 SCARD_E_NO_READERS_FOUND (0x80100002) 或 SCARD_E_NO_SMARTCARD (0x80100003)，表示没有读卡器
        // 或者 SCARD_E_SERVICE_STOPPED (0x8010001D) 表示智能卡服务未运行
        fmt.Printf("SCardListReaders (initial call) failed: 0x%X %s\n", ReturnValue(err), err)
        // 如果错误是 SCARD_E_NO_READERS_FOUND，不认为是致命错误，可以继续
        if ReturnValue(err) == 0x80100002 {
            fmt.Println("No smart card readers found.")
        } else {
            return
        }
    }

    // 如果有读卡器，分配缓冲区并再次调用 SCardListReaders 获取实际数据
    if cReaders > 0 {
        r := make([]uint16, cReaders) // 分配足够大的 UTF-16 缓冲区
        err = SCardListReaders(context, groups, &r[0], &cReaders) // 传入缓冲区地址
        if err != nil {
            fmt.Printf("SCardListReaders (data retrieval) failed: 0x%X %s\n", ReturnValue(err), err)
            return
        }
        // 将 UTF-16 编码的读卡器列表转换为 Go 的 []string
        readers := UTF16ToStrings(r[:cReaders])
        fmt.Println("Readers:", len(readers), readers)
    } else {
        fmt.Println("No readers found after initial check.")
    }


    // --- 建立智能卡上下文 ---
    scope = SCARD_SCOPE_SYSTEM // 设置上下文范围为系统级别
    // 调用 SCardEstablishContext，phContext 传入 context 变量的地址
    err = SCardEstablishContext(scope, 0, 0, &context)
    if err != nil {
        fmt.Printf("SCardEstablishContext failed: 0x%X %s\n", ReturnValue(err), err)
        // 常见错误：0x8010001D (SCARD_E_SERVICE_STOPPED) - 智能卡资源管理器服务未运行
        return
    }
    // 确保在函数退出时释放上下文
    defer SCardReleaseContext(context)
    fmt.Printf("Context established: %X\n", context)

    // 可以在这里进行其他智能卡操作...
}