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