2N/A#

2N/A# CDDL HEADER START

2N/A#

2N/A# The contents of this file are subject to the terms of the

2N/A# Common Development and Distribution License (the "License").

2N/A# You may not use this file except in compliance with the License.

2N/A#

2N/A# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

2N/A# or http://www.opensolaris.org/os/licensing.

2N/A# See the License for the specific language governing permissions

2N/A# and limitations under the License.

2N/A#

2N/A# When distributing Covered Code, include this CDDL HEADER in each

2N/A# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

2N/A# If applicable, add the following below this CDDL HEADER, with the

2N/A# fields enclosed by brackets "[]" replaced with your own identifying

2N/A# information: Portions Copyright [yyyy] [name of copyright owner]

2N/A#

2N/A# CDDL HEADER END

2N/A#

2N/A#

2N/A# Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.

2N/A#

2N/A# lib/libnwam/README

2N/A#

2N/A

2N/ANAME

2N/A libnwam - Network Auto-Magic (NWAM) configuration and event

2N/A management library

2N/A

2N/ADESCRIPTION

2N/A

2N/AThe libnwam library is provided so that the various consumers of

2N/ANetwork Auto-Magic (NWAM) configuration information - i.e. the NWAM

2N/AGUI, the netcfg CLI and the NWAM daemon - have a consistent interface

2N/Afor retrieving and updating NWAM-related configuration data, abstracted

2N/Afrom the actual manner in which the data is persistently stored. It

2N/Aprovides functionality to interact with the key components of NWAM

2N/Aconfiguration, as described below. Additionally the library provides

2N/Afunctionality for system events to flow from the NWAM daemon to a

2N/Aclient (like the GUI panel applet).

2N/A

2N/AEach of these configuration components is referred to as an 'entity'.

2N/A

2N/ANetwork Configuration Units (NCUs): units that specify either link or

2N/Ainterface (IP) configuration. An NCP consists of a set of NCUs, one for

2N/Aeach datalink (physical, tunnel, aggregation etc), and one for each IP

2N/Ainterface.

2N/A

2N/ANetwork Configuration Profiles (NCPs): A network configuration profile (NCP)

2N/Acomprises of a set of NCUs specifying configuration preferences to be applied

2N/Awhen that profile is active.

2N/A

2N/ALocations: A location consists of additional configuration preferences

2N/Ato be applied when basic IP configuration is complete. Information

2N/Asuch as name service specification, proxies, etc. can be specified.

2N/A

2N/AExternal Network Modifiers (ENMs): units that specify an external service

2N/Aor executable that modifies the network configuration. Properties of an

2N/AENM include an FMRI or Start and Stop exec strings, an optional environment

2N/Awhich will be activated when the ENM is started, an activation type specifying

2N/Awhen the ENM should be started (e.g. on user input, dependent on an NCU--

2N/Aeither requiring or excluding a particular NCU, or always-on). Each ENM

2N/Aalso has a read-only state property, which indicates whether or not the

2N/AENM has been activated by nwam.

2N/A

2N/AKnown WiFi Networks (known WLANs): units that specify configuration

2N/Adata associated with known WiFi access points that the user visits. If

2N/Aa WLAN found by scanning is one of the known WLANs, NWAM will automatically

2N/Aconnect. Priorities associated with known WLANs can also be manipulated

2N/Aallowing users to prioritize particular WLANs.

2N/A

2N/AEvents

2N/A

2N/AThe event interface allows a client of NWAM (usu. the GUI) to subscribe

2N/Ato a stream of system events such as link and interface up/down,

2N/Awireless scans, and times when NWAM needs the user to be queried.

2N/A

2N/AEvents types are in libnwam.h as NWAM_EVENTS_* and the actual bodies of

2N/Athe events are in nwam_events_msg_t. The semantics of the events have

2N/Abeen simplified so that none require response. They are all

2N/Anotification.

2N/A

2N/ANWAM_EVENTS_SOURCE_{DEAD,BACK} provide notification that the nwam

