libwladm: WLAN Administration Interface ---------------------------------------- 1. Core APIs ------------ 1.1. wladm_scan() ----------------- wladm_status_t wladm_scan(const char *link, void *arg, boolean_t (*func)(void *, wladm_wlan_attr_t *)); Description: wladm_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, wladm_scan() will terminate; otherwise, it will continue until all discovered WLANs are encountered. The attributes structure contains: typedef struct wladm_wlan_attr { uint_t wa_valid; wladm_essid_t wa_essid; wladm_bssid_t wa_bssid; wladm_secmode_t wa_secmode; wladm_strength_t wa_strength; wladm_mode_t wa_mode; wladm_speed_t wa_speed; wladm_auth_t wa_auth; wladm_bsstype_t wa_bsstype; } wladm_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: WLADM_WLAN_ATTR_ESSID WLADM_WLAN_ATTR_BSSID WLADM_WLAN_ATTR_ENCR WLADM_WLAN_ATTR_STRENGTH WLADM_WLAN_ATTR_MODE WLADM_WLAN_ATTR_SPEED WLADM_WLAN_ATTR_AUTH WLADM_WLAN_ATTR_BSSTYPE Return values: WLADM_STATUS_OK is returned if the scan succeeds (regardless of whether or not WLANs are discovered). WLADM_STATUS_BADARG is returned if the specified link is NULL or is not a wireless link. WLADM_STATUS_FAILED is returned if a scan cannot be initiated due to a hardware related issue. 1.2. wladm_connect() -------------------- wladm_status_t wladm_connect(const char *link, wladm_wlan_attr_t *attrp, int timeout, void **keys, int key_count, uint_t flags); Description: wladm_connect() will first initiate a scan on the specified link. The discovered WLANs will then be maintained internally as a list of wladm_wlan_attr_t. Next, if attr is non-NULL and the attr->wa_valid bitfield contains one or more bits set (see 1.1), wladm_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: WLADM_OPT_CREATEIBSS: If this flag is set and the bsstype attribute attr->wa_bsstype is set to WLADM_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. WLADM_OPT_NOSCAN: If this flag is set, wladm_connect() will, without doing a scan, attempt to associate with a WLAN with attributes most closely matching attributes specified in attrp. Return values: WLADM_STATUS_OK is returned if connect has succeeded on one of the discovered WLANs or if an adhoc WLAN has been created. WLADM_STATUS_BADARG if any of the specified arguments contain invalid values (e.g. link is NULL or is not a wireless link, illegal values in attr, keys == NULL but key_count > 0) WLADM_STATUS_FAILED is returned if a scan or connect cannot be initiated due to a hardware related issue. 1.3. wladm_disconnect() ---------------------------- wladm_status_t wladm_disconnect(const char *link); Description: wladm_disconnect() will initiate a disconnect on the specified link. Return values: WLADM_STATUS_OK is returned if disconnect succeeds. WLADM_STATUS_BADARG is returned if link is NULL or is not a wireless link. WLADM_STATUS_NOTCONN is returned if the specified link isn't connected to any WLAN. 1.4. wladm_get_link_attr() -------------------------- wladm_status_t wladm_get_link_attr(const char *link, wladm_link_attr_t *attrp); Description: wladm_get_link_attr() queries the specified link for its attributes and fills in the following structure: typedef struct wladm_link_attr { uint_t la_valid; wladm_linkstatus_t la_status; wladm_wlan_attr_t la_wlan_attr; } wladm_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: WLADM_LINK_ATTR_STATUS WLADM_LINK_ATTR_WLAN la_wlan_attr holds the wlan attributes and is only valid when la_status is WLADM_LINKSTATUS_CONNECTED. Return values: WLADM_STATUS_OK is returned if attributes are successfully obtained from the specified link. WLADM_STATUS_BADARG is returned if link or attr is NULL or if link is not a wireless link. 1.5. wladm_walk() ---------------------- void wladm_walk(void *arg, boolean_t (*func)(void *, 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, wladm_walk() will terminate; otherwise, it will continue until all wireless links are encountered. Return values: None 1.6. wladm_is_valid() -------------------- boolean_t wladm_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 wladm_set_prop() -------------------- wladm_status_t wladm_set_prop(const char *link, char *prop_name, char *prop_val); Description: wladm_set_prop() assigns the value prop_val 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. 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 1,2,11,54 no channel 1 1-99 yes powermode off off, fast, maximum no Return Values: WLADM_STATUS_OK is returned if the operation is successful. WLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. WLADM_STATUS_FAILED is returned if the specified property cannot be set to the desired value. 2.2. wladm_walk_prop() ---------------------- void wladm_walk_prop(const char *link, void *arg, boolean_t (*func)(void *, char *)); Description: For each property belonging to the specified link, wladm_walk_prop() will call func() with arguments arg and the property's name. If func() returns B_FALSE, wladm_walk_prop() will terminate; otherwise, it will continue until all properties are encountered. Return Values: None 2.3. wladm_get_prop() --------------------- wladm_status_t wladm_get_prop(const char *link, wladm_prop_type_t type, char *prop_name, char **prop_val, uint_t *val_cnt); Description: wladm_get_prop() obtains the specified property value(s) from the specified link. type can be one of WLADM_PROP_VAL_CURRENT, WLADM_PROP_VAL_DEFAULT, or WLADM_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_cnt used for storing the retrieved property value(s). If no error occurs, wladm_get_prop() will set *val_cnt to the actual number of values retrieved upon return; otherwise, *val_cnt will be left unmodified. Return Values: WLADM_STATUS_OK is returned if the operation is successful. WLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. WLADM_STATUS_TOOSMALL is returned if the array prop_val is not large enough to hold the retrieved values. WLADM_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 WLADM_STRSIZE bytes. const char *wladm_essid2str(wladm_essid_t *, char *); const char *wladm_bssid2str(wladm_bssid_t *, char *); const char *wladm_secmode2str(wladm_secmode_t *, char *); const char *wladm_strength2str(wladm_strength_t *, char *); const char *wladm_mode2str(wladm_mode_t *, char *); const char *wladm_speed2str(wladm_speed_t *, char *); const char *wladm_auth2str(wladm_auth_t *, char *); const char *wladm_bsstype2str(wladm_bsstype_t *, char *); const char *wladm_linkstatus2str(wladm_linkstatus_t *, char *); const char *wladm_status2str(wladm_status_t, char *); 3.2 String to datatype ---------------------- The following routines convert strings to wladm datatypes. WLADM_STATUS_OK is returned if conversion is successful. WLADM_STATUS_BADARG is returned if conversion is unsuccessful. wladm_status_t wladm_str2essid(const char *, wladm_essid_t *); wladm_status_t wladm_str2bssid(const char *, wladm_bssid_t *); wladm_status_t wladm_str2secmode(const char *, wladm_secmode_t *); wladm_status_t wladm_str2strength(const char *, wladm_strength_t *); wladm_status_t wladm_str2mode(const char *, wladm_mode_t *); wladm_status_t wladm_str2speed(const char *, wladm_speed_t *); wladm_status_t wladm_str2auth(const char *, wladm_auth_t *); wladm_status_t wladm_str2bsstype(const char *, wladm_bsstype_t *); wladm_status_t wladm_str2linkstatus(const char *, wladm_linkstatus_t *);