Ttangmeng1234docs: add English translation for API reference documentation

Wireless Network Interface (WAPI) API

The wapi_* series of interfaces is a wrapper around Linux Wireless Extensions (WEXT), providing wireless network configuration, scanning, association, power management, country code, and PMKSA cache capabilities.

Header: #include <wireless/wapi.h>

openvela Implementation Notes

Underlying mechanism: Communicates with Wi-Fi drivers via the ioctl protocol of Linux Wireless Extensions (WEXT)
Supported scenarios: Station (client) mode, AP mode, and promiscuous mode (depending on driver support)
Configuration dependency: Requires CONFIG_WIRELESS_WAPI and the corresponding Wi-Fi chip driver to be enabled
Typical usage:
- wapi_set_ifup/wapi_set_ifdown to bring the interface up or down
- wapi_set_essid + wapi_set_mode to configure the connection target
- wapi_scan_* / wapi_escan_* to scan surrounding APs
- wapi_load_config / wapi_save_config to persist configuration
Extended capabilities: Interact with driver-specific features via interfaces such as wapi_extend_params / wapi_set_pmksa

Wireless Network Interface

Header: #include <wireless/wapi.h>

wapi provides wireless network configuration interfaces, including SSID scanning, connection, and frequency setting.

Connection Management

wapi_get_ifup

int wapi_get_ifup(int sock, const char *ifname, int *is_up);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
is_up Interface status; 0 means enabled, 1 means disabled.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_ifup

int wapi_set_ifup(int sock, const char *ifname);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_ifdown

int wapi_set_ifdown(int sock, const char *ifname);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name to be brought down.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_ip

int wapi_get_ip(int sock, const char *ifname, struct in_addr *addr);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
addr Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_ip

int wapi_set_ip(int sock, const char *ifname, const struct in_addr *addr);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name whose IP address is set.
addr Pointer to the structure containing the new IP address.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_netmask

int wapi_get_netmask(int sock, const char *ifname, struct in_addr *addr);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
addr Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_netmask

int wapi_set_netmask(int sock, const char *ifname, const struct in_addr *addr);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
addr Pointer to the structure containing the new subnet mask.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_add_route_gw

int wapi_add_route_gw(int sock, enum wapi_route_target_e targettype, const struct in_addr *target, const struct in_addr *netmask, const struct in_addr *gw);

Parameters:

sock Socket descriptor (used for ioctl operations).
targettype Target type.
target Pointer to the target IP address.
netmask Pointer to the subnet mask corresponding to the target address.
gw Pointer to the corresponding gateway (router) IP address, used for routing.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_del_route_gw

int wapi_del_route_gw(int sock, enum wapi_route_target_e targettype, const struct in_addr *target, const struct in_addr *netmask, const struct in_addr *gw);

Parameters:

sock Socket descriptor (used for ioctl operations).
targettype Target type.
target Pointer to the target IP address of the route.
netmask Pointer to the subnet mask corresponding to the target address.
gw Pointer to the corresponding gateway (router) IP address, used for routing.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_freq

