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_channel_t wa_channel; } 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 WLADM_WLAN_ATTR_CHANNEL 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_LINKINVAL is returned if the specified link is invalid. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. 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, uint_t 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 is returned if any of the specified arguments contain invalid values (e.g.illegal values in attr, keys == NULL but key_count > 0) WLADM_STATUS_LINKINVAL is returned if the specified link is invalid. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. WLADM_STATUS_ISCONN is returned if the specified link is already connected to a WLAN. WLADM_STATUS_NOTFOUND is returned if no non-hidden WLANs are within range. 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_LINKINVAL is returned if the specified link is invalid. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. WLADM_STATUS_NOTCONN is returned if the specified link isn't connected to any WLAN. WLADM_STATUS_FAILED is returned if the disconnect cannot succeed due to a hardware issue. 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_LINKINVAL is returned if the specified link is invalid. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. WLADM_STATUS_BADARG is returned if link or attr is NULL or if link is not a wireless link. WLADM_STATUS_FAILED is returned if the link attributes cannot be retrieved due to a hardware issue. 1.5. wladm_walk() ---------------------- wladm_status_t wladm_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, wladm_walk() will terminate; otherwise, it will continue until all wireless links are encountered. Return values: WLADM_STATUS_OK is returned if the operation is successful. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. 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, const char *prop_name, char **prop_val, uint_t val_cnt); Description: wladm_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: 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_PROPRDONLY is returned the specified property is read-only. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. WLADM_STATUS_FAILED is returned if the specified property cannot be set to the desired value(s). 2.2. wladm_walk_prop() ---------------------- wladm_status_t wladm_walk_prop(const char *link, void *arg, boolean_t (*func)(void *, const 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: WLADM_STATUS_OK is returned always. 2.3. wladm_get_prop() --------------------- wladm_status_t wladm_get_prop(const char *link, wladm_prop_type_t type, const char *prop_name, char **prop_val, uint_t *val_cntp); 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_cntp used for storing the retrieved property value(s). If no error occurs, wladm_get_prop() will set *val_cntp to the actual number of values retrieved upon return; otherwise, *val_cntp 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_LINKINVAL is returned if the specified link is invalid. WLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. WLADM_STATUS_NOTSUP is returned if the specified property type is not supported. 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 *);