NMDeviceWifi: libnm Reference Manual

- - -

NMDeviceWifi

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

const char * -	-nm_device_wifi_get_hw_address () -
const char * -	-nm_device_wifi_get_permanent_hw_address () -
-NM80211Mode -	-nm_device_wifi_get_mode () -
-guint32 -	-nm_device_wifi_get_bitrate () -
-NMDeviceWifiCapabilities -	-nm_device_wifi_get_capabilities () -
-NMAccessPoint * -	-nm_device_wifi_get_active_access_point () -
-NMAccessPoint * -	-nm_device_wifi_get_access_point_by_path () -
const GPtrArray * -	-nm_device_wifi_get_access_points () -
-gint64 -	-nm_device_wifi_get_last_scan () -
-gboolean -	-nm_device_wifi_request_scan () -
-gboolean -	-nm_device_wifi_request_scan_options () -
-void -	-nm_device_wifi_request_scan_async () -
-void -	-nm_device_wifi_request_scan_options_async () -
-gboolean -	-nm_device_wifi_request_scan_finish () -

Properties

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-GPtrArray *	access-points	Read
-NMAccessPoint *	active-access-point	Read
guint	bitrate	Read
gint64	last-scan	Read
NM80211Mode	mode	Read
-char *	perm-hw-address	Read
NMDeviceWifiCapabilities	wireless-capabilities	Read

Signals

----- - - - - - - - - - - - - -

void	access-point-added	Run First
void	access-point-removed	Run First

Types and Values

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#define	NM_DEVICE_WIFI_HW_ADDRESS
#define	NM_DEVICE_WIFI_PERMANENT_HW_ADDRESS
#define	NM_DEVICE_WIFI_MODE
#define	NM_DEVICE_WIFI_BITRATE
#define	NM_DEVICE_WIFI_ACTIVE_ACCESS_POINT
#define	NM_DEVICE_WIFI_CAPABILITIES
#define	NM_DEVICE_WIFI_ACCESS_POINTS
#define	NM_DEVICE_WIFI_LAST_SCAN
	NMDeviceWifi

Object Hierarchy

    GObject
-    ╰── NMObject
-        ╰── NMDevice
-            ╰── NMDeviceWifi
-

Description

Functions

nm_device_wifi_get_hw_address ()

const char *
-nm_device_wifi_get_hw_address (NMDeviceWifi *device);

nm_device_wifi_get_hw_address has been deprecated since version 1.24 and should not be used in newly-written code.

Use nm_device_get_hw_address() instead.

Gets the actual hardware (MAC) address of the NMDeviceWifi

[skip]

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the actual hardware address. This is the internal string used by the -device, and must not be modified.

nm_device_wifi_get_permanent_hw_address ()

const char *
-nm_device_wifi_get_permanent_hw_address
-                               (NMDeviceWifi *device);

Gets the permanent hardware (MAC) address of the NMDeviceWifi

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the permanent hardware address. This is the internal string used by the -device, and must not be modified.

nm_device_wifi_get_mode ()

NM80211Mode
-nm_device_wifi_get_mode (NMDeviceWifi *device);

Gets the NMDeviceWifi mode.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the mode

nm_device_wifi_get_bitrate ()

guint32
-nm_device_wifi_get_bitrate (NMDeviceWifi *device);

Gets the bit rate of the NMDeviceWifi in kbit/s.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the bit rate (kbit/s)

nm_device_wifi_get_capabilities ()

NMDeviceWifiCapabilities
-nm_device_wifi_get_capabilities (NMDeviceWifi *device);

Gets the Wi-Fi capabilities of the NMDeviceWifi.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the capabilities

nm_device_wifi_get_active_access_point ()

NMAccessPoint *
-nm_device_wifi_get_active_access_point
-                               (NMDeviceWifi *device);

Gets the active NMAccessPoint.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the access point or NULL if none is active.

[transfer none]

nm_device_wifi_get_access_point_by_path ()

NMAccessPoint *
-nm_device_wifi_get_access_point_by_path
-                               (NMDeviceWifi *device,
-                                const char *path);

Gets a NMAccessPoint by path.

Parameters

----- - - - - - - - - - - - - -

device	a NMDeviceWifi
path	the object path of the access point

Returns

the access point or NULL if none is found.

[transfer none]

nm_device_wifi_get_access_points ()

const GPtrArray *
-nm_device_wifi_get_access_points (NMDeviceWifi *device);

Gets all the scanned access points of the NMDeviceWifi.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

a GPtrArray containing all the -scanned NMAccessPoints. -The returned array is owned by the client and should not be modified.

[element-type NMAccessPoint]

nm_device_wifi_get_last_scan ()

gint64
-nm_device_wifi_get_last_scan (NMDeviceWifi *device);

Returns the timestamp (in CLOCK_BOOTTIME milliseconds) for the last finished -network scan. A value of -1 means the device never scanned for access points.

