add wireless measurement probe infrastructure, developed at Fraunhofer FOKUS

[openwrt/svn-archive/archive.git] / package / wprobe / src / user / wprobe.h

diff --git a/package/wprobe/src/user/wprobe.h b/package/wprobe/src/user/wprobe.h
new file mode 100644 (file)
index 0000000..e0c33fa
--- /dev/null
+++ b/package/wprobe/src/user/wprobe.h
@@ -0,0 +1,143 @@
+/*
+ * wprobe.h: Wireless probe user space library
+ * Copyright (C) 2008-2009 Felix Fietkau <nbd@openwrt.org>
+ *
+ * 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 program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#ifndef __WPROBE_USER_H
+#define __WPROBE_USER_H
+#include <inttypes.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include "list.h"
+
+/**
+ * struct wprobe_value: data structure for attribute values
+ * @STRING: string value (currently unsupported)
+ * @U8: unsigned 8-bit integer value
+ * @U16: unsigned 16-bit integer value
+ * @U32: unsigned 32-bit integer value
+ * @U64: unsigned 64-bit integer value
+ * @S8: signed 8-bit integer value
+ * @S16: signed 16-bit integer value
+ * @S32: signed 32-bit integer value
+ * @S64: signed 64-bit integer value
+ *
+ * @n: number of sample values 
+ * @avg: average value
+ * @stdev: standard deviation
+ * @s: sum of all sample values (internal use)
+ * @ss: sum of all sample values squared (internal use)
+ */
+struct wprobe_value {
+       /* attribute value */
+       union {
+               const char *STRING;
+               uint8_t U8;
+               uint16_t U16;
+               uint32_t U32;
+               uint64_t U64;
+               int8_t S8;
+               int16_t S16;
+               int32_t S32;
+               int64_t S64;
+       };
+       /* statistics */
+       int64_t s, ss;
+       float avg, stdev;
+       unsigned int n;
+};
+
+/**
+ * struct wprobe_attribute: data structures for attribute descriptions
+ * @list: linked list data structure for a list of attributes
+ * @id: attribute id
+ * @type: netlink type for the attribute (see kernel api documentation)
+ * @flags: attribute flags (see kernel api documentation)
+ * @val: cached version of the last netlink query, will be overwritten on each request
+ * @name: attribute name
+ */
+struct wprobe_attribute {
+       struct list_head list;
+       int id;
+       int type;
+       uint32_t flags;
+       struct wprobe_value val;
+       char name[];
+};
+
+/**
+ * struct wprobe_link: data structure for the link description
+ * @list: linked list data structure for a list of links 
+ * @flags: link flags (see kernel api documentation)
+ * @addr: mac address of the remote link partner
+ */
+struct wprobe_link {
+       struct list_head list;
+       uint32_t flags;
+       unsigned char addr[6];
+};
+
+/**
+ * wprobe_init: initialize internal data structures and connect to the wprobe netlink api
+ */
+extern int wprobe_init(void);
+
+/**
+ * wprobe_free: free all internally allocated data structures
+ */
+extern void wprobe_free(void);
+
+/**
+ * wprobe_update_links: get a list of all link partners
+ * @ifname: name of the wprobe interface
+ * @list: linked list for storing link descriptions
+ *
+ * when wprobe_update_links is called multiple times, the linked list 
+ * is updated with new link partners, old entries are automatically expired
+ */
+extern int wprobe_update_links(const char *ifname, struct list_head *list);
+
+/**
+ * wprobe_measure: start a measurement request for all global attributes
+ * @ifname: name of the wprobe interface
+ *
+ * not all attributes are automatically filled with data, since for some
+ * it may be desirable to control the sampling interval from user space
+ * you can use this function to do that.
+ */
+extern void wprobe_measure(const char *ifname);
+
+/**
+ * wprobe_dump_attributes: create a linked list of available attributes
+ * @ifname: name of the wprobe interface
+ * @link: false: get the list of global attributes; true: get the list of per-link attributes
+ * @list: linked list to store the attributes in
+ * @addr: buffer to store the interface's mac address in (optional)
+ *
+ * attributes must be freed by the caller
+ */
+extern int wprobe_dump_attributes(const char *ifname, bool link, struct list_head *list, char *addr);
+
+/**
+ * wprobe_request_data: request new sampling values for the given list of attributes
+ * @ifname: name of the wprobe interface
+ * @attrs: attribute list
+ * @addr: (optional) mac address of the link partner
+ * @scale: scale down values by a factor (scale < 0: reset statistics entirely)
+ *
+ * if addr is unset, attrs must point to the list of global attributes,
+ * if addr is set, attrs must point to the list of per-link attributes
+ */
+extern int wprobe_request_data(const char *ifname, struct list_head *attrs, const unsigned char *addr, int scale);
+
+#endif