From 11c83aae730a4350ab9b6d96840efd7abcf9acdd Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Tue, 21 Feb 2012 23:24:16 +0900 Subject: [PATCH] Updated doc --- lib/spdylay_buffer.h | 15 ++++++++--- lib/spdylay_helper.h | 9 +++++-- lib/spdylay_pq.h | 38 +++++++++++++++++++++++++++ lib/spdylay_zlib.c | 8 +++--- lib/spdylay_zlib.h | 61 ++++++++++++++++++++++++++++++++++++++++++-- 5 files changed, 119 insertions(+), 12 deletions(-) diff --git a/lib/spdylay_buffer.h b/lib/spdylay_buffer.h index f46126b6..980e1d51 100644 --- a/lib/spdylay_buffer.h +++ b/lib/spdylay_buffer.h @@ -30,7 +30,6 @@ #endif /* HAVE_CONFIG_H */ #include -#include "spdylay_queue.h" typedef struct spdylay_buffer_chunk { uint8_t *data; @@ -67,9 +66,17 @@ size_t spdylay_buffer_avail(spdylay_buffer *buffer); /* Advances buffer pointer by amount. This reduces available buffer length. */ void spdylay_buffer_advance(spdylay_buffer *buffer, size_t amount); -/* Allocate new chunk buffer. This will increase total length of - buffer (returned by spdylay_buffer_length) by capacity-last_offset. - It means untouched buffer is assumued to be written. */ +/* + * Allocate new chunk buffer. This will increase total length of + * buffer (returned by spdylay_buffer_length) by capacity-last_offset. + * It means untouched buffer is assumued to be written. + * + * This function returns 0 if it succeeds, or one of the following + * negative eror codes: + * + * SPDYLAY_ERR_NOMEM + * Out of memory. + */ int spdylay_buffer_alloc(spdylay_buffer *buffer); /* Returns total length of buffer */ diff --git a/lib/spdylay_helper.h b/lib/spdylay_helper.h index 4ac44768..6108b0ec 100644 --- a/lib/spdylay_helper.h +++ b/lib/spdylay_helper.h @@ -61,10 +61,15 @@ uint32_t spdylay_get_uint32(const uint8_t *data); * allocates new buffer having at least |min_length| bytes and assigns * its pointer to |*buf_ptr| and allocated number of bytes to * |*buflen_ptr|. The memory pointed by |*buf_ptr| previously is - * freed. No memory copy is done between old and new buffer. This - * function returns 0 if it succeeds, or negative error code. + * freed. No memory copy is done between old and new buffer. * |*buf_ptr| and |*buflen_ptr| are only updated iff this function * succeeds. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * SPDYLAY_ERR_NOMEM + * Out of memory. */ int spdylay_reserve_buffer(uint8_t **buf_ptr, size_t *buflen_ptr, size_t min_length); diff --git a/lib/spdylay_pq.h b/lib/spdylay_pq.h index 7009fa43..09ce1b97 100644 --- a/lib/spdylay_pq.h +++ b/lib/spdylay_pq.h @@ -35,22 +35,60 @@ /* Implementation of priority queue */ typedef struct { + /* The pointer to the pointer to the item stored */ void **q; + /* The number of items sotred */ size_t length; + /* The maximum number of items this pq can store. This is + automatically extended when length is reached to this value. */ size_t capacity; + /* The compare function between items */ spdylay_compar compar; } spdylay_pq; +/* + * Initializes priority queue |pq| with compare function |cmp|. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * SPDYLAY_ERR_NOMEM + * Out of memory. + */ int spdylay_pq_init(spdylay_pq *pq, spdylay_compar cmp); +/* + * Deallocates any resources allocated for |pq|. The stored items are + * not freed by this function. + */ void spdylay_pq_free(spdylay_pq *pq); +/* + * Adds |item| to the priority queue |pq|. + * + * This function returns 0 if it succeds, or one of the following + * negative error codes: + * + * SPDYLAY_ERR_NOMEM + * Out of memory. + */ int spdylay_pq_push(spdylay_pq *pq, void *item); +/* + * Returns item at the top of the queue |pq|. If the queue is empty, + * this function returns NULL. + */ void* spdylay_pq_top(spdylay_pq *pq); +/* + * Pops item at the top of the queue |pq|. The popped item is not + * freed by this function. + */ void spdylay_pq_pop(spdylay_pq *pq); +/* + * Returns nonzero if the queue |pq| is empty. + */ int spdylay_pq_empty(spdylay_pq *pq); #endif /* SPDYLAY_PQ_H */ diff --git a/lib/spdylay_zlib.c b/lib/spdylay_zlib.c index 1600915d..623968e3 100644 --- a/lib/spdylay_zlib.c +++ b/lib/spdylay_zlib.c @@ -72,14 +72,14 @@ int spdylay_zlib_inflate_hd_init(spdylay_zlib *inflater) return 0; } -void spdylay_zlib_deflate_free(spdylay_zlib *zlib) +void spdylay_zlib_deflate_free(spdylay_zlib *deflater) { - deflateEnd(&zlib->zst); + deflateEnd(&deflater->zst); } -void spdylay_zlib_inflate_free(spdylay_zlib *zlib) +void spdylay_zlib_inflate_free(spdylay_zlib *inflater) { - inflateEnd(&zlib->zst); + inflateEnd(&inflater->zst); } ssize_t spdylay_zlib_deflate_hd(spdylay_zlib *deflater, diff --git a/lib/spdylay_zlib.h b/lib/spdylay_zlib.h index 938b4b96..3ca3dca1 100644 --- a/lib/spdylay_zlib.h +++ b/lib/spdylay_zlib.h @@ -32,24 +32,81 @@ #include "spdylay_buffer.h" +/* This structure is used for both deflater and inflater. */ typedef struct { z_stream zst; } spdylay_zlib; +/* + * Initializes |deflater| for deflating name/values pairs in the + * frame. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * SPDYLAY_ERR_ZLIB + * The z_stream initialization failed. + */ int spdylay_zlib_deflate_hd_init(spdylay_zlib *deflater); +/* + * Initializes |inflater| for inflating name/values pairs in the + * frame. + * + * This function returns 0 if it succeeds, or one of the following + * negative error codes: + * + * SPDYLAY_ERR_ZLIB + * The z_stream initialization failed. + */ int spdylay_zlib_inflate_hd_init(spdylay_zlib *inflater); -void spdylay_zlib_deflate_free(spdylay_zlib *zlib); +/* + * Deallocates any resources allocated for |deflater|. + */ +void spdylay_zlib_deflate_free(spdylay_zlib *deflater); -void spdylay_zlib_inflate_free(spdylay_zlib *zlib); +/* + * Deallocates any resources allocated for |inflater|. + */ +void spdylay_zlib_inflate_free(spdylay_zlib *inflater); +/* + * Returns the maximum length when |len| bytes of data are deflated by + * |deflater|. + */ size_t spdylay_zlib_deflate_hd_bound(spdylay_zlib *deflater, size_t len); +/* + * Deflates data stored in |in| with length |inlen|. The output is + * written to |out| with length |outlen|. This is not a strict + * requirement but |outlen| should have at least + * spdylay_zlib_deflate_hd_bound(|inlen|) bytes for successful + * operation. + * + * This function returns the number of bytes outputted if it succeeds, + * or one of the following negative error codes: + * + * SPDYLAY_ERR_ZLIB + * The deflate operation failed. + */ ssize_t spdylay_zlib_deflate_hd(spdylay_zlib *deflater, uint8_t *out, size_t outlen, const uint8_t *in, size_t inlen); +/* + * Inflates data stored in |in| with length |inlen|. The output is + * added to |buf|. + * + * This function returns the number of bytes outputted if it succeeds, + * or one of the following negative error codes: + * + * SPDYLAY_ERR_ZLIB + * The inflate operation failed. + * + * SPDYLAY_ERR_NOMEM + * Out of memory. + */ ssize_t spdylay_zlib_inflate_hd(spdylay_zlib *inflater, spdylay_buffer* buf, const uint8_t *in, size_t inlen);