lib/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2025-05-19 07:13:42 +03:00
Code

Fixed the documentation of buffer.c

Browse Source
This commit is contained in:
Andreas Schneider 2010-04-04 15:00:36 +02:00
parent e736725d35
commit d39dce85b4
1 changed files with 237 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

358
libssh/buffer.c
View File

@ -30,19 +30,25 @@
#include "libssh/priv.h" #include "libssh/priv.h"
#include "libssh/buffer.h" #include "libssh/buffer.h"
/** \defgroup ssh_buffer SSH Buffers
* \brief buffer handling
*/
/** \addtogroup ssh_buffer /**
* @defgroup libssh_buffer The SSH buffer functions.
* @ingroup libssh
*
* Functions to handle SSH buffers.
*
* @{ * @{
*/ */
/** \brief checks that preconditions and postconditions are valid
* \internal
*/
#ifdef DEBUG_BUFFER #ifdef DEBUG_BUFFER
/**
* @internal
*
* @brief Check that preconditions and postconditions are valid.
*
* @param[in] buf The buffer to check.
*/
static void buffer_verify(struct buffer_struct *buf){ static void buffer_verify(struct buffer_struct *buf){
int doabort=0; int doabort=0;
if(buf->data == NULL) if(buf->data == NULL)
@ -67,8 +73,10 @@ static void buffer_verify(struct buffer_struct *buf){
#define buffer_verify(x) #define buffer_verify(x)
#endif #endif
/** \brief creates a new buffer /**
* \return a new initialized buffer, NULL on error. * @brief Create a new SSH buffer.
*
* @return A newly initialized SSH buffer, NULL on error.
*/ */
struct ssh_buffer_struct *buffer_new(void) { struct ssh_buffer_struct *buffer_new(void) {
struct ssh_buffer_struct *buf = malloc(sizeof(struct ssh_buffer_struct)); struct ssh_buffer_struct *buf = malloc(sizeof(struct ssh_buffer_struct));
@ -81,8 +89,10 @@ struct ssh_buffer_struct *buffer_new(void) {
return buf; return buf;
} }
/** \brief deallocate a buffer /**
* \param buffer buffer to free * @brief Deallocate a SSH buffer.
*
* \param[in] buffer The buffer to free.
*/ */
void buffer_free(struct ssh_buffer_struct *buffer) { void buffer_free(struct ssh_buffer_struct *buffer) {
if (buffer == NULL) { if (buffer == NULL) {
@ -118,10 +128,14 @@ static int realloc_buffer(struct ssh_buffer_struct *buffer, int needed) {
return 0; return 0;
} }
/* \internal /**
* \brief reinitialize a buffer * @internal
* \param buffer buffer *
* \return 0 on success, < 0 on error * @brief Reinitialize a SSH buffer.
*
* @param[in] buffer The buffer to reinitialize.
*
* @return 0 on success, < 0 on error.
*/ */
int buffer_reinit(struct ssh_buffer_struct *buffer) { int buffer_reinit(struct ssh_buffer_struct *buffer) {
buffer_verify(buffer); buffer_verify(buffer);
@ -137,11 +151,18 @@ int buffer_reinit(struct ssh_buffer_struct *buffer) {
return 0; return 0;
} }
/** \internal /**
* \brief add data at tail of the buffer * @internal
* \param buffer buffer *
* \param data data pointer * @brief Add data at the tail of a buffer.
* \param len length of data *
* @param[in] buffer The buffer to add the data.
*
* @param[in] data A pointer to the data to add.
*
* @param[in] len The length of the data to add.
*
* @return 0 on success, < 0 on error.
*/ */
int buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t len) { int buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t len) {
buffer_verify(buffer); buffer_verify(buffer);
@ -157,11 +178,16 @@ int buffer_add_data(struct ssh_buffer_struct *buffer, const void *data, uint32_t
return 0; return 0;
} }
/** \internal /**
* \brief add a SSH string to the tail of buffer * @internal
* \param buffer buffer *
* \param string SSH String to add * @brief Add a SSH string to the tail of a buffer.
* \return 0 on success, -1 on error. *
* @param[in] buffer The buffer to add the string.
*
* @param[in] string The SSH String to add.
*
* @return 0 on success, < 0 on error.
*/ */
int buffer_add_ssh_string(struct ssh_buffer_struct *buffer, int buffer_add_ssh_string(struct ssh_buffer_struct *buffer,
struct ssh_string_struct *string) { struct ssh_string_struct *string) {
@ -175,11 +201,16 @@ int buffer_add_ssh_string(struct ssh_buffer_struct *buffer,
return 0; return 0;
} }
/** \internal /**
* \brief add a 32 bits unsigned integer to the tail of buffer * @internal
* \param buffer buffer *
* \param data 32 bits integer * @brief Add a 32 bits unsigned integer to the tail of a buffer.
* \return 0 on success, -1 on error. *
* @param[in] buffer The buffer to add the integer.
*
* @param[in] data The 32 bits integer to add.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data){ int buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data){
if (buffer_add_data(buffer, &data, sizeof(data)) < 0) { if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@ -189,11 +220,16 @@ int buffer_add_u32(struct ssh_buffer_struct *buffer,uint32_t data){
return 0; return 0;
} }
/** \internal /**
* \brief add a 16 bits unsigned integer to the tail of buffer * @internal
* \param buffer buffer *
* \param data 16 bits integer * @brief Add a 16 bits unsigned integer to the tail of a buffer.
* \return 0 on success, -1 on error. *
* @param[in] buffer The buffer to add the integer.
*
* @param[in] data The 16 bits integer to add.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data){ int buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data){
if (buffer_add_data(buffer, &data, sizeof(data)) < 0) { if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@ -203,11 +239,16 @@ int buffer_add_u16(struct ssh_buffer_struct *buffer,uint16_t data){
return 0; return 0;
} }
/** \internal /**
* \brief add a 64 bits unsigned integer to the tail of buffer * @internal
* \param buffer buffer *
* \param data 64 bits integer * @brief Add a 64 bits unsigned integer to the tail of a buffer.
* \return 0 on success, -1 on error. *
* @param[in] buffer The buffer to add the integer.
*
* @param[in] data The 64 bits integer to add.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data){ int buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data){
if (buffer_add_data(buffer, &data, sizeof(data)) < 0) { if (buffer_add_data(buffer, &data, sizeof(data)) < 0) {
@ -216,11 +257,17 @@ int buffer_add_u64(struct ssh_buffer_struct *buffer, uint64_t data){
return 0; return 0;
} }
/** \internal
* \brief add a 8 bits unsigned integer to the tail of buffer /**
* \param buffer buffer * @internal
* \param data 8 bits integer *
* \return 0 on success, -1 on error. * @brief Add a 8 bits unsigned integer to the tail of a buffer.
*
* @param[in] buffer The buffer to add the integer.
*
* @param[in] data The 8 bits integer to add.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data){ int buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data){
if (buffer_add_data(buffer, &data, sizeof(uint8_t)) < 0) { if (buffer_add_data(buffer, &data, sizeof(uint8_t)) < 0) {
@ -230,12 +277,18 @@ int buffer_add_u8(struct ssh_buffer_struct *buffer,uint8_t data){
return 0; return 0;
} }
/** \internal /**
* \brief add data at head of a buffer * @internal
* \param buffer buffer *
* \param data data to add * @brief Add data at the head of a buffer.
* \param len length of data *
* \return 0 on success, -1 on error. * @param[in] buffer The buffer to add the data.
*
* @param[in] data The data to prepend.
*
* @param[in] len The length of data to prepend.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data, int buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data,
uint32_t len) { uint32_t len) {
@ -252,11 +305,17 @@ int buffer_prepend_data(struct ssh_buffer_struct *buffer, const void *data,
return 0; return 0;
} }
/** \internal /**
* \brief append data from a buffer to tail of another * @internal
* \param buffer destination buffer *
* \param source source buffer. Doesn't take position in buffer into account * @brief Append data from a buffer to the tail of another buffer.
* \return 0 on success, -1 on error. *
* @param[in] buffer The destination buffer.
*
* @param[in] source The source buffer to append. It doesn't take the
* position of the buffer into account.
*
* @return 0 on success, -1 on error.
*/ */
int buffer_add_buffer(struct ssh_buffer_struct *buffer, int buffer_add_buffer(struct ssh_buffer_struct *buffer,
struct ssh_buffer_struct *source) { struct ssh_buffer_struct *source) {
@ -267,54 +326,80 @@ int buffer_add_buffer(struct ssh_buffer_struct *buffer,
return 0; return 0;
} }
/** \brief get a pointer on the head of the buffer /**
* \param buffer buffer * @brief Get a pointer on the head of a buffer.
* \return data pointer on the head. Doesn't take position into account. *
* \warning don't expect data to be nul-terminated * @param[in] buffer The buffer to get the head pointer.
* \see buffer_get_rest() *
* \see buffer_get_len() * @return A data pointer on the head. It doesn't take the position
* into account.
*
* @warning Don't expect data to be nul-terminated.
*
* @see buffer_get_rest()
* @see buffer_get_len()
*/ */
void *buffer_get(struct ssh_buffer_struct *buffer){ void *buffer_get(struct ssh_buffer_struct *buffer){
return buffer->data; return buffer->data;
} }
/** \internal /**
* \brief get a pointer to head of the buffer at current position * @internal
* \param buffer buffer *
* \return pointer to the data from current position * @brief Get a pointer to the head of a buffer at the current position.
* \see buffer_get_rest_len() *
* \see buffer_get() * @param[in] buffer The buffer to get the head pointer.
*
* @return A pointer to the data from current position.
*
* @see buffer_get_rest_len()
* @see buffer_get()
*/ */
void *buffer_get_rest(struct ssh_buffer_struct *buffer){ void *buffer_get_rest(struct ssh_buffer_struct *buffer){
return buffer->data + buffer->pos; return buffer->data + buffer->pos;
} }
/** \brief get length of the buffer, not counting position /**
* \param buffer * @brief Get the length of the buffer, not counting position.
* \return length of the buffer *
* \see buffer_get() * @param[in] buffer The buffer to get the length from.
*
* @return The length of the buffer.
*
* @see buffer_get()
*/ */
uint32_t buffer_get_len(struct ssh_buffer_struct *buffer){ uint32_t buffer_get_len(struct ssh_buffer_struct *buffer){
return buffer->used; return buffer->used;
} }
/** \internal /**
* \brief get length of the buffer from the current position * @internal
* \param buffer *
* \return length of the buffer * @brief Get the length of the buffer from the current position.
* \see buffer_get_rest() *
* @param[in] buffer The buffer to get the length from.
*
* @return The length of the buffer.
*
* @see buffer_get_rest()
*/ */
uint32_t buffer_get_rest_len(struct ssh_buffer_struct *buffer){ uint32_t buffer_get_rest_len(struct ssh_buffer_struct *buffer){
buffer_verify(buffer); buffer_verify(buffer);
return buffer->used - buffer->pos; return buffer->used - buffer->pos;
} }
/** \internal /**
* has effect to "eat" bytes at head of the buffer * @internal
* \brief advance the position in the buffer *
* \param buffer buffer * @brief Advance the position in the buffer.
* \param len number of bytes to eat *
* \return new size of the buffer * This has effect to "eat" bytes at head of the buffer.
*
* @param[in] buffer The buffer to advance the position.
*
* @param[in] len The number of bytes to eat.
*
* @return The new size of the buffer.
*/ */
uint32_t buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){ uint32_t buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){
buffer_verify(buffer); buffer_verify(buffer);
@ -330,11 +415,16 @@ uint32_t buffer_pass_bytes(struct ssh_buffer_struct *buffer, uint32_t len){
return len; return len;
} }
/** \internal /**
* \brief cut the end of the buffer * @internal
* \param buffer buffer *
* \param len number of bytes to remove from tail * @brief Cut the end of the buffer.
* \return new size of the buffer *
* @param[in] buffer The buffer to cut.
*
* @param[in] len The number of bytes to remove from the tail.
*
* @return The new size of the buffer.
*/ */
uint32_t buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t len){ uint32_t buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t len){
buffer_verify(buffer); buffer_verify(buffer);
@ -345,13 +435,18 @@ uint32_t buffer_pass_bytes_end(struct ssh_buffer_struct *buffer, uint32_t len){
return len; return len;
} }
/** \internal /**
* \brief gets remaining data out of the buffer. Adjust the read pointer. * @internal
* \param buffer Buffer to read *
* \param data data buffer where to store the data * @brief Get the remaining data out of the buffer and adjust the read pointer.
* \param len length to read from the buffer *
* \returns 0 if there is not enough data in buffer * @param[in] buffer The buffer to read.
* \returns len otherwise. *
* @param[in] data The data buffer where to store the data.
*
* @param[in] len The length to read from the buffer.
*
* @returns 0 if there is not enough data in buffer, len otherwise.
*/ */
uint32_t buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t len){ uint32_t buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t len){
/* /*
@ -365,12 +460,18 @@ uint32_t buffer_get_data(struct ssh_buffer_struct *buffer, void *data, uint32_t
buffer->pos+=len; buffer->pos+=len;
return len; /* no yet support for partial reads (is it really needed ?? ) */ return len; /* no yet support for partial reads (is it really needed ?? ) */
} }
/** \internal
* \brief gets a 8 bits unsigned int out of the buffer. Adjusts the read pointer. /**
* \param buffer Buffer to read * @internal
* \param data pointer to a uint8_t where to store the data *
* \returns 0 if there is not enough data in buffer * @brief Get a 8 bits unsigned int out of the buffer and adjusts the read
* \returns 1 otherwise. * pointer.
*
* @param[in] buffer The buffer to read.
*
* @param[in] data A pointer to a uint8_t where to store the data.
*
* @returns 0 if there is not enough data in buffer, 1 otherwise.
*/ */
int buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){ int buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){
return buffer_get_data(buffer,data,sizeof(uint8_t)); return buffer_get_data(buffer,data,sizeof(uint8_t));
@ -386,21 +487,30 @@ int buffer_get_u8(struct ssh_buffer_struct *buffer, uint8_t *data){
int buffer_get_u32(struct ssh_buffer_struct *buffer, uint32_t *data){ int buffer_get_u32(struct ssh_buffer_struct *buffer, uint32_t *data){
return buffer_get_data(buffer,data,sizeof(uint32_t)); return buffer_get_data(buffer,data,sizeof(uint32_t));
} }
/** \internal /**
* \brief gets a 64 bits unsigned int out of the buffer. Adjusts the read pointer. * @internal
* \param buffer Buffer to read *
* \param data pointer to a uint64_t where to store the data * @brief Get a 64 bits unsigned int out of the buffer and adjusts the read
* \returns 0 if there is not enough data in buffer * pointer.
* \returns 8 otherwise. *
* @param[in] buffer The buffer to read.
*
* @param[in] data A pointer to a uint64_t where to store the data.
*
* @returns 0 if there is not enough data in buffer, 8 otherwise.
*/ */
int buffer_get_u64(struct ssh_buffer_struct *buffer, uint64_t *data){ int buffer_get_u64(struct ssh_buffer_struct *buffer, uint64_t *data){
return buffer_get_data(buffer,data,sizeof(uint64_t)); return buffer_get_data(buffer,data,sizeof(uint64_t));
} }
/** \internal
* \brief gets a SSH String out of the buffer. Adjusts the read pointer. /**
* \param buffer Buffer to read * @internal
* \returns The SSH String read *
* \returns NULL otherwise. * @brief Get a SSH String out of the buffer and adjusts the read pointer.
*
* @param[in] buffer The buffer to read.
*
* @returns The SSH String, NULL on error.
*/ */
struct ssh_string_struct *buffer_get_ssh_string(struct ssh_buffer_struct *buffer) { struct ssh_string_struct *buffer_get_ssh_string(struct ssh_buffer_struct *buffer) {
uint32_t stringlen; uint32_t stringlen;
@ -427,14 +537,18 @@ struct ssh_string_struct *buffer_get_ssh_string(struct ssh_buffer_struct *buffer
return str; return str;
} }
/** \internal
* \brief gets a mpint out of the buffer. Adjusts the read pointer.
* SSH-1 only
* \param buffer Buffer to read
* \returns the SSH String containing the mpint
* \returns NULL otherwise
*/
/**
* @internal
*
* @brief Get a mpint out of the buffer and adjusts the read pointer.
*
* @note This function is SSH-1 only.
*
* @param[in] buffer The buffer to read.
*
* @returns The SSH String containing the mpint, NULL on error.
*/
struct ssh_string_struct *buffer_get_mpint(struct ssh_buffer_struct *buffer) { struct ssh_string_struct *buffer_get_mpint(struct ssh_buffer_struct *buffer) {
uint16_t bits; uint16_t bits;
uint32_t len; uint32_t len;
@ -458,5 +572,7 @@ struct ssh_string_struct *buffer_get_mpint(struct ssh_buffer_struct *buffer) {
} }
return str; return str;
} }
/** @} */
/* vim: set ts=2 sw=2 et cindent: */ /* @} */
/* vim: set ts=4 sw=4 et cindent: */