C语言WiFi扫描函数签名的最佳结构方式问询

先看你给出的函数签名：

void wifi_client_scan(struct wifi_client* client, uint16_t max_results, wifi_ap_record_t* results, uint16_t *results_count);

1. 传入wifi_ap_record_t*数组指针而非返回指针的合理性 #

这种做法不仅合理，还是C语言处理这类场景的标准推荐方案。原因在于：

• C没有自动内存回收机制，如果函数返回wifi_ap_record_t*，要么用静态内存（线程不安全，多线程调用会出现数据覆盖），要么在函数内用malloc分配堆内存（调用者必须手动free，极易引发内存泄漏）。
• 让调用者提前分配数组并传入，内存生命周期完全由调用者掌控，灵活性更高——调用者可按需选择栈内存（小批量结果）或堆内存（大批量结果），也能避免内存管理权责不清的问题。

2. 通过uint16_t指针返回结果数量是否正确 #

这是C语言处理「需要返回多个值」场景的标准做法，完全正确。
需要注意一个细节：当扫描到的AP数量超过max_results时，*results_count应返回实际扫描到的总数量，而非max_results——这样调用者能明确当前数组容量不足，需要重新分配更大的数组再次扫描。如果只返回max_results，调用者会误以为扫描到的AP仅此而已，容易遗漏数据。

3. 其他需要考虑的要点 #

• 错误处理：当前函数是void类型，无法返回扫描失败状态（比如硬件故障、权限不足、扫描超时等）。建议改成返回int类型，用0表示成功，负数表示具体错误码（比如-1代表硬件错误，-2代表权限不足），让调用者能处理异常情况。
• 参数合法性检查：函数开头必须检查关键参数：
  • client不能为NULL（否则无法操作WiFi客户端实例）
  • 如果max_results > 0，results和results_count都不能为NULL
  • max_results不能为0（空扫描无实际意义）
• 缓冲区溢出防护：扫描过程中必须严格控制写入results的元素数量不超过max_results，哪怕实际扫描到更多AP，也只能写入前max_results个，避免越界访问导致程序崩溃或内存损坏。
• 线程安全：如果该函数可能被多线程调用，要确保struct wifi_client内部资源（比如硬件操作句柄、状态变量）有同步机制（比如互斥锁），防止多线程同时操作引发数据混乱。
• 数据初始化：函数内部应清空每个写入results的wifi_ap_record_t元素，避免调用者传入的数组残留垃圾数据，导致后续处理出错。
• 超时控制：同步扫描WiFi可能耗时数秒，可考虑给函数增加超时参数，或在内部设置合理超时时间，避免函数无限阻塞。

内容的提问来源于stack exchange，提问作者Damian Dudycz