libdlwlan.h: WLAN Administration Interface
------------------------------------------

1. Core APIs
------------
1.1. dladm_wlan_scan()
----------------------
dladm_status_t
dladm_wlan_scan(const char *link, void *arg,
    boolean_t (*func)(void *, dladm_wlan_attr_t *));

Description:
dladm_wlan_scan() will initiate a scan on the specified link. For each WLAN
discovered, func() will be called with arguments arg and a pointer to
the WLAN's attributes. If func() returns B_FALSE, dladm_wlan_scan() will
terminate; otherwise, it will continue until all discovered WLANs are
encountered.

| If func() is NULL, dladm_wlan_scan() will return immediately after
| initiating the scan.

The attributes structure contains:
typedef struct dladm_wlan_wlan_attr {
	uint_t			wa_valid;
	dladm_wlan_essid_t	wa_essid;
	dladm_wlan_bssid_t	wa_bssid;
	dladm_wlan_secmode_t	wa_secmode;
	dladm_wlan_strength_t	wa_strength;
	dladm_wlan_mode_t	wa_mode;
	dladm_wlan_speed_t	wa_speed;
	dladm_wlan_auth_t	wa_auth;
	dladm_wlan_bsstype_t	wa_bsstype;
	dladm_wlan_channel_t	wa_channel;
} dladm_wlan_attr_t;

wa_valid is a bitfield used for indicating the validity of each attribute.
wa_valid may have 0 or more of the following bits set:
	DLADM_WLAN_ATTR_ESSID
	DLADM_WLAN_ATTR_BSSID
	DLADM_WLAN_ATTR_ENCR
	DLADM_WLAN_ATTR_STRENGTH
	DLADM_WLAN_ATTR_MODE
	DLADM_WLAN_ATTR_SPEED
	DLADM_WLAN_ATTR_AUTH
	DLADM_WLAN_ATTR_BSSTYPE
	DLADM_WLAN_ATTR_CHANNEL

Return values:
DLADM_STATUS_OK is returned if the scan succeeds (regardless of whether
or not WLANs are discovered).

DLADM_STATUS_BADARG is returned if the specified link is NULL or is
not a wireless link.

DLADM_STATUS_LINKINVAL is returned if the specified link is invalid.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_FAILED is returned if a scan cannot be initiated due to a
hardware related issue.


1.2. dladm_wlan_connect()
-------------------------
dladm_status_t
dladm_wlan_connect(const char *link, dladm_wlan_attr_t *attrp,
    int timeout, void *keys, uint_t key_count, uint_t flags);

Description:
dladm_wlan_connect() will first initiate a scan on the specified link.
The discovered WLANs will then be maintained internally as a list of
dladm_wlan_attr_t. Next, if attr is non-NULL and the attr->wa_valid
bitfield contains one or more bits set (see 1.1), dladm_wlan_connect()
will walk its WLAN list and remove the ones which do not have the
attributes specified in attr. If attr is NULL, the WLAN list will be
left unfiltered.

The WLANs remaining on the list will be prioritized, first by signal
strength and then by maximum speed. A connect will be attempted on each
WLAN in order of priority, stopping when a connect succeeds or when
there are no more WLANs.  The timeout argument indicates the time to
wait before aborting a connect attempt. Keys will be made use of during
connect if the chosen security mode requires keys, keys are specified
(i.e. keys != NULL), and the target WLAN has the chosen security mode
enabled.

The following flags are supported:
DLADM_WLAN_CONNECT_CREATEIBSS:
If this flag is set and the bsstype attribute attr->wa_bsstype is
set to DLADM_WLAN_BSSTYPE_IBSS:
-If the essid attribute attr->wa_essid is specified and there exists
 no WLAN on the discovered WLAN with this particular essid, an adhoc
 WLAN with essid equal to attr->wa_essid will be created.
-If the essid attribute is not specified, an adhoc WLAN with a random
 essid will be created, irrespective of which WLANs are available.

DLADM_WLAN_CONNECT_NOSCAN:
If this flag is set, dladm_wlan_connect() will, without doing a scan,
attempt to associate with a WLAN with attributes most closely matching
attributes specified in attrp.

Return values:
DLADM_STATUS_OK is returned if connect has succeeded on one of the
discovered WLANs or if an adhoc WLAN has been created.

DLADM_STATUS_BADARG is returned if any of the specified arguments
contain invalid values (e.g.illegal values in attr, keys == NULL but
key_count > 0)

DLADM_STATUS_LINKINVAL is returned if the specified link is invalid.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_ISCONN is returned if the specified link is already connected
to a WLAN.

DLADM_STATUS_NOTFOUND is returned if no non-hidden WLANs are within range.

DLADM_STATUS_FAILED is returned if a scan or connect cannot be initiated
due to a hardware related issue.


