struct espconn and reverse field

[kolban]

The struct espconn data structure has a field in it called "reverse". Looking at the SDK API docs, the comment beside the field is:

// reserved for customer use

I am thinking that we have a typo in the field name and instead of "reverse" (which in English means "to go backwards") it should be "reserved" (which in English means to "pre-allocate in advance").

[ESP_Faye]

Hi,

Thanks for your advice !

So sorry for our poor English ..

We will revise them in next SDK !

[kolban]

Please ... no need to apologize. I'm a huge fan of the ESP8266 and am grateful for all y'alls work and especially for being super responsive to your community.

[zaxl]

Hi,


If you are going to rename the field, please, please do not name it to "reserved".

In english it may mean "pre-allocate in advance" but in any kind of code it means - reserved - do not touch, do not use . Most common case is reserved for future use. Other variants include but not limited to - get proper struct padding, get specific struct size, get specific struct members alignment.

The right way to name a callback data is:
void *data; // user callback data
or
void *callback_data; // if you want to be more verbose
or
void *priv; // which means it's private to the user, i.e. the sdk would not touch it

TIA!

[kolban]

Great catch Zaxl,

My personal vote would be one of:

void *data;

or

void *userData;

[kolban]

I'm starting to get nervous that the "struct espconn -> reverse" property may not be safe for end user applications to store arbitrary pointers of data. Does anyone have any evidence one way or the other whether this pointer contained within a struct espconn can be used for end user applications?

[ESP_Faye]

Hi,

Sorry that we did not modify the "reverse" to be "reserve", because some developers may already use it.

But we are working on RTOS espconn now, it will be fixed in RTOS espconn. It is reserved for user data.

Code: Select all

struct espconn {
    enum espconn_type type;     /**< type of the espconn (TCP or UDP)   */
    enum espconn_state state;   /**< current state of the espconn       */
    union {
        esp_tcp *tcp;
        esp_udp *udp;
    } proto;
    espconn_recv_callback recv_callback;    /**< data received callback */
    espconn_sent_callback sent_callback;    /**< data sent callback     */
    uint8 link_cnt;         /**< link count             */
    void *reserve;          /**< reserved for user data */
};