Use nm_utils_get_timestamp_msec() to obtain current time value suitable for -comparing to this value.

Parameters

----- - - - - - -

device

a NMDeviceWifi

Returns

the last scan time in milliseconds (in clock_gettime(CLOCK_BOOTTIME) scale).

Since: 1.12

nm_device_wifi_request_scan ()

gboolean
-nm_device_wifi_request_scan (NMDeviceWifi *device,
-                             GCancellable *cancellable,
-                             GError **error);

nm_device_wifi_request_scan has been deprecated since version 1.22 and should not be used in newly-written code.

Use nm_device_wifi_request_scan_async() or GDBusConnection.

Request NM to scan for access points on device -. Note that the function -returns immediately after requesting the scan, and it may take some time -after that for the scan to complete.

Parameters

----- - - - - - - - - - - - - - - - - - -

device	a NMDeviceWifi
cancellable	a GCancellable, or `NULL`
error	location for a GError, or `NULL`

Returns

TRUE on success, FALSE on error, in which case error -will be -set.

nm_device_wifi_request_scan_options ()

gboolean
-nm_device_wifi_request_scan_options (NMDeviceWifi *device,
-                                     GVariant *options,
-                                     GCancellable *cancellable,
-                                     GError **error);

nm_device_wifi_request_scan_options has been deprecated since version 1.22 and should not be used in newly-written code.

Use nm_device_wifi_request_scan_options_async() or GDBusConnection.

Request NM to scan for access points on device -. Note that the function -returns immediately after requesting the scan, and it may take some time -after that for the scan to complete. -This is the same as nm_device_wifi_request_scan - except it accepts options - -for the scanning. The argument is the dictionary passed to RequestScan() -D-Bus call. Valid options inside the dictionary are: -'ssids' => array of SSIDs (saay)

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

device	a NMDeviceWifi
options	dictionary with options for `RequestScan()`, or `NULL`
cancellable	a GCancellable, or `NULL`
error	location for a GError, or `NULL`

Returns

TRUE on success, FALSE on error, in which case error -will be -set.

Since: 1.2

nm_device_wifi_request_scan_async ()

void
-nm_device_wifi_request_scan_async (NMDeviceWifi *device,
-                                   GCancellable *cancellable,
-                                   GAsyncReadyCallback callback,
-                                   gpointer user_data);

Request NM to scan for access points on device -. Note that callback - will be -called immediately after requesting the scan, and it may take some time after -that for the scan to complete.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

device	a NMDeviceWifi
cancellable	a GCancellable, or `NULL`
callback	callback to be called when the scan has been requested
user_data	caller-specific data passed to `callback` -

nm_device_wifi_request_scan_options_async ()

void
-nm_device_wifi_request_scan_options_async
-                               (NMDeviceWifi *device,
-                                GVariant *options,
-                                GCancellable *cancellable,
-                                GAsyncReadyCallback callback,
-                                gpointer user_data);

Request NM to scan for access points on device -. Note that callback - will be -called immediately after requesting the scan, and it may take some time after -that for the scan to complete. -This is the same as nm_device_wifi_request_scan_async - except it accepts options - -for the scanning. The argument is the dictionary passed to RequestScan() -D-Bus call. Valid options inside the dictionary are: -'ssids' => array of SSIDs (saay)

To complete the request call nm_device_wifi_request_scan_finish().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

device	a NMDeviceWifi
options	dictionary with options for `RequestScan()`, or `NULL`
cancellable	a GCancellable, or `NULL`
callback	callback to be called when the scan has been requested
user_data	caller-specific data passed to `callback` -

Since: 1.2

nm_device_wifi_request_scan_finish ()

gboolean
-nm_device_wifi_request_scan_finish (NMDeviceWifi *device,
-                                    GAsyncResult *result,
-                                    GError **error);

Gets the result of a call to nm_device_wifi_request_scan_async() and -nm_device_wifi_request_scan_options_async().

Parameters

----- - - - - - - - - - - - - - - - - - -

device	a NMDeviceWifi
result	the result passed to the GAsyncReadyCallback
error	location for a GError, or `NULL`

Returns

TRUE on success, FALSE on error, in which case error -will be -set.

Types and Values

NM_DEVICE_WIFI_HW_ADDRESS

#define NM_DEVICE_WIFI_HW_ADDRESS           "hw-address"
-

NM_DEVICE_WIFI_PERMANENT_HW_ADDRESS

#define NM_DEVICE_WIFI_PERMANENT_HW_ADDRESS "perm-hw-address"
-

NM_DEVICE_WIFI_MODE

#define NM_DEVICE_WIFI_MODE                 "mode"
-

NM_DEVICE_WIFI_BITRATE

#define NM_DEVICE_WIFI_BITRATE              "bitrate"
-

NM_DEVICE_WIFI_ACTIVE_ACCESS_POINT