1.3. dladm_wlan_disconnect()
----------------------------
dladm_status_t
dladm_wlan_disconnect(const char *link);

Description:
dladm_wlan_disconnect() will initiate a disconnect on the specified link.

Return values:
DLADM_STATUS_OK is returned if disconnect succeeds.

DLADM_STATUS_LINKINVAL is returned if the specified link is invalid.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_NOTCONN is returned if the specified link isn't connected
to any WLAN.

DLADM_STATUS_FAILED is returned if the disconnect cannot succeed due to
a hardware issue.


1.4. dladm_wlan_get_link_attr()
-------------------------------
dladm_status_t
dladm_wlan_get_link_attr(const char *link, dladm_wlan_link_attr_t *attrp);

Description:
dladm_wlan_get_link_attr() queries the specified link for its attributes and
fills in the following structure:

typedef struct dladm_wlan_link_attr {
	uint_t			la_valid;
	dladm_wlan_linkstatus_t	la_status;
	dladm_wlan_attr_t	la_wlan_attr;
} dladm_wlan_link_attr_t;

la_valid is a bitfield which specifies which attributes within this
structure are valid. la_valid may have 0 or more of the following bits set:
	DLADM_WLAN_LINKATTR_STATUS
	DLADM_WLAN_LINKATTR_WLAN

| The wa_essid and wa_bssid attributes of la_wlan_attr are always valid
| upon successful return.  Other la_wlan_attr attributes are only valid
| when la_status is DLADM_WLAN_LINKSTATUS_CONNECTED.

Return values:
DLADM_STATUS_OK is returned if attributes are successfully obtained from
the specified link.

DLADM_STATUS_LINKINVAL is returned if the specified link is invalid.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_BADARG is returned if link or attr is NULL or if link is not
a wireless link.

DLADM_STATUS_FAILED is returned if the link attributes cannot be retrieved
due to a hardware issue.


1.5. dladm_wlan_walk()
----------------------
dladm_status_t
dladm_wlan_walk(void *arg, boolean_t (*func)(void *, const char *));

Description:
For each wireless link in the system, func() will be called with arguments
arg and the link name. If func() returns B_FALSE, dladm_wlan_walk() will
terminate; otherwise, it will continue until all wireless links are
encountered.

Return values:
DLADM_STATUS_OK is returned if the operation is successful.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.


1.6. dladm_wlan_is_valid()
--------------------------
boolean_t
dladm_wlan_is_valid(const char *link);

Description:
Determines if the specified link is a valid wireless link.

Return Values:
B_TRUE if link is valid.
B_FALSE if link is invalid.


2. Link property APIs
---------------------
2.1 dladm_wlan_set_prop()
-------------------------
dladm_status_t
dladm_wlan_set_prop(const char *link, const char *prop_name, char **prop_val,
    uint_t val_cnt);

Description:
dladm_wlan_set_prop() assigns the value(s) in the array prop_val (of size
val_cnt) to the property prop_name on the specified link. If prop_val is
NULL, the property prop_name will be set to its default value(s). If
prop_name is NULL, all properties on the specified link will be set to
their default value(s).

The following table shows the supported properties:
name		default value(s)	possible value(s)	read-only
----		----------------	-----------------	---------
radio		on			on, off			yes
speeds		--			1,2,11,54		no
channel		1			1-99			yes
powermode	off			off, fast, maximum	no

Return Values:
DLADM_STATUS_OK is returned if the operation is successful.

DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.

DLADM_STATUS_PROPRDONLY is returned the specified property is read-only.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_NOTSUP is returned if the operation is not supported by the
underlying driver.

DLADM_STATUS_BADVALCNT is returned if the number of values provided is invalid.

DLADM_STATUS_FAILED is returned if the specified property cannot be set to
the desired value(s).


2.2. dladm_wlan_walk_prop()
---------------------------
dladm_status_t
dladm_wlan_walk_prop(const char *link, void *arg,
    boolean_t (*func)(void *, const char *));

Description:
For each property belonging to the specified link, dladm_wlan_walk_prop() will
call func() with arguments arg and the property's name. If func() returns
B_FALSE, dladm_wlan_walk_prop() will terminate; otherwise, it will continue
until all properties are encountered.

Return Values:
DLADM_STATUS_OK is returned always.


2.3. dladm_wlan_get_prop()
--------------------------
dladm_status_t
dladm_wlan_get_prop(const char *link, dladm_wlan_prop_type_t type,
    const char *prop_name, char **prop_val, uint_t *val_cntp);

