1.\" $NetBSD: ieee80211_node.9,v 1.8 2018/02/08 09:03:23 dholland Exp $ 2.\" 3.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 4.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 29.\" 30.Dd September 12, 2006 31.Dt IEEE80211_NODE 9 32.Os 33.Sh NAME 34.Nm ieee80211_node_attach , 35.Nm ieee80211_node_lateattach , 36.Nm ieee80211_node_detach , 37.Nm ieee80211_begin_scan , 38.Nm ieee80211_next_scan , 39.Nm ieee80211_end_scan , 40.Nm ieee80211_create_ibss , 41.Nm ieee80211_alloc_node , 42.Nm ieee80211_dup_bss , 43.Nm ieee80211_find_node , 44.Nm ieee80211_free_node , 45.Nm ieee80211_free_allnodes , 46.Nm ieee80211_iterate_nodes 47.Nd software 802.11 stack node management functions 48.Sh SYNOPSIS 49.In net80211/ieee80211_var.h 50.In net80211/ieee80211_proto.h 51.In net80211/ieee80211_node.h 52.Ft void 53.Fn ieee80211_node_attach "struct ieee80211com *ic" 54.Ft void 55.Fn ieee80211_node_lateattach "struct ieee80211com *ic" 56.Ft void 57.Fn ieee80211_node_detach "struct ieee80211com *ic" 58.Ft void 59.Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset" 60.Ft void 61.Fn ieee80211_next_scan "struct ieee80211com *ic" 62.Ft void 63.Fn ieee80211_end_scan "struct ieee80211com *ic" 64.Ft void 65.Fo ieee80211_create_ibss 66.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" 67.Fc 68.Ft struct ieee80211_node * 69.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr" 70.Ft struct ieee80211_node * 71.Fo ieee80211_dup_bss 72.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr" 73.Fc 74.Ft struct ieee80211_node * 75.Fo ieee80211_find_node 76.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr" 77.Fc 78.Ft void 79.Fn ieee80211_free_node "struct ieee80211_node *ni" 80.Ft void 81.Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt" 82.Ft void 83.Fo ieee80211_iterate_nodes 84.Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg" 85.Fc 86.Sh DESCRIPTION 87These functions are used to manage node lists within the software 88802.11 stack. 89These lists are typically used for implementing host-mode AP functionality, 90or providing signal quality information about neighbouring nodes. 91.Pp 92.\" 93The 94.Fn ieee80211_node_attach 95function is called from 96.Xr ieee80211_ifattach 9 97to initialize node database management callbacks for the interface 98.Fa ic 99(specifically for memory allocation, node copying and node 100signal inspection). 101These functions may be overridden in special circumstances, 102as long as this is done after calling 103.Xr ieee80211_ifattach 9 104and prior to any other call which may allocate a node. 105.Pp 106.\" 107The 108.Fn ieee80211_node_lateattach 109function initialises the 110.Va ic_bss 111node element of the interface 112.Fa ic 113during 114.Xr ieee80211_media_init 9 . 115This late attachment is to account for certain special cases described under 116.Fn ieee80211_node_attach . 117.Pp 118.\" 119The 120.Fn ieee80211_node_detach 121function destroys all node database state associated with the interface 122.Fa ic , 123and is usually called during device detach. 124.Pp 125.\" 126The 127.Fn ieee80211_begin_scan 128function initialises the node database in preparation of a 129scan for an access point on the interface 130.Fa ic 131and begins the scan. 132The parameter 133.Fa reset 134controls if a previously built node list should be cleared. 135The actual scanning for an access point is not fully automated: 136the device driver itself controls stepping through the channels, usually 137by a periodical callback. 138.Pp 139.\" 140The 141.Fn ieee80211_next_scan 142function is used to inform the 143.Xr ieee80211 9 144layer that the next channel for interface 145.Fa ic 146should be scanned. 147.Pp 148.\" 149The 150.Fn ieee80211_create_ibss 151function sets up the net80211-specific portion of an interface's softc, 152.Fa ic , 153for use in IBSS mode. 154.Pp 155.\" 156The 157.Fn ieee80211_end_scan 158function is called by 159.Fn ieee80211_next_scan 160when the state machine has performed a full cycle of scanning on 161all available radio channels. 162Internally, 163.Fn ieee80211_end_scan 164will inspect the node cache associated with the interface 165.Fa ic 166for suitable access points found during scanning, and associate with one, 167should the parameters of the node match those of the configuration 168requested. 169.Pp 170.\" 171The 172.Fn ieee80211_alloc_node 173function allocates an instance of 174.Vt "struct ieee80211_node" 175for a node having the MAC address 176.Fa macaddr , 177and associates it with the node table 178.Fa nt . 179If the allocation is successful, the node structure is initialised by 180.Fn ieee80211_setup_node ; 181otherwise, 182.Dv NULL 183is returned. 184.Pp 185.\" 186The 187.Fn ieee80211_dup_bss 188function is similar to 189.Fn ieee80211_alloc_node , 190but is instead used to create a node database entry for the BSSID 191.Fa macaddr 192associated with the note table 193.Fa nt . 194If the allocation is successful, the node structure is initialised by 195.Fn ieee80211_setup_node ; 196otherwise, 197.Dv NULL 198is returned. 199.Pp 200.\" 201The 202.Fn ieee80211_find_node 203function will iterate through the node table 204.Fa nt , 205searching for a node entry which matches 206.Fa macaddr . 207If the entry is found, its reference count is incremented, and 208a pointer to the node is returned; otherwise, 209.Dv NULL 210is returned. 211.Pp 212.\" 213The 214.Fn ieee80211_free_allnodes 215function will iterate through the node list calling 216.Fn ieee80211_free_node 217for all the nodes in table 218.Fa nt . 219.Pp 220.\" 221The 222.Fn ieee80211_iterate_nodes 223function will call the user-defined callback function 224.Fa f 225for all nodes in the table 226.Fa nt . 227The callback is invoked with the with the user-supplied value 228.Fa arg 229and a pointer to the current node. 230.\" 231.Sh SEE ALSO 232.Xr ieee80211 9 233.Sh HISTORY 234The 235.Nm ieee80211 236series of functions first appeared in 237.Nx 1.5 , 238and were later ported to 239.Fx 4.6 . 240.Sh AUTHORS 241.An -nosplit 242This man page was written by 243.An Bruce M. Simpson Aq Mt bms@FreeBSD.org 244and 245.An Darron Broad Aq Mt darron@kewl.org . 246