[Linphone-developers] Help about the esballoc() function in oRTP

[Felix TOTIR]

Dear all,

 The help for the esballoc() function defined in oRTP's str_utils.h/str_utils.c states that:

/* allocates a mblk_t, that points to a datab_t, that points to buf; buf will be freed using freefn */
mblk_t *esballoc(uint8_t *buf, int size, int pri, void (*freefn)(void*) );

 From the several examples that I saw in oRTP and Mediastreamer2, the aim of this function is to encapsulate existing data into a mblk_t structure and no more being forced to allocate a mblk_t structure and then copy the data inside the message (through allocb() and, then, some memcpy()).

 First, please confirm that my understanding so far is the correct one.

 Second, I still do not grasp accurately the meaning of the third (pri) and fourth (freefn) parameter of the esballoc().

 The third parameter (int pri) seems to not be used inside the definition of esballoc() inside str_utils.c. It also appears in the allocb(), being named "unused" in the declaration and "pri" into the definition. Why?

 The fourth parameter (void (*freefn)(void*)) is, I suppose, a function that will free the data encapsulated in the mblk_t created by esballoc(). I assume this is made through reference counting: creating the mblk_t through esballoc() will count 1 reference to that thada, any subsequent dupmsg() function will add 1 reference to that data and any freemsg() function will substract 1 reference from that data. When the number of references drops to zero, some function inside oRTP (I assume this function is the freemsg() function) will destroy that data, as no more needed, through a call like freefn(buf) (where buf is the original parameter passed to esballoc()).

 I also assume that, once the data is encapsulated through esballoc(), all pointers pointing to that data shold be dropped (ie. forced to NULL), since any further reading or writing to that data should be rather made through the b_rptr and b_wptr pointers, and the destruction of that data will solely be made through the freemsg() calls. Stated otherwise, after an esballoc() call, the data cease to be application's data, but becomes some kind of data internal to oRTP, very much *like* it would have been created through allocb().

 Now, my questions are:

 Is the above sequence correctly identified?

 How to force that freefn function to simply be the classical free() function of stdlib.h? (I assume it is enough)

 How to use esballoc() in the simple scenario: I have some {void *p; int p_len} data in memory that I want to be encapsulated into a message and passed to the output of some mediastreamer2 filter? I assume free(p) is sufficient to release the memory (is that true, btw?). Finally, it is expected and correct that I should forget about that *p data after passing it through esballoc()?

 Thank you. This should free some burden with data-copying in my algorithms.

Cordially,

 Felix

-- 
"La vie, c'est comme un arc-en-ciel : ça prend du soleil et de la pluie afin d'en savourer toutes les couleurs."