1/* SPDX-License-Identifier: LGPL-2.1-or-later */
2/*
3 * Copyright (C) 2007 - 2008 Novell, Inc.
4 * Copyright (C) 2007 - 2014 Red Hat, Inc.
5 */
6
7#ifndef __NM_CLIENT_H__
8#define __NM_CLIENT_H__
9
10#if !defined(__NETWORKMANAGER_H_INSIDE__) && !defined(NETWORKMANAGER_COMPILATION)
11#error "Only <NetworkManager.h> can be included directly."
12#endif
13
14G_BEGIN_DECLS
15
16/**
17 * NMClientInstanceFlags:
18 * @NM_CLIENT_INSTANCE_FLAGS_NONE: special value to indicate no flags.
19 * @NM_CLIENT_INSTANCE_FLAGS_NO_AUTO_FETCH_PERMISSIONS: by default, NMClient
20 * will fetch the permissions via "GetPermissions" and refetch them when
21 * "CheckPermissions" signal gets received. By setting this flag, this behavior
22 * can be disabled. You can toggle this flag to enable and disable automatic
23 * fetching of the permissions. Watch also nm_client_get_permissions_state()
24 * to know whether the permissions are up to date.
25 * @NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD: as #NMClient is an GInitable
26 * and GAsyncInitable, nm_client_get_instance_flags() returns this flag
27 * once initialization completed with success. This flag cannot be set
28 * as NM_CLIENT_INSTANCE_FLAGS property. Since: 1.42.
29 * @NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_BAD: like @NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD
30 * indicates that the instance completed initialization with failure. In that
31 * case the instance is unusable. Since: 1.42.
32 *
33 * Since: 1.24
34 */
35typedef enum /*< flags >*/ {
36 NM_CLIENT_INSTANCE_FLAGS_NONE = 0,
37 NM_CLIENT_INSTANCE_FLAGS_NO_AUTO_FETCH_PERMISSIONS = 0x1,
38 NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD = 0x2,
39 NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_BAD = 0x4,
40} NMClientInstanceFlags;
41
42#define NM_TYPE_CLIENT (nm_client_get_type())
43#define NM_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), NM_TYPE_CLIENT, NMClient))
44#define NM_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), NM_TYPE_CLIENT, NMClientClass))
45#define NM_IS_CLIENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), NM_TYPE_CLIENT))
46#define NM_IS_CLIENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), NM_TYPE_CLIENT))
47#define NM_CLIENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), NM_TYPE_CLIENT, NMClientClass))
48
49#define NM_CLIENT_VERSION "version"
50#define NM_CLIENT_VERSION_INFO "version-info"
51#define NM_CLIENT_STATE "state"
52#define NM_CLIENT_STARTUP "startup"
53#define NM_CLIENT_NM_RUNNING "nm-running"
54#define NM_CLIENT_DBUS_CONNECTION "dbus-connection"
55#define NM_CLIENT_DBUS_NAME_OWNER "dbus-name-owner"
56#define NM_CLIENT_INSTANCE_FLAGS "instance-flags"
57
58_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
59#define NM_CLIENT_NETWORKING_ENABLED "networking-enabled"
60
61_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
62#define NM_CLIENT_WIRELESS_ENABLED "wireless-enabled"
63_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
64#define NM_CLIENT_WWAN_ENABLED "wwan-enabled"
65_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
66#define NM_CLIENT_WIMAX_ENABLED "wimax-enabled"
67
68#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"
69#define NM_CLIENT_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"
70#define NM_CLIENT_WIMAX_HARDWARE_ENABLED "wimax-hardware-enabled"
71
72#define NM_CLIENT_RADIO_FLAGS "radio-flags"
73
74#define NM_CLIENT_ACTIVE_CONNECTIONS "active-connections"
75#define NM_CLIENT_CONNECTIVITY "connectivity"
76#define NM_CLIENT_CONNECTIVITY_CHECK_URI "connectivity-check-uri"
77#define NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE "connectivity-check-available"
78
79_NM_DEPRECATED_SYNC_WRITABLE_PROPERTY
80#define NM_CLIENT_CONNECTIVITY_CHECK_ENABLED "connectivity-check-enabled"
81
82#define NM_CLIENT_PRIMARY_CONNECTION "primary-connection"
83#define NM_CLIENT_ACTIVATING_CONNECTION "activating-connection"
84#define NM_CLIENT_DEVICES "devices"
85#define NM_CLIENT_ALL_DEVICES "all-devices"
86#define NM_CLIENT_CONNECTIONS "connections"
87#define NM_CLIENT_HOSTNAME "hostname"
88#define NM_CLIENT_CAN_MODIFY "can-modify"
89#define NM_CLIENT_METERED "metered"
90#define NM_CLIENT_DNS_MODE "dns-mode"
91#define NM_CLIENT_DNS_RC_MANAGER "dns-rc-manager"
92#define NM_CLIENT_DNS_CONFIGURATION "dns-configuration"
93#define NM_CLIENT_CHECKPOINTS "checkpoints"
94#define NM_CLIENT_CAPABILITIES "capabilities"
95#define NM_CLIENT_PERMISSIONS_STATE "permissions-state"
96
97#define NM_CLIENT_DEVICE_ADDED "device-added"
98#define NM_CLIENT_DEVICE_REMOVED "device-removed"
99#define NM_CLIENT_ANY_DEVICE_ADDED "any-device-added"
100#define NM_CLIENT_ANY_DEVICE_REMOVED "any-device-removed"
101#define NM_CLIENT_PERMISSION_CHANGED "permission-changed"
102#define NM_CLIENT_CONNECTION_ADDED "connection-added"
103#define NM_CLIENT_CONNECTION_REMOVED "connection-removed"
104#define NM_CLIENT_ACTIVE_CONNECTION_ADDED "active-connection-added"
105#define NM_CLIENT_ACTIVE_CONNECTION_REMOVED "active-connection-removed"
106
107/**
108 * NMClientError:
109 * @NM_CLIENT_ERROR_FAILED: unknown or unclassified error
110 * @NM_CLIENT_ERROR_MANAGER_NOT_RUNNING: an operation that requires NetworkManager
111 * failed because NetworkManager is not running
112 * @NM_CLIENT_ERROR_OBJECT_CREATION_FAILED: NetworkManager claimed that an
113 * operation succeeded, but the object that was allegedly created (eg,
114 * #NMRemoteConnection, #NMActiveConnection) was apparently destroyed before
115 * #NMClient could create a representation of it.
116 *
117 * Describes errors that may result from operations involving a #NMClient.
118 *
119 * D-Bus operations may also return errors from other domains, including
120 * #NMManagerError, #NMSettingsError, #NMAgentManagerError, and #NMConnectionError.
121 **/
122typedef enum {
123 NM_CLIENT_ERROR_FAILED = 0,
124 NM_CLIENT_ERROR_MANAGER_NOT_RUNNING,
125 NM_CLIENT_ERROR_OBJECT_CREATION_FAILED,
126} NMClientError;
127
128#define NM_CLIENT_ERROR nm_client_error_quark()
129GQuark nm_client_error_quark(void);
130
131/* DNS stuff */
132
133/**
134 * NMDnsEntry:
135 *
136 * Since: 1.6
137 */
138typedef struct _NMDnsEntry NMDnsEntry;
139
140NM_AVAILABLE_IN_1_6
141GType nm_dns_entry_get_type(void);
142NM_AVAILABLE_IN_1_6
143void nm_dns_entry_unref(NMDnsEntry *entry);
144NM_AVAILABLE_IN_1_6
145const char *nm_dns_entry_get_interface(NMDnsEntry *entry);
146NM_AVAILABLE_IN_1_6
147const char *const *nm_dns_entry_get_nameservers(NMDnsEntry *entry);
148NM_AVAILABLE_IN_1_6
149const char *const *nm_dns_entry_get_domains(NMDnsEntry *entry);
150NM_AVAILABLE_IN_1_6
151int nm_dns_entry_get_priority(NMDnsEntry *entry);
152NM_AVAILABLE_IN_1_6
153gboolean nm_dns_entry_get_vpn(NMDnsEntry *entry);
154
155/**
156 * NMClient:
157 *
158 * NMClient contains a cache of the objects of NetworkManager's D-Bus API.
159 * It uses #GMainContext and #GDBusConnection for that and registers to
160 * D-Bus signals. That means, when iterating the associated #GMainContext,
161 * D-Bus signals gets processed and the #NMClient instance updates and
162 * emits #GObject signals.
163 */
164typedef struct _NMClient NMClient;
165typedef struct _NMClientClass NMClientClass;
166
167GType nm_client_get_type(void);
168
169NMClient *nm_client_new(GCancellable *cancellable, GError **error);
170
171void
172nm_client_new_async(GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data);
173NMClient *nm_client_new_finish(GAsyncResult *result, GError **error);
174
175NM_AVAILABLE_IN_1_24
176NMClientInstanceFlags nm_client_get_instance_flags(NMClient *self);
177
178NM_AVAILABLE_IN_1_22
179GDBusConnection *nm_client_get_dbus_connection(NMClient *client);
180
181NM_AVAILABLE_IN_1_22
182GMainContext *nm_client_get_main_context(NMClient *self);
183
184NM_AVAILABLE_IN_1_22
185GObject *nm_client_get_context_busy_watcher(NMClient *self);
186
187NM_AVAILABLE_IN_1_22
188const char *nm_client_get_dbus_name_owner(NMClient *client);
189
190const char *nm_client_get_version(NMClient *client);
191
192NM_AVAILABLE_IN_1_42
193const guint32 *nm_client_get_version_info(NMClient *client, gsize *length);
194
195NMState nm_client_get_state(NMClient *client);
196gboolean nm_client_get_startup(NMClient *client);
197gboolean nm_client_get_nm_running(NMClient *client);
198
199NMObject *nm_client_get_object_by_path(NMClient *client, const char *dbus_path);
200
201NM_AVAILABLE_IN_1_22
202NMMetered nm_client_get_metered(NMClient *client);
203
204gboolean nm_client_networking_get_enabled(NMClient *client);
205
206NM_AVAILABLE_IN_1_24
207const guint32 *nm_client_get_capabilities(NMClient *client, gsize *length);
208
209_NM_DEPRECATED_SYNC_METHOD
210gboolean nm_client_networking_set_enabled(NMClient *client, gboolean enabled, GError **error);
211
212gboolean nm_client_wireless_get_enabled(NMClient *client);
213
214_NM_DEPRECATED_SYNC_METHOD
215void nm_client_wireless_set_enabled(NMClient *client, gboolean enabled);
216
217gboolean nm_client_wireless_hardware_get_enabled(NMClient *client);
218
219gboolean nm_client_wwan_get_enabled(NMClient *client);
220
221_NM_DEPRECATED_SYNC_METHOD
222void nm_client_wwan_set_enabled(NMClient *client, gboolean enabled);
223
224gboolean nm_client_wwan_hardware_get_enabled(NMClient *client);
225
226NM_DEPRECATED_IN_1_22
227gboolean nm_client_wimax_get_enabled(NMClient *client);
228
229NM_DEPRECATED_IN_1_22
230_NM_DEPRECATED_SYNC_METHOD
231void nm_client_wimax_set_enabled(NMClient *client, gboolean enabled);
232
233NM_DEPRECATED_IN_1_22
234gboolean nm_client_wimax_hardware_get_enabled(NMClient *client);
235
236NM_AVAILABLE_IN_1_38
237NMRadioFlags nm_client_get_radio_flags(NMClient *client);
238
239NM_AVAILABLE_IN_1_10
240gboolean nm_client_connectivity_check_get_available(NMClient *client);
241
242NM_AVAILABLE_IN_1_10
243gboolean nm_client_connectivity_check_get_enabled(NMClient *client);
244
245NM_AVAILABLE_IN_1_10
246_NM_DEPRECATED_SYNC_METHOD
247void nm_client_connectivity_check_set_enabled(NMClient *client, gboolean enabled);
248
249NM_AVAILABLE_IN_1_20
250const char *nm_client_connectivity_check_get_uri(NMClient *client);
251
252_NM_DEPRECATED_SYNC_METHOD
253gboolean nm_client_get_logging(NMClient *client, char **level, char **domains, GError **error);
254
255_NM_DEPRECATED_SYNC_METHOD
256gboolean
257nm_client_set_logging(NMClient *client, const char *level, const char *domains, GError **error);
258
259NMClientPermissionResult nm_client_get_permission_result(NMClient *client,
260 NMClientPermission permission);
261
262NM_AVAILABLE_IN_1_24
263NMTernary nm_client_get_permissions_state(NMClient *self);
264
265NMConnectivityState nm_client_get_connectivity(NMClient *client);
266
267_NM_DEPRECATED_SYNC_METHOD
268NM_DEPRECATED_IN_1_22
269NMConnectivityState
270nm_client_check_connectivity(NMClient *client, GCancellable *cancellable, GError **error);
271
272void nm_client_check_connectivity_async(NMClient *client,
273 GCancellable *cancellable,
274 GAsyncReadyCallback callback,
275 gpointer user_data);
276NMConnectivityState
277nm_client_check_connectivity_finish(NMClient *client, GAsyncResult *result, GError **error);
278
279_NM_DEPRECATED_SYNC_METHOD
280gboolean nm_client_save_hostname(NMClient *client,
281 const char *hostname,
282 GCancellable *cancellable,
283 GError **error);
284
285void nm_client_save_hostname_async(NMClient *client,
286 const char *hostname,
287 GCancellable *cancellable,
288 GAsyncReadyCallback callback,
289 gpointer user_data);
290gboolean nm_client_save_hostname_finish(NMClient *client, GAsyncResult *result, GError **error);
291
292/* Devices */
293
294const GPtrArray *nm_client_get_devices(NMClient *client);
295NM_AVAILABLE_IN_1_2
296const GPtrArray *nm_client_get_all_devices(NMClient *client);
297NMDevice *nm_client_get_device_by_path(NMClient *client, const char *object_path);
298NMDevice *nm_client_get_device_by_iface(NMClient *client, const char *iface);
299
300/* Active Connections */
301
302const GPtrArray *nm_client_get_active_connections(NMClient *client);
303
304NMActiveConnection *nm_client_get_primary_connection(NMClient *client);
305NMActiveConnection *nm_client_get_activating_connection(NMClient *client);
306
307void nm_client_activate_connection_async(NMClient *client,
308 NMConnection *connection,
309 NMDevice *device,
310 const char *specific_object,
311 GCancellable *cancellable,
312 GAsyncReadyCallback callback,
313 gpointer user_data);
314NMActiveConnection *
315nm_client_activate_connection_finish(NMClient *client, GAsyncResult *result, GError **error);
316
317void nm_client_add_and_activate_connection_async(NMClient *client,
318 NMConnection *partial,
319 NMDevice *device,
320 const char *specific_object,
321 GCancellable *cancellable,
322 GAsyncReadyCallback callback,
323 gpointer user_data);
324NMActiveConnection *nm_client_add_and_activate_connection_finish(NMClient *client,
325 GAsyncResult *result,
326 GError **error);
327
328NM_AVAILABLE_IN_1_16
329void nm_client_add_and_activate_connection2(NMClient *client,
330 NMConnection *partial,
331 NMDevice *device,
332 const char *specific_object,
333 GVariant *options,
334 GCancellable *cancellable,
335 GAsyncReadyCallback callback,
336 gpointer user_data);
337NM_AVAILABLE_IN_1_16
338NMActiveConnection *nm_client_add_and_activate_connection2_finish(NMClient *client,
339 GAsyncResult *result,
340 GVariant **out_result,
341 GError **error);
342
343_NM_DEPRECATED_SYNC_METHOD
344gboolean nm_client_deactivate_connection(NMClient *client,
345 NMActiveConnection *active,
346 GCancellable *cancellable,
347 GError **error);
348
349void nm_client_deactivate_connection_async(NMClient *client,
350 NMActiveConnection *active,
351 GCancellable *cancellable,
352 GAsyncReadyCallback callback,
353 gpointer user_data);
354gboolean
355nm_client_deactivate_connection_finish(NMClient *client, GAsyncResult *result, GError **error);
356
357/* Connections */
358
359const GPtrArray *nm_client_get_connections(NMClient *client);
360
361NMRemoteConnection *nm_client_get_connection_by_id(NMClient *client, const char *id);
362NMRemoteConnection *nm_client_get_connection_by_path(NMClient *client, const char *path);
363NMRemoteConnection *nm_client_get_connection_by_uuid(NMClient *client, const char *uuid);
364
365void nm_client_add_connection_async(NMClient *client,
366 NMConnection *connection,
367 gboolean save_to_disk,
368 GCancellable *cancellable,
369 GAsyncReadyCallback callback,
370 gpointer user_data);
371NMRemoteConnection *
372nm_client_add_connection_finish(NMClient *client, GAsyncResult *result, GError **error);
373
374NM_AVAILABLE_IN_1_20
375void nm_client_add_connection2(NMClient *client,
376 GVariant *settings,
377 NMSettingsAddConnection2Flags flags,
378 GVariant *args,
379 gboolean ignore_out_result,
380 GCancellable *cancellable,
381 GAsyncReadyCallback callback,
382 gpointer user_data);
383
384NM_AVAILABLE_IN_1_20
385NMRemoteConnection *nm_client_add_connection2_finish(NMClient *client,
386 GAsyncResult *result,
387 GVariant **out_result,
388 GError **error);
389
390_NM_DEPRECATED_SYNC_METHOD
391gboolean nm_client_load_connections(NMClient *client,
392 char **filenames,
393 char ***failures,
394 GCancellable *cancellable,
395 GError **error);
396
397void nm_client_load_connections_async(NMClient *client,
398 char **filenames,
399 GCancellable *cancellable,
400 GAsyncReadyCallback callback,
401 gpointer user_data);
402gboolean nm_client_load_connections_finish(NMClient *client,
403 char ***failures,
404 GAsyncResult *result,
405 GError **error);
406
407_NM_DEPRECATED_SYNC_METHOD
408gboolean nm_client_reload_connections(NMClient *client, GCancellable *cancellable, GError **error);
409
410void nm_client_reload_connections_async(NMClient *client,
411 GCancellable *cancellable,
412 GAsyncReadyCallback callback,
413 gpointer user_data);
414gboolean
415nm_client_reload_connections_finish(NMClient *client, GAsyncResult *result, GError **error);
416
417NM_AVAILABLE_IN_1_6
418const char *nm_client_get_dns_mode(NMClient *client);
419NM_AVAILABLE_IN_1_6
420const char *nm_client_get_dns_rc_manager(NMClient *client);
421NM_AVAILABLE_IN_1_6
422const GPtrArray *nm_client_get_dns_configuration(NMClient *client);
423
424NM_AVAILABLE_IN_1_12
425const GPtrArray *nm_client_get_checkpoints(NMClient *client);
426
427NM_AVAILABLE_IN_1_12
428void nm_client_checkpoint_create(NMClient *client,
429 const GPtrArray *devices,
430 guint32 rollback_timeout,
431 NMCheckpointCreateFlags flags,
432 GCancellable *cancellable,
433 GAsyncReadyCallback callback,
434 gpointer user_data);
435NM_AVAILABLE_IN_1_12
436NMCheckpoint *
437nm_client_checkpoint_create_finish(NMClient *client, GAsyncResult *result, GError **error);
438
439NM_AVAILABLE_IN_1_12
440void nm_client_checkpoint_destroy(NMClient *client,
441 const char *checkpoint_path,
442 GCancellable *cancellable,
443 GAsyncReadyCallback callback,
444 gpointer user_data);
445NM_AVAILABLE_IN_1_12
446gboolean
447nm_client_checkpoint_destroy_finish(NMClient *client, GAsyncResult *result, GError **error);
448
449NM_AVAILABLE_IN_1_12
450void nm_client_checkpoint_rollback(NMClient *client,
451 const char *checkpoint_path,
452 GCancellable *cancellable,
453 GAsyncReadyCallback callback,
454 gpointer user_data);
455NM_AVAILABLE_IN_1_12
456GHashTable *
457nm_client_checkpoint_rollback_finish(NMClient *client, GAsyncResult *result, GError **error);
458
459NM_AVAILABLE_IN_1_12
460void nm_client_checkpoint_adjust_rollback_timeout(NMClient *client,
461 const char *checkpoint_path,
462 guint32 add_timeout,
463 GCancellable *cancellable,
464 GAsyncReadyCallback callback,
465 gpointer user_data);
466
467NM_AVAILABLE_IN_1_12
468gboolean nm_client_checkpoint_adjust_rollback_timeout_finish(NMClient *client,
469 GAsyncResult *result,
470 GError **error);
471
472NM_AVAILABLE_IN_1_22
473void nm_client_reload(NMClient *client,
474 NMManagerReloadFlags flags,
475 GCancellable *cancellable,
476 GAsyncReadyCallback callback,
477 gpointer user_data);
478NM_AVAILABLE_IN_1_22
479gboolean nm_client_reload_finish(NMClient *client, GAsyncResult *result, GError **error);
480
481/*****************************************************************************/
482
483NM_AVAILABLE_IN_1_24
484void nm_client_dbus_call(NMClient *client,
485 const char *object_path,
486 const char *interface_name,
487 const char *method_name,
488 GVariant *parameters,
489 const GVariantType *reply_type,
490 int timeout_msec,
491 GCancellable *cancellable,
492 GAsyncReadyCallback callback,
493 gpointer user_data);
494
495NM_AVAILABLE_IN_1_24
496GVariant *nm_client_dbus_call_finish(NMClient *client, GAsyncResult *result, GError **error);
497
498NM_AVAILABLE_IN_1_24
499void nm_client_dbus_set_property(NMClient *client,
500 const char *object_path,
501 const char *interface_name,
502 const char *property_name,
503 GVariant *value,
504 int timeout_msec,
505 GCancellable *cancellable,
506 GAsyncReadyCallback callback,
507 gpointer user_data);
508
509NM_AVAILABLE_IN_1_24
510gboolean nm_client_dbus_set_property_finish(NMClient *client, GAsyncResult *result, GError **error);
511
512/*****************************************************************************/
513
514NM_AVAILABLE_IN_1_30
515void nm_utils_print(int output_mode, const char *msg);
516
517gboolean nm_utils_file_is_certificate(const char *filename);
518gboolean nm_utils_file_is_private_key(const char *filename, gboolean *out_encrypted);
519gboolean nm_utils_file_is_pkcs12(const char *filename);
520
521/*****************************************************************************/
522
523NM_AVAILABLE_IN_1_42
524void nm_client_wait_shutdown(NMClient *client,
525 gboolean integrate_maincontext,
526 GCancellable *cancellable,
527 GAsyncReadyCallback callback,
528 gpointer user_data);
529
530NM_AVAILABLE_IN_1_42
531gboolean nm_client_wait_shutdown_finish(GAsyncResult *result, GError **error);
532
533G_END_DECLS
534
535#endif /* __NM_CLIENT_H__ */
536

source code of include/libnm/nm-client.h