From 6e18d454004fcaff4b6064c04989db51393395e7 Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Sat, 4 Sep 2010 13:19:28 +0200 Subject: src: convert documentation from kerneldoc to doxygen format Still missing several enumerations that should be documented. You still have to look at libnetfilter_conntrack.h to check conntrack object attributes. Signed-off-by: Pablo Neira Ayuso --- src/expect/api.c | 218 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 136 insertions(+), 82 deletions(-) (limited to 'src/expect') diff --git a/src/expect/api.c b/src/expect/api.c index 7a11f53..d560178 100644 --- a/src/expect/api.c +++ b/src/expect/api.c @@ -12,6 +12,11 @@ #include "internal/internal.h" +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_new - allocate a new expectation * @@ -33,7 +38,7 @@ struct nf_expect *nfexp_new(void) /** * nfexp_destroy - release an expectation object - * @exp: pointer to the expectation object + * \param exp pointer to the expectation object */ void nfexp_destroy(struct nf_expect *exp) { @@ -44,7 +49,7 @@ void nfexp_destroy(struct nf_expect *exp) /** * nfexp_sizeof - return the size in bytes of a certain expect object - * @exp: pointer to the expect object + * \param exp pointer to the expect object */ size_t nfexp_sizeof(const struct nf_expect *exp) { @@ -57,11 +62,11 @@ size_t nfexp_sizeof(const struct nf_expect *exp) * * Use this function if you want to allocate a expect object in the stack * instead of the heap. For example: - * + * * char buf[nfexp_maxsize()]; * struct nf_expect *exp = (struct nf_expect *) buf; * memset(exp, 0, nfexp_maxsize()); - * + * * Note: As for now this function returns the same size that nfexp_sizeof(exp) * does although _this could change in the future_. Therefore, do not assume * that nfexp_sizeof(exp) == nfexp_maxsize(). @@ -73,7 +78,7 @@ size_t nfexp_maxsize(void) /** * nfexp_clone - clone a expectation object - * @exp: pointer to a valid expectation object + * \param exp pointer to a valid expectation object * * On error, NULL is returned and errno is appropiately set. Otherwise, * a valid pointer to the clone expect is returned. @@ -91,16 +96,25 @@ struct nf_expect *nfexp_clone(const struct nf_expect *exp) return clone; } +/** + * @} + */ + +/** + * \defgroup LibrarySetup Library setup + * @{ + */ + /** * nfexp_callback_register - register a callback - * @h: library handler - * @cb: callback used to process expect received - * @data: data used by the callback, if any. + * \param h library handler + * \param cb callback used to process expect received + * \param data data used by the callback, if any. * * This function register a callback to handle the expect received, * in case of error -1 is returned and errno is set appropiately, otherwise * 0 is returned. - * + * * Note that the data parameter is optional, if you do not want to pass any * data to your callback, then use NULL. */ @@ -142,7 +156,7 @@ int nfexp_callback_register(struct nfct_handle *h, /** * nfexp_callback_unregister - unregister a callback - * @h: library handler + * \param h library handler */ void nfexp_callback_unregister(struct nfct_handle *h) { @@ -161,20 +175,20 @@ void nfexp_callback_unregister(struct nfct_handle *h) /** * nfexp_callback_register2 - register a callback - * @h: library handler - * @cb: callback used to process expect received - * @data: data used by the callback, if any. + * \param h library handler + * \param cb callback used to process expect received + * \param data data used by the callback, if any. * * This function register a callback to handle the expect received, * in case of error -1 is returned and errno is set appropiately, otherwise * 0 is returned. - * + * * Note that the data parameter is optional, if you do not want to pass any * data to your callback, then use NULL. - * + * * NOTICE: The difference with nfexp_callback_register() is that this function * uses the new callback interface that includes the Netlink header. - * + * * WARNING: Don't mix nfexp_callback_register() and nfexp_callback_register2() * calls, use only once at a time. */ @@ -217,7 +231,7 @@ int nfexp_callback_register2(struct nfct_handle *h, /** * nfexp_callback_unregister2 - unregister a callback - * @h: library handler + * \param h library handler */ void nfexp_callback_unregister2(struct nfct_handle *h) { @@ -234,11 +248,20 @@ void nfexp_callback_unregister2(struct nfct_handle *h) h->nfnl_cb.attr_count = 0; } +/** + * @} + */ + +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_set_attr - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: pointer to the attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value pointer to the attribute value * * Note that certain attributes are unsettable: * - ATTR_EXP_USE @@ -264,9 +287,9 @@ void nfexp_set_attr(struct nf_expect *exp, /** * nfexp_set_attr_u8 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 8 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 8 bits attribute value */ void nfexp_set_attr_u8(struct nf_expect *exp, const enum nf_expect_attr type, @@ -277,9 +300,9 @@ void nfexp_set_attr_u8(struct nf_expect *exp, /** * nfexp_set_attr_u16 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 16 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 16 bits attribute value */ void nfexp_set_attr_u16(struct nf_expect *exp, const enum nf_expect_attr type, @@ -290,9 +313,9 @@ void nfexp_set_attr_u16(struct nf_expect *exp, /** * nfexp_set_attr_u32 - set the value of a certain expect attribute - * @exp: pointer to a valid expect - * @type: attribute type - * @value: unsigned 32 bits attribute value + * \param exp pointer to a valid expect + * \param type attribute type + * \param value unsigned 32 bits attribute value */ void nfexp_set_attr_u32(struct nf_expect *exp, const enum nf_expect_attr type, @@ -303,8 +326,8 @@ void nfexp_set_attr_u32(struct nf_expect *exp, /** * nfexp_get_attr - get an expect attribute - * exp: pointer to a valid expect - * @type: attribute type + * \param exp pointer to a valid expect + * \param type attribute type * * In case of success a valid pointer to the attribute requested is returned, * on error NULL is returned and errno is set appropiately. @@ -329,8 +352,8 @@ const void *nfexp_get_attr(const struct nf_expect *exp, /** * nfexp_get_attr_u8 - get attribute of unsigned 8-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -345,8 +368,8 @@ u_int8_t nfexp_get_attr_u8(const struct nf_expect *exp, /** * nfexp_get_attr_u16 - get attribute of unsigned 16-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -361,8 +384,8 @@ u_int16_t nfexp_get_attr_u16(const struct nf_expect *exp, /** * nfexp_get_attr_u32 - get attribute of unsigned 32-bits long - * @exp: pointer to a valid expectation - * @type: attribute type + * \param exp pointer to a valid expectation + * \param type attribute type * * Returns the value of the requested attribute, if the attribute is not * set, 0 is returned. In order to check if the attribute is set or not, @@ -377,8 +400,8 @@ u_int32_t nfexp_get_attr_u32(const struct nf_expect *exp, /** * nfexp_attr_is_set - check if a certain attribute is set - * @exp: pointer to a valid expectation object - * @type: attribute type + * \param exp pointer to a valid expectation object + * \param type attribute type * * On error, -1 is returned and errno is set appropiately, otherwise * the value of the attribute is returned. @@ -397,9 +420,9 @@ int nfexp_attr_is_set(const struct nf_expect *exp, /** * nfexp_attr_unset - unset a certain attribute - * @type: attribute type - * @exp: pointer to a valid expectation object - * + * \param type attribute type + * \param exp pointer to a valid expectation object + * * On error, -1 is returned and errno is set appropiately, otherwise * 0 is returned. */ @@ -417,19 +440,28 @@ int nfexp_attr_unset(struct nf_expect *exp, return 0; } +/** + * @} + */ + +/** + * \defgroup nl Low level object to Netlink message + * @{ + */ + /** * nfexp_build_expect - build a netlink message from a conntrack object - * @ssh: nfnetlink subsystem handler - * @req: buffer used to build the netlink message - * @size: size of the buffer passed - * @type: netlink message type - * @flags: netlink flags - * @exp: pointer to a conntrack object + * \param ssh nfnetlink subsystem handler + * \param req buffer used to build the netlink message + * \param size size of the buffer passed + * \param type netlink message type + * \param flags netlink flags + * \param exp pointer to a conntrack object * * This is a low level function for those that require to be close to * netlink details via libnfnetlink. If you do want to obviate the netlink * details then we suggest you to use nfexp_query. - * + * * On error, -1 is returned and errno is appropiately set. * On success, 0 is returned. */ @@ -449,31 +481,31 @@ static int nfexp_build_expect(struct nfnl_subsys_handle *ssh, /** * nfexp_build_query - build a query in netlink message format for ctnetlink - * @ssh: nfnetlink subsystem handler - * @qt: query type - * @data: data required to build the query - * @req: buffer to build the netlink message - * @size: size of the buffer passed + * \param ssh nfnetlink subsystem handler + * \param qt query type + * \param data data required to build the query + * \param req buffer to build the netlink message + * \param size size of the buffer passed * * This is a low level function, use it if you want to require to work * with netlink details via libnfnetlink, otherwise we suggest you to * use nfexp_query. - * + * * The pointer to data can be a conntrack object or the protocol family * depending on the request. - * + * * For query types: * NFEXP_Q_CREATE * NFEXP_Q_DESTROY - * + * * Pass a valid pointer to an expectation object. - * + * * For query types: * NFEXP_Q_FLUSH * NFEXP_Q_DUMP - * + * * Pass a valid pointer to the protocol family (u_int8_t) - * + * * On success, 0 is returned. On error, -1 is returned and errno is set * appropiately. */ @@ -517,24 +549,24 @@ static int nfexp_build_query(struct nfnl_subsys_handle *ssh, /** * nfexp_parse_expect - translate a netlink message to a conntrack object - * @type: do the translation iif the message type is of a certain type - * @nlh: pointer to the netlink message - * @exp: pointer to the conntrack object + * \param type do the translation iif the message type is of a certain type + * \param nlh pointer to the netlink message + * \param exp pointer to the conntrack object * * This is a low level function, use it in case that you require to work * with netlink details via libnfnetlink. Otherwise, we suggest you to * use the high level API. - * + * * The message types are: - * + * * NFEXP_T_NEW: parse messages with new conntracks * NFEXP_T_UPDATE: parse messages with conntrack updates * NFEXP_T_DESTROY: parse messages with conntrack destroy * NFEXP_T_ALL: all message types - * + * * The message type is a flag, therefore the can be combined, ie. * NFEXP_T_NEW | NFEXP_T_DESTROY to parse only new and destroy messages - * + * * On error, NFEXP_T_ERROR is returned and errno is set appropiately. If * the message received is not of the requested type then 0 is returned, * otherwise this function returns the message type parsed. @@ -568,11 +600,20 @@ static int nfexp_parse_expect(enum nf_conntrack_msg_type type, return flags; } +/** + * @} + */ + +/** + * \defgroup cmd Send commands to kernel-space and receive replies + * @{ + */ + /** * nfexp_query - send a query to ctnetlink - * @h: library handler - * @qt: query type - * @data: data required to send the query + * \param h library handler + * \param qt query type + * \param data data required to send the query * * On error, -1 is returned and errno is explicitely set. On success, 0 * is returned. @@ -598,7 +639,7 @@ int nfexp_query(struct nfct_handle *h, /** * nfexp_catch - catch events - * @h: library handler + * \param h library handler * * On error, -1 is returned and errno is set appropiately. On success, * a value greater or equal to 0 is returned indicating the callback @@ -611,28 +652,37 @@ int nfexp_catch(struct nfct_handle *h) return nfnl_catch(h->nfnlh); } +/** + * @} + */ + +/** + * \defgroup exp Expect object handling + * @{ + */ + /** * nfexp_snprintf - print a conntrack object to a buffer - * @buf: buffer used to build the printable conntrack - * @size: size of the buffer - * @exp: pointer to a valid expectation object - * @message_type: print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...) - * @output_type: print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...) - * @flags: extra flags for the output type (NFEXP_OF_LAYER3) - * - * If you are listening to events, probably you want to display the message + * \param buf buffer used to build the printable conntrack + * \param size size of the buffer + * \param exp pointer to a valid expectation object + * \param message_type print message type (NFEXP_T_UNKNOWN, NFEXP_T_NEW,...) + * \param output_type print type (NFEXP_O_DEFAULT, NFEXP_O_XML, ...) + * \param flags extra flags for the output type (NFEXP_OF_LAYER3) + * + * If you are listening to events, probably you want to display the message * type as well. In that case, set the message type parameter to any of the * known existing types, ie. NFEXP_T_NEW, NFEXP_T_UPDATE, NFEXP_T_DESTROY. * If you pass NFEXP_T_UNKNOWN, the message type will not be output. - * + * * Currently, the output available are: * - NFEXP_O_DEFAULT: default /proc-like output * - NFEXP_O_XML: XML output - * + * * The output flags are: * - NFEXP_O_LAYER: include layer 3 information in the output, this is * *only* required by NFEXP_O_DEFAULT. - * + * * On error, -1 is returned and errno is set appropiately. Otherwise, * 0 is returned. */ @@ -649,3 +699,7 @@ int nfexp_snprintf(char *buf, return __snprintf_expect(buf, size, exp, msg_type, out_type, flags); } + +/** + * @} + */ -- cgit v1.2.3