Haiku Book: added NetworkAddress, NetworkDevice, NetworkNotifications, NetworkRoster and NetworkRoute
Change-Id: If2123eabeb30e9d09e2de0a603a77f30c8324f7f Reviewed-on: https://review.haiku-os.org/c/haiku/+/10225 Haiku-Format: Haiku-format Bot <[email protected]> Tested-by: Commit checker robot <[email protected]> Reviewed-by: Adrien Destugues <[email protected]>
This commit is contained in:
cafeina
committed by
Adrien Destugues
Adrien Destugues
parent
d1c493cc67
commit
49d1c362d3
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,734 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2026 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/net/NetworkDevice.h hrev59275
|
||||||
|
* src/kits/network/libnetapi/NetworkDevice.cpp hrev59275
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file NetworkDevice.h
|
||||||
|
\ingroup network
|
||||||
|
\brief Provides the BNetworkDevice class and wireless_network struct.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_AUTHENTICATION_NONE
|
||||||
|
\brief Authentication is performed without any authentication method.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_AUTHENTICATION_WEP
|
||||||
|
\brief Authentication is performed via Wired Equivalent Privacy (WEP)
|
||||||
|
authentication method.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_AUTHENTICATION_WPA
|
||||||
|
\brief Authentication is performed via Wi-Fi Protected Access (WPA)
|
||||||
|
authentication method.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_AUTHENTICATION_WPA2
|
||||||
|
\brief Authentication is performed via Wi-Fi Protected Access 2 (WPA2)
|
||||||
|
authentication method.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_AUTHENTICATION_EAP
|
||||||
|
\brief Authentication is performed via Extensible Authentication Protocol
|
||||||
|
(EAP) authentication method.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_NONE
|
||||||
|
\brief The data stream is not ciphered.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_WEP_40
|
||||||
|
\brief The data stream is ciphered using WEP-40: a RC4 based stream cipher
|
||||||
|
consisting of a 40-bit key plus a 24-bit initialization vector.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_WEP_104
|
||||||
|
\brief The data stream is ciphered using WEP-104: a RC4 based stream cipher
|
||||||
|
consisting of a 104-bit key plus a 24-bit initialization vector.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_TKIP
|
||||||
|
\brief The data stream is ciphered using Temporal Key Integrity Protocol
|
||||||
|
(TKIP).
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_CCMP
|
||||||
|
\brief The data stream is ciphered using Counter Mode with CBC-MAC
|
||||||
|
Protocol (CCMP).
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
/* RFC 4493 */
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_CIPHER_AES_128_CMAC
|
||||||
|
\brief The data stream is ciphered using Advanced Encryption Standard (AES)
|
||||||
|
with a 128-bit block size with Cipher-based Message Authentication Code
|
||||||
|
(CMAC) for data integrity.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_IEEE802_1X
|
||||||
|
\brief The cryptographic key is distibuted using IEEE 802.1X mode,
|
||||||
|
making use of the Extensible Authentication Protocol (EAP). Also
|
||||||
|
known as WPA-Enterprise.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_PSK
|
||||||
|
\brief The cryptographic key is distibuted using Pre-shared Key (PSK) mode.
|
||||||
|
Also known as WPA-Personal.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_NONE
|
||||||
|
\brief There is no particular key mode or the network is open
|
||||||
|
(not encrypted).
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_FT_IEEE802_1X
|
||||||
|
\brief The cryptographic key is distibuted using IEEE 802.1X Fast Transition
|
||||||
|
mode, making use of the Extensible Authentication Protocol (EAP).
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_FT_PSK
|
||||||
|
\brief The cryptographic key is distibuted using Pre-shared Key (PSK)
|
||||||
|
Fast Transition mode.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_IEEE802_1X_SHA256
|
||||||
|
\brief The cryptographic key is distibuted using IEEE 802.1X with SHA-256
|
||||||
|
mode.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_PSK_SHA256
|
||||||
|
\brief The cryptographic key is distibuted using Pre-shared Key (PSK)
|
||||||
|
with SHA-256 mode.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_KEY_MODE_WPS
|
||||||
|
\brief The cryptographic key is distibuted through Wi-Fi Protected Setup
|
||||||
|
(WPS).
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_EAP_ENCAPSULATION_NONE
|
||||||
|
\brief There is no particular encapsulation for the Extensible
|
||||||
|
Authentication Protocol (EAP) mode or the network device is not using
|
||||||
|
this protocol.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_EAP_ENCAPSULATION_PEAP
|
||||||
|
\brief The Extensible Authentication Protocol (EAP) authentication is encapsulated
|
||||||
|
within a Protected Extensible Authentication Protocol (PEAP)
|
||||||
|
encrypted tunnel.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var ::B_NETWORK_EAP_ENCAPSULATION_TLS
|
||||||
|
\brief The Extensible Authentication Protocol (EAP) authentication is performed
|
||||||
|
using Transport Layer Security (TLS) for cryptographic negotiation
|
||||||
|
between the endpoints.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_IS_ENCRYPTED
|
||||||
|
\brief The wireless_network is encrypted.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_IS_PERSISTENT
|
||||||
|
\brief The wireless_network is set as persistent.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\struct wireless_network
|
||||||
|
\ingroup network
|
||||||
|
\brief Describes a wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::name
|
||||||
|
|
||||||
|
\brief The service set identifier (SSID) of the wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::address
|
||||||
|
|
||||||
|
\brief The basic service set identifier (BSSID) of the wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::noise_level
|
||||||
|
|
||||||
|
\brief The noise level of the wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::signal_strength
|
||||||
|
|
||||||
|
\brief The signal strength of the wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::flags
|
||||||
|
\brief Configuration flags of the wireless_network object.
|
||||||
|
|
||||||
|
Valid values are:
|
||||||
|
- ::B_NETWORK_IS_ENCRYPTED
|
||||||
|
- ::B_NETWORK_IS_PERSISTENT
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::authentication_mode
|
||||||
|
|
||||||
|
\brief The authentication mode of the wireless network.
|
||||||
|
|
||||||
|
The authentication modes are described in this enumeration:
|
||||||
|
\code{.cpp}
|
||||||
|
// authentication modes
|
||||||
|
enum {
|
||||||
|
B_NETWORK_AUTHENTICATION_NONE = 0,
|
||||||
|
B_NETWORK_AUTHENTICATION_WEP = 1,
|
||||||
|
B_NETWORK_AUTHENTICATION_WPA = 2,
|
||||||
|
B_NETWORK_AUTHENTICATION_WPA2 = 3,
|
||||||
|
B_NETWORK_AUTHENTICATION_EAP = 4
|
||||||
|
};
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::cipher
|
||||||
|
|
||||||
|
\brief The cipher algorithm of the wireless network.
|
||||||
|
|
||||||
|
The cipher algorithms are described in this enumeration:
|
||||||
|
\code{.cpp}
|
||||||
|
// cipher algorithms
|
||||||
|
enum {
|
||||||
|
B_NETWORK_CIPHER_NONE = 0x01,
|
||||||
|
B_NETWORK_CIPHER_WEP_40 = 0x02,
|
||||||
|
B_NETWORK_CIPHER_WEP_104 = 0x04,
|
||||||
|
B_NETWORK_CIPHER_TKIP = 0x08,
|
||||||
|
B_NETWORK_CIPHER_CCMP = 0x10,
|
||||||
|
B_NETWORK_CIPHER_AES_128_CMAC = 0x20
|
||||||
|
};
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::group_cipher
|
||||||
|
|
||||||
|
\brief This field could be defined with one of the values described
|
||||||
|
in wireless_network::cipher.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var wireless_network::key_mode
|
||||||
|
|
||||||
|
\brief The key negotiation mode.
|
||||||
|
|
||||||
|
The key modes are described in this enumeration:
|
||||||
|
\code{.cpp}
|
||||||
|
// key modes
|
||||||
|
enum {
|
||||||
|
B_KEY_MODE_IEEE802_1X = 0x0001,
|
||||||
|
B_KEY_MODE_PSK = 0x0002,
|
||||||
|
B_KEY_MODE_NONE = 0x0004,
|
||||||
|
B_KEY_MODE_FT_IEEE802_1X = 0x0020,
|
||||||
|
B_KEY_MODE_FT_PSK = 0x0040,
|
||||||
|
B_KEY_MODE_IEEE802_1X_SHA256 = 0x0080,
|
||||||
|
B_KEY_MODE_PSK_SHA256 = 0x0100,
|
||||||
|
B_KEY_MODE_WPS = 0x0200
|
||||||
|
};
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool wireless_network::operator==(const wireless_network& other)
|
||||||
|
\brief Checks if \a other is the same wireless network as this.
|
||||||
|
|
||||||
|
The check ignores the address difference between \a address and
|
||||||
|
\a other.address.
|
||||||
|
|
||||||
|
\returns \c true if both wireless_network objects represent the same
|
||||||
|
wireless network, or \c false otherwise.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\class BNetworkDevice
|
||||||
|
\ingroup network
|
||||||
|
\brief BNetworkDevice class represents a network device.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BNetworkDevice::BNetworkDevice()
|
||||||
|
\brief Creates a BNetworkDevice object in an uninitialized state.
|
||||||
|
|
||||||
|
\sa SetTo()
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BNetworkDevice::BNetworkDevice(const char* name)
|
||||||
|
\brief Creates and initializes a BNetworkDevice object identified by \a name.
|
||||||
|
|
||||||
|
\param[in] name The device name.
|
||||||
|
|
||||||
|
\sa SetTo()
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkDevice::Unset()
|
||||||
|
\brief Returns the object to an uninitialized state.
|
||||||
|
|
||||||
|
\sa SetTo()
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkDevice::SetTo(const char* name)
|
||||||
|
\brief (Re)initializes the BNetworkDevice object to work with the
|
||||||
|
device in \a name.
|
||||||
|
|
||||||
|
\param[in] name The device name.
|
||||||
|
|
||||||
|
\sa Unset()
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const char* BNetworkDevice::Name() const
|
||||||
|
\brief Returns the device name.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BNetworkDevice::Exists() const
|
||||||
|
\brief Checks if the network device identified as Name() exists in the system.
|
||||||
|
|
||||||
|
\retval true The device exists.
|
||||||
|
\retval false The device does not exist or the BNetworkDevice object
|
||||||
|
is not initialized.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn uint32 BNetworkDevice::Index() const
|
||||||
|
\brief Returns the index of the device in the list of network devices.
|
||||||
|
|
||||||
|
If the device was not found or this object is not initialized,
|
||||||
|
it returns \c 0.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn uint32 BNetworkDevice::Flags() const
|
||||||
|
\brief Returns a bit mask of the flags associated with the device.
|
||||||
|
|
||||||
|
Possible flags are those defined in the POSIX header \c net/if.h.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BNetworkDevice::HasLink() const
|
||||||
|
\brief Checks if the device has an active connection with another interface.
|
||||||
|
|
||||||
|
\retval true The device has a link.
|
||||||
|
\retval false The device does not have a link.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BNetworkDevice::Media() const
|
||||||
|
\brief Returns a bit mask of the device's media options.
|
||||||
|
|
||||||
|
Possible flags are those defined in the header \c net/if_media.h.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::SetMedia(int32 media)
|
||||||
|
\brief Configures the media options of the device.
|
||||||
|
|
||||||
|
\returns B_OK on success, or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetHardwareAddress(BNetworkAddress& address)
|
||||||
|
\brief Gets the MAC address of the device.
|
||||||
|
|
||||||
|
\param[out] address A BNetworkAddress object where to write the address.
|
||||||
|
|
||||||
|
\returns \c B_OK on success, or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BNetworkDevice::IsEthernet()
|
||||||
|
\brief Checks if the device media type is ethernet.
|
||||||
|
|
||||||
|
\retval true The device is an ethernet device.
|
||||||
|
\retval false The device is not an ethernet device.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn bool BNetworkDevice::IsWireless()
|
||||||
|
\brief Checks if the device media type is IEEE 802.11 (WLAN) or wireless.
|
||||||
|
|
||||||
|
\retval true The device is a wireless device.
|
||||||
|
\retval false The device is not a wireless device.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::Control(int option, void* request)
|
||||||
|
\brief Sends an ioctl request to the device.
|
||||||
|
|
||||||
|
\param[in] option The kind of operation.
|
||||||
|
\param[in] request The request data.
|
||||||
|
|
||||||
|
\returns \c B_OK on success, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK Command sent and processed successfully.
|
||||||
|
\retval B_ERROR Something went wrong, or performing ioctl calls is not
|
||||||
|
supported for the device's media type.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::Scan(bool wait = true, bool forceRescan = true)
|
||||||
|
\brief Scans for a wireless network.
|
||||||
|
|
||||||
|
\param[in] wait Tells the object to wait for any WLAN change before starting
|
||||||
|
to scan.
|
||||||
|
\param[in] forceRescan Flush any previous scan result.
|
||||||
|
|
||||||
|
\return B_OK if the operation was performed successfully or an error code
|
||||||
|
otherwise.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetNetworks(wireless_network*& networks,
|
||||||
|
uint32& count)
|
||||||
|
\brief Gets all the detected wireless networks from a previous scan.
|
||||||
|
|
||||||
|
\param[out] networks A \c NULL pointer where an array of wireless_network
|
||||||
|
will be written to.
|
||||||
|
\param[out] count How many items there are in \a networks.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE \a networks is not \c NULL.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetNetwork(const char* name,
|
||||||
|
wireless_network& network)
|
||||||
|
\brief Returns a wireless_network object of the network identified as \a name.
|
||||||
|
|
||||||
|
\param[in] name The wireless network name.
|
||||||
|
\param[out] network A wireless_network object where the network information
|
||||||
|
will be written to.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE \a name is \c NULL.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There is no network called \a name.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetNetwork(const BNetworkAddress& address,
|
||||||
|
wireless_network& network)
|
||||||
|
\brief Returns a wireless_network object of the network
|
||||||
|
described in \a address.
|
||||||
|
|
||||||
|
\param[in] address A BNetworkAddress object of the wireless network.
|
||||||
|
\param[out] network A wireless_network object where the network information
|
||||||
|
will be written to.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE \a address' family is not \c AF_LINK.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There is no network called \a name.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::JoinNetwork(const char* name,
|
||||||
|
const char* password = NULL)
|
||||||
|
\brief Connects to the network identified as \a name.
|
||||||
|
|
||||||
|
\param[in] name The network name.
|
||||||
|
\param[in] password The network password.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE \a name is \c NULL.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::JoinNetwork(const wireless_network& network,
|
||||||
|
const char* password = NULL)
|
||||||
|
\brief Connects to the network described in \a network.
|
||||||
|
|
||||||
|
\param[in] network A wireless_network object with the network information.
|
||||||
|
\param[in] password The network password.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE The name in \a network is \c NULL.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::JoinNetwork(const BNetworkAddress& address,
|
||||||
|
const char* password = NULL)
|
||||||
|
\brief Connects to the network in \a address.
|
||||||
|
|
||||||
|
\param[in] address The network address.
|
||||||
|
\param[in] password The network password.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_BAD_VALUE \a address is not properly initialized.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::LeaveNetwork(const char* name)
|
||||||
|
\brief Disconnects from the wireless network \a name.
|
||||||
|
|
||||||
|
\param[in] name The network name.
|
||||||
|
|
||||||
|
\return \c B_OK if it could leave the network or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::LeaveNetwork(const wireless_network& network)
|
||||||
|
\brief Disconnects from the wireless \a network.
|
||||||
|
|
||||||
|
\param[in] network A wireless_network object with the network name.
|
||||||
|
|
||||||
|
\return \c B_OK if it could leave the network or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::LeaveNetwork(const BNetworkAddress& address)
|
||||||
|
\brief Disconnects from the wireless network in \a address.
|
||||||
|
|
||||||
|
\return \c B_OK if it could leave the network or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetNextAssociatedNetwork(uint32& cookie,
|
||||||
|
wireless_network& network)
|
||||||
|
\brief Iterates through the associated networks and saves the next one
|
||||||
|
in \a network.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There are no more associated networks.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkDevice::GetNextAssociatedNetwork(uint32& cookie,
|
||||||
|
BNetworkAddress& address)
|
||||||
|
\brief Iterates through the associated networks and saves the address of
|
||||||
|
next one in \a address.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There are no more associated networks.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
@@ -0,0 +1,197 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2026 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/net/NetworkNotifications.h hrev59275
|
||||||
|
* src/kits/network/libnetapi/notifications.cpp hrev59275
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file NetworkNotifications.h
|
||||||
|
\ingroup network
|
||||||
|
\brief Provides C functions to get network related notifications.
|
||||||
|
|
||||||
|
There is a C++ view of the API: BNetworkRoster::StartWatching() to
|
||||||
|
subscribe to get these events and BNetworkRoster::StopWatching() to
|
||||||
|
unsubscribe from them.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_INTERFACE_ADDED
|
||||||
|
\brief Notification sent to subscribers when a network interface was added.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_INTERFACE_REMOVED
|
||||||
|
\brief Notification sent to subscribers when a network interface was removed.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_INTERFACE_CHANGED
|
||||||
|
\brief Notification sent to subscribers when a network interface was modified.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_DEVICE_LINK_CHANGED
|
||||||
|
\brief Notification sent to subscribers when a network link was changed.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_WLAN_JOINED
|
||||||
|
\brief Notification sent to subscribers when joining a wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_WLAN_LEFT
|
||||||
|
\brief Notification sent to subscribers when leaving a wireless network.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_WLAN_SCANNED
|
||||||
|
\brief Notification sent to subscribers after scanning for available
|
||||||
|
wireless networks.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\def B_NETWORK_WLAN_MESSAGE_INTEGRITY_FAILED
|
||||||
|
\brief Notification sent to subscribers when in a wireless network using WPA
|
||||||
|
based protocols, the message integrity check sent to prevent tampering
|
||||||
|
of messages by "man in the middle" attacks has failed.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var B_WATCH_NETWORK_INTERFACE_CHANGES
|
||||||
|
\brief Flag to subscribe to receive network interface changes notifications.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var B_WATCH_NETWORK_LINK_CHANGES
|
||||||
|
\brief Flag to subscribe to receive network link changes notifications.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\var B_WATCH_NETWORK_WLAN_CHANGES
|
||||||
|
\brief Flag to subscribe to receive wireless networks changes notifications.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t start_watching_network(uint32 flags, const BMessenger& target)
|
||||||
|
\brief Subscribes \a target to receive network events' notifications
|
||||||
|
described in \a flags.
|
||||||
|
|
||||||
|
Valid values for \a flags are any combination of the following:
|
||||||
|
- \c ::B_WATCH_NETWORK_INTERFACE_CHANGES
|
||||||
|
- \c ::B_WATCH_NETWORK_LINK_CHANGES
|
||||||
|
- \c ::B_WATCH_NETWORK_WLAN_CHANGES
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_INTERFACE_CHANGES, the following notifications
|
||||||
|
will be sent to \a target if such events happen:
|
||||||
|
- \c ::B_NETWORK_INTERFACE_ADDED
|
||||||
|
- \c ::B_NETWORK_INTERFACE_REMOVED
|
||||||
|
- \c ::B_NETWORK_INTERFACE_CHANGED
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_LINK_CHANGES, the following notification
|
||||||
|
will be sent to \a target if such event happens:
|
||||||
|
- \c ::B_NETWORK_DEVICE_LINK_CHANGED
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_WLAN_CHANGES, the following notifications
|
||||||
|
will be sent to \a target if such events happen:
|
||||||
|
- \c ::B_NETWORK_WLAN_JOINED
|
||||||
|
- \c ::B_NETWORK_WLAN_LEFT
|
||||||
|
- \c ::B_NETWORK_WLAN_SCANNED
|
||||||
|
- \c ::B_NETWORK_WLAN_MESSAGE_INTEGRITY_FAILED
|
||||||
|
|
||||||
|
If \a flags is \c 0, it will stop sending notifications to \a target.
|
||||||
|
|
||||||
|
\param[in] flags A flags mask for the events to watch. Setting it to
|
||||||
|
\c 0 will stop watching for network events.
|
||||||
|
\param[in] target A BMessenger object to where the notification messages
|
||||||
|
will be delivered.
|
||||||
|
|
||||||
|
\retval B_OK \a target was subscribed to receive network notifications.
|
||||||
|
\retval B_NOT_SUPPORTED The network notifications API is not supported.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t start_watching_network(uint32 flags, const BHandler* target,
|
||||||
|
const BLooper* looper = NULL)
|
||||||
|
\brief Subscribes \a target or \a looper to receive network notifications.
|
||||||
|
|
||||||
|
For the valid values for \a flags and the notifications that will be
|
||||||
|
received by the subscriber, see
|
||||||
|
start_watching_network(uint32, const BMessenger&).
|
||||||
|
|
||||||
|
\retval B_OK \a target or \a looper was subscribed to receive
|
||||||
|
network notifications.
|
||||||
|
\retval B_NOT_SUPPORTED The network notifications API is not supported.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t stop_watching_network(const BMessenger& target)
|
||||||
|
\brief Unsubscribes \a target from receiving network messages.
|
||||||
|
|
||||||
|
\retval B_OK \a target was unsubscribed from receiving network notifications.
|
||||||
|
\retval B_NOT_SUPPORTED The network notifications API is not supported.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t stop_watching_network(const BHandler* target,
|
||||||
|
const BLooper* looper = NULL)
|
||||||
|
\brief Unsubscribes \a target or \a looper from receiving network messages.
|
||||||
|
|
||||||
|
\retval B_OK \a target or \a looper was subscribed from receiving
|
||||||
|
network notifications.
|
||||||
|
\retval B_NOT_SUPPORTED The network notifications API is not supported.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
@@ -0,0 +1,296 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2025 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/net/NetworkRoster.h hrev59275
|
||||||
|
* src/kits/network/libnetapi/NetworkRoster.cpp hrev59275
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file NetworkRoster.h
|
||||||
|
\ingroup network
|
||||||
|
\brief Provides the BNetworkRoster class.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\class BNetworkRoster
|
||||||
|
\ingroup network
|
||||||
|
\brief BNetworkRoster class allows to manage network interfaces as well as
|
||||||
|
persistent (wireless) networks.
|
||||||
|
|
||||||
|
To use this class you have to call the default instance:
|
||||||
|
|
||||||
|
\code{.cpp}
|
||||||
|
BNetworkRoster& roster = BNetworkRoster::Default();
|
||||||
|
\endcode
|
||||||
|
|
||||||
|
Once done, you can manage network interfaces using AddInterface() and
|
||||||
|
RemoveInterface(), or enumerate them using CountInterfaces() and
|
||||||
|
GetNextInterface().
|
||||||
|
|
||||||
|
You can also manage persistent networks using AddPersistentNetwork() and
|
||||||
|
RemovePersistentNetwork(), as well as enumerate them using
|
||||||
|
CountPersistentNetworks() and GetNextPersistentNetwork().
|
||||||
|
|
||||||
|
In addition, you can have access to the network notifications API using
|
||||||
|
StartWatching() and StopWatching(), attaching to it a BMessenger instance
|
||||||
|
as a parameter to start or stop monitoring for network related events.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static BNetworkRoster& BNetworkRoster::Default()
|
||||||
|
\brief Returns the default network roster.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Network interfaces
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn size_t BNetworkRoster::CountInterfaces() const
|
||||||
|
\brief Returns the number of network interfaces in the system.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::GetNextInterface(uint32* cookie, BNetworkInterface& interface) const
|
||||||
|
\brief Iterate through the network interfaces.
|
||||||
|
|
||||||
|
\param[out] cookie A cookie used to keep track of where you are in the list
|
||||||
|
of network interfaces. Before doing the first query, it has to be
|
||||||
|
initialized to \c 0. After that, pass the cookie to each subsequent call
|
||||||
|
to progress the iterator.
|
||||||
|
\param[out] interface A pre-allocated BNetworkInterface where to write the
|
||||||
|
network interface information. For each successful iteration,
|
||||||
|
the existing contents is overwritten.
|
||||||
|
|
||||||
|
\returns \c B_OK if the iteration was successful, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK The iteration was successful and the current
|
||||||
|
interface information was written to \a interface.
|
||||||
|
\retval B_BAD_VALUE \a cookie is \c NULL, or no more interfaces were found.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::AddInterface(const char* name)
|
||||||
|
\brief Add a network interface identified by \a name.
|
||||||
|
|
||||||
|
\param[in] name The name of the interface.
|
||||||
|
|
||||||
|
\returns B_OK if the interface was added, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::AddInterface(const BNetworkInterface& interface)
|
||||||
|
\brief Add a network interface from a BNetworkInterface object.
|
||||||
|
|
||||||
|
\param[in] interface A BNetworkInterface object from where
|
||||||
|
to create the interface.
|
||||||
|
|
||||||
|
\returns B_OK if the interface was added, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::RemoveInterface(const char* name)
|
||||||
|
\brief Remove the network interface identified by \a name.
|
||||||
|
|
||||||
|
\param[in] name The name of the interface.
|
||||||
|
|
||||||
|
\returns B_OK if the interface was removed, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::RemoveInterface(const BNetworkInterface& interface)
|
||||||
|
\brief Remove the network interface matching a BNetworkInterface object.
|
||||||
|
|
||||||
|
\param[in] interface A BNetworkInterface object from where to get the
|
||||||
|
interface name to remove.
|
||||||
|
|
||||||
|
\returns B_OK if the interface was removed, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK Operation performed successfully.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @}
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Persistent networks
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int32 BNetworkRoster::CountPersistentNetworks() const
|
||||||
|
\brief Returns the number of saved persistent networks.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::GetNextPersistentNetwork(uint32* cookie,
|
||||||
|
wireless_network& network) const
|
||||||
|
\brief Iterate through the saved persistent networks.
|
||||||
|
|
||||||
|
\param[out] cookie A cookie used to keep track of where you are in the list
|
||||||
|
of persistent networks. Before doing the first query, it has to be
|
||||||
|
initialized to \c 0. After that, pass the cookie to each subsequent call
|
||||||
|
to progress the iterator.
|
||||||
|
\param[out] network A pre-allocated wireless_network object where to write
|
||||||
|
the network information. For each successful iteration, the existing
|
||||||
|
contents is overwritten.
|
||||||
|
|
||||||
|
\returns \c B_OK if the iteration was successful, or an error code.
|
||||||
|
|
||||||
|
\retval B_OK The iteration was successful and the current persistent
|
||||||
|
network was written to \a network.
|
||||||
|
\retval B_ERROR There was an error receiving the reply from the net server,
|
||||||
|
the end of the persistent networks was reached,
|
||||||
|
or the network name could not be retrieved.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::AddPersistentNetwork(
|
||||||
|
const wireless_network& network) const
|
||||||
|
\brief Add \a network to the list of persistent networks.
|
||||||
|
|
||||||
|
\param[in] network The wireless_network instance containing the network
|
||||||
|
information.
|
||||||
|
|
||||||
|
\returns \c B_OK on success, or an error code otherwise.
|
||||||
|
|
||||||
|
\retval B_OK The network was added to the persistent network list.
|
||||||
|
\retval B_BAD_VALUE wireless_network::name is NULL or its length
|
||||||
|
is equal to \c 0.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::RemovePersistentNetwork(const char* name) const
|
||||||
|
\brief Remove the persistent network identified as \a name.
|
||||||
|
|
||||||
|
\param[in] name The network name.
|
||||||
|
|
||||||
|
\returns \c B_OK on success, or an error code otherwise.
|
||||||
|
|
||||||
|
\retval B_OK The network was removed successfully.
|
||||||
|
\retval B_BAD_VALUE \a name is NULL or its length is equal to \c 0.
|
||||||
|
\retval B_ENTRY_NOT_FOUND A network \a name could not be found in the
|
||||||
|
persistent networks list.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @}
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\name Notifications API
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @{
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoster::StartWatching(const BMessenger& target,
|
||||||
|
uint32 eventMask)
|
||||||
|
\brief Subscribes \a target to receive network events' notifications
|
||||||
|
described in \a eventMask.
|
||||||
|
|
||||||
|
Valid values for \a eventMask are any combination of the following:
|
||||||
|
- \c ::B_WATCH_NETWORK_INTERFACE_CHANGES
|
||||||
|
- \c ::B_WATCH_NETWORK_LINK_CHANGES
|
||||||
|
- \c ::B_WATCH_NETWORK_WLAN_CHANGES
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_INTERFACE_CHANGES, the following notifications
|
||||||
|
will be sent to \a target if such events happen:
|
||||||
|
- \c ::B_NETWORK_INTERFACE_ADDED
|
||||||
|
- \c ::B_NETWORK_INTERFACE_REMOVED
|
||||||
|
- \c ::B_NETWORK_INTERFACE_CHANGED
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_LINK_CHANGES, the following notification
|
||||||
|
will be sent to \a target if such event happens:
|
||||||
|
- \c ::B_NETWORK_DEVICE_LINK_CHANGED
|
||||||
|
|
||||||
|
For \c B_WATCH_NETWORK_WLAN_CHANGES, the following notifications
|
||||||
|
will be sent to \a target if such events happen:
|
||||||
|
- \c ::B_NETWORK_WLAN_JOINED
|
||||||
|
- \c ::B_NETWORK_WLAN_LEFT
|
||||||
|
- \c ::B_NETWORK_WLAN_SCANNED
|
||||||
|
- \c ::B_NETWORK_WLAN_MESSAGE_INTEGRITY_FAILED
|
||||||
|
|
||||||
|
If \a eventMask is \c 0, it will stop sending notifications to \a target.
|
||||||
|
|
||||||
|
\param[in] target A BMessenger object to where the notification messages
|
||||||
|
will be delivered.
|
||||||
|
\param[in] eventMask A flags mask for the events to watch. Setting it to
|
||||||
|
\c 0 will stop watching for network events (the same as calling
|
||||||
|
StopWatching()).
|
||||||
|
|
||||||
|
\returns \c B_OK on success or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoster::StopWatching(const BMessenger& target)
|
||||||
|
\brief Unsubscribes \a target from receiving network messages.
|
||||||
|
|
||||||
|
\param[in] target A BMessenger object that will not be sent any more messages.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
//! @}
|
||||||
@@ -0,0 +1,337 @@
|
|||||||
|
/*
|
||||||
|
* Copyright 2026 Haiku, Inc. All rights reserved.
|
||||||
|
* Distributed under the terms of the MIT License.
|
||||||
|
*
|
||||||
|
* Authors:
|
||||||
|
* cafeina
|
||||||
|
*
|
||||||
|
* Corresponds to:
|
||||||
|
* headers/os/net/NetworkRoute.h hrev59275
|
||||||
|
* src/kits/network/libnetapi/NetworkRoute.cpp hrev59275
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\file NetworkRoute.h
|
||||||
|
\ingroup network
|
||||||
|
\brief Provides the BNetworkRoute class.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\class BNetworkRoute
|
||||||
|
\ingroup network
|
||||||
|
\brief BNetworkRoute class represents a network route, a path for
|
||||||
|
traffic across one or multiple networks.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BNetworkRoute::BNetworkRoute()
|
||||||
|
\brief Creates an uninitialized BNetworkRoute object.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn BNetworkRoute::~BNetworkRoute()
|
||||||
|
\brief Releases all the allocated resources.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetTo(const BNetworkRoute& other)
|
||||||
|
\brief Initializes this object from \a other BNetworkRoute object.
|
||||||
|
|
||||||
|
\param[in] other The BNetworkRoute instance from where to
|
||||||
|
initialize this object.
|
||||||
|
|
||||||
|
\return \c B_OK if the object was initialized or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetTo(const route_entry& routeEntry)
|
||||||
|
\brief Initializes this object from a route_entry instance.
|
||||||
|
|
||||||
|
\param[in] routeEntry A route_entry object with the routing information.
|
||||||
|
|
||||||
|
\return \c B_OK if the object was initialized or an error code.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::Adopt(BNetworkRoute& other)
|
||||||
|
\brief Moves \a other to this instance.
|
||||||
|
|
||||||
|
\a other is left uninitialized.
|
||||||
|
|
||||||
|
\param other The other BNetworkRoute object.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const route_entry& BNetworkRoute::RouteEntry() const
|
||||||
|
\brief Returns a copy of the route_entry with routing information of this
|
||||||
|
object.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const sockaddr* BNetworkRoute::Destination() const
|
||||||
|
\brief Returns the destination address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetDestination(const sockaddr& destination)
|
||||||
|
\brief Sets the destination address.
|
||||||
|
|
||||||
|
\param[in] destination A sockaddr struct instance with the destination
|
||||||
|
information.
|
||||||
|
|
||||||
|
\retval B_OK The destination has been modified successfully.
|
||||||
|
\retval B_BAD_VALUE The length in \a destination.sa_len is higher than
|
||||||
|
the size of sockaddr_storage struct.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::UnsetDestination()
|
||||||
|
\brief Uninitializes the destination address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const sockaddr* BNetworkRoute::Mask() const
|
||||||
|
\brief Returns the subnet mask address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetMask(const sockaddr& mask)
|
||||||
|
\brief Sets the subnet mask address.
|
||||||
|
|
||||||
|
\param[in] mask A sockaddr struct instance with the mask information.
|
||||||
|
|
||||||
|
\retval B_OK The mask has been modified successfully.
|
||||||
|
\retval B_BAD_VALUE The length in \a mask.sa_len is higher than
|
||||||
|
the size of sockaddr_storage struct.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::UnsetMask()
|
||||||
|
\brief Uninitializes the subnet mask address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const sockaddr* BNetworkRoute::Gateway() const
|
||||||
|
\brief Returns the gateway address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetGateway(const sockaddr& gateway)
|
||||||
|
\brief Sets the gateway address.
|
||||||
|
|
||||||
|
\param[in] gateway A sockaddr struct instance with the gateway information.
|
||||||
|
|
||||||
|
\retval B_OK The gateway has been modified successfully.
|
||||||
|
\retval B_BAD_VALUE The length in \a gateway.sa_len is higher than
|
||||||
|
the size of sockaddr_storage struct.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::UnsetGateway()
|
||||||
|
\brief Uninitializes the gateway address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn const sockaddr* BNetworkRoute::Source() const
|
||||||
|
\brief Returns the source address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn status_t BNetworkRoute::SetSource(const sockaddr& source)
|
||||||
|
\brief Sets the source address.
|
||||||
|
|
||||||
|
\param[in] source A sockaddr struct instance with the source address
|
||||||
|
information.
|
||||||
|
|
||||||
|
\retval B_OK The source address has been modified successfully.
|
||||||
|
\retval B_BAD_VALUE The length in \a source.sa_len is higher than
|
||||||
|
the size of sockaddr_storage struct.
|
||||||
|
\retval B_NO_MEMORY Internal memory allocation error.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::UnsetSource()
|
||||||
|
\brief Uninitializes the source address.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn uint32 BNetworkRoute::Flags() const
|
||||||
|
\brief Returns the route's flags mask.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::SetFlags(uint32 flags)
|
||||||
|
\brief Sets the route's flags mask.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn uint32 BNetworkRoute::MTU() const
|
||||||
|
\brief Returns the maximum transmission unit size of the route.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn void BNetworkRoute::SetMTU(uint32 mtu)
|
||||||
|
\brief Sets the maximum transmission unit size of the route.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn int BNetworkRoute::AddressFamily() const
|
||||||
|
\brief Returns the route's address family.
|
||||||
|
|
||||||
|
If this object is uninitialized, it returns \c AF_UNSPEC.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static status_t BNetworkRoute::GetDefaultRoute(int family,
|
||||||
|
const char* interfaceName, BNetworkRoute& route)
|
||||||
|
\brief Gets the default route.
|
||||||
|
|
||||||
|
\param[in] family The address family. See the POSIX header file
|
||||||
|
sys/socket.h for the address families.
|
||||||
|
\param[in] interfaceName The network interface name.
|
||||||
|
\param[out] route A BNetworkRoute where to write the default route.
|
||||||
|
|
||||||
|
\retval B_OK The default route was successfully retrieved.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There is not a default route configured.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static status_t BNetworkRoute::GetDefaultGateway(int family,
|
||||||
|
const char* interfaceName, sockaddr& gateway)
|
||||||
|
\brief Gets the default gateway.
|
||||||
|
|
||||||
|
\param[in] family The address family. See the POSIX header file
|
||||||
|
sys/socket.h for the address families.
|
||||||
|
\param[in] interfaceName The network interface name.
|
||||||
|
\param[out] gateway A sockaddr instance where to write the default gateway.
|
||||||
|
|
||||||
|
\return \c B_OK on success, or an error code otherwise.
|
||||||
|
|
||||||
|
\retval B_OK The default gateway was successfully retrieved.
|
||||||
|
\retval B_ENTRY_NOT_FOUND There is not a default route or
|
||||||
|
a default gateway configured.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static status_t BNetworkRoute::GetRoutes(int family,
|
||||||
|
BObjectList<BNetworkRoute, true>& routes)
|
||||||
|
\brief Returns the routes of \a family type into \a routes.
|
||||||
|
|
||||||
|
\sa BNetworkRoute::GetRoutes(int, const char*,
|
||||||
|
uint32, BObjectList<BNetworkRoute, true>&)
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static status_t BNetworkRoute::GetRoutes(int family, const char* interfaceName,
|
||||||
|
BObjectList<BNetworkRoute, true>& routes)
|
||||||
|
\brief Returns the routes of \a family type in \a interfaceName
|
||||||
|
into \a routes.
|
||||||
|
|
||||||
|
\sa BNetworkRoute::GetRoutes(int, const char*,
|
||||||
|
uint32, BObjectList<BNetworkRoute, true>&)
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
/*!
|
||||||
|
\fn static status_t BNetworkRoute::GetRoutes(int family, const char* interfaceName,
|
||||||
|
uint32 filterFlags, BObjectList<BNetworkRoute, true>& routes)
|
||||||
|
\brief Returns the routes of \a family type in \a interfaceName that are not
|
||||||
|
filtered by \a filterFlags into \a routes.
|
||||||
|
|
||||||
|
\param[in] family The address family. See the POSIX header file
|
||||||
|
sys/socket.h for the address families.
|
||||||
|
\param[in] interfaceName The network interface name.
|
||||||
|
\param[in] filterFlags Flag mask to filter out routes. See the
|
||||||
|
POSIX header file net/route.h for the valid route flags.
|
||||||
|
\param[out] routes A BObjectList of BNetworkRoute to store the found routes.
|
||||||
|
|
||||||
|
\since Haiku R1
|
||||||
|
*/
|
||||||
Reference in New Issue
Block a user