From ef53066dfaf1b5467c790bfa65a295a6cccd7562 Mon Sep 17 00:00:00 2001 From: Pablo Neira Ayuso Date: Sat, 26 May 2012 14:39:48 +0200 Subject: src: improvements for the doxygen documentation Do this before the first official release. Signed-off-by: Pablo Neira Ayuso --- doxygen.cfg.in | 2 +- src/libnetfilter_cttimeout.c | 65 ++++++++++++++++++++++++++++++++++++++------ 2 files changed, 58 insertions(+), 9 deletions(-) diff --git a/doxygen.cfg.in b/doxygen.cfg.in index 5131166..8e5d449 100644 --- a/doxygen.cfg.in +++ b/doxygen.cfg.in @@ -72,7 +72,7 @@ RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = */.git/* .*.d -EXCLUDE_SYMBOLS = EXPORT_SYMBOL nfct_timeout +EXCLUDE_SYMBOLS = EXPORT_SYMBOL nfct_timeout _container_policy_cb EXAMPLE_PATH = EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO diff --git a/src/libnetfilter_cttimeout.c b/src/libnetfilter_cttimeout.c index b626407..b930089 100644 --- a/src/libnetfilter_cttimeout.c +++ b/src/libnetfilter_cttimeout.c @@ -1,11 +1,12 @@ /* * (C) 2012 by Pablo Neira Ayuso - * (C) 2012 by Vyatta Inc. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published * by the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. + * + * This code has been sponsored by Vyatta Inc. */ #include "internal.h" @@ -137,6 +138,41 @@ struct nfct_timeout { uint16_t polset; }; +/** + * \mainpage + * + * libnetfilter_cttimeout is the userspace library that provides a programming + * interface (API) to the in-kernel cttimeout infrastructure. This + * infrastructure allows you to define fine-grain connection tracking timeout + * policies that can be attached to traffic flows via iptables CT target. + * Before the existence of this infrastructure, you could only set global + * timeout policies per protocol. This library is currently used by the nfct + * utility that is part of the conntrack-tools. + * + * libnetfilter_cttimeout homepage is: + * http://netfilter.org/projects/libnetfilter_cttimeout/ + * + * \section Dependencies + * libnetfilter_cttimeout requires libmnl and a kernel that includes the + * nfnetlink_cttimeout subsystem (i.e. 3.4.0 or later). + * + * \section Main Features + * - listing/retrieving entries from the timeout policy table. + * - inserting/modifying/deleting entries from the timeout policy table. + * + * \section Git Tree + * The current development version of libnetfilter_cttimeout can be accessed at + * https://git.netfilter.org/cgi-bin/gitweb.cgi?p=libnetfilter_cttimeout.git + * + * \section Privileges + * You need the CAP_NET_ADMIN capability in order to allow your application + * to receive events from and to send commands to kernel-space, excepting + * the timeout policy table dumping operation. + * + * \section Authors + * libnetfilter_conntrack has been written by Pablo Neira Ayuso. + */ + /** * \defgroup nfcttimeout Accounting object handling * @{ @@ -165,7 +201,7 @@ EXPORT_SYMBOL(nfct_timeout_alloc); /** * nfct_timeout_free - release one conntrack timeout object - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object */ void nfct_timeout_free(struct nfct_timeout *t) { @@ -177,7 +213,7 @@ EXPORT_SYMBOL(nfct_timeout_free); /** * nfct_timeout_attr_set - set one attribute of the conntrack timeout object - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object * \param type attribute type you want to set * \param data pointer to data that will be used to set this attribute */ @@ -204,7 +240,7 @@ EXPORT_SYMBOL(nfct_timeout_attr_set); /** * nfct_timeout_attr_set_u8 - set one attribute of the conntrack timeout object - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object * \param type attribute type you want to set * \param data pointer to data that will be used to set this attribute */ @@ -217,7 +253,7 @@ EXPORT_SYMBOL(nfct_timeout_attr_set_u8); /** * nfct_timeout_attr_set_u16 - set one attribute of the conntrack timeout object - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object * \param type attribute type you want to set * \param data pointer to data that will be used to set this attribute */ @@ -228,6 +264,11 @@ nfct_timeout_attr_set_u16(struct nfct_timeout *t, uint32_t type, uint16_t data) } EXPORT_SYMBOL(nfct_timeout_attr_set_u16); +/** + * nfct_timeout_attr_unset - unset one attribute of the conntrack timeout object + * \param t pointer to the conntrack timeout object + * \param type attribute type you want to set + */ void nfct_timeout_attr_unset(struct nfct_timeout *t, uint32_t type) { t->attrset &= ~(1 << type); @@ -236,7 +277,7 @@ EXPORT_SYMBOL(nfct_timeout_attr_unset); /** * nfct_timeout_policy_attr_set_u32 - set one attribute of the policy - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object * \param type attribute type you want to set * \param data data that will be used to set this attribute */ @@ -282,7 +323,7 @@ EXPORT_SYMBOL(nfct_timeout_policy_attr_set_u32); /** * nfct_timeout_policy_attr_unset - unset one attribute of the policy - * \param nfct_timeout pointer to the conntrack timeout object + * \param t pointer to the conntrack timeout object * \param type attribute type you want to set */ void nfct_timeout_policy_attr_unset(struct nfct_timeout *t, uint32_t type) @@ -291,6 +332,14 @@ void nfct_timeout_policy_attr_unset(struct nfct_timeout *t, uint32_t type) } EXPORT_SYMBOL(nfct_timeout_policy_attr_unset); +/** + * nfct_timeout_policy_attr_to_name - get state name from protocol state number + * \param l4proto protocol, ie. IPPROTO_* + * \param state state number that you want to get the state name + * + * This function returns NULL if unsupported protocol or state number is passed. + * Otherwise, a pointer to valid string is returned. + */ const char *nfct_timeout_policy_attr_to_name(uint8_t l4proto, uint32_t state) { if (timeout_protocol[l4proto].state_to_name == NULL) { @@ -547,7 +596,7 @@ timeout_parse_attr_data(struct nfct_timeout *t, const struct nlattr *nest) /** * nfct_timeout_nlmsg_parse_payload - set timeout object attributes from message * \param nlh: netlink message that you want to use to add the payload. - * \param nfct_timeout: pointer to a conntrack timeout object + * \param t: pointer to a conntrack timeout object * * This function returns -1 in case that some mandatory attributes are * missing. On sucess, it returns 0. -- cgit v1.2.3