Description:
dladm_wlan_get_prop() obtains the specified property value(s) from the
specified link. type can be one of DLADM_WLAN_PROP_VAL_CURRENT,
DLADM_WLAN_PROP_VAL_DEFAULT, or DLADM_WLAN_PROP_VAL_MODIFIABLE. prop_name
specifies the name of the property whose value(s) is/are to be retrieved.
prop_val is a string array of size *val_cntp used for storing the retrieved
property value(s). If no error occurs, dladm_wlan_get_prop() will set
*val_cntp to the actual number of values retrieved upon return; otherwise,
*val_cntp will be left unmodified.

Return Values:
DLADM_STATUS_OK is returned if the operation is successful.

DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.

DLADM_STATUS_TOOSMALL is returned if the array prop_val is not large enough
to hold the retrieved values.

DLADM_STATUS_LINKINVAL is returned if the specified link is invalid.

DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred.

DLADM_STATUS_NOTSUP is returned if the operation is not supported by the
underlying driver.

DLADM_STATUS_FAILED is returned if the specified property value(s) cannot
be retrieved.


3. String Conversion APIs
-------------------------
3.1 Datatype to string
----------------------
The following routines convert wladm datatypes to strings. The 2nd argument
is the buffer to which the converted string will be written. This buffer
will be returned to the caller. Its size must be at least DLADM_WLAN_STRSIZE
bytes.

const char *dladm_wlan_essid2str(dladm_wlan_essid_t *, char *);
const char *dladm_wlan_bssid2str(dladm_wlan_bssid_t *, char *);
const char *dladm_wlan_secmode2str(dladm_wlan_secmode_t *, char *);
const char *dladm_wlan_strength2str(dladm_wlan_strength_t *, char *);
const char *dladm_wlan_mode2str(dladm_wlan_mode_t *, char *);
const char *dladm_wlan_speed2str(dladm_wlan_speed_t *, char *);
const char *dladm_wlan_auth2str(dladm_wlan_auth_t *, char *);
const char *dladm_wlan_bsstype2str(dladm_wlan_bsstype_t *, char *);
const char *dladm_wlan_linkstatus2str(dladm_wlan_linkstatus_t *, char *);
const char *dladm_wlan_status2str(dladm_status_t, char *);

3.2 String to datatype
----------------------
The following routines convert strings to wladm datatypes. DLADM_STATUS_OK
is returned if conversion is successful. DLADM_STATUS_BADARG is returned if
conversion is unsuccessful.

dladm_status_t dladm_wlan_str2essid(const char *, dladm_wlan_essid_t *);
dladm_status_t dladm_wlan_str2bssid(const char *, dladm_wlan_bssid_t *);
dladm_status_t dladm_wlan_str2secmode(const char *, dladm_wlan_secmode_t *);
dladm_status_t dladm_wlan_str2strength(const char *, dladm_wlan_strength_t *);
dladm_status_t dladm_wlan_str2mode(const char *, dladm_wlan_mode_t *);
dladm_status_t dladm_wlan_str2speed(const char *, dladm_wlan_speed_t *);
dladm_status_t dladm_wlan_str2auth(const char *, dladm_wlan_auth_t *);
dladm_status_t dladm_wlan_str2bsstype(const char *, dladm_wlan_bsstype_t *);
dladm_status_t dladm_wlan_str2linkstatus(const char *,
    dladm_wlan_linkstatus_t *);


| 4. WPA Enhancements APIs
| ------------------------
|
| 4.1. dladm_wlan_wpa_set_wpa()
| -----------------------------

