FreeRTOS_setsockopt()

[FreeRTOS-Plus-TCP API 引用]

如果 lOptionName 为 FREERTOS_SO_RECTIMEO， pvOptionValue 必须指向 TickType_t 类型的变量。

指定以 tick 为单位的超时值 以滴答 (tick) 为单位。 要将毫秒为单位的时间转换为 tick 为单位的时间， 可将毫秒为单位的时间除以 portTICK_PERIOD_MS，或 使用 pdMS_TO_TICKS() 宏。

如果 lOptionName 为 FREERTOS_SO_SNDTIMEO， pvOptionValue 必须指向 TickType_t 类型的变量。

指定以 tick 为单位的超时值 以滴答 (tick) 为单位。 要将毫秒为单位的时间转换为 tick 为单位的时间， 可将毫秒为单位的时间除以 portTICK_PERIOD_MS，或 使用 pdMS_TO_TICKS() 宏。

打开或关闭传出 UDP 数据包的校验和值的生成。

如果 lOptionName 为 FREERTOS_SO_UDPCKSUM_OUT， 并且 lOptionValue 为 NULL (0)，那么传出 UDP 数据包的校验和将始终设置为 0。

如果 lOptionName 为 FREERTOS_SO_UDPCKSUM_OUT， 并且 lOptionValue 为除 NULL (0) 以外的任何值， 那么传出 UDP 数据包将包括有效的校验和值 。

借助此选项，可将对信号量的引用 传递给套接字。 然后， TCP/IP RTOS 任务 将在以下任何事件发生时提供信号量：

• 新数据到达
• 传输数据后，新的传输缓冲区空间可用时
• 传出 TCP 连接已成功
• 新客户端已连接到 TCP 套接字
• TCP 连接已关闭或重置

/* Declare the semaphore. */

SemaphoreHandle_t xSemaphore;



/* Create the semaphore. */

xSemaphore = xSemaphoreCreateBinary();

if( xSemaphore != NULL )

{

    /* Pass the semaphore to the socket. */

    FreeRTOS_setsockopt( xSocket,

                         0,

                         FREERTOS_SO_SET_SEMAPHORE,

                         ( void * )&xSemaphore,

                         sizeof( xSemaphore ) );



    /*  The semaphore has been passed to the socket

    and will be used.



    Note: If a socket has a reference to a semaphore

    then the semaphore must not be deleted!  To

    remove the semaphore call FreeRTOS_setsockopt()

    again, but this time with a NULL semaphore. */

    SemaphoreHandle_t xNoSem = NULL;

    FreeRTOS_setsockopt( xSocket,

                         0,

                         FREERTOS_SO_SET_SEMAPHORE,

                         ( void * ) &xNoSem,

                         sizeof( xNoSem ) );



    /* Now the semaphore can be deleted. */

    vSemaphoreDelete( xSemaphore );

}



Example of passing a semaphore to a socket

每个套接字都有一个回调函数，可在套接字所有者想要处理事件时执行， 旨在为套接字注册并设置唤醒回调函数。

回调函数应为以下类型：

void (* SocketWakeupCallback_t)( struct xSOCKET * pxSocket );

用于设置 TCP 接收的低水位和高水位值，流式传输音乐时非常有用。选项值应为 LowHighWater_t 类型， 具有以下结构定义：

typedef struct xLOW_HIGH_WATER

    {

        size_t uxLittleSpace; /**< Send a STOP when buffer space drops below X bytes */

        size_t uxEnoughSpace; /**< Send a GO when buffer space grows above X bytes */

    } LowHighWater_t;

用于设置接收缓冲区的大小。 理想情况下，该大小应设置为 滑动窗口的两倍。

该参数只能设置为在正在创建的套接字和正在套接字上接收的数据 之间的值，因为 接收缓冲区的大小会在创建缓冲区后固定。

如果 lOptionName 为 FREERTOS_SO_RCVBUF， 则 pvOptionValue 必须指向 int32_t 类型的变量。

接收缓冲区大小以字节为单位。 在内部， 指定的大小将四舍五入到 最接近的 ipconfigTCP_MSS 大小 的倍数。 例如，如果 ipconfigTCP_MSS 为 500， 将缓冲区大小设置为 400，会指定缓冲区大小为 500 (1 * ipconfigTCP_MSS)； 将缓冲区大小设置为 500， 会指定缓冲区大小为 500 (1 * ipconfigTCP_MSS)；将缓冲区大小设置为 510， 会指定缓冲区大小为 1000 (2 * ipconfigTCP_MSS)。

