diff options
| -rw-r--r-- | include/dect/ie.h | 41 | ||||
| -rw-r--r-- | include/dect/s_fmt.h | 6 | ||||
| -rw-r--r-- | src/s_msg.c | 54 |
3 files changed, 87 insertions, 14 deletions
diff --git a/include/dect/ie.h b/include/dect/ie.h index 410d36e..ed1b969 100644 --- a/include/dect/ie.h +++ b/include/dect/ie.h @@ -25,16 +25,21 @@ extern "C" { struct dect_handle; /** - * struct dect_ie_collection - common representation of a DECT IE collection + * Common representation of a DECT IE collection * - * @arg refcnt reference count - * @arg size size of entire collection - * @arg ie dynamic amount of IEs/IE lists + * IE collections are used to encapsulate sets of IEs, like parameters of libdect + * primitives. IE collections passed upwards from libdect are allocated and + * reference counted, the contained IEs will not be released while references to + * the IE collection are held. IE collections passed to libdect primitives may be + * allocated on the stack. + * + * The members of this structure may only be manipulated through the appropriate + * helper functions. */ struct dect_ie_collection { - unsigned int refcnt; - unsigned int size; - struct dect_ie_common *ie[]; + unsigned int refcnt; /**< Reference count */ + unsigned int size; /**< Size if bytes of entire collection */ + struct dect_ie_common *ie[]; /**< Dynamic amount of IEs/IE lists */ }; extern void *dect_ie_collection_alloc(const struct dect_handle *dh, unsigned int size); @@ -55,14 +60,19 @@ extern void __dect_ie_collection_put(const struct dect_handle *dh, struct dect_i #define dect_ie_collection_put(dh, iec) __dect_ie_collection_put(dh, &(iec)->common) /** - * struct dect_ie_common - common representation of a DECT IE + * Common representation of a DECT IE + * + * Every IE contains a struct dect_ie_common to support operations common to all + * IE types. IEs passed upwards from libdect are allocated and reference counted, + * they will not be freed while references to the Information Element are held. + * IEs Elements passed to libdect primitives may be allocated on the stack. * - * @arg next IE list list node - * @arg refcnt reference count + * The members of this structure may only be manipulated through the appropriate + * helper functions. */ struct dect_ie_common { - struct dect_ie_common *next; - unsigned int refcnt; + struct dect_ie_common *next; /**< IE list list node */ + unsigned int refcnt; /**< Reference count */ }; /** @@ -108,13 +118,18 @@ extern void __dect_ie_put(const struct dect_handle *dh, struct dect_ie_common *i /* Repeat indicator */ /** - * enum dect_ie_list_types - Repeat indicator list types + * Repeat indicator list types */ enum dect_ie_list_types { DECT_IE_LIST_NORMAL = 0x1, /**< Non prioritized list */ DECT_IE_LIST_PRIORITIZED = 0x2, /**< Prioritized list */ }; +/** + * Repeat indicator + * + * A repeat indicator contains a list of Information Elements. + */ struct dect_ie_list { struct dect_ie_common common; enum dect_ie_list_types type; diff --git a/include/dect/s_fmt.h b/include/dect/s_fmt.h index 7df2354..0b7cc08 100644 --- a/include/dect/s_fmt.h +++ b/include/dect/s_fmt.h @@ -11,6 +11,11 @@ extern "C" { #endif +/** + * @addtogroup ie_sfmt + * @{ + */ + /* * Information elements */ @@ -137,6 +142,7 @@ extern enum dect_sfmt_error dect_parse_sfmt_ie_header(struct dect_sfmt_ie *ie, extern enum dect_sfmt_error dect_parse_sfmt_ie(const struct dect_handle *dh, uint8_t type, struct dect_ie_common **dst, const struct dect_sfmt_ie *ie); +/** @} */ #ifdef __cplusplus } diff --git a/src/s_msg.c b/src/s_msg.c index 8c41cbe..9ce5a68 100644 --- a/src/s_msg.c +++ b/src/s_msg.c @@ -8,6 +8,16 @@ * published by the Free Software Foundation. */ +/** + * @defgroup ie_sfmt S-Format encoded IEs + * + * Raw S-Format encoded IE construction and parsing functions. Usually the + * libdect user deals only with readily parsed IE structures representing the + * S-Format encoded IEs, however the CLMS service carries raw encoded IEs. + * + * @{ + */ + #include <stdint.h> #include <stdio.h> #include <string.h> @@ -2414,6 +2424,17 @@ static void dect_msg_ie_init(const struct dect_sfmt_ie_desc *desc, #endif } +/** + * Parse a S-Format encoded Information Element header + * + * @ie: result pointer to the Information Element + * @mb: message buffer + * + * Parse a S-Format encoded Information Element header and return the parsed + * information in the ie structure. + * + * @return 0 on success or -1 if a parsing error occured. + */ enum dect_sfmt_error dect_parse_sfmt_ie_header(struct dect_sfmt_ie *ie, const struct dect_msg_buf *mb) @@ -2472,10 +2493,25 @@ static int dect_build_sfmt_ie_header(struct dect_sfmt_ie *dst, uint8_t id) return 0; } +/** + * Parse a S-Format encoded Information Element + * + * @param dh libdect DECT handle + * @param type IE type + * @param dst result pointer to the allocated information element + * @param ie information element + * + * Parse a S-Format encoded Information Element and return an allocated IE + * structure. + * + * @return #DECT_SFMT_OK on success or one of the @ref dect_sfmt_error + * "S-Format error codes" on error. On success the dst parameter is set to + * point to the allocated information element structure. + */ enum dect_sfmt_error dect_parse_sfmt_ie(const struct dect_handle *dh, uint8_t type, struct dect_ie_common **dst, - const const struct dect_sfmt_ie *ie) + const struct dect_sfmt_ie *ie) { const struct dect_ie_handler *ieh; int err = -1; @@ -2606,6 +2642,20 @@ out: return DECT_SFMT_OK; } +/** + * Construct a S-Format encoded Information Element + * + * @param dh libdect DECT handle + * @param type IE type + * @param mb message buffer to append IE to + * @param ie information element + * + * Construct a S-Format encoded Information Element and append it to the message + * buffer. + * + * @return #DECT_SFMT_OK on success or one of the @ref dect_sfmt_error + * "S-Format error codes" on error. + */ enum dect_sfmt_error dect_build_sfmt_ie(const struct dect_handle *dh, uint8_t type, struct dect_msg_buf *mb, @@ -2740,3 +2790,5 @@ void dect_msg_free(const struct dect_handle *dh, desc++; } } + +/** @} */ |