NetworkManager/libnm/nm-client.h
Thomas Haller 35b024acaa libnm: hide NMClient struct from public headers and use direct private field
Having the NMClient/NMClientClass structs in the public header allows
the user to subclass these types. Subclassing this type was never
intended, nor is it supported, nor does it seem useful. Subclassing only
makes sense if the type has suitable hooks to extend the type in a
meaningful way. NMClient hasn't, and everybody trying to derive from
this class would better delegate the actions.

Also, having these structs in the public header prevents us from
embedding the private data in the object structure itself.
It has thus an runtime overhead and is less convenient for debugging (it's
hard to find the private data pointer in gdb).

Most importantly, there is no easy way to find the offset of the private
data fields, short of calling NM_CLIENT_GET_PRIVATE() -- which currently
is a macro. Later we want to generically lookup the offset of the
private data, we would need NM_CLIENT_GET_PRIVATE() as a function.
Instead, by having an internally, statically known offset, we can use
that offset instead.

Also drop all signal hooks. They are also not useful.

This is an ABI and API change, but of something that we never wanted to
be part of the ABI/API, and which hopefull nobody is using.
2019-10-21 18:34:54 +02:00

516 lines
24 KiB
C

// SPDX-License-Identifier: LGPL-2.1+
/*
* Copyright (C) 2007 - 2008 Novell, Inc.
* Copyright (C) 2007 - 2014 Red Hat, Inc.
*/
#ifndef __NM_CLIENT_H__
#define __NM_CLIENT_H__
#if !defined (__NETWORKMANAGER_H_INSIDE__) && !defined (NETWORKMANAGER_COMPILATION)
#error "Only <NetworkManager.h> can be included directly."
#endif
#include "nm-types.h"
G_BEGIN_DECLS
#define NM_TYPE_CLIENT (nm_client_get_type ())
#define NM_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_CLIENT, NMClient))
#define NM_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_CLIENT, NMClientClass))
#define NM_IS_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_CLIENT))
#define NM_IS_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_CLIENT))
#define NM_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_CLIENT, NMClientClass))
#define NM_CLIENT_VERSION "version"
#define NM_CLIENT_STATE "state"
#define NM_CLIENT_STARTUP "startup"
#define NM_CLIENT_NM_RUNNING "nm-running"
#define NM_CLIENT_DBUS_CONNECTION "dbus-connection"
#define NM_CLIENT_DBUS_NAME_OWNER "dbus-name-owner"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
#define NM_CLIENT_NETWORKING_ENABLED "networking-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
#define NM_CLIENT_WIRELESS_ENABLED "wireless-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
#define NM_CLIENT_WWAN_ENABLED "wwan-enabled"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
#define NM_CLIENT_WIMAX_ENABLED "wimax-enabled"
#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
#define NM_CLIENT_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"
#define NM_CLIENT_WIMAX_HARDWARE_ENABLED "wimax-hardware-enabled"
#define NM_CLIENT_ACTIVE_CONNECTIONS "active-connections"
#define NM_CLIENT_CONNECTIVITY "connectivity"
#define NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE "connectivity-check-available"
_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
#define NM_CLIENT_CONNECTIVITY_CHECK_ENABLED "connectivity-check-enabled"
#define NM_CLIENT_PRIMARY_CONNECTION "primary-connection"
#define NM_CLIENT_ACTIVATING_CONNECTION "activating-connection"
#define NM_CLIENT_DEVICES "devices"
#define NM_CLIENT_ALL_DEVICES "all-devices"
#define NM_CLIENT_CONNECTIONS "connections"
#define NM_CLIENT_HOSTNAME "hostname"
#define NM_CLIENT_CAN_MODIFY "can-modify"
#define NM_CLIENT_METERED "metered"
#define NM_CLIENT_DNS_MODE "dns-mode"
#define NM_CLIENT_DNS_RC_MANAGER "dns-rc-manager"
#define NM_CLIENT_DNS_CONFIGURATION "dns-configuration"
#define NM_CLIENT_DEVICE_ADDED "device-added"
#define NM_CLIENT_DEVICE_REMOVED "device-removed"
#define NM_CLIENT_ANY_DEVICE_ADDED "any-device-added"
#define NM_CLIENT_ANY_DEVICE_REMOVED "any-device-removed"
#define NM_CLIENT_PERMISSION_CHANGED "permission-changed"
#define NM_CLIENT_CONNECTION_ADDED "connection-added"
#define NM_CLIENT_CONNECTION_REMOVED "connection-removed"
#define NM_CLIENT_ACTIVE_CONNECTION_ADDED "active-connection-added"
#define NM_CLIENT_ACTIVE_CONNECTION_REMOVED "active-connection-removed"
/**
* NMClientPermission:
* @NM_CLIENT_PERMISSION_NONE: unknown or no permission
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_NETWORK: controls whether networking
* can be globally enabled or disabled
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIFI: controls whether Wi-Fi can be
* globally enabled or disabled
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_WWAN: controls whether WWAN (3G) can be
* globally enabled or disabled
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIMAX: controls whether WiMAX can be
* globally enabled or disabled
* @NM_CLIENT_PERMISSION_SLEEP_WAKE: controls whether the client can ask
* NetworkManager to sleep and wake
* @NM_CLIENT_PERMISSION_NETWORK_CONTROL: controls whether networking connections
* can be started, stopped, and changed
* @NM_CLIENT_PERMISSION_WIFI_SHARE_PROTECTED: controls whether a password
* protected Wi-Fi hotspot can be created
* @NM_CLIENT_PERMISSION_WIFI_SHARE_OPEN: controls whether an open Wi-Fi hotspot
* can be created
* @NM_CLIENT_PERMISSION_SETTINGS_MODIFY_SYSTEM: controls whether connections
* that are available to all users can be modified
* @NM_CLIENT_PERMISSION_SETTINGS_MODIFY_OWN: controls whether connections
* owned by the current user can be modified
* @NM_CLIENT_PERMISSION_SETTINGS_MODIFY_HOSTNAME: controls whether the
* persistent hostname can be changed
* @NM_CLIENT_PERMISSION_SETTINGS_MODIFY_GLOBAL_DNS: modify persistent global
* DNS configuration
* @NM_CLIENT_PERMISSION_RELOAD: controls access to Reload.
* @NM_CLIENT_PERMISSION_CHECKPOINT_ROLLBACK: permission to create checkpoints.
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_STATISTICS: controls whether device
* statistics can be globally enabled or disabled
* @NM_CLIENT_PERMISSION_ENABLE_DISABLE_CONNECTIVITY_CHECK: controls whether
* connectivity check can be enabled or disabled
* @NM_CLIENT_PERMISSION_WIFI_SCAN: controls whether wifi scans can be performed
* @NM_CLIENT_PERMISSION_LAST: a reserved boundary value
*
* #NMClientPermission values indicate various permissions that NetworkManager
* clients can obtain to perform certain tasks on behalf of the current user.
**/
typedef enum {
NM_CLIENT_PERMISSION_NONE = 0,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_NETWORK = 1,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIFI = 2,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WWAN = 3,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIMAX = 4,
NM_CLIENT_PERMISSION_SLEEP_WAKE = 5,
NM_CLIENT_PERMISSION_NETWORK_CONTROL = 6,
NM_CLIENT_PERMISSION_WIFI_SHARE_PROTECTED = 7,
NM_CLIENT_PERMISSION_WIFI_SHARE_OPEN = 8,
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_SYSTEM = 9,
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_OWN = 10,
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_HOSTNAME = 11,
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_GLOBAL_DNS = 12,
NM_CLIENT_PERMISSION_RELOAD = 13,
NM_CLIENT_PERMISSION_CHECKPOINT_ROLLBACK = 14,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_STATISTICS = 15,
NM_CLIENT_PERMISSION_ENABLE_DISABLE_CONNECTIVITY_CHECK = 16,
NM_CLIENT_PERMISSION_WIFI_SCAN = 17,
NM_CLIENT_PERMISSION_LAST = 17,
} NMClientPermission;
/**
* NMClientPermissionResult:
* @NM_CLIENT_PERMISSION_RESULT_UNKNOWN: unknown or no authorization
* @NM_CLIENT_PERMISSION_RESULT_YES: the permission is available
* @NM_CLIENT_PERMISSION_RESULT_AUTH: authorization is necessary before the
* permission is available
* @NM_CLIENT_PERMISSION_RESULT_NO: permission to perform the operation is
* denied by system policy
*
* #NMClientPermissionResult values indicate what authorizations and permissions
* the user requires to obtain a given #NMClientPermission
**/
typedef enum {
NM_CLIENT_PERMISSION_RESULT_UNKNOWN = 0,
NM_CLIENT_PERMISSION_RESULT_YES,
NM_CLIENT_PERMISSION_RESULT_AUTH,
NM_CLIENT_PERMISSION_RESULT_NO
} NMClientPermissionResult;
/**
* NMClientError:
* @NM_CLIENT_ERROR_FAILED: unknown or unclassified error
* @NM_CLIENT_ERROR_MANAGER_NOT_RUNNING: an operation that requires NetworkManager
* failed because NetworkManager is not running
* @NM_CLIENT_ERROR_OBJECT_CREATION_FAILED: NetworkManager claimed that an
* operation succeeded, but the object that was allegedly created (eg,
* #NMRemoteConnection, #NMActiveConnection) was apparently destroyed before
* #NMClient could create a representation of it.
*
* Describes errors that may result from operations involving a #NMClient.
*
* D-Bus operations may also return errors from other domains, including
* #NMManagerError, #NMSettingsError, #NMAgentManagerError, and #NMConnectionError.
**/
typedef enum {
NM_CLIENT_ERROR_FAILED = 0,
NM_CLIENT_ERROR_MANAGER_NOT_RUNNING,
NM_CLIENT_ERROR_OBJECT_CREATION_FAILED,
} NMClientError;
#define NM_CLIENT_ERROR nm_client_error_quark ()
GQuark nm_client_error_quark (void);
/* DNS stuff */
typedef struct NMDnsEntry NMDnsEntry;
NM_AVAILABLE_IN_1_6
GType nm_dns_entry_get_type (void);
NM_AVAILABLE_IN_1_6
void nm_dns_entry_unref (NMDnsEntry *entry);
NM_AVAILABLE_IN_1_6
const char * nm_dns_entry_get_interface (NMDnsEntry *entry);
NM_AVAILABLE_IN_1_6
const char * const *nm_dns_entry_get_nameservers (NMDnsEntry *entry);
NM_AVAILABLE_IN_1_6
const char * const *nm_dns_entry_get_domains (NMDnsEntry *entry);
NM_AVAILABLE_IN_1_6
int nm_dns_entry_get_priority (NMDnsEntry *entry);
NM_AVAILABLE_IN_1_6
gboolean nm_dns_entry_get_vpn (NMDnsEntry *entry);
/**
* NMClient:
*/
typedef struct _NMClientClass NMClientClass;
GType nm_client_get_type (void);
NMClient *nm_client_new (GCancellable *cancellable,
GError **error);
void nm_client_new_async (GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMClient *nm_client_new_finish (GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_22
GDBusConnection *nm_client_get_dbus_connection (NMClient *client);
NM_AVAILABLE_IN_1_22
const char *nm_client_get_dbus_name_owner (NMClient *client);
const char *nm_client_get_version (NMClient *client);
NMState nm_client_get_state (NMClient *client);
gboolean nm_client_get_startup (NMClient *client);
gboolean nm_client_get_nm_running (NMClient *client);
gboolean nm_client_networking_get_enabled (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_networking_set_enabled (NMClient *client,
gboolean enabled,
GError **error);
gboolean nm_client_wireless_get_enabled (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
void nm_client_wireless_set_enabled (NMClient *client, gboolean enabled);
gboolean nm_client_wireless_hardware_get_enabled (NMClient *client);
gboolean nm_client_wwan_get_enabled (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
void nm_client_wwan_set_enabled (NMClient *client, gboolean enabled);
gboolean nm_client_wwan_hardware_get_enabled (NMClient *client);
gboolean nm_client_wimax_get_enabled (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
void nm_client_wimax_set_enabled (NMClient *client, gboolean enabled);
gboolean nm_client_wimax_hardware_get_enabled (NMClient *client);
NM_AVAILABLE_IN_1_10
gboolean nm_client_connectivity_check_get_available (NMClient *client);
NM_AVAILABLE_IN_1_10
gboolean nm_client_connectivity_check_get_enabled (NMClient *client);
NM_AVAILABLE_IN_1_10
_NM_DEPRECATED_SYNC_METHOD
void nm_client_connectivity_check_set_enabled (NMClient *client,
gboolean enabled);
NM_AVAILABLE_IN_1_20
const char *nm_client_connectivity_check_get_uri (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_get_logging (NMClient *client,
char **level,
char **domains,
GError **error);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_set_logging (NMClient *client,
const char *level,
const char *domains,
GError **error);
NMClientPermissionResult nm_client_get_permission_result (NMClient *client,
NMClientPermission permission);
NMConnectivityState nm_client_get_connectivity (NMClient *client);
_NM_DEPRECATED_SYNC_METHOD
NM_DEPRECATED_IN_1_22
NMConnectivityState nm_client_check_connectivity (NMClient *client,
GCancellable *cancellable,
GError **error);
void nm_client_check_connectivity_async (NMClient *client,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMConnectivityState nm_client_check_connectivity_finish (NMClient *client,
GAsyncResult *result,
GError **error);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_save_hostname (NMClient *client,
const char *hostname,
GCancellable *cancellable,
GError **error);
void nm_client_save_hostname_async (NMClient *client,
const char *hostname,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_client_save_hostname_finish (NMClient *client,
GAsyncResult *result,
GError **error);
/* Devices */
const GPtrArray *nm_client_get_devices (NMClient *client);
NM_AVAILABLE_IN_1_2
const GPtrArray *nm_client_get_all_devices(NMClient *client);
NMDevice *nm_client_get_device_by_path (NMClient *client, const char *object_path);
NMDevice *nm_client_get_device_by_iface (NMClient *client, const char *iface);
/* Active Connections */
const GPtrArray *nm_client_get_active_connections (NMClient *client);
NMActiveConnection *nm_client_get_primary_connection (NMClient *client);
NMActiveConnection *nm_client_get_activating_connection (NMClient *client);
void nm_client_activate_connection_async (NMClient *client,
NMConnection *connection,
NMDevice *device,
const char *specific_object,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMActiveConnection *nm_client_activate_connection_finish (NMClient *client,
GAsyncResult *result,
GError **error);
void nm_client_add_and_activate_connection_async (NMClient *client,
NMConnection *partial,
NMDevice *device,
const char *specific_object,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMActiveConnection *nm_client_add_and_activate_connection_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_16
void nm_client_add_and_activate_connection2 (NMClient *client,
NMConnection *partial,
NMDevice *device,
const char *specific_object,
GVariant *options,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_16
NMActiveConnection *nm_client_add_and_activate_connection2_finish (NMClient *client,
GAsyncResult *result,
GVariant **out_result,
GError **error);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_deactivate_connection (NMClient *client,
NMActiveConnection *active,
GCancellable *cancellable,
GError **error);
void nm_client_deactivate_connection_async (NMClient *client,
NMActiveConnection *active,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_client_deactivate_connection_finish (NMClient *client,
GAsyncResult *result,
GError **error);
/* Connections */
const GPtrArray *nm_client_get_connections (NMClient *client);
NMRemoteConnection *nm_client_get_connection_by_id (NMClient *client, const char *id);
NMRemoteConnection *nm_client_get_connection_by_path (NMClient *client, const char *path);
NMRemoteConnection *nm_client_get_connection_by_uuid (NMClient *client, const char *uuid);
void nm_client_add_connection_async (NMClient *client,
NMConnection *connection,
gboolean save_to_disk,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NMRemoteConnection *nm_client_add_connection_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_20
void nm_client_add_connection2 (NMClient *client,
GVariant *settings,
NMSettingsAddConnection2Flags flags,
GVariant *args,
gboolean ignore_out_result,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_20
NMRemoteConnection *nm_client_add_connection2_finish (NMClient *client,
GAsyncResult *result,
GVariant **out_result,
GError **error);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_load_connections (NMClient *client,
char **filenames,
char ***failures,
GCancellable *cancellable,
GError **error);
void nm_client_load_connections_async (NMClient *client,
char **filenames,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_client_load_connections_finish (NMClient *client,
char ***failures,
GAsyncResult *result,
GError **error);
_NM_DEPRECATED_SYNC_METHOD
gboolean nm_client_reload_connections (NMClient *client,
GCancellable *cancellable,
GError **error);
void nm_client_reload_connections_async (NMClient *client,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
gboolean nm_client_reload_connections_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_6
const char *nm_client_get_dns_mode (NMClient *client);
NM_AVAILABLE_IN_1_6
const char *nm_client_get_dns_rc_manager (NMClient *client);
NM_AVAILABLE_IN_1_6
const GPtrArray *nm_client_get_dns_configuration (NMClient *client);
NM_AVAILABLE_IN_1_12
const GPtrArray *nm_client_get_checkpoints (NMClient *client);
NM_AVAILABLE_IN_1_12
void nm_client_checkpoint_create (NMClient *client,
const GPtrArray *devices,
guint32 rollback_timeout,
NMCheckpointCreateFlags flags,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_12
NMCheckpoint *nm_client_checkpoint_create_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_12
void nm_client_checkpoint_destroy (NMClient *client,
const char *checkpoint_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_12
gboolean nm_client_checkpoint_destroy_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_12
void nm_client_checkpoint_rollback (NMClient *client,
const char *checkpoint_path,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_12
GHashTable *nm_client_checkpoint_rollback_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_12
void nm_client_checkpoint_adjust_rollback_timeout (NMClient *client,
const char *checkpoint_path,
guint32 add_timeout,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_12
gboolean nm_client_checkpoint_adjust_rollback_timeout_finish (NMClient *client,
GAsyncResult *result,
GError **error);
NM_AVAILABLE_IN_1_22
void nm_client_reload (NMClient *client,
NMManagerReloadFlags flags,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
NM_AVAILABLE_IN_1_22
gboolean nm_client_reload_finish (NMClient *client,
GAsyncResult *result,
GError **error);
G_END_DECLS
#endif /* __NM_CLIENT_H__ */