| dladm_status_t
| dladm_wlan_wpa_set_wpa(const char *link, boolean_t on)
| 
| Description:
| Enabled or disables WPA in the driver for a specified WiFi link.
| If on is B_TRUE, the WPA service is enabled.
| If on is B_FALSE, the WPA service is disabled.
| 
| dladm_wlan_wpa_set_wpa() tells the driver when the WPA daemon is willing
| to handle incoming WPA traffic on a particular link (e.g., so that the
| driver will make door upcalls).  The WPA daemon calls this API whenever a
| WPA-secured link is connected or disconnected.  The behavior of other
| WPA APIs are unaffected by enabling or disabling WPA.
| 
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
| 
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the specified value cannot be set in
| the driver.
| 
| 4.2. dladm_wlan_wpa_set_ie()
| ----------------------------
| dladm_status_t
| dladm_wlan_wpa_set_ie(const char *link, uint8_t *wpa_ie, uint_t wpa_ie_len)
| 
| Description:
| Sets the WPA/RSN information in the driver for a specified WiFi link.
| The WPA/RSN information is provided by the byte array wpa_ie, which
| is wpa_ie_len bytes long and whose format is specified by the IEEE802.11i
| standard [section 7, 7.3.2.25 RSN information element].
| 
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
|
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the specified value cannot be set to
| the driver.
| 
| 4.3. dladm_wlan_wpa_del_key()
| -----------------------------
| dladm_status_t
| dladm_wlan_wpa_del_key(const char *link, uint_t key_idx,
|     const dladm_wlan_bssid_t *addr)
| 
| Description:
| Deletes specific WPA keys in the driver for a specified WiFi link.
| 
| The index of the key to delete is specified by key_idx; the peer
| hardware address related to that key is specifed by addr.  (This
| address is required by some WiFi chipsets using hardware encryption
| to remove the key from hardware.)
| 
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
|
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the key cannot be removed.
| 
| 4.4. dladm_wlan_wpa_set_key()
| -----------------------------
| dladm_status_t
| dladm_wlan_wpa_set_key(const char *link, dladm_wlan_cipher_t cipher,
|     const dladm_wlan_bssid_t *addr, boolean_t set_tx, uint64_t seq,
|     uint_t key_idx, uint8_t *key, uint_t key_len)
| 
| typedef enum {
| 	DLADM_WLAN_CIPHER_WEP		= 0,
| 	DLADM_WLAN_CIPHER_TKIP,
| 	DLADM_WLAN_CIPHER_AES_OCB,
| 	DLADM_WLAN_CIPHER_AES_CCM,
| 	DLADM_WLAN_CIPHER_CKIP,
| 	DLADM_WLAN_CIPHER_NONE
| } dladm_wlan_cipher_t;
|
| Description:
| Sets the dynamically-generated WPA keys (unicast/multicast/broadcast) in
| the driver for a specified WiFi link.
| 
| The index of the key to set is specified by key_idx.  The cipher to use
| is specified by cipher.  If set_tx is B_TRUE, the key is used for both
| transmit and receive; otherwise, it is only used for receive (e.g., for
| receiving broadcast/multicast packets from APs).  The initial transfer
| sequence number is specified by seq, whose value is determined by
| negotiation between the WPA daemon an APs.
| 
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
|
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the key cannot be set.
| 
| 4.5. dladm_wlan_wpa_set_mlme()
| ------------------------------
| dladm_status_t
| dladm_wlan_wpa_set_mlme(const char *link, dladm_wlan_mlme_op_t op,
|     dladm_wlan_reason_t reason, const dladm_wlan_bssid_t *bssid)
| 
| typedef enum {
| 	DLADM_WLAN_MLME_ASSOC  = 1,		/* associate station */
| 	DLADM_WLAN_MLME_DISASSOC = 2		/* disassociate station */
| } dladm_wlan_mlme_op_t;
| 
| typedef enum {
| 	DLADM_WLAN_REASON_UNSPECIFIED = 1,
| 	DLADM_WLAN_REASON_DISASSOC_LEAVING = 5
| } dladm_wlan_reason_t;
|
| Description:
| Sets the WPA associate/disassociate information in the driver for
| a specified WiFi link.
|
| If op is DLADM_WLAN_MLME_DISASSOC, the bssid will be ignored, and the reason
| must be DLADM_WLAN_REASON_DISASSOC_LEAVING.  If op is DLADM_WLAN_MLME_ASSOC,
| the bssid indicates the peer to associate with, and the reason is ignored.
| The numeric values correspond to values in the WPA specification.
|
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
|
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the mlme value cannot be set.
| 
| 4.6. dladm_wlan_wpa_get_sr()
| ----------------------------
| dladm_status_t
| dladm_wlan_wpa_get_sr(const char *link, dladm_wlan_ess_t *es, uint_t escnt,
|     uint_t *estot)
| 
| typedef struct dladm_wlan_ess {
| 	dladm_wlan_bssid_t	we_bssid;
| 	dladm_wlan_essid_t	we_ssid;
| 	uint_t			we_ssid_len;
| 	uint8_t			we_wpa_ie[DLADM_WLAN_MAX_WPA_IE_LEN];
| 	uint_t			we_wpa_ie_len;
| 	int			we_freq;	/* AP frequency in MHz */
| } dladm_wlan_ess_t;
|
| Description:
| Gets the WPA/RSN information from WPA-mode APs on a WiFi link.

| The es argument points to zero or more dladm_wlan_ess_t structures for
| dladm_wlan_wpa_get_sr() to fill in.  The escnt argument indicates how
| many structures were provided.  Upon return, up to escnt structures will
| be filled in, and the estot argument will contain the total number of
| dladm_wlan_ess_t structures for the specified link.
| 
| The caller can find out the number of es's on a link at any moment in
| time by doing:
|     dladm_wlan_wpa_get_sr(link, NULL, 0, &estot);
| 
| Return Values:
| DLADM_STATUS_OK is returned if the operation is successful.
| 
| DLADM_STATUS_NOTSUP is returned if the driver does not support WPA.
|
| DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid.
| 
| DLADM_STATUS_FAILED is returned if the specific value cannot be retrieved.