DIY - ESP8266：ESP8266 SDK ESPCONN TCP 網路介面函數（三十一）

DIY - ESP8266：ESP8266 SDK ESPCONN TCP 網路介面函數（三十一）：

網路 ESPCONN 網路介面（ESPCONN Network API）主要是使用 TCP 或 UDP 來收發數據，所以 Espressif（樂鑫）提供了 TCP 或 UDP 的網路介面函數（ESPCONN TCP / UDP Network API），TCP 網路介面函數（ESPCONN TCP Network API）僅用於 TCP 連接，請勿用於 UDP 傳輸，ESPCONN 的網路函數是儲存在 ESP8266_NONOS_SDK/include/espconn.h。

ESP8266 SDK ESPCONN TCP 網路介面函數

ESPCONN TCP網路介面函數（ESPCONN TCP Network API）：

1. espconn_accept
2. espconn_regist_time
3. espconn_connect
4. espconn_set_opt
5. espconn_clear_opt
6. espconn_set_keepalive
7. espconn_get_keepalive 
8. espconn_disconnect
9. espconn_abort
10. espconn_tcp_get_max_con
11. espconn_tcp_set_max_con
12. espconn_tcp_set_max_con_allow
13. espconn_recv_hold
14. espconn_recv_unhold

espconn_accept
功能	創建 TCP 伺服器 server，建立偵聽
函數定義	sint8 espconn_ accept (struct espconn *espconn)
輸入參數	struct espconn *espconn - 相應連接的控制塊結構
返回	0：成功 其他：失敗，返回錯誤碼 • ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接 • ESPCONN_MEM：空間不足 • ESPCONN_ISCONN：連接已經建立

espconn_regist_time
功能	ESP8266作為伺服器，設置超時斷開連接的超時時長
函數定義	sin8 espconn_regist_time(struct espconn *espconn, uint32 interval, uint8 type_flag)
輸入參數	• struct espconn *espconn：對應網路連接的結構體 • uint32 interval：超時時間，單位：秒，最大值：7200 秒 • uint8 type_flag - 0：對所有 TCP 連接生效 - 1：僅對某一 TCP 連接生效
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	• 請在 espconn_accept 之後，連接未建立之前，調用本接口。本接口不能用於 SSL 連接。 • 如果超時時間設置為 0，ESP8266 TCP server 將始終不會斷開已經不與它通信的 TCP client，不建議這樣使用。

espconn_connect
功能	連接 TCP server（ESP8266 作為 TCP client）
函數定義	sint8 espconn_connect(struct espconn *espconn)
輸入參數	struct espconn *espconn - 相應連接的控制塊結構
返回	0：成功 其他：失敗，返回錯誤碼 • ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接 • ESPCONN_MEM：空間不足 • ESPCONN_ISCONN：連接已經建立 • ESPCONN_RTE：路路由異常
注意	• 如果 espconn_connect 失敗，返回非零值，連接未建立，不會進入任何 espconn callback。 • 建議使用 espconn_port 接口，設置一個可用的端口號。

espconn_set_opt
功能	設置 TCP 連接的相關配置，對應清除配置標誌位元的接口為 espconn_clear_opt
函數定義	sint8 espconn_set_opt(struct espconn *espconn, uint8 opt )
輸入參數	• struct espconn *espconn：對應網路連接的結構體 • uint8 opt：TCP 連接的相關配置，參考 espconn_option - bit 0：1，TCP 連接斷開時，及時釋放記憶體，無需等待 2 分鐘才釋放占用記憶體； - bit 1：1，關閉 TCP 資料傳輸時的 algorithm 演算法； - bit 2：1，使能 write finish callback，進入此回調表示 espconn_send 要發送的資料已經寫入 2920 位元組的 write buffer 等待發送或已經發送； - bit 3：1，使能 keep alive；
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	• SSL 連接不支援使用本接口 • 一般情況下，無需調用本接口；如需設置 espconn_set_opt 請在 espconn_connect_callback 中調用

espconn_clear_opt
功能	清除 TCP 連接的相關配置
函數定義	sint8 espconn_clear_opt(struct espconn *espconn, uint8 opt )
輸入參數	• struct espconn *espconn：對應網路連接的結構體 • uint8 opt：清除 TCP 連接的相關配置，參考 espconn_option
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
結構體	enum espconn_option{ ESPCONN_START = 0x00， ESPCONN_REUSEADDR = 0x01， ESPCONN_NODELAY = 0x02， ESPCONN_COPY = 0x04， ESPCONN_KEEPALIVE = 0x08， ESPCONN_END }

