KRTS 高速以太网：网络模块套接字 API_krts高速以太网-优快云博客

本文链接：https://blog.youkuaiyun.com/EZCODETECH/article/details/141344507

高速以太网：网络模块套接字 API

打开套接字

在打开套接字之前，必须打开适配器。有关详细信息(请参阅高速以太网：网络模块)。

要创建新套接字，可以使用函数 KS_openSocket。作为参数，套接字句柄、适配器句柄、结构 KSSocketAddr、协议和标志被传递。调用函数后，将返回套接字句柄。

使用结构 KSSocketAddr 可以传递协议版本、端口和 IP 地址。可以使用函数 KS_makeIPv4 创建有效的 IPv4 地址。

对于原始 IP、UDP 或 TCP，协议可以是"KS_PROTOCOL_RAW"、“KS_PROTOCOL_UDP"或"KS_PROTOCOL_TCP”。

对于 UDP 或 TCP 套接字，可以使用标志"KSF_CLIENT"或"KSF_SERVER"来指定套接字的角色。

关闭套接字

要关闭套接字，必须使用函数 KS_closeSocket。

无连接发送和接收

如果是原始 IP 套接字或 UDP 套接字，则套接字是无连接的，即可以通过函数 KS_recvFromSocket 和 KS_sendToSocket 立即接收或发送数据。

函数"KS_recvFromSocket"从 UDP/IP 套接字接收数据。作为参数，套接字句柄、结构 KSSocketAddr、缓冲区、缓冲区的大小(以字节为单位)、所需的缓冲区大小和标志将被传递。参数 pLength 返回接收消息所需的字节数。如果缓冲区较小，则返回错误"KSERROR_NOT_ENOUGH_MEMORY"。用户有机会传递正确大小 pLength 的缓冲区。参数 pSourceAddr 是类型为"KSSocketAddr"的用户分配结构，必须包含发送方的地址。

函数"KS_sendToSocket"通过 UDP/IP 套接字发送数据。作为参数，套接字句柄、结构 KSSocketAddr、缓冲区、长度、缓冲区的大小(以字节为单位)、实际发送的大小(以字节为单位)以及传递的标志。目标地址在参数 pTargetAddr 中给出。缓冲区必须包含要发送的数据。

通过连接发送和接收

对于 TCP 协议，必须先建立连接，然后才能发送数据包。使用 KS_openSocket 创建 TCP 服务器后，服务器会立即进入状态 LISTEN。对于 TCP 客户端，必须调用函数 KS_connectSocket 才能连接到服务器。TCP 服务器获取客户端的地址，并且必须调用函数 KS_acceptSocket。

建立TCP连接后，可以通过函数KS_recvSocket和KS_sendSocket接收或发送数据。

函数 ‘KS_connectSocket’ 具有客户端套接字句柄、结构 KSSocketAddr 和作为参数的标志。调用此函数时，给定的客户端套接字尝试使用参数 pServerAddr 中给定的 IP 地址连接到服务器套接字。在服务器响应请求之前，这些函数会阻塞。如果设置了标志"KSF_DONT_WAIT"，则函数不会阻塞。如果再次调用"KS_connectSocket"，但服务器仍然没有应答，则返回错误"KSERROR_OPERATION_PENDING"。

如果调用函数"KS_acceptSocket"，服务器将等待传入连接。作为服务器套接字句柄的参数，将传递结构"KSSocketAddr"和标志。如果连接已存在，则该函数将立即返回。否则，当前线程将阻塞，直到客户端与服务器建立连接或套接字关闭。

如果设置了标志"KSF_DONT_WAIT"，则函数不会阻塞。如果再次调用"KS_acceptSocket"，但仍然没有传入连接，则返回错误"KSERROR_OPERATION_PENDING"。

返回时，有关已连接客户端套接字的信息(例如其 IP 地址和端口号)在参数 pClientAddr 中可用。

函数"KS_recvSocket"从 TCP 套接字接收数据。作为参数，套接字句柄、缓冲区的大小(以字节为单位)、接收消息所需的大小(以字节为单位)和标志都被传递。参数 pLength 返回所需的实际缓冲区大小。如果缓冲区较小，则函数返回错误"KSERROR_NOT_ENOUGH_MEMORY"。函数 ‘KS_recvSocket’ 也可用于获取缓冲区实际需要的大小。

// ...  
int length = 0;  
ksError = KS_recvSocket(hSocket, NULL, 0, &length, 0);  
if (KSERROR_CODE(ksError) != KSERROR_NOT_ENOUGH_MEMORY)  
// ...

函数"KS_sendSocket"通过 TCP 套接字发送数据。作为参数，套接字句柄、缓冲区、缓冲区的大小(以字节为单位)、发送的实际大小(以字节为单位)以及传递标志。此函数用于通过面向连接的套接字 hSocket 发送数据。在 pBuffer 中，必须提供指向数据缓冲区的指针，在 length 中，必须提供该缓冲区的长度(以字节为单位)。通过可选地址 pLength，可以回写发送数据的实际长度。

执行套接字命令

函数 KS_execSocketCommand 在套接字上执行特定命令。作为参数，套接字句柄、命令、可选参数和标志被传递。

具体命令的说明可以在 KS_execSocketCommand 的 API 文档中找到。有关如何设置可选参数 pParam 或标志的信息也可以在此处找到。

例如，如果需要设置最大传输单位，则可以使用命令"KS_SOCKET_SET_MTU"。可选参数 pParam 设置为 32 位整数。

安装套接字处理器

要安装套接字处理程序，可以使用函数 KS_installSocketHandler。作为参数，套接字句柄、事件代码、回调句柄和标志被传递。使用事件代码时，将指定处理程序的类型。

事件代码	描述
‘KS_SOCKET_RECV’	已收到数据。
‘KS_SOCKET_CONNECTED’	客户端已连接(仅限 TCP)。
‘KS_SOCKET_DISCONNECTED’	客户端已断开连接(仅限 TCP)。
‘KS_SOCKET_CLEAR_TO_SEND’	套接字已准备好进行发送操作(仅限 TCP)。

注意：事件代码"KS_SOCKET_CONNECTED"、"KS_SOCKET_DISCONNECTED"和"KS_SOCKET_CLEAR_TO_SEND"仅适用于 TCP。

调用处理程序时应执行的代码作为回调句柄传递(参见创建回调)。对于不同的事件代码，特殊的上下文结构在 context 参数中传递给回调函数。可以在函数 KS_installSocketHandler 的 API 文档中找到列表。

对于"KS_SOCKET_RECV"事件代码，对应的上下文结构为 SocketUserContext。

如果输入 null/NULL/NIL 作为回调句柄，则再次卸载处理程序。

‘KS_SOCKET_RECV’：此事件允许使用所有协议，并在数据可用时立即使用"KS_recvFromSocket"/"KS_recvSocket"发出信号。

‘KS_SOCKET_CONNECTED’：这些事件仅适用于 TCP 套接字。一旦客户端尝试注册，它将在服务器套接字上发出信号;在客户端套接字上(如果已建立连接)。

‘KS_SOCKET_DISCONNECTED’：这些事件仅适用于 TCP 套接字。一旦另一端关闭连接，它将在服务器或客户端套接字上发出信号。

‘KS_SOCKET_CLEAR_TO_SEND’：此事件仅适用于 TCP 套接字。当必须发送的数据量减少到缓冲区大小的一半以下时，将发出此事件信号。