/*
 * 模块名称：Network Events & Reconcile —— 内部头
 * 模块功能：声明「芯片边沿事件处理 + 100ms 周期对账」模块对 net 层宿主提供的接口。
 * 适用平台：STM32F407ZGTx + CH395F 以太网芯片
 * 作者：王建锋
 * 创建日期：2026-10-14
 *
 * ⚠ **内部头**：只被 `net_socket.c`（宿主）与 `net_events.c`（实现）include，
 *   **不进** 公开的 `net_socket.h`，也**不被应用层引用**——与 `net_listener.h` 同族约定。
 *   本模块依赖 `ch395f_*` SPI 驱动，属**真机专属**：模拟器（Winsock 后端）不编译，
 *   故已在 `scripts/check_registration.py` 的 SIM_EXEMPT 显式点名（每行附理由）。
 *
 * 设计依据 → docs/网络/网络自愈架构设计.md §4
 *   形态表 §4.1 / 单一重建所有者 §4.2 / 沉降与隔离 §4.3 / 读即清信源纪律 §4.10
 */
#ifndef NET_EVENTS_H
#define NET_EVENTS_H

#include "net_types.h" /* net_sock_t / net_event_t / NET_MAX_SOCKETS */

/* ===== 宿主 net_socket.c 提供 ===== */

/* `net_sock_raw()`（对账循环需要的"不判 in_use"数组访问器）声明在**配对头** net_socket.h
 * —— 规范 S17 2.2 要求非 static 函数声明在配对头文件，内部头不算（同 net_set_errno 先例）。 */

/* ===== 本模块 net_events.c 提供 ===== */

/* 芯片边沿事件处理器：由 net_poll() 在全局中断位命中后分派（netTask 上下文） */
void handle_connect_event(net_sock_t *p_sock);    /* CONNECT：转 ESTABLISHED + 记对端 + KeepAlive */
void handle_disconnect_event(net_sock_t *p_sock); /* DISCONNECT：陈旧甄别 + 登记沉降事实 */
void handle_recv_event(net_sock_t *p_sock);       /* RECV_OK：置 readable 电平 */
void handle_send_event(net_sock_t *p_sock);       /* SEND_OK：清发送忙 + 回调 */
void handle_timeout_event(net_sock_t *p_sock);    /* TIM_OUT：按异常释放处理（隔离重建） */

/* 100ms 周期对账：形态①②③④⑤ + U11 的唯一判据所在；由 net_process_messages 每轮调用 */
void net_reconcile_tick(void);

/* accept 路径探针：芯片已 ESTABLISHED 而 CONNECT 事件未到时补做 accept */
void net_lost_connect_probe(net_sock_t *p_sock);

#if defined(NET_BENCH_CMD_LOG)
/* 台架芯片命令序列日志（编译开关默认关；net_poll / 消息分派 / 事件处理三处消费） */
void net_bench_cmd_log(char tag, int sock, int detail);
#endif

#endif /* NET_EVENTS_H */