1 # 2 # CDDL HEADER START 3 # 4 # The contents of this file are subject to the terms of the 5 # Common Development and Distribution License (the "License"). 6 # You may not use this file except in compliance with the License. 7 # 8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 # or http://www.opensolaris.org/os/licensing. 10 # See the License for the specific language governing permissions 11 # and limitations under the License. 12 # 13 # When distributing Covered Code, include this CDDL HEADER in each 14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 # If applicable, add the following below this CDDL HEADER, with the 16 # fields enclosed by brackets "[]" replaced with your own identifying 17 # information: Portions Copyright [yyyy] [name of copyright owner] 18 # 19 # CDDL HEADER END 20 # 21 # 22 # Copyright 2010 Sun Microsystems, Inc. All rights reserved. 23 # Use is subject to license terms. 24 # 25 # lib/libnwam/README 26 # 27 28 NAME 29 libnwam - Network Auto-Magic (NWAM) configuration and event 30 management library 31 32 DESCRIPTION 33 34 The libnwam library is provided so that the various consumers of 35 Network Auto-Magic (NWAM) configuration information - i.e. the NWAM 36 GUI, the nwamcfg CLI and the NWAM daemon - have a consistent interface 37 for retrieving and updating NWAM-related configuration data, abstracted 38 from the actual manner in which the data is persistently stored. It 39 provides functionality to interact with the key components of NWAM 40 configuration, as described below. Additionally the library provides 41 functionality for system events to flow from the NWAM daemon to a 42 client (like the GUI panel applet). 43 44 Each of these configuration components is referred to as an 'entity'. 45 46 Network Configuration Units (NCUs): units that specify either link or 47 interface (IP) configuration. An NCP consists of a set of NCUs, one for 48 each datalink (physical, tunnel, aggregation etc), and one for each IP 49 interface. 50 51 Network Configuration Profiles (NCPs): A network configuration profile (NCP) 52 comprises of a set of NCUs specifying configuration preferences to be applied 53 when that profile is active. 54 55 Locations: A location consists of additional configuration preferences 56 to be applied when basic IP configuration is complete. Information 57 such as name service specification, proxies, etc. can be specified. 58 59 External Network Modifiers (ENMs): units that specify an external service 60 or executable that modifies the network configuration. Properties of an 61 ENM include an FMRI or Start and Stop exec strings, an optional environment 62 which will be activated when the ENM is started, an activation type specifying 63 when the ENM should be started (e.g. on user input, dependent on an NCU-- 64 either requiring or excluding a particular NCU, or always-on). Each ENM 65 also has a read-only state property, which indicates whether or not the 66 ENM has been activated by nwam. 67 68 Known WiFi Networks (known WLANs): units that specify configuration 69 data associated with known WiFi access points that the user visits. If 70 a WLAN found by scanning is one of the known WLANs, NWAM will automatically 71 connect. Priorities associated with known WLANs can also be manipulated 72 allowing users to prioritize particular WLANs. 73 74 Events 75 76 The event interface allows a client of NWAM (usu. the GUI) to subscribe 77 to a stream of system events such as link and interface up/down, 78 wireless scans, and times when NWAM needs the user to be queried. 79 80 Events types are in libnwam.h as NWAM_EVENTS_* and the actual bodies of 81 the events are in nwam_events_msg_t. The semantics of the events have 82 been simplified so that none require response. They are all 83 notification. 84 85 NWAM_EVENTS_SOURCE_{DEAD,BACK} provide notification that the nwam 86 daemon has died or has reappeared. These are synthetic events in that 87 they come from the library and not from nwamd. 88 89 NWAM_EVENTS_NO_MAGIC provides notification that nwam couldn't make a 90 determination of what to do without user guidance. This event provides 91 information that can be used to ask the user if he wants to pick a 92 wireless lan although in some cases nwam might have no idea what is 93 intended. 94 95 NWAM_EVENTS_IF_{STATE,REMOVED} provide information about changes in 96 interface state or the removal of an interface. 97 98 NWAM_EVENTS_LINK_{STATE, REMOVED} provides information about changes in 99 link state or the removal of a link. 100 101 NWAM_EVENTS_SCAN_REPORT is used to communicate information about 102 wireless networks encountered. 103 104 Persistent configuration state of entities is stored in project-private 105 /etc/nwam configuration files, and the details of storage are hidden 106 from libnwam consumers. 107 108 Access to entities is attained via an entity-specific handle. These 109 handles can be obtained via calls to nwam_<entity>_create() or 110 nwam_<entity>_read(), and freed (in memory) via calls to nwam_<entity>_free(). 111 nwam_<entity>_create() will create an in-memory representation of the 112 entity, but that entity will not be stored until nwam_<entity>_commit() is 113 called. Persistently stored entitites are retrieved via nwam_<entity>_read(), 114 can be modified in-memory, and later persistently committed to storage 115 via nwam_<entity>_commit(). Entities can also be copied with 116 nwam_<entity>_copy(). 117 118 All changes made after binding a handle to an entity, and prior to calling 119 nwam_<entity>_commit() are carried out on the in-memory representation of that 120 entity. nwam_<entity>_commit() updates persistent storage in an all-or-none 121 transactional manner, applying the (possibly changed) in-memory representation 122 to persistent storage atomically. 123 124 To destroy an entity in persistent storage, nwam_<entity>_destroy() is 125 used. This is distinct from nwam_<entity>_free(), which simply frees 126 the in-memory representation - destroy both removes the object from 127 persistent storage, and frees it in memory. 128 129 To summarize, the pattern of interactions with an entity is 130 - nwam_<entity>_read(), nwam_<entity>_create() or nwam_<entity>_copy() 131 - possibly modify entity properties 132 - nwam_<entity>_commit() or nwam_<entity>_destroy() 133 - nwam_<entity>_handle_free() 134 135 Unless otherwise stated functions in libnwam are MT-safe. The 136 atomicity of _commit() and _read() operations is guaranteed - i.e. 137 _commit() is guaranteed to deliver all property changes to persistent 138 storage, while _read() is guaranteed to read a consistent view of the 139 entity (i.e. _read() cannot collide with another entity _commit()ting 140 changes). However, it is possible that a _read() will retrieve an 141 outdated view of an entity, if after the _read() completes, another 142 entity _commit()s changes. In other words, lost updates are possible. 143 These are permitted given the nature of the entities changing NWAM 144 configuration (the CLI and GUI) - it seems intuitive that the most 145 recent update best captures user intent. 146 147 Entity validation on an in-memory representation can be explicitly requested 148 via a call to nwam_<entity>_validate(), and individual property values 149 can be validated via nwam_<entity>_validate_prop(). 150 151 Storage and retrieval of properties is done via nwam_<entity>_set_prop_value() 152 and nwam_<entity>_get_prop_value(). These functions require an nwam_value_t as 153 a parameter, which is created via the nwam_value_create_<type>() family 154 of functions. Data can be retrieved from the nwam_value_t via the 155 nwam_value_get_<type>() family of functions. Once a property has been 156 set, the associated nwam_value_t can be immediately freed. For retrieval, 157 the nwam_value_t should be freed when the value(s) are no longer needed. 158 A property can also be delete with nwam_<entity>_delete_prop(). 159 160 Implicit validation occurs as part of the nwam_<entity>_set_prop_value() 161 and nwam_<entity>_commit() functions. 162 163 INTERFACES 164 165 For error handling: 166 167 const char *nwam_strerror(nwam_error_t error); 168 169 For values: 170 171 Values can be any of the following types: 172 173 NWAM_VALUE_TYPE_BOOLEAN 174 NWAM_VALUE_TYPE_UINT64 175 NWAM_VALUE_TYPE_INT64 176 NWAM_VALUE_TYPE_STRING 177 178 and are possibly multi-valued. An nwam_value_t must be created in order 179 to set property values in libnwam, this is done via the follwing functions: 180 181 nwam_error_t nwam_value_create_boolean(boolean_t, nwam_value_t *); 182 nwam_error_t nwam_value_create_boolean_array(boolean_t *, uint_t, 183 nwam_value_t *); 184 nwam_error_t nwam_value_create_uint64(uint64_t, nwam_value_t *); 185 nwam_error_t nwam_value_create_uint64_array(uint64_t *, uint_t, nwam_value_t *); 186 nwam_error_t nwam_value_create_int64(int64_t, nwam_value_t *); 187 nwam_error_t nwam_value_create_int64_array(int64_t *, uint_t, nwam_value_t *); 188 nwam_error_t nwam_value_create_string(char *, nwam_value_t *); 189 nwam_error_t nwam_value_create_string_array(char **, uint_t, nwam_value_t *); 190 191 Values are returned from the _get_prop_value() functions, and the data 192 contained in them can be retrieved via the following functions: 193 194 nwam_error_t nwam_value_get_boolean(nwam_value_t, boolean_t *); 195 nwam_error_t nwam_value_get_boolean_array(nwam_value_t, boolean_t **, uint_t *); 196 nwam_error_t nwam_value_get_uint64(nwam_value_t, uint64_t *); 197 nwam_error_t nwam_value_get_uint64_array(nwam_value_t, uint64_t **, uint_t *); 198 nwam_error_t nwam_value_get_int64(nwam_value_t, int64_t *); 199 nwam_error_t nwam_value_get_int64_array(nwam_value_t, int64_t **, uint_t *); 200 nwam_error_t nwam_value_get_string(nwam_value_t, char **); 201 nwam_error_t nwam_value_get_string_array(nwam_value_t, char ***, uint_t *); 202 203 Type and number of value can be retrieved via: 204 205 nwam_error_t nwam_value_get_type(nwam_value_t, nwam_value_type_t *); 206 nwam_error_t nwam_value_get_numvalues(nwam_value_t, uint_t *); 207 208 and a value is freed using: 209 210 void nwam_value_free(nwam_value_t); 211 212 For property setting, a typical set of events is to create the value, 213 call the appropriate set_prop_value() function, then free the value (values 214 can be safely freed prior to commit). For retrieval, the type and 215 number of values usually need to be tested before calling the appropriate 216 retrieval function. In this case, the value should not be freed until 217 the associated data is no longer needed. 218 219 NCUs, locations and ENMs can all specify conditional activation conditions. 220 Interfaces are provided to convert a conditional activation predicate into 221 a string, or from a string to a parsed set of variables that comprise the 222 condition. Additionally a function is provided to rate the specificity of 223 the activation condition, used to compare location conditions to choose 224 the most specific condition to activate in the case where the activation 225 conditions of multiple locations are specified. 226 227 nwam_error_t nwam_condition_to_condition_string(nwam_condition_object_type_t, 228 nwam_condition_t, const char *, char **); 229 nwam_error_t nwam_condition_string_to_condition(const char *, 230 nwam_condition_object_type_t *, nwam_condition_t *, char **); 231 nwam_error_t nwam_condition_rate(nwam_condition_object_type_t, 232 nwam_condition_t, uint64_t *); 233 234 For NCP entities: 235 236 nwam_error_t nwam_ncp_create(const char *name, uint64_t flags, 237 nwam_ncp_handle_t *ncp); 238 nwam_error_t nwam_ncp_read(const char *name, uint64_t flags, 239 nwam_ncp_handle_t *ncp); 240 nwam_error_t nwam_ncp_copy(nwam_ncp_handle_t ncp, const char *newname, 241 nwam_ncp_handle_t *newncp); 242 nwam_error_t nwam_ncp_walk_ncus(nwam_ncp_handle_t ncp, 243 int(*cb)(nwam_ncu_handle_t, void *), void *data, uint64_t flags, int *ret); 244 nwam_error_t nwam_ncp_get_name(nwam_ncp_handle_t ncp, char **name); 245 nwam_error_t nwam_ncp_activate(nwam_ncp_handle_t ncp); 246 nwam_error_t nwam_ncp_deactivate(nwam_ncp_handle_t ncp); 247 nwam_error_t nwam_ncp_destroy(nwam_ncp_handle_t ncp, uint64_t flags); 248 void nwam_ncp_free(nwam_ncp_handle_t ncp); 249 250 Since the NCP simply consists of the NCUs that comprise it, there is 251 no NCP-specific commit() function - we simply read the NCP, walk the 252 constituent NCUs, reading, changing or committing them in turn. The 253 walk can be modified via the flags option to only select specific NCU types 254 and classes. 255 256 Each NCP has a set of NCUs associated with it, each of which is created/modifed 257 using the functions below. 258 259 For NCU entities: 260 261 nwam_error_t nwam_ncu_create(nwam_ncp_handle_t ncp, const char *name, 262 nwam_ncu_type_t type, nwam_ncu_class_t class, nwam_ncu_handle_t *ncu); 263 nwam_error_t nwam_ncu_read(nwam_ncp_handle_t ncp, const char *name, 264 nwam_ncu_type_t type, uint64_t flags, nwam_ncu_handle_t *ncu); 265 nwam_error_t nwam_ncu_copy(nwam_ncu_handle_t ncu, const char *newname, 266 nwam_ncu_handle_t *newncu); 267 nwam_error_t nwam_ncu_commit(nwam_ncu_handle_t ncu, uint64_t flags); 268 nwam_error_t nwam_ncu_destroy(nwam_ncu_handle_t ncu, uint64_t flags); 269 nwam_error_t nwam_ncu_free(nwam_ncu_handle_t ncu); 270 nwam_error_t nwam_ncu_validate(nwam_ncu_handle_t ncu, const char **errprop); 271 nwam_error_t nwam_ncu_get_prop_value(nwam_ncu_handle_t ncu, const char *prop, 272 nwam_value_t *value); 273 nwam_error_t nwam_ncu_get_prop_description(const char *prop, 274 const char **description); 275 nwam_error_t nwam_ncu_delete_prop(nwam_ncu_handle_t ncu, const char *prop); 276 nwam_error_t nwam_ncu_set_prop_value(nwam_ncu_handle_t ncu, const char *prop, 277 nwam_value_t value); 278 nwam_error_t nwam_ncu_get_name(nwam_ncu_handle_t ncu, char **name); 279 nwam_error_t nwam_ncu_set_name(nwam_ncu_handle_t ncu, const char *name); 280 nwam_error_t nwam_ncu_get_read_only(nwam_ncu_handle_t ncu, boolean_t *readp); 281 nwam_error_t nwam_ncu_validate_prop(nwam_ncu_handle_t ncu, const char *prop, 282 nwam_value_t value); 283 nwam_error_t nwam_ncu_walk_props(nwam_ncu_handle_t ncu, 284 int (*func)(void *, const char *, nwam_value_t), void *data, 285 uint64_t flags, int *ret); 286 nwam_error_t nwam_ncu_prop_get_type(const char *prop, 287 nwam_value_type_t *value_type); 288 nwam_error_t nwam_ncu_get_ncp(nwam_ncu_handle_t ncu, nwam_ncp_handle_t *ncp); 289 290 NCUs are manipulated via an nwam_ncu_handle_t. 291 292 Each NCU has a set of properties associated with it. Each property can 293 have mutiple values associated with it, which are set or retrieved via an 294 nwam_value_t. The approach is similar to that used for Locations, with 295 the difference that read/commit/destroy must specify an NCP. Only two 296 NCPs are supported at present, the automatic and user NCPs. Modification 297 of the former is restricted to nwamd itself, and attempts to modify 298 the automatic NCP's consituent NCUs will result in an NWAM_ENTITY_READ_ONLY 299 error. 300 301 For Location entities: 302 303 nwam_error_t nwam_loc_create(const char *name, nwam_loc_handle_t *loc); 304 nwam_error_t nwam_loc_read(const char *name, uint64_t flags, 305 nwam_loc_handle_t *loc); 306 nwam_error_t nwam_loc_copy(nwam_loc_handle_t loc, const char *newname, 307 nwam_loc_handle_t *newloc); 308 nwam_error_t nwam_walk_locs(int (*cb)(nwam_loc_handle_t loc, void *arg), 309 void *arg, uint64_t flags, int *cbretp); 310 nwam_error_t nwam_loc_commit(nwam_loc_handle_t loc, uint64_t flags); 311 nwam_error_t nwam_loc_destroy(nwam_loc_handle_t loc, uint64_t flags); 312 void nwam_loc_free(nwam_loc_handle_t loc); 313 nwam_error_t nwam_loc_validate(nwam_loc_handle_t loc, const char *errprop); 314 nwam_error_t nwam_loc_walk_props(nwam_loc_handle_t loc, 315 int (*cb)(const char *, nwam_value_t **, void *), 316 void *arg, uint64_t flags, int *cbret); 317 nwam_error_t nwam_loc_validate_prop(nwam_loc_handle_t loc, 318 const char *prop, nwam_value_t value); 319 nwam_error_t nwam_loc_prop_get_type(const char *prop, 320 nwam_value_type_t *value_type); 321 nwam_error_t nwam_loc_get_prop_value(nwam_loc_handle_t loc, const char *prop, 322 nwam_value_t *value); 323 nwam_error_t nwam_loc_get_prop_description(const char *prop, 324 const char **description); 325 nwam_error_t nwam_loc_delete_prop(nwam_loc_handle_t loc, const char *prop); 326 nwam_error_t nwam_loc_set_prop_value(nwam_loc_handle_t loc, const char *prop, 327 nwam_value_t value); 328 nwam_error_t nwam_loc_get_name(nwam_loc_handle_t loc, char **name); 329 nwam_error_t nwam_loc_set_name(nwam_loc_handle_t loc, const char *name); 330 nwam_error_t nwam_loc_activate(nwam_loc_handle_t loc); 331 nwam_error_t nwam_loc_deactivate(nwam_loc_handle_t loc); 332 333 Locations are manipulated via an nwam_loc_handle_t. 334 335 A loc handle maps to an in-memory representation of a location; operations via 336 this interface manipulate the in-memory data. In-memory data is read from 337 persistant storage via the nwam_loc_read() or nwam_walk_locs() functions, and 338 written out to persistent storage via the nwam_loc_commit() function. A loc 339 may be permanently removed from persistent storage with the nwam_loc_destroy() 340 function. Interactions with persistent storage will be nonblocking by default; 341 this behavior can be changed by passing the NWAM_FLAG_BLOCKING in the flags 342 parameter. 343 344 A typical sequence would be to allocate a loc handle, either by creating a 345 new loc (nwam_loc_create()) or by reading one from persistent storage (nwam_ 346 loc_read() or nwam_walk_locs()). The various set/get/walk/validate/(de)activate 347 functions may then be used to manipulate the loc; any changes made may then be 348 committed to persistent storage via nwam_loc_commit(). A call to nwam_loc_ 349 free() is required to release in-memory resources associated with the handle. 350 351 The flags parameter in the walk functions allows filtering of the locs that 352 will be examined, depending on the state of each loc. Passing in 353 NWAM_FLAG_STATE_ALL will examine all locs; specific state flags are defined 354 in <libnwam.h>. 355 356 Like NCUs, each loc has a set of properties associated with it. Loc properties 357 are stored in nwam_value_t structures; see the Values section for how to store/ 358 retrieve using these. 359 360 For ENM entities: 361 362 nwam_error_t nwam_enm_create(const char *name, const char *fmri, 363 nwam_enm_handle_t *enm); 364 nwam_error_t nwam_enm_read(const char *name, uint64_t flags, 365 nwam_enm_handle_t *enm); 366 nwam_error_t nwam_enm_copy(nwam_enm_handle_t enm, const char *newname, 367 nwam_enm_handle_t *newenm); 368 nwam_error_t nwam_walk_enms(int (*cb)(nwam_enm_handle_t enm, void *arg), 369 void *arg, uint64_t flags, int *cbretp); 370 nwam_error_t nwam_enm_commit(nwam_enm_handle_t enm, uint64_t flags); 371 nwam_error_t nwam_enm_destroy(nwam_enm_handle_t enm, uint64_t flags); 372 void nwam_enm_free(nwam_enm_handle_t enm); 373 nwam_error_t nwam_enm_validate(nwam_enm_handle_t enm, const char *errprop); 374 nwam_error_t nwam_enm_walk_props(nwam_enm_handle_t enm, 375 int (*cb)(const char *, nwam_value_t **, void *), 376 void *arg, uint64_t flags, int *cbret); 377 nwam_error_t nwam_enm_validate_prop(nwam_enm_handle_t enm, 378 const char *prop, nwam_value_t value); 379 nwam_error_t nwam_enm_prop_get_type(const char *prop, 380 nwam_value_type_t *value_type); 381 nwam_error_t nwam_enm_get_prop_value(nwam_enm_handle_t enm, const char *prop, 382 nwam_value_t *value); 383 nwam_error_t nwam_enm_get_prop_description(const char *prop, 384 const char **description); 385 nwam_error_t nwam_enm_delete_prop(nwam_enm_handle_t enm, const char *prop); 386 nwam_error_t nwam_enm_set_prop_value(nwam_enm_handle_t enm, const char *prop, 387 nwam_value_t value); 388 nwam_error_t nwam_enm_get_name(nwam_enm_handle_t enm, char **name); 389 nwam_error_t nwam_enm_set_name(nwam_enm_handle_t enm, const char *name); 390 nwam_error_t nwam_enm_activate(nwam_enm_handle_t enm); 391 nwam_error_t nwam_enm_deactivate(nwam_enm_handle_t enm); 392 393 ENMs are manipulated via an nwam_enm_handle_t, in a similar manner to 394 NCUs and locations. 395 396 The flags parameter in the walk functions allows filtering of the ENMs that 397 will be examined, depending on the state of each ENM. Passing in 398 NWAM_FLAG_STATE_ALL will examine all ENMs; specific state flags are defined 399 in <libnwam.h>. 400 401 Like NCUs, each ENM has a set of properties associated with it. ENM properties 402 are all single valued, though the interface is aligned with the NCU interface, 403 which allows for multi-valued properties. ENM properties are stored in 404 nwam_value_t structures; see the Values section for how to store/retrieve 405 using these. 406 407 For known WLAN entities: 408 409 nwam_error_t nwam_known_wlan_create(const char *name, 410 nwam_known_wlan_handle_t *kwhp); 411 nwam_error_t nwam_known_wlan_read(const char *name, uint64_t flags, 412 nwam_known_wlan_handle_t *kwhp); 413 nwam_error_t nwam_known_wlan_copy(nwam_known_wlan_handle_t kwh, 414 const char *newname, nwam_known_wlan_handle_t *newkwh); 415 nwam_error_t nwam_walk_known_wlans(int (*cb)(nwam_known_wlan_handle_t, void *), 416 void *arg, uint64_t flags, int *cbretp); 417 nwam_error_t nwam_known_wlan_commit(nwam_known_wlan_handle_t kwh, 418 uint64_t flags); 419 nwam_error_t nwam_known_wlan_destroy(nwam_known_wlan_handle_t kwh, 420 uint64_t flags); 421 void nwam_known_wlan_free(nwam_known_wlan_handle_t kwh); 422 nwam_error_t nwam_known_wlan_validate(nwam_known_wlan_handle_t kwh, 423 const char *errprop); 424 nwam_error_t nwam_known_wlan_walk_props(nwam_known_wlan_handle_t kwh, 425 int (*cb)(const char *, nwam_value_t **, void *), 426 void *arg, uint64_t flags, int *cbret); 427 nwam_error_t nwam_known_wlan_validate_prop(nwam_known_wlan_handle_t kwh, 428 const char *prop, nwam_value_t value); 429 nwam_error_t nwam_known_wlan_prop_get_type(const char *prop, 430 nwam_value_type_t *value_type); 431 nwam_error_t nwam_known_wlan_get_prop_value(nwam_known_wlan_handle_t kwh, 432 const char *prop, nwam_value_t *value); 433 nwam_error_t nwam_known_wlan_get_prop_description(const char *prop, 434 const char **description); 435 nwam_error_t nwam_known_wlan_delete_prop(nwam_known_wlan_handle_t kwh, 436 const char *prop); 437 nwam_error_t nwam_known_wlan_set_prop_value(nwam_known_wlan_handle_t kwh, 438 const char *prop, nwam_value_t value); 439 nwam_error_t nwam_known_wlan_get_name(nwam_known_wlan_handle_t kwh, 440 char **name); 441 nwam_error_t nwam_known_wlan_set_name(nwam_known_wlan_handle_t kwh, 442 const char *name); 443 nwam_error_t nwam_known_wlan_add_to_known_wlan(const char *essid, 444 const char *bssid); 445 nwam_error_t nwam_known_wlan_remove_from_known_wlan(const char *essid, 446 const char *bssid); 447 448 Known WLANs are manipulated via an nwam_known_wlan_handle_t, in a similar 449 manner to NCUs, locations and ENMs. 450 451 Like ENMs, each known WLAN has a set of properties associated with it. 452 Known WLAN properties are stored in nwam_value_t structures; see the Values 453 section for how to store/retrieve using these. 454 455 For WLANs, we define a set of functions to ask nwamd to initiate a scan, 456 select a WLAN (and possibly add it to the known WLAN list) or set a WLAN 457 key: 458 459 460 extern nwam_error_t nwam_wlan_scan(const char *linkname); 461 extern nwam_error_t nwam_wlan_get_scan_results(const char *linkname, 462 uint_t *num_resultsp, nwam_wlan_t **wlansp); 463 extern nwam_error_t nwam_wlan_select(const char *linkname, 464 const char *essid, const char *bssid, boolean_t add_to_known_wlans); 465 extern nwam_error_t nwam_wlan_set_key(const char *linkname, const char *essid, 466 const char *bssid, uint32_t security_mode, uint_t keyslot, const char *key); 467 468 For Events: 469 470 typedef struct nwam_event { 471 uint32_t type; 472 473 union { 474 struct { 475 nwam_object_type_t object_type; 476 char name[NWAM_MAX_NAME_LEN]; 477 nwam_action_t action; 478 } object_action; 479 480 481 ... and so on for each message ... 482 483 } data; 484 485 } *nwam_event_t; 486 487 type comes from the set of constants NWAM_EVENT_TYPE_*. 488 489 Registration and cancellation of registration are done via 490 _init and _fini functions: 491 492 extern nwam_error_t nwam_events_init(void); 493 extern void nwam_events_fini(void); 494 495 Events can then be recieved by calling nwam_event_wait(): 496 497 extern nwam_error_t nwam_event_wait(nwam_event_t *); 498 499 The event can then be processed, and free via nwam_event_free(); 500 501 RETURN VALUES 502 503 All functions return an nwam_error_t if they return an error. Possible 504 errors are: 505 506 NWAM_SUCCESS No error occured 507 NWAM_LIST_END End of list 508 NWAM_INVALID_HANDLE Entity handle is invalid 509 NWAM_HANDLE_UNBOUND Handle not bound to entity 510 NWAM_INVALID_ARG Argument is invalid 511 NWAM_PERMISSION_DENIED Insufficient privileges for action 512 NWAM_NO_MEMORY Out of memory 513 NWAM_ENTITY_EXISTS Entity already exists 514 NWAM_ENTITY_IN_USE Another user is interacting with entity 515 NWAM_ENTITY_COMMITTED Entity already committed 516 NWAM_ENTITY_NOT_FOUND Entity not found 517 NWAM_ENTITY_TYPE_MISMATCH Entity value-type mismatch 518 NWAM_ENTITY_INVALID Validation of entity failed 519 NWAM_ENTITY_INVALID_MEMBER Entity member invalid 520 NWAM_ENTITY_INVALID_VALUE Validation of entity value failed 521 NWAM_ENTITY_NO_VALUE No value associated with entity 522 NWAM_ENTITY_MULTIPLE_VALUES, Multiple values for entity 523 NWAM_ENTITY_READ_ONLY, Entity is marked read only 524 NWAM_WALK_HALTED, Callback function returned nonzero 525 NWAM_ERROR_BIND, Could not bind to backend 526 NWAM_ERROR_BACKEND_INIT, Could not initialize backend 527 NWAM_ERROR_INTERNAL Internal error 528 529 FILES 530 /lib/libnwam.so.1 shared object 531 532 ATTRIBUTES 533 534 535 SEE ALSO 536 nwamd(1M), nwamcfg(1M), nwamadm(1M) 537