marc
/
RIOT
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: fix doxygen warnings for CBOR

Browse Source
dev/timer
Oleg Hahm 8 years ago
parent 67a2b37ff8
commit 93c7627f07
1 changed files with 117 additions and 51 deletions
Show Stats Download Patch File Download Diff File

168
sys/include/cbor.h
Unescape Escape View File

@ -129,46 +129,52 @@ extern "C" {
* @sa cbor_destroy
*/
typedef struct cbor_stream_t {
/* Array containing CBOR encoded data */
/** Array containing CBOR encoded data */
unsigned char *data;
/* Size of the array */
/** Size of the array */
size_t size;
/* Index to the next free byte */
/** Index to the next free byte */
size_t pos;
} cbor_stream_t;
/**
* Initialize cbor struct
* @brief Initialize cbor struct
*
* @note Does *not* take ownership of @p buffer
*
* @param buffer The buffer used for storing CBOR-encoded data
* @param size The size of buffer @p buffer
* @param[in] stream The cbor struct to initialize
* @param[in] buffer The buffer used for storing CBOR-encoded data
* @param[in] size The size of buffer @p buffer
*/
void cbor_init(cbor_stream_t *stream, unsigned char *buffer, size_t size);
/**
* Clear cbor struct
* @brief Clear cbor struct
*
* Sets pos to zero
*
* Sets pos to zero
* @param[in, out] stream Pointer to the cbor struct
*/
void cbor_clear(cbor_stream_t *stream);
/**
* Destroy the cbor struct
* @brief Destroy the cbor struct
*
* @note Does *not* free data
*
* @param[in, out] stream Pointer to the cbor struct
*/
void cbor_destroy(cbor_stream_t *stream);
#ifndef CBOR_NO_PRINT
/**
* Print @p stream in hex representation
* @brief Print @p stream in hex representation
*
* @param[in] stream Pointer to the cbor struct
*/
void cbor_stream_print(const cbor_stream_t *stream);
/**
* Decode CBOR from @p stream
* @brief Decode CBOR from @p stream
*
* This method interprets the data and prints each item in its natural representation
*
@ -181,6 +187,8 @@ void cbor_stream_print(const cbor_stream_t *stream);
* (tag: 0, date/time string: "Mon Jul 14 19:07:40 2014")
* (tag: 1, date/time epoch: 1405357660)
* @endcode
*
* @param[in] stream Pointer to the cbor struct
*/
void cbor_stream_decode(cbor_stream_t *stream);
#endif /* CBOR_NO_PRINT */
@ -203,26 +211,35 @@ size_t cbor_deserialize_double(const cbor_stream_t *stream, size_t offset, doubl
#endif /* CBOR_NO_FLOAT */
size_t cbor_serialize_byte_string(cbor_stream_t *s, const char *val);
/**
* Deserialize bytes from @p stream to @p val
* @brief Deserialize bytes from @p stream to @p val
*
* @param[in] stream The stream to deserialize
* @param[in] offset The offset within the stream where to start deserializing
* @param[in] val Pointer to destination array
* @param[in] length Length of destination array
*
* @param val Pointer to destination array
* @param length Length of destination array
* @return Number of bytes written into @p val
*/
size_t cbor_deserialize_byte_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length);
size_t cbor_serialize_unicode_string(cbor_stream_t *s, const char *val);
size_t cbor_serialize_unicode_string(cbor_stream_t *stream, const char *val);
/**
* Deserialize unicode string from @p stream to @p val
* @brief Deserialize unicode string from @p stream to @p val
*
* @param[in] stream The stream to deserialize
* @param[in] offset The offset within the stream where to start deserializing
* @param[in] val Pointer to destination array
* @param[in] length Length of destination array
*
* @param val Pointer to destination array
* @param length Length of destination array
* @return Number of bytes written into @p val
*/
size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, size_t offset, char *val, size_t length);
/**
* Serialize array of length @p array_length
* @brief Serialize array of length @p array_length
*
* Basic usage:
* @code
@ -234,32 +251,40 @@ size_t cbor_deserialize_unicode_string(const cbor_stream_t *stream, size_t offse
* @note You have to make sure to serialize the correct amount of items.
* If you exceed the length @p array_length, items will just be appened as normal
*
* @param array_length Length of the array of items which follows
* @param[out] stream The destination stream for serializing the array
* @param[in] array_length Length of the array of items which follows
*
* @return Number of bytes written to stream @p s
* @return Number of bytes written to stream @p stream
*/
size_t cbor_serialize_array(cbor_stream_t *s, size_t array_length);
size_t cbor_serialize_array(cbor_stream_t *stream, size_t array_length);
/**
* Deserialize array of items
* @brief Deserialize array of items
*
* Basic usage:
* @code
* size_t array_length;
* size_t offset = cbor_deserialize_array(&stream, 0, &array_length); // read out length of the array
* // read out length of the array
* size_t offset = cbor_deserialize_array(&stream, 0, &array_length);
* int i1, i2;
* offset += cbor_deserialize_int(&stream, offset, &i1); // read item 1
* offset += cbor_deserialize_int(&stream, offset, &i2); // read item 2
* @endcode
*
* @param array_length Where the array length is stored
* @param[in] stream The stream to deserialize
* @param[in] offset The offset within the stream
* @param[in] array_length Where the array length is stored
*
* @return Number of deserialized bytes from stream
*/
size_t cbor_deserialize_array(const cbor_stream_t *s, size_t offset, size_t *array_length);
size_t cbor_deserialize_array(const cbor_stream_t *stream, size_t offset, size_t *array_length);
size_t cbor_serialize_array_indefinite(cbor_stream_t *s);
size_t cbor_deserialize_array_indefinite(const cbor_stream_t *s, size_t offset);
size_t cbor_serialize_array_indefinite(cbor_stream_t *stream);
size_t cbor_deserialize_array_indefinite(const cbor_stream_t *stream, size_t offset);
/**
* Serialize map of length @p map_length
* @brief Serialize map of length @p map_length
*
* Basic usage:
* @code
@ -270,11 +295,15 @@ size_t cbor_deserialize_array_indefinite(const cbor_stream_t *s, size_t offset);
* cbor_serialize_byte_string(&stream, "2")); // write value 2
* @endcode
*
* @param[out] stream The destination stream for serializing the map
* @param map_length Length of the map of items which follows
*
* @return Number of bytes written to stream @p stream
*/
size_t cbor_serialize_map(cbor_stream_t *s, size_t map_length);
size_t cbor_serialize_map(cbor_stream_t *stream, size_t map_length);
/**
* Deserialize map of items
* @brief Deserialize map of items
*
* Basic usage:
* @code
@ -288,17 +317,22 @@ size_t cbor_serialize_map(cbor_stream_t *s, size_t map_length);
* offset += cbor_deserialize_byte_string(&stream, offset, value2, sizeof(value)); // read value 2
* @endcode
*
* @param map_length Where the array length is stored
* @param[in] stream The stream to deserialize
* @param[in] offset The offset within the stream where to start deserializing
* @param[in] map_length Where the array length is stored
*
* @return Number of deserialized bytes from @p stream
*/
size_t cbor_deserialize_map(const cbor_stream_t *s, size_t offset, size_t *map_length);
size_t cbor_deserialize_map(const cbor_stream_t *stream, size_t offset, size_t *map_length);
size_t cbor_serialize_map_indefinite(cbor_stream_t *s);
size_t cbor_deserialize_map_indefinite(const cbor_stream_t *s, size_t offset);
size_t cbor_serialize_map_indefinite(cbor_stream_t *stream);
size_t cbor_deserialize_map_indefinite(const cbor_stream_t *stream, size_t offset);
#ifndef CBOR_NO_SEMANTIC_TAGGING
#ifndef CBOR_NO_CTIME
/**
* Serialize date and time
* @brief Serialize date and time
*
* Basic usage:
* @code
@ -313,11 +347,15 @@ size_t cbor_deserialize_map_indefinite(const cbor_stream_t *s, size_t offset);
* cbor_serialize_date_time(&stream, &val);
* @endcode
*
* @param val tm struct containing the date/time info to be encoded
* @param[out] stream The destination stream for serializing the date_time
* @param[in] val tm struct containing the date/time info to be encoded
*
* @return Number of bytes written to stream @p stream
*/
size_t cbor_serialize_date_time(cbor_stream_t *stream, struct tm *val);
/**
* Deserialize date and time
* @brief Deserialize date and time
*
* Basic usage:
* @code
@ -325,48 +363,76 @@ size_t cbor_serialize_date_time(cbor_stream_t *stream, struct tm *val);
* cbor_deserialize_date_time(&stream, 0, &val);
* @endcode
*
* @param val tm struct where the decoded date/time will be stored
* @param[in] stream The stream to deserialize
* @param[in] offset The offset within the stream where to start deserializing
* @param[in] val tm struct where the decoded date/time will be stored
*
* @return The number of deserialized bytes
*/
size_t cbor_deserialize_date_time(const cbor_stream_t *stream, size_t offset, struct tm *val);
size_t cbor_serialize_date_time_epoch(cbor_stream_t *stream, time_t val);
size_t cbor_deserialize_date_time_epoch(const cbor_stream_t *stream, size_t offset, time_t *val);
#endif /* CBOR_NO_CTIME */
/**
* Write a tag to give the next CBOR item additional semantics
* @brief Write a tag to give the next CBOR item additional semantics
*
* Also see https://tools.ietf.org/html/rfc7049#section-2.4 (Optional Tagging of Items)
*
* @param[in, out] stream Pointer to the cbor struct
* @param[in] tag The tag to write
*
* @return Always 1
*/
size_t cbor_write_tag(cbor_stream_t *s, unsigned char tag);
size_t cbor_write_tag(cbor_stream_t *stream, unsigned char tag);
/**
* Whether we are at a tag symbol in stream @p s at offset @p offset
* @brief Whether we are at a tag symbol in stream @p stream at offset @p offset
*
* @param[in] stream Pointer to the cbor struct
* @param[in] offset The offset within @p stream
*
* @return True in case there is a tag symbol at the current offset
*/
bool cbor_at_tag(const cbor_stream_t *s, size_t offset);
bool cbor_at_tag(const cbor_stream_t *stream, size_t offset);
#endif /* CBOR_NO_SEMANTIC_TAGGING */
/**
* Write a break symbol at the current offset in stream @p s
* @brief Write a break symbol at the current offset in stream @p stream
*
* Used for marking the end of indefinite length CBOR items
*
* @param[in] stream Pointer to the cbor struct
*
* @return Always 1
*/
#endif /* CBOR_NO_SEMANTIC_TAGGING */
size_t cbor_write_break(cbor_stream_t *stream);
size_t cbor_write_break(cbor_stream_t *s);
/**
* Whether we are at a break symbol in stream @p s at offset @p offset
* @brief Whether we are at a break symbol in stream @p stream at offset @p offset
*
* @param[in] stream Pointer to the cbor struct
* @param[in] offset The offset within @p stream
*
* @return True in case the there is a break symbol at the current offset
*/
bool cbor_at_break(const cbor_stream_t *s, size_t offset);
bool cbor_at_break(const cbor_stream_t *stream, size_t offset);
/**
* Whether we are at the end of the stream @p s at offset @p offset
* @brief Whether we are at the end of the stream @p stream at offset @p offset
*
* Useful for abort conditions in loops while deserializing CBOR items
*
* @param[in] stream Pointer to the cbor struct
* @param[in] offset The offset within @p stream
*
* @return True in case @p offset marks the end of the stream
*/
bool cbor_at_end(const cbor_stream_t *s, size_t offset);
bool cbor_at_end(const cbor_stream_t *stream, size_t offset);
#ifdef __cplusplus
}

Write Preview
Loading…
Cancel
Save