espconn_set_keepalive
功能	設置 TCP keep alive 的參數
函數定義	sint8 espconn_set_keepalive(struct espconn *espconn, uint8 level, void* optarg)
輸入參數	• struct espconn *espconn：對應網路連接的結構體 • uint8 level：默認設置為每隔 ESPCONN_KEEPIDLE 時長進行行一次 keep alive 探查，如果報文無回應，則每隔 ESPCONN_KEEPINTVL 時長探查一次，最多探查 ESPCONN_KEEPCNT 次；若始終無回應，則認為網路連接斷開，釋放本地連接相關資源，進入espconn_reconnect_callback。注意，時間間隔設置並不可靠精准，僅供參考，受其他高優先級任務執行的影響。參數說明如下： - ESPCONN_KEEPIDLE：設置進行 keep alive 探查的時間間隔，單位：秒 - ESPCONN_KEEPINTVL：keep alive 探查過程中，報文的時間間隔，單位：秒 - ESPCONN_KEEPCNT：每次 keep alive 探查，發送報文的最大次數 • void* optarg：設置參數值
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
結構體	enum espconn_level{ ESPCONN_KEEPIDLE, ESPCONN_KEEPINTVL, ESPCONN_KEEPCNT }
注意	• 一般情況下，不需要調用本接口 • 如果設置，請在 espconn_connect_callback 中調用，並先設置 espconn_set_opt 使能 keep alive

espconn_get_keepalive
功能	查詢 TCP keep alive 的參數
函數定義	sint8 espconn_get_keepalive(struct espconn *espconn, uint8 level, void* optarg)
輸入參數	• struct espconn *espconn：對應網路連接的結構體 • uint8 level - ESPCONN_KEEPIDLE：設置進行 keep alive 探查的時間間隔，單位：秒 - ESPCONN_KEEPINTVL：keep alive 探查過程中，報文的時間間隔，單位：秒 - ESPCONN_KEEPCNT：每次 keep alive 探查，發送報文的最大次數 • void* optarg：設置參數值
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
結構體	enum espconn_level{ ESPCONN_KEEPIDLE, ESPCONN_KEEPINTVL, ESPCONN_KEEPCNT }

espconn_disconnect
功能	斷開 TCP 連接
函數定義	sin8 espconn_disconnect(struct espconn *espconn)
輸入參數	struct espconn *espconn -相應連接的控制塊結構
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	請勿在 espconn 的任何 callback 中調用本接口斷開連接。如有需要，可以在 callback 中使用任務觸發調用本接口斷開連接。

espconn_abort
功能	強制斷開 TCP 連接
函數定義	sint8 espconn_abort(struct espconn *espconn)
輸入參數	struct espconn *espconn -相應連接的控制塊結構
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	請勿在 espconn 的任何 callback 中調用本接口斷開連接。如有需要，可以在 callback 中使用任務觸發調⽤用本接口斷開連接。

espconn_tcp_get_max_con
功能	查詢允許的 TCP 最大連接數
函數定義	uint8 espconn_tcp_get_max_con(void)
輸入參數	無
返回	返回允許的 TCP 最大連接數

espconn_tcp_set_max_con
功能	查設置允許的 TCP 最大連接數。在記憶體足夠的情況下，建議不不超過 10。預設值為 5。
函數定義	sint8 espconn_tcp_set_max_con(uint8 num)
輸入參數	uint8 num：允許的 TCP 最大連接數
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接

espconn_tcp_get_max_con_allow
功能	查詢 ESP8266 某個 TCP server 最多允許連接的 TCP client 數目
函數定義	sint8 espconn_tcp_get_max_con_allow(struct espconn *espconn)
輸入參數	struct espconn *espconn：對應 TCP server 的結構體
返回	＞0：最多允許連接的 TCP client 數目 ＜0 ：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接

espconn_tcp_set_max_con_allow
功能	設置 ESP8266 某個 TCP server 最多允許連接的 TCP client 數目
函數定義	sint8 espconn_tcp_set_max_con_allow(struct espconn *espconn, uint8 num)
輸入參數	struct espconn *espconn：對應 TCP server 的結構體 uint8 num：允許的 TCP 最大連接數
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接

espconn_recv_hold
功能	阻塞 TCP 接收資料
函數定義	sint8 espconn_recv_hold(struct espconn *espconn)
輸入參數	struct espconn *espconn：對應 TCP server 的結構體
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	調用本接口會逐漸減小 TCP 的窗口，並不是即時阻塞，因此建議預留留 1460*5 位元組左右的空間時候調用，且本接口可以反復調用。

espconn_recv_unhold
功能	解除 TCP 收包阻塞，即對應的阻塞接口 espconn_recv_hold
函數定義	sint8 espconn_recv_unhold(struct espconn *espconn)
輸入參數	struct espconn *espconn：對應 TCP server 的結構體
返回	0：成功 其他：失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接失敗，返回錯誤碼 ESPCONN_ARG：未找到參數 espconn 對應的 TCP 連接
注意	本接口實時生效

2017年 6月 6日 天氣報告

氣溫：29.9度 @ 22:00

相對濕度：百分之 82%

天氣： 天色大致良好