bufferlist_* functions have no documentation whatsoever and the name is
not always enough to fully understand what the function is doing.
For this reason and for the sake of having better documented code, add
function doc in buffer.h.
Signed-off-by: Antonio Quartulli <a...@unstable.cc>
---
Some doc might be extended and some might be unecessary.
Still I think it is good to start having doc for more helper functions
we have around.
src/openvpn/buffer.h | 67 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h
index cb9e9dff..dbc5bfc3 100644
--- a/src/openvpn/buffer.h
+++ b/src/openvpn/buffer.h
@@ -1091,26 +1091,93 @@ struct buffer_list
int max_size; /* maximum size list should grow to */
};
+/**
+ * Allocate an empty buffer list of capacity \c max_size.
+ *
+ * @param max_size the capacity of the list to allocate
+ *
+ * @return the new list
+ */
struct buffer_list *buffer_list_new(const int max_size);
+/**
+ * Frees a buffer list and all the buffers in it.
+ *
+ * @param ol the list to free
+ */
void buffer_list_free(struct buffer_list *ol);
+/**
+ * Checks if the list is valid and non-empty
+ *
+ * @param ol the list to check
+ *
+ * @return true iff \c ol is not NULL and contains at least one buffer
+ */
bool buffer_list_defined(const struct buffer_list *ol);
+/**
+ * Empty the list \c ol and frees all the contained buffers
+ *
+ * @param ol the list to reset
+ */
void buffer_list_reset(struct buffer_list *ol);
+/**
+ * Allocates and appends a new buffer containing \c str as data to \c ol
+ *
+ * @param ol the list to append the new buffer to
+ * @param str the string to copy into the new buffer
+ */
void buffer_list_push(struct buffer_list *ol, const char *str);
+/**
+ * Allocatea and appends a new buffer containing \c data of length \c size.
+ *
+ * @param ol the list to append the new buffer to
+ * @param data the data to copy into the new buffer
+ * @param size the length of \c data to copy into the buffer
+ *
+ * @return the new buffer
+ */
struct buffer_entry *buffer_list_push_data(struct buffer_list *ol, const void
*data, size_t size);
+/**
+ * Retrieve the head buffer
+ *
+ * @param ol the list to retrieve the buffer from
+ *
+ * @return a pointer to the head buffer or NULL if the list is empty
+ */
struct buffer *buffer_list_peek(struct buffer_list *ol);
void buffer_list_advance(struct buffer_list *ol, int n);
void buffer_list_pop(struct buffer_list *ol);
+/**
+ * Aggregates as many buffers as possible from \c bl in a new buffer of maximum
+ * length \c max_len .
+ * All the aggregated buffers are removed from the list and replaced by the new
+ * one, followed by any additional (non-aggregated) data.
+ *
+ * @param bl the list of buffer to aggregate
+ * @param max the maximum length of the aggregated buffer
+ */
void buffer_list_aggregate(struct buffer_list *bl, const size_t max);
+/**
+ * Aggregates as many buffers as possible from \c bl in a new buffer
+ * of maximum length \c max_len . \c sep is written after
+ * each copied buffer (also after the last one). All the aggregated buffers are
+ * removed from the list and replaced by the new one, followed by any
additional
+ * (non-aggregated) data.
+ * Nothing happens if \c max_len is not enough to aggregate at least 2 buffers.
+ *
+ * @param bl the list of buffer to aggregate
+ * @param max_len the maximum length of the aggregated buffer
+ * @param sep the separator to put between buffers during aggregation
+ */
void buffer_list_aggregate_separator(struct buffer_list *bl,
const size_t max_len, const char *sep);
--
2.19.1
_______________________________________________
Openvpn-devel mailing list
Openvpn-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/openvpn-devel