设置发送缓冲区的大小。 此参数与数据包的大小或滑动 窗口无关，只设置缓冲区的大小。

该参数只能设置为在正在创建的套接字和正在套接字上发送的数据 之间的值，因为 发送缓冲区的大小会在创建缓冲区后固定。

如果 lOptionName 为 FREERTOS_SO_SNDBUF， 则 pvOptionValue 必须指向 int32_t 类型的变量。

接收缓冲区大小以字节为单位。 在内部， 指定的大小将四舍五入到 最接近的 ipconfigTCP_MSS 大小 的倍数。 例如，如果 ipconfigTCP_MSS 为 500， 将缓冲区大小设置为 400，会指定缓冲区大小为 500 (1 * ipconfigTCP_MSS)； 将缓冲区大小设置为 500， 会指定缓冲区大小为 500 (1 * ipconfigTCP_MSS)；将缓冲区大小设置为 510， 会指定缓冲区大小为 1000 (2 * ipconfigTCP_MSS)。

仅对 TCP 套接字有效。

一次调用即可设置接收缓冲区、 接收滑动窗口、 发送缓冲区以及发送滑动窗口的大小。

缓冲区和滑动窗口大小只能设置为 正在创建的套接字和发送到套接字 或从套接字接收的任何数据之间的值。

用法示例：

    /* Declare an xWinProperties structure. */

    WinProperties_t  xWinProps;



    /* Fill in the required buffer and window sizes. */

    /* Unit: bytes */

    xWinProps.lTxBufSize = 4 * ipconfigTCP_MSS;

    /* Unit: MSS */

    xWinProps.lTxWinSize = 2;

    /* Unit: bytes */

    xWinProps.lRxBufSize = 4 * ipconfigTCP_MSS;

    /* Unit: MSS */

    xWinProps.lRxWinSize = 2;



    /* Use the structure with the

    FREERTOS_SO_WIN_PROPERTIES parameter in a call to

    FreeRTOS_setsockopt(). */

    FreeRTOS_setsockopt( xSocket,

                         0,

                         FREERTOS_SO_WIN_PROPERTIES,

                         ( void * ) &xWinProps,

                         sizeof( xWinProps ) );



Example of setting the buffer and sliding window sizes

默认情况下，监听 套接字将创建一个新的套接字来处理任何接受的连接。 FREERTOS_SO_REUSE_LISTEN_SOCKET 可用于更改此行为， 因此接受的连接由侦听 套接字本身处理。

如果 lOptionName 为 FREERTOS_SO_REUSE_LISTEN_SOCKET， 则 pvOptionValue 必须指向 BaseType_t 类型的变量，该变量设置为 1 表示 侦听套接字应重新用于传入连接，或设置为 0 表示 侦听套接字应创建一个新套接字 来处理每个传入连接。

对于可重复使用的套接字，可选择调用 FreeRTOS_accept()。 此外，还可调用 FreeRTOS_connect_connected() 来确定套接字是否 已连接。 建议调用 FreeRTOS_accept()，因为它标志着 从未连接更改为已连接。

成功后，FreeRTOS_accept() 返回对 已连接的父套接字的引用。 现在标记为已接受 并停止侦听新连接。

连接结束时，必须通过调用 FreeRTOS_closesocket 关闭套接字。 之后，可创建一个新套接字并将其绑定到同一 端口。

用法示例：

BaseType_t xReuseSocket = pdTRUE;

FreeRTOS_setsockopt( xSocket,

                     0,

                     FREERTOS_SO_REUSE_LISTEN_SOCKET,

                     ( void * ) &xReuseSocket,

                     sizeof( xReuseSocket ) );



Example of setting the re-use option to true

仅对 TCP 套接字有效。

利用 FREERTOS_SO_CLOSE_AFTER_SEND TCP，可在传递 最后一个数据后立即关闭套接字。 例如， 在发送文件的 FTP 中，此选项很有用。 最后一次调用 FreeRTOS_send() 之前，设置此选项， 可确保堆栈最后一个数据包 必须包含 FIN 标志。 堆栈将确保 仅在传递最后一个字节并得到 对等方确认后才关闭连接。

