16ba597c5SAnurag S. Maskey# 26ba597c5SAnurag S. Maskey# CDDL HEADER START 36ba597c5SAnurag S. Maskey# 46ba597c5SAnurag S. Maskey# The contents of this file are subject to the terms of the 56ba597c5SAnurag S. Maskey# Common Development and Distribution License (the "License"). 66ba597c5SAnurag S. Maskey# You may not use this file except in compliance with the License. 76ba597c5SAnurag S. Maskey# 86ba597c5SAnurag S. Maskey# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 96ba597c5SAnurag S. Maskey# or http://www.opensolaris.org/os/licensing. 106ba597c5SAnurag S. Maskey# See the License for the specific language governing permissions 116ba597c5SAnurag S. Maskey# and limitations under the License. 126ba597c5SAnurag S. Maskey# 136ba597c5SAnurag S. Maskey# When distributing Covered Code, include this CDDL HEADER in each 146ba597c5SAnurag S. Maskey# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 156ba597c5SAnurag S. Maskey# If applicable, add the following below this CDDL HEADER, with the 166ba597c5SAnurag S. Maskey# fields enclosed by brackets "[]" replaced with your own identifying 176ba597c5SAnurag S. Maskey# information: Portions Copyright [yyyy] [name of copyright owner] 186ba597c5SAnurag S. Maskey# 196ba597c5SAnurag S. Maskey# CDDL HEADER END 206ba597c5SAnurag S. Maskey# 216ba597c5SAnurag S. Maskey# 226ba597c5SAnurag S. Maskey# Copyright 2010 Sun Microsystems, Inc. All rights reserved. 236ba597c5SAnurag S. Maskey# Use is subject to license terms. 246ba597c5SAnurag S. Maskey# 256ba597c5SAnurag S. Maskey# lib/libnwam/README 266ba597c5SAnurag S. Maskey# 276ba597c5SAnurag S. Maskey 286ba597c5SAnurag S. MaskeyNAME 296ba597c5SAnurag S. Maskey libnwam - Network Auto-Magic (NWAM) configuration and event 306ba597c5SAnurag S. Maskey management library 316ba597c5SAnurag S. Maskey 326ba597c5SAnurag S. MaskeyDESCRIPTION 336ba597c5SAnurag S. Maskey 346ba597c5SAnurag S. MaskeyThe libnwam library is provided so that the various consumers of 356ba597c5SAnurag S. MaskeyNetwork Auto-Magic (NWAM) configuration information - i.e. the NWAM 366ba597c5SAnurag S. MaskeyGUI, the nwamcfg CLI and the NWAM daemon - have a consistent interface 376ba597c5SAnurag S. Maskeyfor retrieving and updating NWAM-related configuration data, abstracted 386ba597c5SAnurag S. Maskeyfrom the actual manner in which the data is persistently stored. It 396ba597c5SAnurag S. Maskeyprovides functionality to interact with the key components of NWAM 406ba597c5SAnurag S. Maskeyconfiguration, as described below. Additionally the library provides 416ba597c5SAnurag S. Maskeyfunctionality for system events to flow from the NWAM daemon to a 426ba597c5SAnurag S. Maskeyclient (like the GUI panel applet). 436ba597c5SAnurag S. Maskey 446ba597c5SAnurag S. MaskeyEach of these configuration components is referred to as an 'entity'. 456ba597c5SAnurag S. Maskey 466ba597c5SAnurag S. MaskeyNetwork Configuration Units (NCUs): units that specify either link or 476ba597c5SAnurag S. Maskeyinterface (IP) configuration. An NCP consists of a set of NCUs, one for 486ba597c5SAnurag S. Maskeyeach datalink (physical, tunnel, aggregation etc), and one for each IP 496ba597c5SAnurag S. Maskeyinterface. 506ba597c5SAnurag S. Maskey 516ba597c5SAnurag S. MaskeyNetwork Configuration Profiles (NCPs): A network configuration profile (NCP) 526ba597c5SAnurag S. Maskeycomprises of a set of NCUs specifying configuration preferences to be applied 536ba597c5SAnurag S. Maskeywhen that profile is active. 546ba597c5SAnurag S. Maskey 556ba597c5SAnurag S. MaskeyLocations: A location consists of additional configuration preferences 566ba597c5SAnurag S. Maskeyto be applied when basic IP configuration is complete. Information 576ba597c5SAnurag S. Maskeysuch as name service specification, proxies, etc. can be specified. 586ba597c5SAnurag S. Maskey 596ba597c5SAnurag S. MaskeyExternal Network Modifiers (ENMs): units that specify an external service 606ba597c5SAnurag S. Maskeyor executable that modifies the network configuration. Properties of an 616ba597c5SAnurag S. MaskeyENM include an FMRI or Start and Stop exec strings, an optional environment 626ba597c5SAnurag S. Maskeywhich will be activated when the ENM is started, an activation type specifying 636ba597c5SAnurag S. Maskeywhen the ENM should be started (e.g. on user input, dependent on an NCU-- 646ba597c5SAnurag S. Maskeyeither requiring or excluding a particular NCU, or always-on). Each ENM 656ba597c5SAnurag S. Maskeyalso has a read-only state property, which indicates whether or not the 666ba597c5SAnurag S. MaskeyENM has been activated by nwam. 676ba597c5SAnurag S. Maskey 686ba597c5SAnurag S. MaskeyKnown WiFi Networks (known WLANs): units that specify configuration 696ba597c5SAnurag S. Maskeydata associated with known WiFi access points that the user visits. If 706ba597c5SAnurag S. Maskeya WLAN found by scanning is one of the known WLANs, NWAM will automatically 716ba597c5SAnurag S. Maskeyconnect. Priorities associated with known WLANs can also be manipulated 726ba597c5SAnurag S. Maskeyallowing users to prioritize particular WLANs. 736ba597c5SAnurag S. Maskey 746ba597c5SAnurag S. MaskeyEvents 756ba597c5SAnurag S. Maskey 766ba597c5SAnurag S. MaskeyThe event interface allows a client of NWAM (usu. the GUI) to subscribe 776ba597c5SAnurag S. Maskeyto a stream of system events such as link and interface up/down, 786ba597c5SAnurag S. Maskeywireless scans, and times when NWAM needs the user to be queried. 796ba597c5SAnurag S. Maskey 806ba597c5SAnurag S. MaskeyEvents types are in libnwam.h as NWAM_EVENTS_* and the actual bodies of 816ba597c5SAnurag S. Maskeythe events are in nwam_events_msg_t. The semantics of the events have 826ba597c5SAnurag S. Maskeybeen simplified so that none require response. They are all 836ba597c5SAnurag S. Maskeynotification. 846ba597c5SAnurag S. Maskey 856ba597c5SAnurag S. MaskeyNWAM_EVENTS_SOURCE_{DEAD,BACK} provide notification that the nwam 866ba597c5SAnurag S. Maskeydaemon has died or has reappeared. These are synthetic events in that 876ba597c5SAnurag S. Maskeythey come from the library and not from nwamd. 886ba597c5SAnurag S. Maskey 896ba597c5SAnurag S. MaskeyNWAM_EVENTS_NO_MAGIC provides notification that nwam couldn't make a 906ba597c5SAnurag S. Maskeydetermination of what to do without user guidance. This event provides 916ba597c5SAnurag S. Maskeyinformation that can be used to ask the user if he wants to pick a 926ba597c5SAnurag S. Maskeywireless lan although in some cases nwam might have no idea what is 936ba597c5SAnurag S. Maskeyintended. 946ba597c5SAnurag S. Maskey 956ba597c5SAnurag S. MaskeyNWAM_EVENTS_IF_{STATE,REMOVED} provide information about changes in 966ba597c5SAnurag S. Maskeyinterface state or the removal of an interface. 976ba597c5SAnurag S. Maskey 986ba597c5SAnurag S. MaskeyNWAM_EVENTS_LINK_{STATE, REMOVED} provides information about changes in 996ba597c5SAnurag S. Maskeylink state or the removal of a link. 1006ba597c5SAnurag S. Maskey 1016ba597c5SAnurag S. MaskeyNWAM_EVENTS_SCAN_REPORT is used to communicate information about 1026ba597c5SAnurag S. Maskeywireless networks encountered. 1036ba597c5SAnurag S. Maskey 1046ba597c5SAnurag S. MaskeyPersistent configuration state of entities is stored in project-private 1056ba597c5SAnurag S. Maskey/etc/nwam configuration files, and the details of storage are hidden 1066ba597c5SAnurag S. Maskeyfrom libnwam consumers. 1076ba597c5SAnurag S. Maskey 1086ba597c5SAnurag S. MaskeyAccess to entities is attained via an entity-specific handle. These 1096ba597c5SAnurag S. Maskeyhandles can be obtained via calls to nwam_<entity>_create() or 1106ba597c5SAnurag S. Maskeynwam_<entity>_read(), and freed (in memory) via calls to nwam_<entity>_free(). 1116ba597c5SAnurag S. Maskeynwam_<entity>_create() will create an in-memory representation of the 1126ba597c5SAnurag S. Maskeyentity, but that entity will not be stored until nwam_<entity>_commit() is 1136ba597c5SAnurag S. Maskeycalled. Persistently stored entitites are retrieved via nwam_<entity>_read(), 1146ba597c5SAnurag S. Maskeycan be modified in-memory, and later persistently committed to storage 1156ba597c5SAnurag S. Maskeyvia nwam_<entity>_commit(). Entities can also be copied with 1166ba597c5SAnurag S. Maskeynwam_<entity>_copy(). 1176ba597c5SAnurag S. Maskey 1186ba597c5SAnurag S. MaskeyAll changes made after binding a handle to an entity, and prior to calling 1196ba597c5SAnurag S. Maskeynwam_<entity>_commit() are carried out on the in-memory representation of that 1206ba597c5SAnurag S. Maskeyentity. nwam_<entity>_commit() updates persistent storage in an all-or-none 1216ba597c5SAnurag S. Maskeytransactional manner, applying the (possibly changed) in-memory representation 1226ba597c5SAnurag S. Maskeyto persistent storage atomically. 1236ba597c5SAnurag S. Maskey 1246ba597c5SAnurag S. MaskeyTo destroy an entity in persistent storage, nwam_<entity>_destroy() is 1256ba597c5SAnurag S. Maskeyused. This is distinct from nwam_<entity>_free(), which simply frees 1266ba597c5SAnurag S. Maskeythe in-memory representation - destroy both removes the object from 1276ba597c5SAnurag S. Maskeypersistent storage, and frees it in memory. 1286ba597c5SAnurag S. Maskey 1296ba597c5SAnurag S. MaskeyTo summarize, the pattern of interactions with an entity is 1306ba597c5SAnurag S. Maskey - nwam_<entity>_read(), nwam_<entity>_create() or nwam_<entity>_copy() 1316ba597c5SAnurag S. Maskey - possibly modify entity properties 1326ba597c5SAnurag S. Maskey - nwam_<entity>_commit() or nwam_<entity>_destroy() 1336ba597c5SAnurag S. Maskey - nwam_<entity>_handle_free() 1346ba597c5SAnurag S. Maskey 1356ba597c5SAnurag S. MaskeyUnless otherwise stated functions in libnwam are MT-safe. The 1366ba597c5SAnurag S. Maskeyatomicity of _commit() and _read() operations is guaranteed - i.e. 1376ba597c5SAnurag S. Maskey_commit() is guaranteed to deliver all property changes to persistent 1386ba597c5SAnurag S. Maskeystorage, while _read() is guaranteed to read a consistent view of the 1396ba597c5SAnurag S. Maskeyentity (i.e. _read() cannot collide with another entity _commit()ting 1406ba597c5SAnurag S. Maskeychanges). However, it is possible that a _read() will retrieve an 1416ba597c5SAnurag S. Maskeyoutdated view of an entity, if after the _read() completes, another 1426ba597c5SAnurag S. Maskeyentity _commit()s changes. In other words, lost updates are possible. 1436ba597c5SAnurag S. MaskeyThese are permitted given the nature of the entities changing NWAM 1446ba597c5SAnurag S. Maskeyconfiguration (the CLI and GUI) - it seems intuitive that the most 1456ba597c5SAnurag S. Maskeyrecent update best captures user intent. 1466ba597c5SAnurag S. Maskey 1476ba597c5SAnurag S. MaskeyEntity validation on an in-memory representation can be explicitly requested 1486ba597c5SAnurag S. Maskeyvia a call to nwam_<entity>_validate(), and individual property values 1496ba597c5SAnurag S. Maskeycan be validated via nwam_<entity>_validate_prop(). 1506ba597c5SAnurag S. Maskey 1516ba597c5SAnurag S. MaskeyStorage and retrieval of properties is done via nwam_<entity>_set_prop_value() 1526ba597c5SAnurag S. Maskeyand nwam_<entity>_get_prop_value(). These functions require an nwam_value_t as 1536ba597c5SAnurag S. Maskeya parameter, which is created via the nwam_value_create_<type>() family 1546ba597c5SAnurag S. Maskeyof functions. Data can be retrieved from the nwam_value_t via the 1556ba597c5SAnurag S. Maskeynwam_value_get_<type>() family of functions. Once a property has been 1566ba597c5SAnurag S. Maskeyset, the associated nwam_value_t can be immediately freed. For retrieval, 1576ba597c5SAnurag S. Maskeythe nwam_value_t should be freed when the value(s) are no longer needed. 1586ba597c5SAnurag S. MaskeyA property can also be delete with nwam_<entity>_delete_prop(). 1596ba597c5SAnurag S. Maskey 1606ba597c5SAnurag S. MaskeyImplicit validation occurs as part of the nwam_<entity>_set_prop_value() 1616ba597c5SAnurag S. Maskeyand nwam_<entity>_commit() functions. 1626ba597c5SAnurag S. Maskey 1636ba597c5SAnurag S. MaskeyINTERFACES 1646ba597c5SAnurag S. Maskey 1656ba597c5SAnurag S. MaskeyFor error handling: 1666ba597c5SAnurag S. Maskey 1676ba597c5SAnurag S. Maskeyconst char *nwam_strerror(nwam_error_t error); 1686ba597c5SAnurag S. Maskey 1696ba597c5SAnurag S. MaskeyFor values: 1706ba597c5SAnurag S. Maskey 1716ba597c5SAnurag S. MaskeyValues can be any of the following types: 1726ba597c5SAnurag S. Maskey 1736ba597c5SAnurag S. Maskey NWAM_VALUE_TYPE_BOOLEAN 1746ba597c5SAnurag S. Maskey NWAM_VALUE_TYPE_UINT64 1756ba597c5SAnurag S. Maskey NWAM_VALUE_TYPE_INT64 1766ba597c5SAnurag S. Maskey NWAM_VALUE_TYPE_STRING 1776ba597c5SAnurag S. Maskey 1786ba597c5SAnurag S. Maskeyand are possibly multi-valued. An nwam_value_t must be created in order 1796ba597c5SAnurag S. Maskeyto set property values in libnwam, this is done via the follwing functions: 1806ba597c5SAnurag S. Maskey 1816ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_boolean(boolean_t, nwam_value_t *); 1826ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_boolean_array(boolean_t *, uint_t, 1836ba597c5SAnurag S. Maskey nwam_value_t *); 1846ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_uint64(uint64_t, nwam_value_t *); 1856ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_uint64_array(uint64_t *, uint_t, nwam_value_t *); 1866ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_int64(int64_t, nwam_value_t *); 1876ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_int64_array(int64_t *, uint_t, nwam_value_t *); 1886ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_string(char *, nwam_value_t *); 1896ba597c5SAnurag S. Maskeynwam_error_t nwam_value_create_string_array(char **, uint_t, nwam_value_t *); 1906ba597c5SAnurag S. Maskey 1916ba597c5SAnurag S. MaskeyValues are returned from the _get_prop_value() functions, and the data 1926ba597c5SAnurag S. Maskeycontained in them can be retrieved via the following functions: 1936ba597c5SAnurag S. Maskey 1946ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_boolean(nwam_value_t, boolean_t *); 1956ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_boolean_array(nwam_value_t, boolean_t **, uint_t *); 1966ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_uint64(nwam_value_t, uint64_t *); 1976ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_uint64_array(nwam_value_t, uint64_t **, uint_t *); 1986ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_int64(nwam_value_t, int64_t *); 1996ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_int64_array(nwam_value_t, int64_t **, uint_t *); 2006ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_string(nwam_value_t, char **); 2016ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_string_array(nwam_value_t, char ***, uint_t *); 2026ba597c5SAnurag S. Maskey 2036ba597c5SAnurag S. MaskeyType and number of value can be retrieved via: 2046ba597c5SAnurag S. Maskey 2056ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_type(nwam_value_t, nwam_value_type_t *); 2066ba597c5SAnurag S. Maskeynwam_error_t nwam_value_get_numvalues(nwam_value_t, uint_t *); 2076ba597c5SAnurag S. Maskey 2086ba597c5SAnurag S. Maskeyand a value is freed using: 2096ba597c5SAnurag S. Maskey 2106ba597c5SAnurag S. Maskeyvoid nwam_value_free(nwam_value_t); 2116ba597c5SAnurag S. Maskey 2126ba597c5SAnurag S. MaskeyFor property setting, a typical set of events is to create the value, 2136ba597c5SAnurag S. Maskeycall the appropriate set_prop_value() function, then free the value (values 2146ba597c5SAnurag S. Maskeycan be safely freed prior to commit). For retrieval, the type and 2156ba597c5SAnurag S. Maskeynumber of values usually need to be tested before calling the appropriate 2166ba597c5SAnurag S. Maskeyretrieval function. In this case, the value should not be freed until 2176ba597c5SAnurag S. Maskeythe associated data is no longer needed. 2186ba597c5SAnurag S. Maskey 2196ba597c5SAnurag S. MaskeyNCUs, locations and ENMs can all specify conditional activation conditions. 2206ba597c5SAnurag S. MaskeyInterfaces are provided to convert a conditional activation predicate into 2216ba597c5SAnurag S. Maskeya string, or from a string to a parsed set of variables that comprise the 2226ba597c5SAnurag S. Maskeycondition. Additionally a function is provided to rate the specificity of 2236ba597c5SAnurag S. Maskeythe activation condition, used to compare location conditions to choose 2246ba597c5SAnurag S. Maskeythe most specific condition to activate in the case where the activation 2256ba597c5SAnurag S. Maskeyconditions of multiple locations are specified. 2266ba597c5SAnurag S. Maskey 2276ba597c5SAnurag S. Maskeynwam_error_t nwam_condition_to_condition_string(nwam_condition_object_type_t, 2286ba597c5SAnurag S. Maskey nwam_condition_t, const char *, char **); 2296ba597c5SAnurag S. Maskeynwam_error_t nwam_condition_string_to_condition(const char *, 2306ba597c5SAnurag S. Maskey nwam_condition_object_type_t *, nwam_condition_t *, char **); 2316ba597c5SAnurag S. Maskeynwam_error_t nwam_condition_rate(nwam_condition_object_type_t, 2326ba597c5SAnurag S. Maskey nwam_condition_t, uint64_t *); 2336ba597c5SAnurag S. Maskey 2346ba597c5SAnurag S. MaskeyFor NCP entities: 2356ba597c5SAnurag S. Maskey 2366ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_create(const char *name, uint64_t flags, 2376ba597c5SAnurag S. Maskey nwam_ncp_handle_t *ncp); 2386ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_read(const char *name, uint64_t flags, 2396ba597c5SAnurag S. Maskey nwam_ncp_handle_t *ncp); 2406ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_copy(nwam_ncp_handle_t ncp, const char *newname, 2416ba597c5SAnurag S. Maskey nwam_ncp_handle_t *newncp); 2426ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_walk_ncus(nwam_ncp_handle_t ncp, 2436ba597c5SAnurag S. Maskey int(*cb)(nwam_ncu_handle_t, void *), void *data, uint64_t flags, int *ret); 2446ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_get_name(nwam_ncp_handle_t ncp, char **name); 2456ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_activate(nwam_ncp_handle_t ncp); 2466ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_deactivate(nwam_ncp_handle_t ncp); 2476ba597c5SAnurag S. Maskeynwam_error_t nwam_ncp_destroy(nwam_ncp_handle_t ncp, uint64_t flags); 2486ba597c5SAnurag S. Maskeyvoid nwam_ncp_free(nwam_ncp_handle_t ncp); 2496ba597c5SAnurag S. Maskey 2506ba597c5SAnurag S. MaskeySince the NCP simply consists of the NCUs that comprise it, there is 2516ba597c5SAnurag S. Maskeyno NCP-specific commit() function - we simply read the NCP, walk the 2526ba597c5SAnurag S. Maskeyconstituent NCUs, reading, changing or committing them in turn. The 2536ba597c5SAnurag S. Maskeywalk can be modified via the flags option to only select specific NCU types 2546ba597c5SAnurag S. Maskeyand classes. 2556ba597c5SAnurag S. Maskey 2566ba597c5SAnurag S. MaskeyEach NCP has a set of NCUs associated with it, each of which is created/modifed 2576ba597c5SAnurag S. Maskeyusing the functions below. 2586ba597c5SAnurag S. Maskey 2596ba597c5SAnurag S. MaskeyFor NCU entities: 2606ba597c5SAnurag S. Maskey 2616ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_create(nwam_ncp_handle_t ncp, const char *name, 2626ba597c5SAnurag S. Maskey nwam_ncu_type_t type, nwam_ncu_class_t class, nwam_ncu_handle_t *ncu); 2636ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_read(nwam_ncp_handle_t ncp, const char *name, 2646ba597c5SAnurag S. Maskey nwam_ncu_type_t type, uint64_t flags, nwam_ncu_handle_t *ncu); 2656ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_copy(nwam_ncu_handle_t ncu, const char *newname, 2666ba597c5SAnurag S. Maskey nwam_ncu_handle_t *newncu); 2676ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_commit(nwam_ncu_handle_t ncu, uint64_t flags); 2686ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_destroy(nwam_ncu_handle_t ncu, uint64_t flags); 2696ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_free(nwam_ncu_handle_t ncu); 2706ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_validate(nwam_ncu_handle_t ncu, const char **errprop); 2716ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_get_prop_value(nwam_ncu_handle_t ncu, const char *prop, 2726ba597c5SAnurag S. Maskey nwam_value_t *value); 2736ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_get_prop_description(const char *prop, 2746ba597c5SAnurag S. Maskey const char **description); 2756ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_delete_prop(nwam_ncu_handle_t ncu, const char *prop); 2766ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_set_prop_value(nwam_ncu_handle_t ncu, const char *prop, 2776ba597c5SAnurag S. Maskey nwam_value_t value); 2786ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_get_name(nwam_ncu_handle_t ncu, char **name); 2796ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_set_name(nwam_ncu_handle_t ncu, const char *name); 2806ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_get_read_only(nwam_ncu_handle_t ncu, boolean_t *readp); 2816ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_validate_prop(nwam_ncu_handle_t ncu, const char *prop, 2826ba597c5SAnurag S. Maskey nwam_value_t value); 2836ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_walk_props(nwam_ncu_handle_t ncu, 2846ba597c5SAnurag S. Maskey int (*func)(void *, const char *, nwam_value_t), void *data, 2856ba597c5SAnurag S. Maskey uint64_t flags, int *ret); 2866ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_prop_get_type(const char *prop, 2876ba597c5SAnurag S. Maskey nwam_value_type_t *value_type); 2886ba597c5SAnurag S. Maskeynwam_error_t nwam_ncu_get_ncp(nwam_ncu_handle_t ncu, nwam_ncp_handle_t *ncp); 2896ba597c5SAnurag S. Maskey 2906ba597c5SAnurag S. MaskeyNCUs are manipulated via an nwam_ncu_handle_t. 2916ba597c5SAnurag S. Maskey 2926ba597c5SAnurag S. MaskeyEach NCU has a set of properties associated with it. Each property can 2936ba597c5SAnurag S. Maskeyhave mutiple values associated with it, which are set or retrieved via an 2946ba597c5SAnurag S. Maskeynwam_value_t. The approach is similar to that used for Locations, with 2956ba597c5SAnurag S. Maskeythe difference that read/commit/destroy must specify an NCP. Only two 2966ba597c5SAnurag S. MaskeyNCPs are supported at present, the automatic and user NCPs. Modification 2976ba597c5SAnurag S. Maskeyof the former is restricted to nwamd itself, and attempts to modify 2986ba597c5SAnurag S. Maskeythe automatic NCP's consituent NCUs will result in an NWAM_ENTITY_READ_ONLY 2996ba597c5SAnurag S. Maskeyerror. 3006ba597c5SAnurag S. Maskey 3016ba597c5SAnurag S. MaskeyFor Location entities: 3026ba597c5SAnurag S. Maskey 3036ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_create(const char *name, nwam_loc_handle_t *loc); 3046ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_read(const char *name, uint64_t flags, 3056ba597c5SAnurag S. Maskey nwam_loc_handle_t *loc); 3066ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_copy(nwam_loc_handle_t loc, const char *newname, 3076ba597c5SAnurag S. Maskey nwam_loc_handle_t *newloc); 3086ba597c5SAnurag S. Maskeynwam_error_t nwam_walk_locs(int (*cb)(nwam_loc_handle_t loc, void *arg), 3096ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbretp); 3106ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_commit(nwam_loc_handle_t loc, uint64_t flags); 3116ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_destroy(nwam_loc_handle_t loc, uint64_t flags); 3126ba597c5SAnurag S. Maskeyvoid nwam_loc_free(nwam_loc_handle_t loc); 3136ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_validate(nwam_loc_handle_t loc, const char *errprop); 3146ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_walk_props(nwam_loc_handle_t loc, 3156ba597c5SAnurag S. Maskey int (*cb)(const char *, nwam_value_t **, void *), 3166ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbret); 3176ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_validate_prop(nwam_loc_handle_t loc, 3186ba597c5SAnurag S. Maskey const char *prop, nwam_value_t value); 3196ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_prop_get_type(const char *prop, 3206ba597c5SAnurag S. Maskey nwam_value_type_t *value_type); 3216ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_get_prop_value(nwam_loc_handle_t loc, const char *prop, 3226ba597c5SAnurag S. Maskey nwam_value_t *value); 3236ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_get_prop_description(const char *prop, 3246ba597c5SAnurag S. Maskey const char **description); 3256ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_delete_prop(nwam_loc_handle_t loc, const char *prop); 3266ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_set_prop_value(nwam_loc_handle_t loc, const char *prop, 3276ba597c5SAnurag S. Maskey nwam_value_t value); 3286ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_get_name(nwam_loc_handle_t loc, char **name); 3296ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_set_name(nwam_loc_handle_t loc, const char *name); 3306ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_activate(nwam_loc_handle_t loc); 3316ba597c5SAnurag S. Maskeynwam_error_t nwam_loc_deactivate(nwam_loc_handle_t loc); 3326ba597c5SAnurag S. Maskey 3336ba597c5SAnurag S. MaskeyLocations are manipulated via an nwam_loc_handle_t. 3346ba597c5SAnurag S. Maskey 3356ba597c5SAnurag S. MaskeyA loc handle maps to an in-memory representation of a location; operations via 3366ba597c5SAnurag S. Maskeythis interface manipulate the in-memory data. In-memory data is read from 3376ba597c5SAnurag S. Maskeypersistant storage via the nwam_loc_read() or nwam_walk_locs() functions, and 3386ba597c5SAnurag S. Maskeywritten out to persistent storage via the nwam_loc_commit() function. A loc 3396ba597c5SAnurag S. Maskeymay be permanently removed from persistent storage with the nwam_loc_destroy() 3406ba597c5SAnurag S. Maskeyfunction. Interactions with persistent storage will be nonblocking by default; 3416ba597c5SAnurag S. Maskeythis behavior can be changed by passing the NWAM_FLAG_BLOCKING in the flags 3426ba597c5SAnurag S. Maskeyparameter. 3436ba597c5SAnurag S. Maskey 3446ba597c5SAnurag S. MaskeyA typical sequence would be to allocate a loc handle, either by creating a 3456ba597c5SAnurag S. Maskeynew loc (nwam_loc_create()) or by reading one from persistent storage (nwam_ 3466ba597c5SAnurag S. Maskeyloc_read() or nwam_walk_locs()). The various set/get/walk/validate/(de)activate 3476ba597c5SAnurag S. Maskeyfunctions may then be used to manipulate the loc; any changes made may then be 3486ba597c5SAnurag S. Maskeycommitted to persistent storage via nwam_loc_commit(). A call to nwam_loc_ 3496ba597c5SAnurag S. Maskeyfree() is required to release in-memory resources associated with the handle. 3506ba597c5SAnurag S. Maskey 3516ba597c5SAnurag S. MaskeyThe flags parameter in the walk functions allows filtering of the locs that 3526ba597c5SAnurag S. Maskeywill be examined, depending on the state of each loc. Passing in 3536ba597c5SAnurag S. MaskeyNWAM_FLAG_STATE_ALL will examine all locs; specific state flags are defined 3546ba597c5SAnurag S. Maskeyin <libnwam.h>. 3556ba597c5SAnurag S. Maskey 3566ba597c5SAnurag S. MaskeyLike NCUs, each loc has a set of properties associated with it. Loc properties 3576ba597c5SAnurag S. Maskeyare stored in nwam_value_t structures; see the Values section for how to store/ 3586ba597c5SAnurag S. Maskeyretrieve using these. 3596ba597c5SAnurag S. Maskey 3606ba597c5SAnurag S. MaskeyFor ENM entities: 3616ba597c5SAnurag S. Maskey 3626ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_create(const char *name, const char *fmri, 3636ba597c5SAnurag S. Maskey nwam_enm_handle_t *enm); 3646ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_read(const char *name, uint64_t flags, 3656ba597c5SAnurag S. Maskey nwam_enm_handle_t *enm); 3666ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_copy(nwam_enm_handle_t enm, const char *newname, 3676ba597c5SAnurag S. Maskey nwam_enm_handle_t *newenm); 3686ba597c5SAnurag S. Maskeynwam_error_t nwam_walk_enms(int (*cb)(nwam_enm_handle_t enm, void *arg), 3696ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbretp); 3706ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_commit(nwam_enm_handle_t enm, uint64_t flags); 3716ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_destroy(nwam_enm_handle_t enm, uint64_t flags); 3726ba597c5SAnurag S. Maskeyvoid nwam_enm_free(nwam_enm_handle_t enm); 3736ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_validate(nwam_enm_handle_t enm, const char *errprop); 3746ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_walk_props(nwam_enm_handle_t enm, 3756ba597c5SAnurag S. Maskey int (*cb)(const char *, nwam_value_t **, void *), 3766ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbret); 3776ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_validate_prop(nwam_enm_handle_t enm, 3786ba597c5SAnurag S. Maskey const char *prop, nwam_value_t value); 3796ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_prop_get_type(const char *prop, 3806ba597c5SAnurag S. Maskey nwam_value_type_t *value_type); 3816ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_get_prop_value(nwam_enm_handle_t enm, const char *prop, 3826ba597c5SAnurag S. Maskey nwam_value_t *value); 3836ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_get_prop_description(const char *prop, 3846ba597c5SAnurag S. Maskey const char **description); 3856ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_delete_prop(nwam_enm_handle_t enm, const char *prop); 3866ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_set_prop_value(nwam_enm_handle_t enm, const char *prop, 3876ba597c5SAnurag S. Maskey nwam_value_t value); 3886ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_get_name(nwam_enm_handle_t enm, char **name); 3896ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_set_name(nwam_enm_handle_t enm, const char *name); 3906ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_activate(nwam_enm_handle_t enm); 3916ba597c5SAnurag S. Maskeynwam_error_t nwam_enm_deactivate(nwam_enm_handle_t enm); 3926ba597c5SAnurag S. Maskey 3936ba597c5SAnurag S. MaskeyENMs are manipulated via an nwam_enm_handle_t, in a similar manner to 3946ba597c5SAnurag S. MaskeyNCUs and locations. 3956ba597c5SAnurag S. Maskey 3966ba597c5SAnurag S. MaskeyThe flags parameter in the walk functions allows filtering of the ENMs that 3976ba597c5SAnurag S. Maskeywill be examined, depending on the state of each ENM. Passing in 3986ba597c5SAnurag S. MaskeyNWAM_FLAG_STATE_ALL will examine all ENMs; specific state flags are defined 3996ba597c5SAnurag S. Maskeyin <libnwam.h>. 4006ba597c5SAnurag S. Maskey 4016ba597c5SAnurag S. MaskeyLike NCUs, each ENM has a set of properties associated with it. ENM properties 4026ba597c5SAnurag S. Maskeyare all single valued, though the interface is aligned with the NCU interface, 4036ba597c5SAnurag S. Maskeywhich allows for multi-valued properties. ENM properties are stored in 4046ba597c5SAnurag S. Maskeynwam_value_t structures; see the Values section for how to store/retrieve 4056ba597c5SAnurag S. Maskeyusing these. 4066ba597c5SAnurag S. Maskey 4076ba597c5SAnurag S. MaskeyFor known WLAN entities: 4086ba597c5SAnurag S. Maskey 4096ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_create(const char *name, 4106ba597c5SAnurag S. Maskey nwam_known_wlan_handle_t *kwhp); 4116ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_read(const char *name, uint64_t flags, 4126ba597c5SAnurag S. Maskey nwam_known_wlan_handle_t *kwhp); 4136ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_copy(nwam_known_wlan_handle_t kwh, 4146ba597c5SAnurag S. Maskey const char *newname, nwam_known_wlan_handle_t *newkwh); 4156ba597c5SAnurag S. Maskeynwam_error_t nwam_walk_known_wlans(int (*cb)(nwam_known_wlan_handle_t, void *), 4166ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbretp); 4176ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_commit(nwam_known_wlan_handle_t kwh, 4186ba597c5SAnurag S. Maskey uint64_t flags); 4196ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_destroy(nwam_known_wlan_handle_t kwh, 4206ba597c5SAnurag S. Maskey uint64_t flags); 4216ba597c5SAnurag S. Maskeyvoid nwam_known_wlan_free(nwam_known_wlan_handle_t kwh); 4226ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_validate(nwam_known_wlan_handle_t kwh, 4236ba597c5SAnurag S. Maskey const char *errprop); 4246ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_walk_props(nwam_known_wlan_handle_t kwh, 4256ba597c5SAnurag S. Maskey int (*cb)(const char *, nwam_value_t **, void *), 4266ba597c5SAnurag S. Maskey void *arg, uint64_t flags, int *cbret); 4276ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_validate_prop(nwam_known_wlan_handle_t kwh, 4286ba597c5SAnurag S. Maskey const char *prop, nwam_value_t value); 4296ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_prop_get_type(const char *prop, 4306ba597c5SAnurag S. Maskey nwam_value_type_t *value_type); 4316ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_get_prop_value(nwam_known_wlan_handle_t kwh, 4326ba597c5SAnurag S. Maskey const char *prop, nwam_value_t *value); 4336ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_get_prop_description(const char *prop, 4346ba597c5SAnurag S. Maskey const char **description); 4356ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_delete_prop(nwam_known_wlan_handle_t kwh, 4366ba597c5SAnurag S. Maskey const char *prop); 4376ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_set_prop_value(nwam_known_wlan_handle_t kwh, 4386ba597c5SAnurag S. Maskey const char *prop, nwam_value_t value); 4396ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_get_name(nwam_known_wlan_handle_t kwh, 4406ba597c5SAnurag S. Maskey char **name); 4416ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_set_name(nwam_known_wlan_handle_t kwh, 4426ba597c5SAnurag S. Maskey const char *name); 4436ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_add_to_known_wlan(const char *essid, 4446ba597c5SAnurag S. Maskey const char *bssid); 4456ba597c5SAnurag S. Maskeynwam_error_t nwam_known_wlan_remove_from_known_wlan(const char *essid, 4466ba597c5SAnurag S. Maskey const char *bssid); 4476ba597c5SAnurag S. Maskey 4486ba597c5SAnurag S. MaskeyKnown WLANs are manipulated via an nwam_known_wlan_handle_t, in a similar 4496ba597c5SAnurag S. Maskeymanner to NCUs, locations and ENMs. 4506ba597c5SAnurag S. Maskey 4516ba597c5SAnurag S. MaskeyLike ENMs, each known WLAN has a set of properties associated with it. 4526ba597c5SAnurag S. MaskeyKnown WLAN properties are stored in nwam_value_t structures; see the Values 4536ba597c5SAnurag S. Maskeysection for how to store/retrieve using these. 4546ba597c5SAnurag S. Maskey 4556ba597c5SAnurag S. MaskeyFor WLANs, we define a set of functions to ask nwamd to initiate a scan, 4566ba597c5SAnurag S. Maskeyselect a WLAN (and possibly add it to the known WLAN list) or set a WLAN 4576ba597c5SAnurag S. Maskeykey: 4586ba597c5SAnurag S. Maskey 4596ba597c5SAnurag S. Maskey 4606ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_wlan_scan(const char *linkname); 4616ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_wlan_get_scan_results(const char *linkname, 4626ba597c5SAnurag S. Maskey uint_t *num_resultsp, nwam_wlan_t **wlansp); 4636ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_wlan_select(const char *linkname, 4646ba597c5SAnurag S. Maskey const char *essid, const char *bssid, boolean_t add_to_known_wlans); 4656ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_wlan_set_key(const char *linkname, const char *essid, 4666ba597c5SAnurag S. Maskey const char *bssid, uint32_t security_mode, uint_t keyslot, const char *key); 4676ba597c5SAnurag S. Maskey 4686ba597c5SAnurag S. MaskeyFor Events: 4696ba597c5SAnurag S. Maskey 4706ba597c5SAnurag S. Maskeytypedef struct nwam_event { 4716ba597c5SAnurag S. Maskey uint32_t type; 4726ba597c5SAnurag S. Maskey 4736ba597c5SAnurag S. Maskey union { 4746ba597c5SAnurag S. Maskey struct { 4756ba597c5SAnurag S. Maskey nwam_object_type_t object_type; 4766ba597c5SAnurag S. Maskey char name[NWAM_MAX_NAME_LEN]; 4776ba597c5SAnurag S. Maskey nwam_action_t action; 4786ba597c5SAnurag S. Maskey } object_action; 4796ba597c5SAnurag S. Maskey 4806ba597c5SAnurag S. Maskey 4816ba597c5SAnurag S. Maskey ... and so on for each message ... 4826ba597c5SAnurag S. Maskey 4836ba597c5SAnurag S. Maskey } data; 4846ba597c5SAnurag S. Maskey 4856ba597c5SAnurag S. Maskey} *nwam_event_t; 4866ba597c5SAnurag S. Maskey 4876ba597c5SAnurag S. Maskeytype comes from the set of constants NWAM_EVENT_TYPE_*. 4886ba597c5SAnurag S. Maskey 4896ba597c5SAnurag S. MaskeyRegistration and cancellation of registration are done via 4906ba597c5SAnurag S. Maskey_init and _fini functions: 4916ba597c5SAnurag S. Maskey 4926ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_events_init(void); 4936ba597c5SAnurag S. Maskeyextern void nwam_events_fini(void); 4946ba597c5SAnurag S. Maskey 4956ba597c5SAnurag S. MaskeyEvents can then be recieved by calling nwam_event_wait(): 4966ba597c5SAnurag S. Maskey 4976ba597c5SAnurag S. Maskeyextern nwam_error_t nwam_event_wait(nwam_event_t *); 4986ba597c5SAnurag S. Maskey 4996ba597c5SAnurag S. MaskeyThe event can then be processed, and free via nwam_event_free(); 5006ba597c5SAnurag S. Maskey 5016ba597c5SAnurag S. MaskeyRETURN VALUES 5026ba597c5SAnurag S. Maskey 5036ba597c5SAnurag S. MaskeyAll functions return an nwam_error_t if they return an error. Possible 5046ba597c5SAnurag S. Maskeyerrors are: 5056ba597c5SAnurag S. Maskey 5066ba597c5SAnurag S. Maskey NWAM_SUCCESS No error occured 5076ba597c5SAnurag S. Maskey NWAM_LIST_END End of list 5086ba597c5SAnurag S. Maskey NWAM_INVALID_HANDLE Entity handle is invalid 5096ba597c5SAnurag S. Maskey NWAM_HANDLE_UNBOUND Handle not bound to entity 5106ba597c5SAnurag S. Maskey NWAM_INVALID_ARG Argument is invalid 5116ba597c5SAnurag S. Maskey NWAM_PERMISSION_DENIED Insufficient privileges for action 5126ba597c5SAnurag S. Maskey NWAM_NO_MEMORY Out of memory 5136ba597c5SAnurag S. Maskey NWAM_ENTITY_EXISTS Entity already exists 5146ba597c5SAnurag S. Maskey NWAM_ENTITY_IN_USE Another user is interacting with entity 5156ba597c5SAnurag S. Maskey NWAM_ENTITY_COMMITTED Entity already committed 5166ba597c5SAnurag S. Maskey NWAM_ENTITY_NOT_FOUND Entity not found 5176ba597c5SAnurag S. Maskey NWAM_ENTITY_TYPE_MISMATCH Entity value-type mismatch 5186ba597c5SAnurag S. Maskey NWAM_ENTITY_INVALID Validation of entity failed 5196ba597c5SAnurag S. Maskey NWAM_ENTITY_INVALID_MEMBER Entity member invalid 5206ba597c5SAnurag S. Maskey NWAM_ENTITY_INVALID_VALUE Validation of entity value failed 5216ba597c5SAnurag S. Maskey NWAM_ENTITY_NO_VALUE No value associated with entity 5226ba597c5SAnurag S. Maskey NWAM_ENTITY_MULTIPLE_VALUES, Multiple values for entity 5236ba597c5SAnurag S. Maskey NWAM_ENTITY_READ_ONLY, Entity is marked read only 5246ba597c5SAnurag S. Maskey NWAM_WALK_HALTED, Callback function returned nonzero 5256ba597c5SAnurag S. Maskey NWAM_ERROR_BIND, Could not bind to backend 5266ba597c5SAnurag S. Maskey NWAM_ERROR_BACKEND_INIT, Could not initialize backend 5276ba597c5SAnurag S. Maskey NWAM_ERROR_INTERNAL Internal error 5286ba597c5SAnurag S. Maskey 5296ba597c5SAnurag S. MaskeyFILES 5306ba597c5SAnurag S. Maskey /lib/libnwam.so.1 shared object 5316ba597c5SAnurag S. Maskey 5326ba597c5SAnurag S. MaskeyATTRIBUTES 5336ba597c5SAnurag S. Maskey 5346ba597c5SAnurag S. Maskey 5356ba597c5SAnurag S. MaskeySEE ALSO 536*bbf21555SRichard Lowe nwamd(8), nwamcfg(8), nwamadm(8) 537