README revision 6ba597c56d749c61b4f783157f63196d7b2445f0
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews# CDDL HEADER START
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# The contents of this file are subject to the terms of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# Common Development and Distribution License (the "License").
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# You may not use this file except in compliance with the License.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# See the License for the specific language governing permissions
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# and limitations under the License.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# When distributing Covered Code, include this CDDL HEADER in each
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# If applicable, add the following below this CDDL HEADER, with the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# fields enclosed by brackets "[]" replaced with your own identifying
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrews# information: Portions Copyright [yyyy] [name of copyright owner]
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# CDDL HEADER END
cedb0bd0c1e3c461b7e479a16d3adfd5b150f1f4Mark Andrews# Copyright 2010 Sun Microsystems, Inc. All rights reserved.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein# Use is subject to license terms.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein libnwam - Network Auto-Magic (NWAM) configuration and event
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein management library
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe libnwam library is provided so that the various consumers of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNetwork Auto-Magic (NWAM) configuration information - i.e. the NWAM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinGUI, the nwamcfg CLI and the NWAM daemon - have a consistent interface
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfor retrieving and updating NWAM-related configuration data, abstracted
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfrom the actual manner in which the data is persistently stored. It
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinprovides functionality to interact with the key components of NWAM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinconfiguration, as described below. Additionally the library provides
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfunctionality for system events to flow from the NWAM daemon to a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinclient (like the GUI panel applet).
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEach of these configuration components is referred to as an 'entity'.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNetwork Configuration Units (NCUs): units that specify either link or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeininterface (IP) configuration. An NCP consists of a set of NCUs, one for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeineach datalink (physical, tunnel, aggregation etc), and one for each IP
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark AndrewsNetwork Configuration Profiles (NCPs): A network configuration profile (NCP)
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincomprises of a set of NCUs specifying configuration preferences to be applied
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwhen that profile is active.
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark AndrewsLocations: A location consists of additional configuration preferences
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto be applied when basic IP configuration is complete. Information
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinsuch as name service specification, proxies, etc. can be specified.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinExternal Network Modifiers (ENMs): units that specify an external service
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinor executable that modifies the network configuration. Properties of an
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark AndrewsENM include an FMRI or Start and Stop exec strings, an optional environment
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrewswhich will be activated when the ENM is started, an activation type specifying
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwhen the ENM should be started (e.g. on user input, dependent on an NCU--
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrewseither requiring or excluding a particular NCU, or always-on). Each ENM
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrewsalso has a read-only state property, which indicates whether or not the
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark AndrewsENM has been activated by nwam.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinKnown WiFi Networks (known WLANs): units that specify configuration
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewsdata associated with known WiFi access points that the user visits. If
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewsa WLAN found by scanning is one of the known WLANs, NWAM will automatically
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewsconnect. Priorities associated with known WLANs can also be manipulated
7329012471d165cd3dc4180ad2a0a43de91e7f01Mark Andrewsallowing users to prioritize particular WLANs.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe event interface allows a client of NWAM (usu. the GUI) to subscribe
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto a stream of system events such as link and interface up/down,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwireless scans, and times when NWAM needs the user to be queried.
035992291cb70ec3be4046fcea921b4a6acb1c77Mark AndrewsEvents types are in libnwam.h as NWAM_EVENTS_* and the actual bodies of
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewsthe events are in nwam_events_msg_t. The semantics of the events have
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinbeen simplified so that none require response. They are all
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnotification.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNWAM_EVENTS_SOURCE_{DEAD,BACK} provide notification that the nwam
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindaemon has died or has reappeared. These are synthetic events in that
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewsthey come from the library and not from nwamd.
035992291cb70ec3be4046fcea921b4a6acb1c77Mark AndrewsNWAM_EVENTS_NO_MAGIC provides notification that nwam couldn't make a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeindetermination of what to do without user guidance. This event provides
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeininformation that can be used to ask the user if he wants to pick a
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewswireless lan although in some cases nwam might have no idea what is
035992291cb70ec3be4046fcea921b4a6acb1c77Mark AndrewsNWAM_EVENTS_IF_{STATE,REMOVED} provide information about changes in
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewsinterface state or the removal of an interface.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNWAM_EVENTS_LINK_{STATE, REMOVED} provides information about changes in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlink state or the removal of a link.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNWAM_EVENTS_SCAN_REPORT is used to communicate information about
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwireless networks encountered.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinPersistent configuration state of entities is stored in project-private
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein/etc/nwam configuration files, and the details of storage are hidden
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfrom libnwam consumers.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAccess to entities is attained via an entity-specific handle. These
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinhandles can be obtained via calls to nwam_<entity>_create() or
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_<entity>_read(), and freed (in memory) via calls to nwam_<entity>_free().
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_<entity>_create() will create an in-memory representation of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinentity, but that entity will not be stored until nwam_<entity>_commit() is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincalled. Persistently stored entitites are retrieved via nwam_<entity>_read(),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincan be modified in-memory, and later persistently committed to storage
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvia nwam_<entity>_commit(). Entities can also be copied with
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_<entity>_copy().
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll changes made after binding a handle to an entity, and prior to calling
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_<entity>_commit() are carried out on the in-memory representation of that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinentity. nwam_<entity>_commit() updates persistent storage in an all-or-none
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintransactional manner, applying the (possibly changed) in-memory representation
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto persistent storage atomically.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTo destroy an entity in persistent storage, nwam_<entity>_destroy() is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinused. This is distinct from nwam_<entity>_free(), which simply frees
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe in-memory representation - destroy both removes the object from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinpersistent storage, and frees it in memory.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTo summarize, the pattern of interactions with an entity is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - nwam_<entity>_read(), nwam_<entity>_create() or nwam_<entity>_copy()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - possibly modify entity properties
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - nwam_<entity>_commit() or nwam_<entity>_destroy()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - nwam_<entity>_handle_free()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinUnless otherwise stated functions in libnwam are MT-safe. The
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinatomicity of _commit() and _read() operations is guaranteed - i.e.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein_commit() is guaranteed to deliver all property changes to persistent
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinstorage, while _read() is guaranteed to read a consistent view of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinentity (i.e. _read() cannot collide with another entity _commit()ting
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinchanges). However, it is possible that a _read() will retrieve an
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinoutdated view of an entity, if after the _read() completes, another
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinentity _commit()s changes. In other words, lost updates are possible.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThese are permitted given the nature of the entities changing NWAM
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinconfiguration (the CLI and GUI) - it seems intuitive that the most
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinrecent update best captures user intent.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEntity validation on an in-memory representation can be explicitly requested
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvia a call to nwam_<entity>_validate(), and individual property values
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincan be validated via nwam_<entity>_validate_prop().
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinStorage and retrieval of properties is done via nwam_<entity>_set_prop_value()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand nwam_<entity>_get_prop_value(). These functions require an nwam_value_t as
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeina parameter, which is created via the nwam_value_create_<type>() family
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinof functions. Data can be retrieved from the nwam_value_t via the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_value_get_<type>() family of functions. Once a property has been
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinset, the associated nwam_value_t can be immediately freed. For retrieval,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe nwam_value_t should be freed when the value(s) are no longer needed.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinA property can also be delete with nwam_<entity>_delete_prop().
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsImplicit validation occurs as part of the nwam_<entity>_set_prop_value()
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsand nwam_<entity>_commit() functions.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsFor error handling:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsconst char *nwam_strerror(nwam_error_t error);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsValues can be any of the following types:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews NWAM_VALUE_TYPE_BOOLEAN
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews NWAM_VALUE_TYPE_UINT64
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews NWAM_VALUE_TYPE_INT64
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_VALUE_TYPE_STRING
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand are possibly multi-valued. An nwam_value_t must be created in order
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinto set property values in libnwam, this is done via the follwing functions:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_boolean(boolean_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_boolean_array(boolean_t *, uint_t,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_uint64(uint64_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_uint64_array(uint64_t *, uint_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_int64(int64_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_int64_array(int64_t *, uint_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_string(char *, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_create_string_array(char **, uint_t, nwam_value_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinValues are returned from the _get_prop_value() functions, and the data
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincontained in them can be retrieved via the following functions:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_boolean(nwam_value_t, boolean_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_boolean_array(nwam_value_t, boolean_t **, uint_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_uint64(nwam_value_t, uint64_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_uint64_array(nwam_value_t, uint64_t **, uint_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_int64(nwam_value_t, int64_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_int64_array(nwam_value_t, int64_t **, uint_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_string(nwam_value_t, char **);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_string_array(nwam_value_t, char ***, uint_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinType and number of value can be retrieved via:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_type(nwam_value_t, nwam_value_type_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_value_get_numvalues(nwam_value_t, uint_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand a value is freed using:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvoid nwam_value_free(nwam_value_t);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor property setting, a typical set of events is to create the value,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincall the appropriate set_prop_value() function, then free the value (values
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincan be safely freed prior to commit). For retrieval, the type and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnumber of values usually need to be tested before calling the appropriate
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinretrieval function. In this case, the value should not be freed until
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe associated data is no longer needed.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNCUs, locations and ENMs can all specify conditional activation conditions.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinInterfaces are provided to convert a conditional activation predicate into
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeina string, or from a string to a parsed set of variables that comprise the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincondition. Additionally a function is provided to rate the specificity of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe activation condition, used to compare location conditions to choose
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe most specific condition to activate in the case where the activation
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinconditions of multiple locations are specified.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_condition_to_condition_string(nwam_condition_object_type_t,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_condition_t, const char *, char **);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_condition_string_to_condition(const char *,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_condition_object_type_t *, nwam_condition_t *, char **);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_condition_rate(nwam_condition_object_type_t,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_condition_t, uint64_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor NCP entities:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_create(const char *name, uint64_t flags,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncp_handle_t *ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_read(const char *name, uint64_t flags,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncp_handle_t *ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_copy(nwam_ncp_handle_t ncp, const char *newname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncp_handle_t *newncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_walk_ncus(nwam_ncp_handle_t ncp,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein int(*cb)(nwam_ncu_handle_t, void *), void *data, uint64_t flags, int *ret);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_get_name(nwam_ncp_handle_t ncp, char **name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_activate(nwam_ncp_handle_t ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_deactivate(nwam_ncp_handle_t ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncp_destroy(nwam_ncp_handle_t ncp, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvoid nwam_ncp_free(nwam_ncp_handle_t ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinSince the NCP simply consists of the NCUs that comprise it, there is
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinno NCP-specific commit() function - we simply read the NCP, walk the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinconstituent NCUs, reading, changing or committing them in turn. The
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwalk can be modified via the flags option to only select specific NCU types
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEach NCP has a set of NCUs associated with it, each of which is created/modifed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinusing the functions below.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor NCU entities:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_create(nwam_ncp_handle_t ncp, const char *name,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncu_type_t type, nwam_ncu_class_t class, nwam_ncu_handle_t *ncu);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_read(nwam_ncp_handle_t ncp, const char *name,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncu_type_t type, uint64_t flags, nwam_ncu_handle_t *ncu);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_copy(nwam_ncu_handle_t ncu, const char *newname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_ncu_handle_t *newncu);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_commit(nwam_ncu_handle_t ncu, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_destroy(nwam_ncu_handle_t ncu, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_free(nwam_ncu_handle_t ncu);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_validate(nwam_ncu_handle_t ncu, const char **errprop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_get_prop_value(nwam_ncu_handle_t ncu, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t *value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_get_prop_description(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char **description);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_delete_prop(nwam_ncu_handle_t ncu, const char *prop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_set_prop_value(nwam_ncu_handle_t ncu, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_get_name(nwam_ncu_handle_t ncu, char **name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_set_name(nwam_ncu_handle_t ncu, const char *name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_get_read_only(nwam_ncu_handle_t ncu, boolean_t *readp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_validate_prop(nwam_ncu_handle_t ncu, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_walk_props(nwam_ncu_handle_t ncu,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein int (*func)(void *, const char *, nwam_value_t), void *data,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uint64_t flags, int *ret);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_prop_get_type(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_type_t *value_type);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_ncu_get_ncp(nwam_ncu_handle_t ncu, nwam_ncp_handle_t *ncp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNCUs are manipulated via an nwam_ncu_handle_t.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinEach NCU has a set of properties associated with it. Each property can
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinhave mutiple values associated with it, which are set or retrieved via an
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_value_t. The approach is similar to that used for Locations, with
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe difference that read/commit/destroy must specify an NCP. Only two
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNCPs are supported at present, the automatic and user NCPs. Modification
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinof the former is restricted to nwamd itself, and attempts to modify
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthe automatic NCP's consituent NCUs will result in an NWAM_ENTITY_READ_ONLY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor Location entities:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_create(const char *name, nwam_loc_handle_t *loc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_read(const char *name, uint64_t flags,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_loc_handle_t *loc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_copy(nwam_loc_handle_t loc, const char *newname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_loc_handle_t *newloc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_walk_locs(int (*cb)(nwam_loc_handle_t loc, void *arg),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein void *arg, uint64_t flags, int *cbretp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_commit(nwam_loc_handle_t loc, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_destroy(nwam_loc_handle_t loc, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvoid nwam_loc_free(nwam_loc_handle_t loc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_validate(nwam_loc_handle_t loc, const char *errprop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_walk_props(nwam_loc_handle_t loc,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein int (*cb)(const char *, nwam_value_t **, void *),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein void *arg, uint64_t flags, int *cbret);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_validate_prop(nwam_loc_handle_t loc,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *prop, nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_prop_get_type(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_type_t *value_type);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_get_prop_value(nwam_loc_handle_t loc, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t *value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_get_prop_description(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char **description);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_delete_prop(nwam_loc_handle_t loc, const char *prop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_set_prop_value(nwam_loc_handle_t loc, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_get_name(nwam_loc_handle_t loc, char **name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_set_name(nwam_loc_handle_t loc, const char *name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_activate(nwam_loc_handle_t loc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_loc_deactivate(nwam_loc_handle_t loc);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLocations are manipulated via an nwam_loc_handle_t.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinA loc handle maps to an in-memory representation of a location; operations via
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthis interface manipulate the in-memory data. In-memory data is read from
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinpersistant storage via the nwam_loc_read() or nwam_walk_locs() functions, and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwritten out to persistent storage via the nwam_loc_commit() function. A loc
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinmay be permanently removed from persistent storage with the nwam_loc_destroy()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfunction. Interactions with persistent storage will be nonblocking by default;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinthis behavior can be changed by passing the NWAM_FLAG_BLOCKING in the flags
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinA typical sequence would be to allocate a loc handle, either by creating a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnew loc (nwam_loc_create()) or by reading one from persistent storage (nwam_
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinloc_read() or nwam_walk_locs()). The various set/get/walk/validate/(de)activate
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfunctions may then be used to manipulate the loc; any changes made may then be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeincommitted to persistent storage via nwam_loc_commit(). A call to nwam_loc_
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinfree() is required to release in-memory resources associated with the handle.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe flags parameter in the walk functions allows filtering of the locs that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwill be examined, depending on the state of each loc. Passing in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNWAM_FLAG_STATE_ALL will examine all locs; specific state flags are defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLike NCUs, each loc has a set of properties associated with it. Loc properties
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinare stored in nwam_value_t structures; see the Values section for how to store/
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinretrieve using these.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor ENM entities:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_create(const char *name, const char *fmri,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_enm_handle_t *enm);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_read(const char *name, uint64_t flags,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_enm_handle_t *enm);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsnwam_error_t nwam_enm_copy(nwam_enm_handle_t enm, const char *newname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_enm_handle_t *newenm);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_walk_enms(int (*cb)(nwam_enm_handle_t enm, void *arg),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein void *arg, uint64_t flags, int *cbretp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_commit(nwam_enm_handle_t enm, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_destroy(nwam_enm_handle_t enm, uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvoid nwam_enm_free(nwam_enm_handle_t enm);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsnwam_error_t nwam_enm_validate(nwam_enm_handle_t enm, const char *errprop);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsnwam_error_t nwam_enm_walk_props(nwam_enm_handle_t enm,
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews int (*cb)(const char *, nwam_value_t **, void *),
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews void *arg, uint64_t flags, int *cbret);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsnwam_error_t nwam_enm_validate_prop(nwam_enm_handle_t enm,
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews const char *prop, nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_prop_get_type(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_type_t *value_type);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_get_prop_value(nwam_enm_handle_t enm, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t *value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_get_prop_description(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char **description);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_delete_prop(nwam_enm_handle_t enm, const char *prop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_set_prop_value(nwam_enm_handle_t enm, const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_get_name(nwam_enm_handle_t enm, char **name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_set_name(nwam_enm_handle_t enm, const char *name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_activate(nwam_enm_handle_t enm);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_enm_deactivate(nwam_enm_handle_t enm);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinENMs are manipulated via an nwam_enm_handle_t, in a similar manner to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNCUs and locations.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe flags parameter in the walk functions allows filtering of the ENMs that
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwill be examined, depending on the state of each ENM. Passing in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNWAM_FLAG_STATE_ALL will examine all ENMs; specific state flags are defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLike NCUs, each ENM has a set of properties associated with it. ENM properties
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinare all single valued, though the interface is aligned with the NCU interface,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinwhich allows for multi-valued properties. ENM properties are stored in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_value_t structures; see the Values section for how to store/retrieve
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor known WLAN entities:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_create(const char *name,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_known_wlan_handle_t *kwhp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_read(const char *name, uint64_t flags,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_known_wlan_handle_t *kwhp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_copy(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *newname, nwam_known_wlan_handle_t *newkwh);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_walk_known_wlans(int (*cb)(nwam_known_wlan_handle_t, void *),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein void *arg, uint64_t flags, int *cbretp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_commit(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_destroy(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uint64_t flags);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinvoid nwam_known_wlan_free(nwam_known_wlan_handle_t kwh);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_validate(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *errprop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_walk_props(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein int (*cb)(const char *, nwam_value_t **, void *),
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein void *arg, uint64_t flags, int *cbret);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_validate_prop(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *prop, nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_prop_get_type(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_value_type_t *value_type);
605b07cadd58ff1d8f89ddf277451ee87a542f9bMark Andrewsnwam_error_t nwam_known_wlan_get_prop_value(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *prop, nwam_value_t *value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_get_prop_description(const char *prop,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char **description);
f293a69bcd1c1dd7bdac8f4102fc2398b9e475c8Eric Lucenwam_error_t nwam_known_wlan_delete_prop(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *prop);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_set_prop_value(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *prop, nwam_value_t value);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_get_name(nwam_known_wlan_handle_t kwh,
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews char **name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_set_name(nwam_known_wlan_handle_t kwh,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *name);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_add_to_known_wlan(const char *essid,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *bssid);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinnwam_error_t nwam_known_wlan_remove_from_known_wlan(const char *essid,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *bssid);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinKnown WLANs are manipulated via an nwam_known_wlan_handle_t, in a similar
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinmanner to NCUs, locations and ENMs.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLike ENMs, each known WLAN has a set of properties associated with it.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinKnown WLAN properties are stored in nwam_value_t structures; see the Values
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinsection for how to store/retrieve using these.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinFor WLANs, we define a set of functions to ask nwamd to initiate a scan,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinselect a WLAN (and possibly add it to the known WLAN list) or set a WLAN
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinextern nwam_error_t nwam_wlan_scan(const char *linkname);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinextern nwam_error_t nwam_wlan_get_scan_results(const char *linkname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uint_t *num_resultsp, nwam_wlan_t **wlansp);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinextern nwam_error_t nwam_wlan_select(const char *linkname,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *essid, const char *bssid, boolean_t add_to_known_wlans);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinextern nwam_error_t nwam_wlan_set_key(const char *linkname, const char *essid,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein const char *bssid, uint32_t security_mode, uint_t keyslot, const char *key);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintypedef struct nwam_event {
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein uint32_t type;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_object_type_t object_type;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein char name[NWAM_MAX_NAME_LEN];
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwam_action_t action;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein } object_action;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein ... and so on for each message ...
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein} *nwam_event_t;
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewstype comes from the set of constants NWAM_EVENT_TYPE_*.
035992291cb70ec3be4046fcea921b4a6acb1c77Mark AndrewsRegistration and cancellation of registration are done via
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrews_init and _fini functions:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinextern nwam_error_t nwam_events_init(void);
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewsextern void nwam_events_fini(void);
035992291cb70ec3be4046fcea921b4a6acb1c77Mark AndrewsEvents can then be recieved by calling nwam_event_wait():
035992291cb70ec3be4046fcea921b4a6acb1c77Mark Andrewsextern nwam_error_t nwam_event_wait(nwam_event_t *);
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe event can then be processed, and free via nwam_event_free();
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinRETURN VALUES
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinAll functions return an nwam_error_t if they return an error. Possible
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_SUCCESS No error occured
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_LIST_END End of list
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_INVALID_HANDLE Entity handle is invalid
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_HANDLE_UNBOUND Handle not bound to entity
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_INVALID_ARG Argument is invalid
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_PERMISSION_DENIED Insufficient privileges for action
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_NO_MEMORY Out of memory
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_EXISTS Entity already exists
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_IN_USE Another user is interacting with entity
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_COMMITTED Entity already committed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_NOT_FOUND Entity not found
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_TYPE_MISMATCH Entity value-type mismatch
3b4098640dd85040270f39b9a5ee5e22de99d3d6Mark Andrews NWAM_ENTITY_INVALID Validation of entity failed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_INVALID_MEMBER Entity member invalid
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_INVALID_VALUE Validation of entity value failed
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_NO_VALUE No value associated with entity
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_MULTIPLE_VALUES, Multiple values for entity
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ENTITY_READ_ONLY, Entity is marked read only
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_WALK_HALTED, Callback function returned nonzero
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ERROR_BIND, Could not bind to backend
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ERROR_BACKEND_INIT, Could not initialize backend
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein NWAM_ERROR_INTERNAL Internal error
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein nwamd(1M), nwamcfg(1M), nwamadm(1M)