1/* SPDX-License-Identifier: LGPL-2.1-or-later */
2
3#ifndef __NM_KEYFILE_H__
4#define __NM_KEYFILE_H__
5
6#if !defined(__NETWORKMANAGER_H_INSIDE__) && !defined(NETWORKMANAGER_COMPILATION)
7#error "Only <NetworkManager.h> can be included directly."
8#endif
9
10#include "nm-core-types.h"
11
12G_BEGIN_DECLS
13
14/**
15 * NMKeyfileHandlerFlags:
16 * @NM_KEYFILE_HANDLER_FLAGS_NONE: no flags set.
17 *
18 * Flags for customizing nm_keyfile_read() and nm_keyfile_write().
19 *
20 * Currently no flags are implemented.
21 *
22 * Since: 1.30
23 */
24typedef enum { /*< flags >*/
25 NM_KEYFILE_HANDLER_FLAGS_NONE = 0,
26} NMKeyfileHandlerFlags;
27
28/**
29 * NMKeyfileHandlerType:
30 * @NM_KEYFILE_HANDLER_TYPE_WARN: a warning.
31 * @NM_KEYFILE_HANDLER_TYPE_WRITE_CERT: for handling certificates while writing
32 * a connection to keyfile.
33 *
34 * The type of the callback for %NMKeyfileReadHandler and %NMKeyfileWriteHandler.
35 * Depending on the type, you can interpret %NMKeyfileHandlerData.
36 *
37 * Since: 1.30
38 */
39typedef enum {
40 NM_KEYFILE_HANDLER_TYPE_WARN = 1,
41 NM_KEYFILE_HANDLER_TYPE_WRITE_CERT = 2,
42} NMKeyfileHandlerType;
43
44/**
45 * NMKeyfileHandlerData:
46 *
47 * Opaque type with parameters for the callback. The actual content
48 * depends on the %NMKeyfileHandlerType.
49 *
50 * Since: 1.30
51 */
52typedef struct _NMKeyfileHandlerData NMKeyfileHandlerData;
53
54/**
55 * NMKeyfileReadHandler:
56 * @keyfile: the #GKeyFile that is currently read
57 * @connection: the #NMConnection that is being constructed.
58 * @handler_type: the %NMKeyfileHandlerType that indicates which type
59 * the request is.
60 * @handler_data: the #NMKeyfileHandlerData. What you can do with it
61 * depends on the @handler_type.
62 * @user_data: the user-data argument to nm_keyfile_read().
63 *
64 * Hook to nm_keyfile_read().
65 *
66 * The callee may abort the reading by setting an error via nm_keyfile_handler_data_fail_with_error().
67 *
68 * Returns: the callee should return TRUE, if the event was handled and/or recognized.
69 * Otherwise, a default action will be performed that depends on the @type.
70 * For %NM_KEYFILE_HANDLER_TYPE_WARN type, the default action is doing nothing.
71 *
72 * Since: 1.30
73 */
74typedef gboolean (*NMKeyfileReadHandler)(GKeyFile *keyfile,
75 NMConnection *connection,
76 NMKeyfileHandlerType handler_type,
77 NMKeyfileHandlerData *handler_data,
78 void *user_data);
79
80NM_AVAILABLE_IN_1_30
81NMConnection *nm_keyfile_read(GKeyFile *keyfile,
82 const char *base_dir,
83 NMKeyfileHandlerFlags handler_flags,
84 NMKeyfileReadHandler handler,
85 void *user_data,
86 GError **error);
87
88/**
89 * NMKeyfileWriteHandler:
90 * @connection: the #NMConnection that is currently written.
91 * @keyfile: the #GKeyFile that is currently constructed.
92 * @handler_type: the %NMKeyfileHandlerType that indicates which type
93 * the request is.
94 * @handler_data: the #NMKeyfileHandlerData. What you can do with it
95 * depends on the @handler_type.
96 * @user_data: the user-data argument to nm_keyfile_read().
97 *
98 * This is a hook to tweak the serialization.
99 *
100 * Handler for certain properties or events that are not entirely contained
101 * within the keyfile or that might be serialized differently. The @type and
102 * @handler_data arguments tell which kind of argument we have at hand.
103 *
104 * Currently only the type %NM_KEYFILE_HANDLER_TYPE_WRITE_CERT is supported.
105 *
106 * The callee may call nm_keyfile_handler_data_fail_with_error() to abort
107 * the writing with error.
108 *
109 * Returns: the callee should return %TRUE if the event was handled. If the
110 * event was unhandled, a default action will be performed that depends on
111 * the @handler_type.
112 *
113 * Since: 1.30
114 */
115typedef gboolean (*NMKeyfileWriteHandler)(NMConnection *connection,
116 GKeyFile *keyfile,
117 NMKeyfileHandlerType handler_type,
118 NMKeyfileHandlerData *handler_data,
119 void *user_data);
120
121NM_AVAILABLE_IN_1_30
122GKeyFile *nm_keyfile_write(NMConnection *connection,
123 NMKeyfileHandlerFlags handler_flags,
124 NMKeyfileWriteHandler handler,
125 void *user_data,
126 GError **error);
127
128/*****************************************************************************/
129
130NM_AVAILABLE_IN_1_30
131void nm_keyfile_handler_data_fail_with_error(NMKeyfileHandlerData *handler_data, GError *src);
132
133NM_AVAILABLE_IN_1_30
134void nm_keyfile_handler_data_get_context(const NMKeyfileHandlerData *handler_data,
135 const char **out_kf_group_name,
136 const char **out_kf_key_name,
137 NMSetting **out_cur_setting,
138 const char **out_cur_property_name);
139
140/**
141 * NMKeyfileWarnSeverity:
142 * @NM_KEYFILE_WARN_SEVERITY_DEBUG: debug message
143 * @NM_KEYFILE_WARN_SEVERITY_INFO: info message
144 * @NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE: info message about a missing file
145 * @NM_KEYFILE_WARN_SEVERITY_WARN: a warning message
146 *
147 * The severity level of %NM_KEYFILE_HANDLER_TYPE_WARN events.
148 *
149 * Since: 1.30
150 */
151typedef enum {
152 NM_KEYFILE_WARN_SEVERITY_DEBUG = 1000,
153 NM_KEYFILE_WARN_SEVERITY_INFO = 2000,
154 NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE = 2901,
155 NM_KEYFILE_WARN_SEVERITY_WARN = 3000,
156} NMKeyfileWarnSeverity;
157
158NM_AVAILABLE_IN_1_30
159void nm_keyfile_handler_data_warn_get(const NMKeyfileHandlerData *handler_data,
160 const char **out_message,
161 NMKeyfileWarnSeverity *out_severity);
162
163G_END_DECLS
164
165#endif /* __NM_KEYFILE_H__ */
166

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