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. 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 la_wlan_attr holds the wlan attributes and is 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 *);