#define NM_DEVICE_WIFI_ACTIVE_ACCESS_POINT  "active-access-point"
-

NM_DEVICE_WIFI_CAPABILITIES

#define NM_DEVICE_WIFI_CAPABILITIES         "wireless-capabilities"
-

NM_DEVICE_WIFI_ACCESS_POINTS

#define NM_DEVICE_WIFI_ACCESS_POINTS        "access-points"
-

NM_DEVICE_WIFI_LAST_SCAN

#define NM_DEVICE_WIFI_LAST_SCAN            "last-scan"
-

NMDeviceWifi

typedef struct _NMDeviceWifi NMDeviceWifi;

Property Details

The `“access-points”` property

  “access-points”            GPtrArray *

List of all Wi-Fi access points the device can see.

[type GPtrArray(NMAccessPoint)]

Owner: NMDeviceWifi

Flags: Read

The `“active-access-point”` property

  “active-access-point”      NMAccessPoint *

The active NMAccessPoint of the device.

Owner: NMDeviceWifi

Flags: Read

The `“bitrate”` property

  “bitrate”                  guint

The bit rate of the device in kbit/s.

Owner: NMDeviceWifi

Flags: Read

Default value: 0

The `“last-scan”` property

  “last-scan”                gint64

The timestamp (in CLOCK_BOOTTIME seconds) for the last finished -network scan. A value of -1 means the device never scanned for -access points.

Owner: NMDeviceWifi

Flags: Read

Allowed values: >= -1

Default value: -1

Since: 1.12

The `“mode”` property

  “mode”                     NM80211Mode

The mode of the device.

Owner: NMDeviceWifi

Flags: Read

Default value: NM_802_11_MODE_UNKNOWN

The `“perm-hw-address”` property

  “perm-hw-address”          char *

The hardware (MAC) address of the device.

Owner: NMDeviceWifi

Flags: Read

Default value: NULL

The `“wireless-capabilities”` property

  “wireless-capabilities”    NMDeviceWifiCapabilities

The wireless capabilities of the device.

Owner: NMDeviceWifi

Flags: Read

Signal Details

The `“access-point-added”` signal

void
-user_function (NMDeviceWifi *device,
-               GObject      *ap,
-               gpointer      user_data)

Notifies that a NMAccessPoint is added to the Wi-Fi device.

Parameters

----- - - - - - - - - - - - - - - - - - -

device	the Wi-Fi device that received the signal
ap	the new access point
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“access-point-removed”` signal

void
-user_function (NMDeviceWifi *device,
-               GObject      *ap,
-               gpointer      user_data)

Notifies that a NMAccessPoint is removed from the Wi-Fi device.

Parameters

----- - - - - - - - - - - - - - - - - - -

device	the Wi-Fi device that received the signal
ap	the removed access point
user_data	user data set when the signal handler was connected.

Flags: Run First

NMDeviceWifi

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Functions

nm_device_wifi_get_hw_address ()

Parameters

Returns

nm_device_wifi_get_permanent_hw_address ()

Parameters

Returns

nm_device_wifi_get_mode ()

Parameters

Returns

nm_device_wifi_get_bitrate ()

Parameters

Returns

nm_device_wifi_get_capabilities ()

Parameters

Returns

nm_device_wifi_get_active_access_point ()

Parameters

Returns

nm_device_wifi_get_access_point_by_path ()

Parameters

Returns

nm_device_wifi_get_access_points ()

Parameters

Returns

nm_device_wifi_get_last_scan ()

Parameters

Returns

nm_device_wifi_request_scan ()

Parameters

Returns

nm_device_wifi_request_scan_options ()

Parameters

Returns

nm_device_wifi_request_scan_async ()

Parameters

nm_device_wifi_request_scan_options_async ()

Parameters

nm_device_wifi_request_scan_finish ()

Parameters

Returns

Types and Values

NM_DEVICE_WIFI_HW_ADDRESS

NM_DEVICE_WIFI_PERMANENT_HW_ADDRESS

NM_DEVICE_WIFI_MODE

NM_DEVICE_WIFI_BITRATE

NM_DEVICE_WIFI_ACTIVE_ACCESS_POINT

NM_DEVICE_WIFI_CAPABILITIES

NM_DEVICE_WIFI_ACCESS_POINTS

NM_DEVICE_WIFI_LAST_SCAN

NMDeviceWifi

Property Details

The “access-points” property

The “active-access-point” property

The “bitrate” property

The “last-scan” property

The “mode” property

The “perm-hw-address” property

The “wireless-capabilities” property

Signal Details

The “access-point-added” signal

Parameters

The “access-point-removed” signal

Parameters

The `“access-points”` property

The `“active-access-point”` property

The `“bitrate”` property

The `“last-scan”` property

The `“mode”` property

The `“perm-hw-address”` property

The `“wireless-capabilities”` property

The `“access-point-added”` signal

The `“access-point-removed”` signal