Declared In
wifi.h
Overview
This chapter describes the constants, data types, and ioctl command codes used to control WiFi connectivity.
WiFi Constants
Channel Constants
Purpose
Define which channels are usable or preferable when multiple channels can be used.
Constants
-
WifiChannel_1
- Channel 1
-
WifiChannel_2
- Channel 2
-
WifiChannel_3
- Channel 3
-
WifiChannel_4
- Channel 4
-
WifiChannel_5
- Channel 5
-
WifiChannel_6
- Channel 6
-
WifiChannel_7
- Channel 7
-
WifiChannel_8
- Channel 8
-
WifiChannel_9
- Channel 9
-
WifiChannel_10
- Channel 10
-
WifiChannel_11
- Channel 11
-
WifiChannel_12
- Channel 12
-
WifiChannel_13
- Channel 13
-
WifiChannel_14
- Channel 14
-
WifiChannel_All
- All channels are allowed.
Connection Status Constants
Purpose
Values that may be used when reporting the association status of the connection.
Constants
-
WifiStatusUndefined
- The current connection state is undefined.
-
WifiStatusDisconnected
- The interface is disconnected.
-
WifiStatusConnecting
- The interface is in the process of attempting to connect.
-
WifiStatusConnectedAccessPoint
- The interface is connected to an access point.
-
WifiStatusConnectedAdHoc
- The interface is connected to an ad-hoc network.
-
WifiStatusOutOfRange
- The interface is connected to an access point that is out of range.
-
WifiStatusConnectionFailed
- The connection attempt has failed.
Event Type Constants
Purpose
Define events that can be delivered to indicate changed conditions on the 802.11 network.
Constants
-
wifiUndefinedEvent
- An event that does not fall under any of the other defined event codes.
-
wifiConnecting
- The station is currently attempting to connect to an access point or ad-hoc network.
-
wifiConnectAccessPoint
- The station has successfully connected to an access point.
-
wifiConnectAdHoc
- The station has successfully connected to an ad-hoc network.
-
wifiConnectFailed
- The interface could not establish a connection. If the reason for the failure can be determined, the reason code will indicate what it is.
-
wifiOutOfRange
- The access point to which the station is connected is out of range. If the station moves back into range of the access point, the interface should return to the
wifiConnectAccessPoint
orwifiConnectAdHoc
state. -
wifiDisconnect
- The station is not connected.
-
wifiScanResults
- The
wifiScanResults
event contains information about a scanned access point or ad-hoc network that has been found. -
wifiSignalStrength
- The interface is reporting updated signal strength information.
-
wifiMediaUnavailable
- The 802.11 hardware has been removed from the device, or has been disabled. The file descriptor for the connection, as well as the device name, are no longer valid.
-
wifiScanFailed
- The 802.11 interface did not find any access points or ad-hoc networks. If the reason for the failure can be determined, the reason code will specify why.
Power Mode Constants
Purpose
Define the power mode for the radio hardware.
Constants
-
WifiPowerOff
- The radio hardware is off.
-
WifiPowerOn
- The radio hardware is on.
-
WifiPowerOnPowerSave
- The radio hardware is in a reduced-power, but still operational, mode.
-
WifiPowerOffHardSwitch
- The radio hardware has been switched off using an external switch.
RSSI Update Mode Constants
Purpose
Constants
-
WifiRSSIUpdateNever
- Disables asynchronous RSSI updates.
-
WifiRSSIUpdateOnDelta
- Specifies that RSSI updates will be sent when the signal strength changes by a given percentage.
-
WifiRSSIUpdatePeriodic
- Specifies that RSSI updates will be generated at a regular interval, which is specified in milliseconds.
-
WifiRSSIUpdateAlways
- Specifies that RSSI update events will be generated every time new signal strength information is available.
Comments
Changing the RSSI update mode allows applications to control how frequently they receive an update. For example, an application designed to test signal strength may want updates constantly, while a typical status bar signal strength monitor would prefer less frequent updates to reduce processor impact.
Scan Result Capability Constants
Purpose
Define bit flags indicating the capabilities of an 802.11 station that responded to a scan. These constants correspond to values defined in section 7.3.1.4 of the IEEE 802.11 Specification.
Constants
-
WifiCapAccessPoint
- The station is an access point.
-
WifiCapAdhocNetwork
- The station can be connected to to form an ad-hoc network.
-
WifiCapPrivacy
- The station supports some form of security protocol. The security protocol may be WEP or WPA.
Comments
WifiCapAccessPoint
and WifiCapAdhocNetwork
are mutually exclusive.
Security Capability Constants
Purpose
Define the security capabilities of the WiFi network.
Constants
Transmission Rate Flags
Purpose
Define the data transmission rate capabilities and preferences of the client hardware and access points.
Constants
-
WifiRate_0Mbit
- 0 Mbps
-
WifiRate_1Mbit
- 1 Mbps
-
WifiRate_2Mbit
- 2 Mbps
-
WifiRate_5_5Mbit
- 5.5 Mbps
-
WifiRate_6Mbit
- 6 Mbps
-
WifiRate_9Mbit
- 9 Mbps
-
WifiRate_11Mbit
- 11 Mbps
-
WifiRate_12Mbit
- 12 Mbps
-
WifiRate_18Mbit
- 18 Mbps
-
WifiRate_22Mbit
- 22 Mbps
-
WifiRate_24Mbit
- 24 Mbps
-
WifiRate_33Mbit
- 33 Mbps
-
WifiRate_36Mbit
- 36 Mbps
-
WifiRate_48Mbit
- 48 Mbps
-
WifiRate_54Mbit
- 54 Mbps
-
WifiRate_All
- Shorthand indicating that all rates are supported.
WEP Flag Constants
Purpose
Define flags used to configure WEP. These constants are only valid when the WiFi encryption mode is set to WifiSecWEP
.
Constants
-
WifiWEPExcludeUnencrpyted
- If this flag is set, unencrypted frames are discarded automatically.
-
WifiWEPIVReuseEvery
- Reuse the initialization vector every frame.
-
WifiWEPIVReuse10
- Reuse the initialization vector every 10 frames.
-
WifiWEPIVReuse50
- Reuse the initialization vector every 50 frames.
-
WifiWEPIVReuse100
- Reuse the initialization vector every 100 frames.
Comments
The initialization vector reuse flags are mutually exclusive.
WiFi Data Structures and Types
WifiEventType Struct
Purpose
Describes a single WiFi event.
Prototype
typedef struct { uint32_t event; union { struct scan{ uint16_t index; uint16_t last; WifiScanResultsType results; } scan; struct connectAccessPoint { char ssid[33]; uint8_t padding[3]; uint8_t bssid[6]; } connectAccessPoint; struct connectAdhoc { char ssid[33]; uint8_t padding[3]; uint8_t bssid[6]; } connectAdhoc; struct connectFailed { status_t reasonCode; } connectFailed; struct scanFailed { status_t reasonCode; } scanFailed; struct signalStrength { uint8_t signal; } signalStrength; } data; } WifiEventType;
Fields
-
scan
- Describes a scan result. This event includes the following additional data:
-
index
- The index within the series of scan results that are being reported.
-
last
- The index of the last element in the series.
-
results
- A description of the scanned station or access point.
-
connectAccessPoint
- Indicates that a connection to an access point has occurred.
-
ssid
- The ESSID of the network to which the connection has been established.
-
bssid
- The 6-byte MAC address of the access point to which the connection has been established.
-
connectAdHoc
- Indicates that a connection to an ad-hoc network has occurred.
-
ssid
- The ESSID of the ad-hoc network to which the connection has been established.
-
bssid
- The 6-byte MAC address of the ad-hoc network to which the connection has been established.
-
connectFailed
- Indicates that a connection attempt has failed.
-
scanFailed
- Indicates that a scan attempt has failed.
-
signalStrength
- Provides updated signal strength information.
WifiScanResultsType Struct
Purpose
Describes an access point or ad-hoc network discovered during a scan.
Prototype
typedef struct { char ssid[33]; int8_t signal; int8_t noise; uint8_t channel; uint8_t bssid[6]; uint16_t ATIMInterval; uint32_t supportedRates; uint32_t responseRate; uint32_t capabilities; uint16_t beaconInterval; uint8_t padding[2]; } WifiScanResultsType;
Fields
-
ssid
- The network name of the scanned access point or ad-hoc network. An SSID is a null terminated ASCII string of 1 to 32 characters in length.
-
signal
- The signal level at which the probe response was received, in dbm.
-
noise
- The average noise level detected while the probe response was being received, in dbm.
-
channel
- The channel number on which the access point or ad-hoc network is operating.
-
bssid
- The MAC address that identifies the access point or station that created the ad-hoc network.
-
ATIMInterval
- The ATIM time window, in units of 100 microseconds. This field is only valid for ad-hoc networks.
-
supportedRates
- A bit mask of all the transmission rates supported by the scanned access point or station. See "Transmission Rate Flags" for the possible values.
-
capabilities
- A bit mask of the capabilities of the scanned access point or station. See "Scan Result Capability Constants" for the possible flag values.
-
beaconInterval
- Specifies how frequently the access point or station transmits a beacon frame. This is an integer value in units of 100 microseconds.
IOCTL Commands
WIOCCONNECT
Purpose
Initiates a connection to an access point or ad-hoc network.
Prototype
struct { uint32_t timeout; char ssid[33]; uint8_t blockTillCompletion; uint8_t pad[2]; } WifiConnectType
Fields
-
→ timeout
- The length of time, in microseconds, for the 802.11 framework to wait before giving up on the connection attempt.
-
→ ssid
- A null-terminated ASCII string containing the SSID of the network to which to connect. The string length must be between one and 32 characters.
-
→ blockTillCompletion
- If
true
, theWIOCONNECT
ioctl will block until the connection has been established or a timeout occurs.
Returns
Comments
Using this command while already connected to a network causes the existing connection to be terminated and a new one to be opened.
See Also
WIOCCREATEIBSS
Purpose
Creates an independent BSS (ad-hoc network).
Prototype
struct { char ssid[33]; uint8_t channel; uint8_t padding[2]; } WifiCreateIBSSType
Fields
-
← ssid
- The name to give the newly created ad-hoc network. The name must be a null terminated ASCII string of 1 to 32 characters in length
-
← channel
- The channel number on which to create the ad-hoc network. This must be one of the channels supported by the radio hardware, as reported by
WIOCGETCHANNEL
. The value must be an integer, rather than one of the channel flag values.
Returns
Comments
This command will terminate any existing connection.
WIOCDISCONNECT
Purpose
Disconnects from the access point or ad-hoc network to which the device is currently connected, or terminates a connection attempt in progress.
Prototype
Fields
Returns
Comments
This call should only be used on a connected interface, or one that is in the process of trying to connect.
See Also
WIOCGETBSSID
Purpose
Retrieves the the BSSID of the access point or ad-hoc network to which the 802.11 interface is connected.
Prototype
struct { uint8_t bssid[6]; } WifiBSSIDType
Fields
Returns
WIOCGETCHANNEL
Purpose
Returns the channel on which the interface is connected, as well as a bit mask indicating which channels are supported by the radio hardware.
Prototype
struct { uint32_t current; uint32_t supportedMask; } WifiChannelType
Fields
-
← current
- The integer number of the channel on which the hardware is currently connected.
-
← supportedMask
- A bit mask indicating which channels the radio hardware supports. See "Channel Constants." for possible values.
Returns
WIOCGETCURRENTRSSI
Purpose
Returns the current signal strength of the wireless connection.
Prototype
struct { uint8_t signal; uint8_t padding[3]; } WifiGetRSSIType
Fields
Returns
errNone
if successful, otherwise an appropriate negative error code.
WIOCGETMACADDR
Purpose
Returns the MAC address of the WiFi interface.
Prototype
struct { uint8_t bssid[6]; } WiFiBSSIDType
Fields
Returns
errNone
if successful, otherwise an appropriate negative error code.
WIOCGETPOWERMODE
Purpose
Returns the current power mode for the radio hardware.
Prototype
uint32_t mode
Fields
-
← mode
- The retrieved power mode setting. See "Power Mode Constants" for possible values.
Returns
errNone
if successful, otherwise an appropriate negative error code.
See Also
WIOCGETRATES
Purpose
Retrieves information about the transmission settings and capabilities of the radio hardware.
Prototype
struct { uint32_t supported_rates; uint32_t preferred_rates; uint32_t current_rate; } WifiGetRatesType
Fields
-
← supported_rates
- A mask of all the transmission rates supported by the radio hardware.
-
← preferred_rates
- A subset of the supported_rates, which may be used when negotiating the transmission rate with an access point or ad-hoc network.
-
← current_rate
- The transmission rate currently in use, if the device is associated with an access point or ad-hoc network.
Returns
See Also
WIOCGETRSSIUPDATE
Purpose
Retrieves the rules governing when the 802.11 adapter sends an RSSI update event.
Prototype
struct { uint32_t updateMode; uint32_t updateValue; } WifiRSSIUpdateType
Fields
-
← updateMode
- The RSSI update mode currently in use. See "RSSI Update Mode Constants" for a list of possible values.
-
← updateValue
- The frequency of updates. If
updateMode
isWifiRSSIUpdatePeriodic
, this is the time interval in milliseconds between updates. IfupdateMode
isWifiRSSIUpdateOnDelta
, then this value is the amount of change in signal strength, in percentage points, that must be exceeded before an update is sent. This value is 0 for other modes.
Returns
See Also
WIOCGETSCANRESULTS
Purpose
Retrieves scan results from the results cache stored in the 802.11 adapter.
Prototype
struct { uint16_t index; uint16_t last; WifiScanResultsType results; } WifiGetScanResultsType
Fields
-
→ index
- The index number of the scan result to retrieve. On the first invocation of this command, the value should be zero. For subsequent invocations, the value should be set to a value in the range 0 to the value returned in
last
. -
← last
- The index of the last scan result. On the first invocation of this command, set this value to zero. When the command returns, it is set to the index of the last scan result available.
Returns
Comments
Use this command to fetch the results of either a passive or active scan.
See Also
WIOCGETSECCAPS
Purpose
Retrieves information about the current security settings and capabilities for the 802.11 interface.
Prototype
struct { uint32_t current; uint32_t capabilities; } WifiGetSecCapType
Fields
-
← current
- The current security mode in effect on the 802.11 interface. See "Security Capability Constants." Only one security mode can be in effect.
-
← capabilities
- A bit mask of all the security modes supported by the 802.11 interface.
Returns
See Also
WIOCGETSSID
Purpose
Retrieves the SSID of the access point or ad-hoc network to which the 802.11 interface is currently connected.
Prototype
struct { char ssid[33]; uint8_t padding[3]; } WifiSSIDType
Fields
-
← ssid
- A null terminated ASCII string with a length between 1 and 32 characters, indicating the SSID of the access point or ad-hoc network to which the interface is connected.
Returns
WIOCGETSTATUS
Purpose
Gets the current connection status for the 802.11 interface.
Prototype
uint32_t status
Fields
-
← status
- The current connection status of the 802.11 interface. See "Connection Status Constants."
Returns
WIOCGETWEPFLAGS
Purpose
Retrieves the current WEP configuration flags.
Prototype
uint32_t flags
Fields
-
← flags
- A mask of all the flags currently set. See "WEP Flag Constants."
Returns
See Also
WIOCJOIN
Purpose
Initiates a connection to an access point or ad-hoc network using a BSSID instead of an SSID to specify the network.
Prototype
struct { uint8_t bssid[6]; uint16_t channel; } WifiJoinType
Fields
-
→ bssid
- The 48-bit MAC address of the BSS the 802.11 interface should join.
-
→ channel
- The channel number on which to create the ad-hoc network. This must be one of the channels supported by the radio hardware, as reported by
WIOCGETCHANNEL
. The value must be an integer, rather than one of the channel flag values.
Returns
Comments
Using this command while already connected to a network causes the existing connection to be terminated and a new one to be opened.
See Also
WIOCPASSIVESCAN
Purpose
Instructs the 802.11 interface to passively scan for available access points and ad-hoc networks at regular intervals. This command is also used to terminate passive scanning.
Prototype
struct { uint32_t interval; uint32_t channelMask; uint32_t rateMask; uint8_t ssid[33]; uint8_t enableScanning; uint8_t padding[2] } WifiPassiveScanType;
Fields
-
→ interval
- The time interval between scans, in milliseconds.
-
→ channelMask
- A bit mask of all the channels that should be checked during the scan. See "Channel Constants" for possible values.
-
→ rateMask
- A bit mask of all the transmission rates to check for while performing the scan. See "Transmission Rate Flags" for possible values.
-
→ ssid
- This parameter, which is optional, lets you specify the SSID of a specific network to search for access points within. If you do not wish to use this restriction, this parameter should be set to an empty string.
-
→ enableScanning
- If
true
, passive scanning is started; iffalse
, passive scanning is canceled and all other parameters are ignored.
Returns
Comments
After this ioctl is issued, use the WIOCGETSCANRESULTS
ioctl to obtain the results.
See Also
WIOCSCAN
Purpose
Instructs the 802.11 interface to perform an active scan for available access points and ad-hoc networks.
Prototype
struct { uint32_t channels; uint32_t rates; uint32_t timeout; uint8_t ssid[33]; uint8_t blockTillCompletion; uint8_t padding[2] } WifiScanRequestType;
Fields
-
→ channels
- A bit mask of all the channels that should be checked during the scan. See "Channel Constants" for possible values.
-
→ rates
- A bit mask of all the transmission rates to check for while performing the scan. See "Transmission Rate Flags" for possible values.
-
→ timeout
- The length of time, in milliseconds, that the 802.11 framework will wait before giving up on a scan. A timeout of zero may be specified if the scan should not time out.
-
→ ssid
- This parameter, which is optional, lets you specify the SSID of a specific network to search for access points within. If you do not wish to use this restriction, this parameter should put to an empty string.
-
→ blockTillCompletion
- If
true
, theWIOCSCAN
ioctl will block until the first scan result comes in.
Returns
Comments
After this ioctl is issued, use the WIOCGETSCANRESULTS
ioctl to obtain the results.
See Also
WIOCPASSIVESCAN
, WIOCGETSCANRESULTS
WIOCSETDEFAULTKEY
Purpose
Sets the default WEP key for the radio hardware.
Prototype
uint32_t key
Fields
Returns
Comments
If WEP encryption is disabled, the default key will be set but not used.
WIOCSETKEY
Purpose
Sets one of the four WEP keys for the radio hardware.
Prototype
struct { uint16_t key; uint16_t len; uint8_t buffer[MAX_KEY_VALUE_LEN]; } WifiSetWEPKeyType
Fields
-
→ key
- The key number to set. Must be a value in the range 0 to 3.
-
→ len
- The length of the key, in bytes. A 40-bit key requires a 5-byte buffer, while a 104-bit key requires a 13-byte buffer.
-
→ buffer
- The key itself.
Returns
WIOCSETPOWERMODE
Purpose
Sets the current power mode for the radio hardware.
Prototype
uint32_t mode
Fields
-
↔ mode
- The power mode to use. See "Power Mode Constants" for possible values.
Returns
errNone
if successful, otherwise an appropriate negative error code.
Comments
The caller should check mode
on output to verify that the requested mode was in fact set. For example, if there is a hardware switch locking WiFi power off, an attempt to turn WiFi on would fail.
See Also
WIOCSETRATES
Purpose
Sets the preferred transmission rates for the radio hardware. The actual transmission rate is selected by negotiation turing the process of associating with an access point or ad-hoc network.
Prototype
uint32_t rate_mask
Fields
-
→ rate_mask
- A bit mask containing all the transmission rates that the station should use. See "Transmission Rate Flags" for possible values.
Returns
See Also
WIOCSETRSSIUPDATE
Purpose
Configures the rules governing when the 802.11 adapter sends an RSSI update event.
Prototype
struct { uint32_t updateMode; uint32_t updateValue; } WifiRSSIUpdateType
Fields
-
→ updateMode
- The RSSI update mode to use. See "RSSI Update Mode Constants" for a list of possible settings.
-
→ updateValue
- The frequency of updates. If
updateMode
isWifiRSSIUpdatePeriodic
, this is the time interval in milliseconds between updates. IfupdateMode
isWifiRSSIUpdateOnDelta
, then this value is the amount of change in signal strength, in percentage points, that must be exceeded before an update is sent.
Returns
See Also
WIOCSETSECMODE
Purpose
Selects the security scheme for the 802.11 interface.
Prototype
uint32_t mode
Fields
-
→ mode
- The security mode to use on the 802.11 interface. See "Security Capability Constants." You may only specify one security mode.
Returns
See Also
WIOCSETWEPFLAGS
Purpose
Prototype
uint32_t flags
Fields
-
→ flags
- A mask of all the flags to set. See "WEP Flag Constants."