nm-keyfile: libnm Reference Manual

+ + +

nm-keyfile

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+gboolean +	+(*NMKeyfileReadHandler) () +
+NMConnection * +	+nm_keyfile_read () +
+gboolean +	+(*NMKeyfileWriteHandler) () +
+GKeyFile * +	+nm_keyfile_write () +
+void +	+nm_keyfile_handler_data_fail_with_error () +
+void +	+nm_keyfile_handler_data_get_context () +
+void +	+nm_keyfile_handler_data_warn_get () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + +

enum	NMKeyfileHandlerFlags
enum	NMKeyfileHandlerType
enum	NMKeyfileWarnSeverity
	NMKeyfileHandlerData

Object Hierarchy

    GEnum
+    ├── NMKeyfileHandlerType
+    ╰── NMKeyfileWarnSeverity
+    GFlags
+    ╰── NMKeyfileHandlerFlags
+

Description

Functions

NMKeyfileReadHandler ()

gboolean
+(*NMKeyfileReadHandler) (GKeyFile *keyfile,
+                         NMConnection *connection,
+                         NMKeyfileHandlerType handler_type,
+                         NMKeyfileHandlerData *handler_data,
+                         void *user_data);

Hook to nm_keyfile_read().

The callee may abort the reading by setting an error via nm_keyfile_handler_data_fail_with_error().

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

keyfile	the GKeyFile that is currently read
connection	the NMConnection that is being constructed.
handler_type	the `NMKeyfileHandlerType` that indicates which type +the request is.
handler_data	the NMKeyfileHandlerData. What you can do with it +depends on the `handler_type` +.
user_data	the user-data argument to `nm_keyfile_read()`.

Returns

the callee should return TRUE, if the event was handled and/or recognized. +Otherwise, a default action will be performed that depends on the type +. +For NM_KEYFILE_HANDLER_TYPE_WARN type, the default action is doing nothing.

Since: 1.30

nm_keyfile_read ()

NMConnection *
+nm_keyfile_read (GKeyFile *keyfile,
+                 const char *base_dir,
+                 NMKeyfileHandlerFlags handler_flags,
+                 NMKeyfileReadHandler handler,
+                 void *user_data,
+                 GError **error);

Tries to create a NMConnection from a keyfile. The resulting keyfile is +not normalized and might not even verify.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

keyfile	the keyfile from which to create the connection
base_dir	when reading certificates from files with relative name, +the relative path is made absolute using `base_dir` +. This must +be an absolute path.
handler_flags	the NMKeyfileHandlerFlags.
handler	read handler.	[allow-none][scope call]
user_data	user data for read handler
error	error.	[allow-none][out]

Returns

on success, returns the created connection.

[transfer full]

Since: 1.30

NMKeyfileWriteHandler ()

gboolean
+(*NMKeyfileWriteHandler) (NMConnection *connection,
+                          GKeyFile *keyfile,
+                          NMKeyfileHandlerType handler_type,
+                          NMKeyfileHandlerData *handler_data,
+                          void *user_data);

This is a hook to tweak the serialization.

Handler for certain properties or events that are not entirely contained +within the keyfile or that might be serialized differently. The type + and +handler_data + arguments tell which kind of argument we have at hand.

Currently only the type NM_KEYFILE_HANDLER_TYPE_WRITE_CERT is supported.

The callee may call nm_keyfile_handler_data_fail_with_error() to abort +the writing with error.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

connection	the NMConnection that is currently written.
keyfile	the GKeyFile that is currently constructed.
handler_type	the `NMKeyfileHandlerType` that indicates which type +the request is.
handler_data	the NMKeyfileHandlerData. What you can do with it +depends on the `handler_type` +.
user_data	the user-data argument to `nm_keyfile_read()`.

Returns

the callee should return TRUE if the event was handled. If the +event was unhandled, a default action will be performed that depends on +the handler_type +.

Since: 1.30

nm_keyfile_write ()

GKeyFile *
+nm_keyfile_write (NMConnection *connection,
+                  NMKeyfileHandlerFlags handler_flags,
+                  NMKeyfileWriteHandler handler,
+                  void *user_data,
+                  GError **error);