int wapi_get_freq(int sock, const char *ifname, double *freq, enum wapi_freq_flag_e *flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
freq Output parameter.
flag Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_freq

int wapi_set_freq(int sock, const char *ifname, double freq, enum wapi_freq_flag_e flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
freq Frequency value.
flag Frequency value.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_freq2chan

int wapi_freq2chan(int sock, const char *ifname, double freq, int *chan);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
freq Frequency, in Hz, to be converted to a channel number.
chan Output parameter.

wapi_chan2freq

int wapi_chan2freq(int sock, const char *ifname, int chan, double *freq);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Channel.
chan Channel number to be converted to a frequency.
freq Output parameter.

wapi_get_essid

int wapi_get_essid(int sock, const char *ifname, char *essid, enum wapi_essid_flag_e *flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
essid Used to store the result.
flag Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_essid

int wapi_set_essid(int sock, const char *ifname, const char *essid, enum wapi_essid_flag_e flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
essid Pointer to a \0-terminated ESSID string.
flag Control flag.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_mode

int wapi_get_mode(int sock, const char *ifname, enum wapi_mode_e *mode);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
mode Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_mode

int wapi_set_mode(int sock, const char *ifname, enum wapi_mode_e mode);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
mode Output parameter.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_make_broad_ether

int wapi_make_broad_ether(struct ether_addr *sa);

Parameters:

sa Output parameter.

Returns:

Returns the result of the underlying wapi_make_ether() call.

wapi_make_null_ether

int wapi_make_null_ether(struct ether_addr *sa);

Parameters:

sa Output parameter.

Returns:

Returns the result of the underlying wapi_make_ether() call.

wapi_get_ap

int wapi_get_ap(int sock, const char *ifname, struct ether_addr *ap);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
ap Address to set.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_ap

int wapi_set_ap(int sock, const char *ifname, const struct ether_addr *ap);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
ap MAC address of the access point.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_bitrate

int wapi_get_bitrate(int sock, const char *ifname, int *bitrate, enum wapi_bitrate_flag_e *flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
bitrate Output parameter for the retrieved bitrate.
flag Output parameter for the bitrate flag bits.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_bitrate

int wapi_set_bitrate(int sock, const char *ifname, int bitrate, enum wapi_bitrate_flag_e flag);

Parameters:

sock Socket descriptor (used for ioctl operations).
ifname Network interface name.
bitrate Bitrate.
flag Bitrate flag.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_dbm2mwatt

int wapi_dbm2mwatt(int dbm);

Parameters:

dbm dBm value to convert.

Returns:

The converted milliwatt value.

wapi_mwatt2dbm

int wapi_mwatt2dbm(int mwatt);

Parameters:

mwatt Milliwatt value.

Returns:

The converted dBm value.

wapi_get_txpower

int wapi_get_txpower(int sock, const char *ifname, int *power, enum wapi_txpower_flag_e *flag);

Parameters:

sock Socket descriptor.
ifname Network interface name.
power Output parameter for the transmit power value.
flag Output parameter for the unit of the transmit power.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_txpower

int wapi_set_txpower(int sock, const char *ifname, int power, enum wapi_txpower_flag_e flag);

Parameters:

sock Socket descriptor.
ifname Network interface name.
power Transmit power.
flag Transmit power.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_make_socket

int wapi_make_socket(void);

wapi_scan_init

int wapi_scan_init(int sock, const char *ifname, const char *essid);

Parameters:

sock Socket descriptor.
ifname Network interface name.
essid ESSID to scan.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_scan_channel_init

int wapi_scan_channel_init(int sock, const char *ifname, const char *essid, uint8_t *channels, int num_channels);

Parameters:

sock Socket descriptor.
ifname Network interface name.
essid ESSID to scan.
channels Pointer to an array of channel numbers to scan.
num_channels Channel count.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_escan_init

int wapi_escan_init(int sock, const char *ifname, uint8_t scan_type, const char *essid);

Parameters:

sock Socket descriptor.
ifname Network interface name.
scan_type Scan type.
essid ESSID to scan.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_escan_channel_init

int wapi_escan_channel_init(int sock, const char *ifname, uint8_t scan_type, const char *essid, uint8_t *channels, int num_channels);

Parameters:

sock Socket descriptor.
ifname Network interface name.
scan_type Scan type.
essid ESSID to scan.
channels Pointer to an array of channel numbers to scan.
num_channels Channel count.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_scan_stat

int wapi_scan_stat(int sock, const char *ifname);

Parameters:

sock Socket descriptor.
ifname Network interface name.

wapi_scan_coll

int wapi_scan_coll(int sock, const char *ifname, struct wapi_list_s *aps);

Parameters:

sock Socket descriptor.
ifname Network interface name.
aps List of collected scan results.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_scan_coll_free

void wapi_scan_coll_free(struct wapi_list_s *aps);

Parameters:

aps Scan result list to free.

wapi_set_country

int wapi_set_country(int sock, const char *ifname, const char *country);

Parameters:

sock Socket descriptor.
ifname Network interface name.
country Pointer to a two-character string indicating the country code to set.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_country

int wapi_get_country(int sock, const char *ifname, char *country);

Parameters:

sock Socket descriptor.
ifname Network interface name.
country Pointer to the caller-provided buffer to receive the country code.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_sensitivity

int wapi_get_sensitivity(int sock, const char *ifname, int *sense);

Parameters:

sock Socket descriptor.
ifname Network interface name.
sense Pointer to the caller-provided integer variable to receive the sensitivity value.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_load_config

void *wapi_load_config(const char *ifname, const char *confname, struct wpa_wconfig_s *conf);

Parameters:

ifname Network interface name.
confname Path.
conf Pointer to the caller-provided structure to be filled with configuration data.

wapi_unload_config

void wapi_unload_config(void *load);

Parameters:

load Configuration resource handle.

wapi_save_config

int wapi_save_config(const char *ifname, const char *confname, const struct wpa_wconfig_s *conf);

Parameters:

ifname Network interface name.
confname Path.
conf Pointer to the structure containing the configuration information.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_pta_prio

int wapi_set_pta_prio(int sock, const char *ifname, enum wapi_pta_prio_e pta_prio);

Parameters:

sock File descriptor.
ifname Network interface name.
pta_prio PTA priority.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_pta_prio

int wapi_get_pta_prio(int sock, const char *ifname, enum wapi_pta_prio_e *pta_prio);

Parameters:

sock File descriptor.
ifname Network interface name.
pta_prio Pointer to the variable that receives the current PTA priority.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_pmksa

int wapi_set_pmksa(int sock, const char *ifname, const uint8_t *pmk, int len);

Parameters:

sock File descriptor.
ifname Network interface name.
pmk Pointer to the buffer containing the PMKSA data.
len Length.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_pmksa

int wapi_get_pmksa(int sock, const char *ifname, uint8_t *pmk, int len);

Parameters:

sock File descriptor.
ifname Network interface name.
pmk Pointer to the buffer that receives the retrieved PMKSA data.
len Buffer size.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_extend_params

int wapi_extend_params(int sock, int cmd, struct iwreq *wrq);

Parameters:

sock File descriptor.
cmd Private ioctl command code.
wrq Pointer to an iwreq structure that the caller must populate in advance.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_set_power_save

int wapi_set_power_save(int sock, const char *ifname, bool on);

Parameters:

sock File descriptor.
ifname Network interface name.
on Control flag.

Returns:

Returns 0 on success, or a negative error code on failure.

wapi_get_power_save

int wapi_get_power_save(int sock, const char *ifname, bool *on);

Parameters:

sock File descriptor.
ifname Network interface name.
on Pointer to a boolean variable that receives the current state.

Returns:

Returns 0 on success, or a negative error code on failure.