README revision e0658725037a65850a11947f881033a2a89e8818 
1Netlink Protocol Library
2
3This library is a clean room re-implementation of libnl 2.0 and
4re-licensed under Apache 2.0. It was developed primarily to support
5wpa_supplicant. However, with additional development can be extended
6to support other netlink applications.
7
8Netlink Protocol Format (RFC3549)
9
10+-----------------+-+-------------------+-+
11|Netlink Message  |P| Generic Netlink   |P|
12|    Header       |A|  Message Header   |A|
13|(struct nlmsghdr)|D|(struct genlmsghdr)|D|
14+-----------------+-+-------------------+-+
15+-----------------+-+-----------------+-+-----------------+-+-----------------+-+---+
16|Netlink Attribute|P|Netlink Attribute|P|Netlink Attribute|P|Netlink Attribute|P|...|
17|    #0 Header    |A|   #0 Payload    |A|   #1 Header     |A|   #1 Payload    |A|   |
18| (struct nlattr) |D|     (void)      |D| (struct nlattr) |D|     (void)      |D|   |
19+-----------------+-+-----------------+-+-----------------+-+-----------------+-+---+
20
21NETLINK OVERVIEW
22
23* Each netlink message consists of a bitstream with a netlink header.
24* After this header a second header *can* be used specific to the netlink
25  family in use. This library was tested using the generic netlink
26  protocol defined by struct genlmsghdr to support nl80211.
27* After the header(s) netlink attributes can be appended to the message
28  which hold can hold basic types such as unsigned integers and strings.
29* Attributes can also be nested. This is accomplished by calling "nla_nest_start"
30  which creates an empty attribute with nest attributes as its payload. Then to
31  close the nest, "nla_nest_end" is called.
32* All data structures in this implementation are byte-aligned (Currently 4 bytes).
33* Acknowledgements (ACKs) are sent as NLMSG_ERROR netlink message types (0x2) and
34  have an error value of 0.
35
36KNOWN ISSUES
37
38  GENERAL
39  * Not tested for thread safety
40
41  Android.mk
42  * No static library because of netlink cache not implemented and
43    not tested for thread safety
44
45  attr.c
46  * nla_parse - does not use nla_policy argument
47
48  cache.c
49  * netlink cache not implemented and only supports one netlink family id
50    which is stored in the nl_cache pointer instead of an actual cache
51
52  netlink.c
53  * nl_recvmsgs - does not support nl_cb_overwrite_recv()
54  * nl_recv - sets/unsets asynchronous socket flag
55
56SOURCE FILES
57
58* Android.mk - Android makefile
59* README - This file
60* attr.c - Netlink attributes
61* cache.c - Netlink cache
62* genl/family.c - Generic netlink family id
63* genl/genl.c - Generic netlink
64* handlers.c - Netlink callbacks
65* msg.c - Netlink messages construction
66* netlink.c - Netlink socket communication
67* object.c - libnl object wrapper
68* socket.c - Netlink kernel socket utils
69
70IMPORTANT HEADER FILES - NOTE: These are based on the the origin GPL libnl headers
71
72* netlink-types.h - Contains many important structs for libnl
73  to represent netlink objects
74* netlink/netlink-kernel.h - Netlink kernel headers and field constants.
75* netlink/msg.h - macros for iterating over netlink messages
76* netlink/attr.h - netlink attribute constants, iteration macros and setters
77
78REFERENCES
79
80* nl80211.h
81* netlink_types.h
82* $LINUX_KERNEL/net/wireless/nl80211.c
83* http://www.infradead.org/~tgr/libnl/doc-3.0/index.html
84* http://www.netfilter.org/projects/libmnl/doxygen/index.html
85