2N/Adaemon has died or has reappeared. These are synthetic events in that

2N/Athey come from the library and not from nwamd.

2N/A

2N/ANWAM_EVENTS_NO_MAGIC provides notification that nwam couldn't make a

2N/Adetermination of what to do without user guidance. This event provides

2N/Ainformation that can be used to ask the user if he wants to pick a

2N/Awireless lan although in some cases nwam might have no idea what is

2N/Aintended.

2N/A

2N/ANWAM_EVENTS_IF_{STATE,REMOVED} provide information about changes in

2N/Ainterface state or the removal of an interface.

2N/A

2N/ANWAM_EVENTS_LINK_{STATE, REMOVED} provides information about changes in

2N/Alink state or the removal of a link.

2N/A

2N/ANWAM_EVENTS_SCAN_REPORT is used to communicate information about

2N/Awireless networks encountered.

2N/A

2N/APersistent configuration state of entities is stored in project-private

2N/A/etc/nwam configuration files, and the details of storage are hidden

2N/Afrom libnwam consumers.

2N/A

2N/AAccess to entities is attained via an entity-specific handle. These

2N/Ahandles can be obtained via calls to nwam_<entity>_create() or

2N/Anwam_<entity>_read(), and freed (in memory) via calls to nwam_<entity>_free().

2N/Anwam_<entity>_create() will create an in-memory representation of the

2N/Aentity, but that entity will not be stored until nwam_<entity>_commit() is

2N/Acalled. Persistently stored entitites are retrieved via nwam_<entity>_read(),

2N/Acan be modified in-memory, and later persistently committed to storage

2N/Avia nwam_<entity>_commit(). Entities can also be copied with

2N/Anwam_<entity>_copy().

2N/A

2N/AAll changes made after binding a handle to an entity, and prior to calling

2N/Anwam_<entity>_commit() are carried out on the in-memory representation of that

2N/Aentity. nwam_<entity>_commit() updates persistent storage in an all-or-none

2N/Atransactional manner, applying the (possibly changed) in-memory representation

2N/Ato persistent storage atomically.

2N/A

2N/ATo destroy an entity in persistent storage, nwam_<entity>_destroy() is

2N/Aused. This is distinct from nwam_<entity>_free(), which simply frees

2N/Athe in-memory representation - destroy both removes the object from

2N/Apersistent storage, and frees it in memory.

2N/A

2N/ATo summarize, the pattern of interactions with an entity is

2N/A - nwam_<entity>_read(), nwam_<entity>_create() or nwam_<entity>_copy()

2N/A - possibly modify entity properties

2N/A - nwam_<entity>_commit() or nwam_<entity>_destroy()

2N/A - nwam_<entity>_handle_free()

2N/A

2N/AUnless otherwise stated functions in libnwam are MT-safe. The

2N/Aatomicity of _commit() and _read() operations is guaranteed - i.e.

2N/A_commit() is guaranteed to deliver all property changes to persistent

2N/Astorage, while _read() is guaranteed to read a consistent view of the

2N/Aentity (i.e. _read() cannot collide with another entity _commit()ting

2N/Achanges). However, it is possible that a _read() will retrieve an

2N/Aoutdated view of an entity, if after the _read() completes, another

2N/Aentity _commit()s changes. In other words, lost updates are possible.

2N/AThese are permitted given the nature of the entities changing NWAM

2N/Aconfiguration (the CLI and GUI) - it seems intuitive that the most

2N/Arecent update best captures user intent.

2N/A

2N/AEntity validation on an in-memory representation can be explicitly requested

2N/Avia a call to nwam_<entity>_validate(), and individual property values

2N/Acan be validated via nwam_<entity>_validate_prop().

2N/A

2N/AStorage and retrieval of properties is done via nwam_<entity>_set_prop_value()

2N/Aand nwam_<entity>_get_prop_value(). These functions require an nwam_value_t as

2N/Aa parameter, which is created via the nwam_value_create_<type>() family

2N/Aof functions. Data can be retrieved from the nwam_value_t via the

