netconn_write() — Send data on TCP connection


err_t netconn_write (struct netconn *conn , void *data , u16_t len , u8_t copy );


This function is only used for TCP connections. It puts the data pointed to by data on the output queue for the TCP connection conn. The length of the data is given by len. There is no restriction on the length of the data. This function does not require the application to explicitly allocate buffers, as this is taken care of by the stack. The copy parameter is a combination of the following bitmask flags:

#define NETCONN_NOFLAG 0x00
#define NETCONN_COPY 0x01
#define NETCONN_MORE 0x02

When passed the flag NETCONN_COPY the data is copied into internal buffers which are allocated for the data. This allows the data to be modified directly after the call, but is inefficient both in terms of execution time and memory usage. If the flag is not set then the data is not copied but rather referenced, and the NETCONN_NOCOPY manifest is provided for backwards compatibality. The data must not be modified after the call, since the data can be put on the retransmission queue for the connection, and stay there for an indeterminate amount of time. This is useful when sending data that is located in ROM and therefore is immutable. If greater control over the modifiability of the data is needed, a combination of copied and non-copied data can be used, as seen in the example below.

The flag NETCONN_MORE can be used for TCP connections and indicates that the PSH (push) flag will be set on the last segment sent. The flag NETCONN_DONTBLOCK tells the stack to only write the data if all the data can be written at once.


Example 164.7. This example demonstrates basic usage of the netconn_write() function [*]

Here, the variable data is assumed to be modified later in the program, and is therefore copied into the internal bufiers by passing the flag NETCONN_COPY to netconn_write(). The text variable contains a string that will not be modified and can therefore be sent using references instead of copying.

    struct netconn *conn;
    char data[10];
    char text[] = "Static text";
    int i;

    /* set up the connection conn */
    /* […] */

    /* create some arbitrary data */
    for(i = 0; i < 10; i++)
        data[i] = i;

    netconn_write(conn, data, 10, NETCONN_COPY);
    netconn_write(conn, text, sizeof(text), NETCONN_NOFLAG);

    /* the data can be modified */
    for(i = 0; i < 10; i++)
        data[i] = 10 - i;

    /* take down the connection conn */

[*] This is only an example for illustrative purposes, and a complete version should perform comprehensive error checking.