Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

17    WiFi Reference

Low-Level Communications

Exploring Palm OS®

Declared In

wifi.h

Overview ^TOP^

This chapter describes the constants, data types, and ioctl command codes used to control WiFi connectivity.

WiFi Constants ^TOP^

Channel Constants ^TOP^

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 ^TOP^

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 ^TOP^

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 or wifiConnectAdHoc 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 ^TOP^

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 ^TOP^

Purpose

Define the RSSI update modes.

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 ^TOP^

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 ^TOP^

Purpose

Define the security capabilities of the WiFi network.

Constants

WifiSecOpen
The network is not secure.
WifiSecWEP
The network supports WEP.

Transmission Rate Flags ^TOP^

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 ^TOP^

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 ^TOP^

WifiEventType Struct ^TOP^

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.
reasonCode
An integer indicating the reason for the failure.
scanFailed
Indicates that a scan attempt has failed.
reasonCode
An integer indicating the reason for the failure.
signalStrength
Provides updated signal strength information.
signal
A value from 0 to 100 indicating the current signal strength as a percentage of maximum strength.

WifiScanResultsType Struct ^TOP^

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.

NOTE: The channel number is an integer, not a constant from the "Channel Constants" list.
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 ^TOP^

WIOCCONNECT ^TOP^

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, the WIOCONNECT ioctl will block until the connection has been established or a timeout occurs.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

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

WIOCDISCONNECT

WIOCCREATEIBSS ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

Comments

This command will terminate any existing connection.

WIOCDISCONNECT ^TOP^

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

None.

Fields

None.

Returns

Nothing.

Comments

This call should only be used on a connected interface, or one that is in the process of trying to connect.

See Also

WIOCCONNECT

WIOCGETBSSID ^TOP^

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

bssid
The 48-bit MAC address representing the BSSID of the access point or ad-hoc network.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

WIOCGETCHANNEL ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

WIOCGETCURRENTRSSI ^TOP^

Purpose

Returns the current signal strength of the wireless connection.

Prototype

struct {
   uint8_t signal;
   uint8_t padding[3];
} WifiGetRSSIType

Fields

signal
The signal strength of the connection, as a percentage from 0 to 100.

Returns

errNone if successful, otherwise an appropriate negative error code.

WIOCGETMACADDR ^TOP^

Purpose

Returns the MAC address of the WiFi interface.

Prototype

struct {
   uint8_t bssid[6];
} WiFiBSSIDType

Fields

bssid
The BSSID (MAC address) of the WiFi interface.

Returns

errNone if successful, otherwise an appropriate negative error code.

WIOCGETPOWERMODE ^TOP^

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

WIOCSETPOWERMODE

WIOCGETRATES ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

See Also

WIOCSETRATES

WIOCGETRSSIUPDATE ^TOP^

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 is WifiRSSIUpdatePeriodic, this is the time interval in milliseconds between updates. If updateMode is WifiRSSIUpdateOnDelta, 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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

See Also

WIOCSETRSSIUPDATE

WIOCGETSCANRESULTS ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

Comments

Use this command to fetch the results of either a passive or active scan.

See Also

WIOCPASSIVESCAN, WIOCSCAN

WIOCGETSECCAPS ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

See Also

WIOCSETSECMODE

WIOCGETSSID ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

WIOCGETSTATUS ^TOP^

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

errNone
Success.
EINVAL
The status parameter is invalid.

Other errors as appropriate.

WIOCGETWEPFLAGS ^TOP^

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

errNone
Success.
EINVAL
The flags parameter is invalid.

Other errors as appropriate.

See Also

WIOCSETWEPFLAGS

WIOCJOIN ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

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

WIOCDISCONNECT

WIOCPASSIVESCAN ^TOP^

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; if false, passive scanning is canceled and all other parameters are ignored.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

Comments

After this ioctl is issued, use the WIOCGETSCANRESULTS ioctl to obtain the results.

See Also

WIOCSCAN, WIOCGETSCANRESULTS

WIOCSCAN ^TOP^

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, the WIOCSCAN ioctl will block until the first scan result comes in.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

Comments

After this ioctl is issued, use the WIOCGETSCANRESULTS ioctl to obtain the results.

See Also

WIOCPASSIVESCAN, WIOCGETSCANRESULTS

WIOCSETDEFAULTKEY ^TOP^

Purpose

Sets the default WEP key for the radio hardware.

Prototype

uint32_t key


Fields

key
The key number to use as the default key. Must be a value in the range 0 to 3.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

Comments

If WEP encryption is disabled, the default key will be set but not used.

WIOCSETKEY ^TOP^

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

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

WIOCSETPOWERMODE ^TOP^

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

WIOCGETPOWERMODE

WIOCSETRATES ^TOP^

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

errNone
Success.
EINVAL
The rate_mask specified is invalid.

Other errors as appropriate.

See Also

WIOCGETRATES

WIOCSETRSSIUPDATE ^TOP^

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 is WifiRSSIUpdatePeriodic, this is the time interval in milliseconds between updates. If updateMode is WifiRSSIUpdateOnDelta, then this value is the amount of change in signal strength, in percentage points, that must be exceeded before an update is sent.

Returns

errNone
Success.
EINVAL
One of the parameters is invalid.

Other errors as appropriate.

See Also

WIOCGETRSSIUPDATE

WIOCSETSECMODE ^TOP^

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

errNone
Success.
EINVAL
The mode is invalid.

Other errors as appropriate.

See Also

WIOCGETSECCAPS

WIOCSETWEPFLAGS ^TOP^

Purpose

Sets options related to WEP.

Prototype

uint32_t flags

Fields

flags
A mask of all the flags to set. See "WEP Flag Constants."

Returns

errNone
Success.
EINVAL
The flags are invalid.

Other errors as appropriate.

See Also

WIOCGETWEPFLAGS