2N/Anwam_value_get_<type>() family of functions. Once a property has been

2N/Aset, the associated nwam_value_t can be immediately freed. For retrieval,

2N/Athe nwam_value_t should be freed when the value(s) are no longer needed.

2N/AA property can also be delete with nwam_<entity>_delete_prop().

2N/A

2N/AImplicit validation occurs as part of the nwam_<entity>_set_prop_value()

2N/Aand nwam_<entity>_commit() functions.

2N/A

2N/AINTERFACES

2N/A

2N/AFor error handling:

2N/A

2N/Aconst char *nwam_strerror(nwam_error_t error);

2N/A

2N/AFor values:

2N/A

2N/AValues can be any of the following types:

2N/A

2N/A NWAM_VALUE_TYPE_BOOLEAN

2N/A NWAM_VALUE_TYPE_UINT64

2N/A NWAM_VALUE_TYPE_INT64

2N/A NWAM_VALUE_TYPE_STRING

2N/A

2N/Aand are possibly multi-valued. An nwam_value_t must be created in order

2N/Ato set property values in libnwam, this is done via the follwing functions:

2N/A

2N/Anwam_error_t nwam_value_create_boolean(boolean_t, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_boolean_array(boolean_t *, uint_t,

2N/A nwam_value_t *);

2N/Anwam_error_t nwam_value_create_uint64(uint64_t, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_uint64_array(uint64_t *, uint_t, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_int64(int64_t, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_int64_array(int64_t *, uint_t, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_string(char *, nwam_value_t *);

2N/Anwam_error_t nwam_value_create_string_array(char **, uint_t, nwam_value_t *);

2N/A

2N/AValues are returned from the _get_prop_value() functions, and the data

2N/Acontained in them can be retrieved via the following functions:

2N/A

2N/Anwam_error_t nwam_value_get_boolean(nwam_value_t, boolean_t *);

2N/Anwam_error_t nwam_value_get_boolean_array(nwam_value_t, boolean_t **, uint_t *);

2N/Anwam_error_t nwam_value_get_uint64(nwam_value_t, uint64_t *);

2N/Anwam_error_t nwam_value_get_uint64_array(nwam_value_t, uint64_t **, uint_t *);

2N/Anwam_error_t nwam_value_get_int64(nwam_value_t, int64_t *);

2N/Anwam_error_t nwam_value_get_int64_array(nwam_value_t, int64_t **, uint_t *);

2N/Anwam_error_t nwam_value_get_string(nwam_value_t, char **);

2N/Anwam_error_t nwam_value_get_string_array(nwam_value_t, char ***, uint_t *);

2N/A

2N/AType and number of value can be retrieved via:

2N/A

2N/Anwam_error_t nwam_value_get_type(nwam_value_t, nwam_value_type_t *);

2N/Anwam_error_t nwam_value_get_numvalues(nwam_value_t, uint_t *);

2N/A

2N/Aand a value is freed using:

2N/A

2N/Avoid nwam_value_free(nwam_value_t);

2N/A

2N/AFor property setting, a typical set of events is to create the value,

2N/Acall the appropriate set_prop_value() function, then free the value (values

2N/Acan be safely freed prior to commit). For retrieval, the type and

2N/Anumber of values usually need to be tested before calling the appropriate

2N/Aretrieval function. In this case, the value should not be freed until

2N/Athe associated data is no longer needed.

2N/A

2N/ANCUs, locations and ENMs can all specify conditional activation conditions.

2N/AInterfaces are provided to convert a conditional activation predicate into

2N/Aa string, or from a string to a parsed set of variables that comprise the

2N/Acondition. Additionally a function is provided to rate the specificity of

2N/Athe activation condition, used to compare location conditions to choose

2N/Athe most specific condition to activate in the case where the activation

2N/Aconditions of multiple locations are specified.

2N/A

2N/Anwam_error_t nwam_condition_to_condition_string(nwam_condition_object_type_t,

2N/A nwam_condition_t, const char *, char **);

2N/Anwam_error_t nwam_condition_string_to_condition(const char *,

2N/A nwam_condition_object_type_t *, nwam_condition_t *, char **);

2N/Anwam_error_t nwam_condition_rate(nwam_condition_object_type_t,

2N/A nwam_condition_t, uint64_t *);

2N/A

2N/AFor NCP entities:

2N/A

2N/Anwam_error_t nwam_ncp_create(const char *name, uint64_t flags,

2N/A nwam_ncp_handle_t *ncp);

2N/Anwam_error_t nwam_ncp_read(const char *name, uint64_t flags,

2N/A nwam_ncp_handle_t *ncp);

2N/Anwam_error_t nwam_ncp_copy(nwam_ncp_handle_t ncp, const char *newname,

2N/A nwam_ncp_handle_t *newncp);

2N/Anwam_error_t nwam_ncp_walk_ncus(nwam_ncp_handle_t ncp,

2N/A int(*cb)(nwam_ncu_handle_t, void *), void *data, uint64_t flags, int *ret);

2N/Anwam_error_t nwam_ncp_get_name(nwam_ncp_handle_t ncp, char **name);

2N/Anwam_error_t nwam_ncp_activate(nwam_ncp_handle_t ncp);

2N/Anwam_error_t nwam_ncp_deactivate(nwam_ncp_handle_t ncp);

2N/Anwam_error_t nwam_ncp_destroy(nwam_ncp_handle_t ncp, uint64_t flags);

2N/Avoid nwam_ncp_free(nwam_ncp_handle_t ncp);

2N/A

2N/ASince the NCP simply consists of the NCUs that comprise it, there is

2N/Ano NCP-specific commit() function - we simply read the NCP, walk the

2N/Aconstituent NCUs, reading, changing or committing them in turn. The

2N/Awalk can be modified via the flags option to only select specific NCU types

2N/Aand classes.

2N/A

2N/AEach NCP has a set of NCUs associated with it, each of which is created/modifed

2N/Ausing the functions below.

2N/A

2N/AFor NCU entities:

2N/A

2N/Anwam_error_t nwam_ncu_create(nwam_ncp_handle_t ncp, const char *name,

2N/A nwam_ncu_type_t type, nwam_ncu_class_t class, nwam_ncu_handle_t *ncu);

2N/Anwam_error_t nwam_ncu_read(nwam_ncp_handle_t ncp, const char *name,

2N/A nwam_ncu_type_t type, uint64_t flags, nwam_ncu_handle_t *ncu);

2N/Anwam_error_t nwam_ncu_copy(nwam_ncu_handle_t ncu, const char *newname,

2N/A nwam_ncu_handle_t *newncu);

2N/Anwam_error_t nwam_ncu_commit(nwam_ncu_handle_t ncu, uint64_t flags);

2N/Anwam_error_t nwam_ncu_destroy(nwam_ncu_handle_t ncu, uint64_t flags);

2N/Anwam_error_t nwam_ncu_free(nwam_ncu_handle_t ncu);

2N/Anwam_error_t nwam_ncu_validate(nwam_ncu_handle_t ncu, const char **errprop);

2N/Anwam_error_t nwam_ncu_get_prop_value(nwam_ncu_handle_t ncu, const char *prop,

2N/A nwam_value_t *value);

2N/Anwam_error_t nwam_ncu_get_prop_description(const char *prop,

2N/A const char **description);

2N/Anwam_error_t nwam_ncu_delete_prop(nwam_ncu_handle_t ncu, const char *prop);

2N/Anwam_error_t nwam_ncu_set_prop_value(nwam_ncu_handle_t ncu, const char *prop,

2N/A nwam_value_t value);

2N/Anwam_error_t nwam_ncu_get_name(nwam_ncu_handle_t ncu, char **name);

2N/Anwam_error_t nwam_ncu_set_name(nwam_ncu_handle_t ncu, const char *name);

2N/Anwam_error_t nwam_ncu_get_read_only(nwam_ncu_handle_t ncu, boolean_t *readp);

2N/Anwam_error_t nwam_ncu_validate_prop(nwam_ncu_handle_t ncu, const char *prop,

2N/A nwam_value_t value);

2N/Anwam_error_t nwam_ncu_walk_props(nwam_ncu_handle_t ncu,

2N/A int (*func)(void *, const char *, nwam_value_t), void *data,

2N/A uint64_t flags, int *ret);

2N/Anwam_error_t nwam_ncu_prop_get_type(const char *prop,

2N/A nwam_value_type_t *value_type);

2N/Anwam_error_t nwam_ncu_get_ncp(nwam_ncu_handle_t ncu, nwam_ncp_handle_t *ncp);

2N/A

2N/ANCUs are manipulated via an nwam_ncu_handle_t.

2N/A

2N/AEach NCU has a set of properties associated with it. Each property can

2N/Ahave mutiple values associated with it, which are set or retrieved via an

2N/Anwam_value_t. The approach is similar to that used for Locations, with

2N/Athe difference that read/commit/destroy must specify an NCP. Only two

2N/ANCPs are supported at present, the automatic and user NCPs. Modification

2N/Aof the former is restricted to nwamd itself, and attempts to modify

2N/Athe automatic NCP's consituent NCUs will result in an NWAM_ENTITY_READ_ONLY

2N/Aerror.

2N/A

2N/AFor Location entities:

2N/A

2N/Anwam_error_t nwam_loc_create(const char *name, nwam_loc_handle_t *loc);

2N/Anwam_error_t nwam_loc_read(const char *name, uint64_t flags,

2N/A nwam_loc_handle_t *loc);

2N/Anwam_error_t nwam_loc_copy(nwam_loc_handle_t loc, const char *newname,

2N/A nwam_loc_handle_t *newloc);

2N/Anwam_error_t nwam_walk_locs(int (*cb)(nwam_loc_handle_t loc, void *arg),

2N/A void *arg, uint64_t flags, int *cbretp);

2N/Anwam_error_t nwam_loc_commit(nwam_loc_handle_t loc, uint64_t flags);

2N/Anwam_error_t nwam_loc_destroy(nwam_loc_handle_t loc, uint64_t flags);

2N/Avoid nwam_loc_free(nwam_loc_handle_t loc);

2N/Anwam_error_t nwam_loc_validate(nwam_loc_handle_t loc, const char *errprop);

2N/Anwam_error_t nwam_loc_walk_props(nwam_loc_handle_t loc,

2N/A int (*cb)(const char *, nwam_value_t **, void *),

2N/A void *arg, uint64_t flags, int *cbret);

2N/Anwam_error_t nwam_loc_validate_prop(nwam_loc_handle_t loc,

2N/A const char *prop, nwam_value_t value);

2N/Anwam_error_t nwam_loc_prop_get_type(const char *prop,

2N/A nwam_value_type_t *value_type);

2N/Anwam_error_t nwam_loc_get_prop_value(nwam_loc_handle_t loc, const char *prop,

2N/A nwam_value_t *value);

2N/Anwam_error_t nwam_loc_get_prop_description(const char *prop,

2N/A const char **description);

2N/Anwam_error_t nwam_loc_delete_prop(nwam_loc_handle_t loc, const char *prop);

2N/Anwam_error_t nwam_loc_set_prop_value(nwam_loc_handle_t loc, const char *prop,

2N/A nwam_value_t value);

2N/Anwam_error_t nwam_loc_get_name(nwam_loc_handle_t loc, char **name);

2N/Anwam_error_t nwam_loc_set_name(nwam_loc_handle_t loc, const char *name);

2N/Anwam_error_t nwam_loc_activate(nwam_loc_handle_t loc);

2N/Anwam_error_t nwam_loc_deactivate(nwam_loc_handle_t loc);

2N/A

2N/ALocations are manipulated via an nwam_loc_handle_t.

2N/A

2N/AA loc handle maps to an in-memory representation of a location; operations via

2N/Athis interface manipulate the in-memory data. In-memory data is read from

2N/Apersistent storage via the nwam_loc_read() or nwam_walk_locs() functions, and

2N/Awritten out to persistent storage via the nwam_loc_commit() function. A loc

2N/Amay be permanently removed from persistent storage with the nwam_loc_destroy()

2N/Afunction. Interactions with persistent storage will be nonblocking by default;

2N/Athis behavior can be changed by passing the NWAM_FLAG_BLOCKING in the flags

2N/Aparameter.

2N/A

2N/AA typical sequence would be to allocate a loc handle, either by creating a

2N/Anew loc (nwam_loc_create()) or by reading one from persistent storage (nwam_

2N/Aloc_read() or nwam_walk_locs()). The various set/get/walk/validate/(de)activate

2N/Afunctions may then be used to manipulate the loc; any changes made may then be

2N/Acommitted to persistent storage via nwam_loc_commit(). A call to nwam_loc_

2N/Afree() is required to release in-memory resources associated with the handle.

2N/A

2N/AThe flags parameter in the walk functions allows filtering of the locs that

2N/Awill be examined, depending on the state of each loc. Passing in

2N/ANWAM_FLAG_STATE_ALL will examine all locs; specific state flags are defined

2N/Ain <libnwam.h>.

2N/A

2N/ALike NCUs, each loc has a set of properties associated with it. Loc properties

2N/Aare stored in nwam_value_t structures; see the Values section for how to store/

2N/Aretrieve using these.

2N/A

2N/AFor ENM entities:

2N/A

2N/Anwam_error_t nwam_enm_create(const char *name, const char *fmri,

2N/A nwam_enm_handle_t *enm);

2N/Anwam_error_t nwam_enm_read(const char *name, uint64_t flags,

2N/A nwam_enm_handle_t *enm);

2N/Anwam_error_t nwam_enm_copy(nwam_enm_handle_t enm, const char *newname,

2N/A nwam_enm_handle_t *newenm);

2N/Anwam_error_t nwam_walk_enms(int (*cb)(nwam_enm_handle_t enm, void *arg),

2N/A void *arg, uint64_t flags, int *cbretp);

2N/Anwam_error_t nwam_enm_commit(nwam_enm_handle_t enm, uint64_t flags);

2N/Anwam_error_t nwam_enm_destroy(nwam_enm_handle_t enm, uint64_t flags);

2N/Avoid nwam_enm_free(nwam_enm_handle_t enm);

2N/Anwam_error_t nwam_enm_validate(nwam_enm_handle_t enm, const char *errprop);

2N/Anwam_error_t nwam_enm_walk_props(nwam_enm_handle_t enm,

2N/A int (*cb)(const char *, nwam_value_t **, void *),

2N/A void *arg, uint64_t flags, int *cbret);

2N/Anwam_error_t nwam_enm_validate_prop(nwam_enm_handle_t enm,

2N/A const char *prop, nwam_value_t value);

2N/Anwam_error_t nwam_enm_prop_get_type(const char *prop,

2N/A nwam_value_type_t *value_type);

2N/Anwam_error_t nwam_enm_get_prop_value(nwam_enm_handle_t enm, const char *prop,

2N/A nwam_value_t *value);

2N/Anwam_error_t nwam_enm_get_prop_description(const char *prop,

2N/A const char **description);

2N/Anwam_error_t nwam_enm_delete_prop(nwam_enm_handle_t enm, const char *prop);

2N/Anwam_error_t nwam_enm_set_prop_value(nwam_enm_handle_t enm, const char *prop,

2N/A nwam_value_t value);

2N/Anwam_error_t nwam_enm_get_name(nwam_enm_handle_t enm, char **name);

2N/Anwam_error_t nwam_enm_set_name(nwam_enm_handle_t enm, const char *name);

2N/Anwam_error_t nwam_enm_activate(nwam_enm_handle_t enm);

2N/Anwam_error_t nwam_enm_deactivate(nwam_enm_handle_t enm);

2N/A

2N/AENMs are manipulated via an nwam_enm_handle_t, in a similar manner to

2N/ANCUs and locations.

2N/A

2N/AThe flags parameter in the walk functions allows filtering of the ENMs that

2N/Awill be examined, depending on the state of each ENM. Passing in

2N/ANWAM_FLAG_STATE_ALL will examine all ENMs; specific state flags are defined

2N/Ain <libnwam.h>.

2N/A

2N/ALike NCUs, each ENM has a set of properties associated with it. ENM properties

2N/Aare all single valued, though the interface is aligned with the NCU interface,

2N/Awhich allows for multi-valued properties. ENM properties are stored in

2N/Anwam_value_t structures; see the Values section for how to store/retrieve

2N/Ausing these.

2N/A

2N/AFor known WLAN entities:

2N/A

2N/Anwam_error_t nwam_known_wlan_create(const char *name,

2N/A nwam_known_wlan_handle_t *kwhp);

2N/Anwam_error_t nwam_known_wlan_read(const char *name, uint64_t flags,

2N/A nwam_known_wlan_handle_t *kwhp);

2N/Anwam_error_t nwam_known_wlan_copy(nwam_known_wlan_handle_t kwh,

2N/A const char *newname, nwam_known_wlan_handle_t *newkwh);

2N/Anwam_error_t nwam_walk_known_wlans(int (*cb)(nwam_known_wlan_handle_t, void *),

2N/A void *arg, uint64_t flags, int *cbretp);

2N/Anwam_error_t nwam_known_wlan_commit(nwam_known_wlan_handle_t kwh,

2N/A uint64_t flags);

2N/Anwam_error_t nwam_known_wlan_destroy(nwam_known_wlan_handle_t kwh,

2N/A uint64_t flags);

2N/Avoid nwam_known_wlan_free(nwam_known_wlan_handle_t kwh);

2N/Anwam_error_t nwam_known_wlan_validate(nwam_known_wlan_handle_t kwh,

2N/A const char *errprop);

2N/Anwam_error_t nwam_known_wlan_walk_props(nwam_known_wlan_handle_t kwh,

2N/A int (*cb)(const char *, nwam_value_t **, void *),

2N/A void *arg, uint64_t flags, int *cbret);

2N/Anwam_error_t nwam_known_wlan_validate_prop(nwam_known_wlan_handle_t kwh,

2N/A const char *prop, nwam_value_t value);

2N/Anwam_error_t nwam_known_wlan_prop_get_type(const char *prop,

2N/A nwam_value_type_t *value_type);

2N/Anwam_error_t nwam_known_wlan_get_prop_value(nwam_known_wlan_handle_t kwh,

2N/A const char *prop, nwam_value_t *value);

2N/Anwam_error_t nwam_known_wlan_get_prop_description(const char *prop,

2N/A const char **description);

2N/Anwam_error_t nwam_known_wlan_delete_prop(nwam_known_wlan_handle_t kwh,

2N/A const char *prop);

2N/Anwam_error_t nwam_known_wlan_set_prop_value(nwam_known_wlan_handle_t kwh,

2N/A const char *prop, nwam_value_t value);

2N/Anwam_error_t nwam_known_wlan_get_name(nwam_known_wlan_handle_t kwh,

2N/A char **name);

2N/Anwam_error_t nwam_known_wlan_set_name(nwam_known_wlan_handle_t kwh,

2N/A const char *name);

2N/Anwam_error_t nwam_known_wlan_add_to_known_wlan(const char *essid,

2N/A const char *bssid);

2N/Anwam_error_t nwam_known_wlan_remove_from_known_wlan(const char *essid,

2N/A const char *bssid);

2N/A

2N/AKnown WLANs are manipulated via an nwam_known_wlan_handle_t, in a similar

2N/Amanner to NCUs, locations and ENMs.

2N/A

2N/ALike ENMs, each known WLAN has a set of properties associated with it.

2N/AKnown WLAN properties are stored in nwam_value_t structures; see the Values

2N/Asection for how to store/retrieve using these.

2N/A

2N/AFor WLANs, we define a set of functions to ask nwamd to initiate a scan,

2N/Aselect a WLAN (and possibly add it to the known WLAN list) or set a WLAN

2N/Akey:

2N/A

2N/A

2N/Aextern nwam_error_t nwam_wlan_scan(const char *linkname);

2N/Aextern nwam_error_t nwam_wlan_get_scan_results(const char *linkname,

2N/A uint_t *num_resultsp, nwam_wlan_t **wlansp);

2N/Aextern nwam_error_t nwam_wlan_select(const char *linkname,

2N/A const char *essid, const char *bssid, boolean_t add_to_known_wlans);

2N/Aextern nwam_error_t nwam_wlan_set_key(const char *linkname, const char *essid,

2N/A const char *bssid, uint32_t security_mode, uint_t keyslot, const char *key);

2N/A

2N/AFor Events:

2N/A

2N/Atypedef struct nwam_event {

2N/A uint32_t type;

2N/A

2N/A union {

2N/A struct {

2N/A nwam_object_type_t object_type;

2N/A char name[NWAM_MAX_NAME_LEN];

2N/A nwam_action_t action;

2N/A } object_action;

2N/A

2N/A

2N/A ... and so on for each message ...

2N/A

2N/A } data;

2N/A

2N/A} *nwam_event_t;

2N/A

2N/Atype comes from the set of constants NWAM_EVENT_TYPE_*.

2N/A

2N/ARegistration and cancellation of registration are done via

2N/A_init and _fini functions:

2N/A

2N/Aextern nwam_error_t nwam_events_init(void);

2N/Aextern void nwam_events_fini(void);

2N/A

2N/AEvents can then be recieved by calling nwam_event_wait():

2N/A

2N/Aextern nwam_error_t nwam_event_wait(nwam_event_t *);

2N/A

2N/AThe event can then be processed, and free via nwam_event_free();

2N/A

2N/ARETURN VALUES

2N/A

2N/AAll functions return an nwam_error_t if they return an error. Possible

2N/Aerrors are:

2N/A

2N/A NWAM_SUCCESS No error occured

2N/A NWAM_LIST_END End of list

2N/A NWAM_INVALID_HANDLE Entity handle is invalid

2N/A NWAM_HANDLE_UNBOUND Handle not bound to entity

2N/A NWAM_INVALID_ARG Argument is invalid

2N/A NWAM_PERMISSION_DENIED Insufficient privileges for action

2N/A NWAM_NO_MEMORY Out of memory

2N/A NWAM_ENTITY_EXISTS Entity already exists

2N/A NWAM_ENTITY_IN_USE Another user is interacting with entity

2N/A NWAM_ENTITY_COMMITTED Entity already committed

2N/A NWAM_ENTITY_NOT_FOUND Entity not found

2N/A NWAM_ENTITY_TYPE_MISMATCH Entity value-type mismatch

2N/A NWAM_ENTITY_INVALID Validation of entity failed

2N/A NWAM_ENTITY_INVALID_MEMBER Entity member invalid

2N/A NWAM_ENTITY_INVALID_VALUE Validation of entity value failed

2N/A NWAM_ENTITY_NO_VALUE No value associated with entity

2N/A NWAM_ENTITY_MULTIPLE_VALUES, Multiple values for entity

2N/A NWAM_ENTITY_READ_ONLY, Entity is marked read only

2N/A NWAM_WALK_HALTED, Callback function returned nonzero

2N/A NWAM_ERROR_BIND, Could not bind to backend

2N/A NWAM_ERROR_BACKEND_INIT, Could not initialize backend

2N/A NWAM_ERROR_INTERNAL Internal error

2N/A

2N/AFILES

2N/A /lib/libnwam.so.1 shared object

2N/A

2N/AATTRIBUTES

2N/A

2N/A

2N/ASEE ALSO

2N/A nwamd(1M), netcfg(1M), netadm(1M)