如果 lOptionName 为 FREERTOS_SO_CLOSE_AFTER_SEND， 则 pvOptionValue 必须指向 BaseType_t 类型的变量，该变量设置为 1 表示 在发送最后一个数据后应关闭套接字，或设置 0 表示 套接字应使用其默认行为 保持套接字打开状态，直到由任何一个对等方显式打开。

用法示例：

BaseType_t xCloseAfterNextSend = pdTRUE;

FreeRTOS_setsockopt( xSocket,

                     0,

                     FREERTOS_SO_CLOSE_AFTER_SEND,

                     ( void * ) &xCloseAfterNextSend,

                     sizeof( xCloseAfterNextSend ) );



Example of using the FREERTOS_SO_CLOSE_AFTER_SEND parameter

仅对 TCP 套接字有效。

使用 FREERTOS_SO_SET_FULL_SIZE 选项，可指示 TCP/IP 堆栈 不从套接字发送任何数据，直到有至少 一个完整的 MSS 大小的数据准备发送就绪。 此选项 可用于提高性能，但必须谨慎使用。 此选项不会超时，因此请确保 在最后一次发送时关闭该选项，以便将最后一个字节 （小于 MSS）传送出去。

如果 lOptionName 为 FREERTOS_SO_SET_FULL_SIZE， 则 pvOptionValue 必须指向 BaseType_t 类型的变量，该变量设置为 1 表示 仅应在至少有 MSS 字节等待传送时 发送套接字，或设置为 0 表示 套接字应使用其默认行为。

仅对 TCP 套接字有效。

TCP 套接字将不断向其对等方 通告窗口大小，因此对等方等待确认前 可以明确发送多少字节。这一切都是自动发生的， 可设置低水位线和高水位线。

使用 FREERTOS_SO_STOP_RX，可强制套接字通告零窗口， 使套接字暂时停止接收 数据。

如果 lOptionName 为 FREERTOS_SO_STOP_RX， 则 pvOptionValue 必须指向 BaseType_t 类型的变量，该变量设置为 1 表示 套接字应通告窗口大小为 0，或设置 0 表示 套接字应使用其默认行为。

BaseType_t xValue = pdTRUE;



/* Temporarily advertise a window size of 0 to stop

reception of data */

FreeRTOS_setsockopt( xSocket,

                     0,

                     FREERTOS_SO_STOP_RX,

                     ( void * ) &xValue,

                     sizeof( xValue ) );

{

    /* Do what ever you need to do. */

}



xValue = pdFALSE;



/* Allow further reception */

FreeRTOS_setsockopt( xSocket,

                     0,

                     FREERTOS_SO_STOP_RX,

                     ( void * ) &xValue,

                     sizeof( xValue ) );



Example of using the FREERTOS_SO_STOP_RX parameter

参数 ipconfig UDP_MAX_RX_PACKETS 可以 限制存储在一个 UDP 套接字中的 最大数据包数。此选项可以更改 单个套接字的此限制

如果 lOptionName 为 FREERTOS_SO_UDP_MAX_RX_PACKETS， 则 pvOptionValue 必须指向 一个 BaseType_t 类型的变量，该变量包含 可以在 UDP 套接字上排队的最大 RX 数据包数。

/* Allow a maximum of ten packets. */

BaseType_t xValue = 10;



FreeRTOS_setsockopt( xSocket,

                     0,

                    FREERTOS_SO_UDP_MAX_RX_PACKETS,

                    ( void * ) &xValue,

                    sizeof( xValue ) );



Example of using the FREERTOS_SO_UDP_MAX_RX_PACKETS parameter

仅对 TCP 套接字有效。

存储要在 TCP 套接字上的连接和断开事件上调用的函数地址。

仅对 TCP 套接字有效。

存储要在 TCP 套接字上接收数据时要调用的函数地址。

仅对 TCP 套接字有效。

存储发送到 TCP 套接字的数据已交付并由对等方确认时要调用的函数地址。

仅对 UDP 套接字有效。

存储在 UDP 套接字上接收到数据后立即调用的函数地址。

仅对 UDP 套接字有效。

存储 数据发送到 UDP 套接字时要立即调用的函数地址。