connection + must verify as a valid profile according to +nm_connection_verify().

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

connection	the NMConnection to persist to keyfile.
handler_flags	the NMKeyfileHandlerFlags.
handler	optional handler for events and +to override the default behavior.	[allow-none][scope call]
user_data	argument for `handler` +.
error	the GError in case writing fails.

Returns

a new GKeyFile or NULL on error.

[transfer full]

Since: 1.30

nm_keyfile_handler_data_fail_with_error ()

void
+nm_keyfile_handler_data_fail_with_error
+                               (NMKeyfileHandlerData *handler_data,
+                                GError *src);

Set the error for the handler. This lets the operation fail +with the provided error. You may only set the error once.

src + must be non-NULL.

Note that src + is no longer valid after this call. If you want +to keep using the same GError*, you need to set it to NULL +after calling this function on it.

Parameters

+++++ + + + + + + + + + + + + +

handler_data	the NMKeyfileHandlerData
src	error to move into the return location.	[transfer full]

Since: 1.30

nm_keyfile_handler_data_get_context ()

void
+nm_keyfile_handler_data_get_context (const NMKeyfileHandlerData *handler_data,
+                                     const char **out_kf_group_name,
+                                     const char **out_kf_key_name,
+                                     NMSetting **out_cur_setting,
+                                     const char **out_cur_property_name);

Get context information of the current event. This function can be called +on all events, but the context information may be unset.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

handler_data	the NMKeyfileHandlerData for any event.
out_kf_group_name	if the event is in the +context of a keyfile group, the group name.	[out][allow-none][transfer none]
out_kf_key_name	if the event is in the +context of a keyfile value, the key name.	[out][allow-none][transfer none]
out_cur_setting	if the event happens while +handling a particular NMSetting instance.	[out][allow-none][transfer none]
out_cur_property_name	the property name if applicable.	[out][allow-none][transfer none]

Since: 1.30

nm_keyfile_handler_data_warn_get ()

void
+nm_keyfile_handler_data_warn_get (const NMKeyfileHandlerData *handler_data,
+                                  const char **out_message,
+                                  NMKeyfileWarnSeverity *out_severity);

Parameters

+++++ + + + + + + + + + + + + + + + + + +

handler_data	the NMKeyfileHandlerData for a `NM_KEYFILE_HANDLER_TYPE_WARN` +event.
out_message	the warning message.	[out][allow-none][transfer none]
out_severity	the NMKeyfileWarnSeverity warning severity.	[out][allow-none]

Since: 1.30

Types and Values

enum NMKeyfileHandlerFlags

Flags for customizing nm_keyfile_read() and nm_keyfile_write().

Currently no flags are implemented.

Members

+++++ + + + + + +

NM_KEYFILE_HANDLER_FLAGS_NONE

no flags set.

Since: 1.30

enum NMKeyfileHandlerType

The type of the callback for NMKeyfileReadHandler and NMKeyfileWriteHandler. +Depending on the type, you can interpret NMKeyfileHandlerData.

Members

+++++ + + + + + + + + + + + + +

NM_KEYFILE_HANDLER_TYPE_WARN	+ a warning. +
NM_KEYFILE_HANDLER_TYPE_WRITE_CERT	+ for handling certificates while writing +a connection to keyfile. +

Since: 1.30

enum NMKeyfileWarnSeverity

The severity level of NM_KEYFILE_HANDLER_TYPE_WARN events.

Members

+++++ + + + + + + + + + + + + + + + + + + + + + + +

NM_KEYFILE_WARN_SEVERITY_DEBUG	+ debug message +
NM_KEYFILE_WARN_SEVERITY_INFO	+ info message +
NM_KEYFILE_WARN_SEVERITY_INFO_MISSING_FILE	+ info message about a missing file +
NM_KEYFILE_WARN_SEVERITY_WARN	+ a warning message +

Since: 1.30

NMKeyfileHandlerData

typedef struct _NMKeyfileHandlerData NMKeyfileHandlerData;

Opaque type with parameters for the callback. The actual content +depends on the NMKeyfileHandlerType.

Since: 1.30