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.	[nullable][scope call]
user_data	user data for read handler
error	error

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 should verify as a valid profile according to nm_connection_verify(). If it does not verify, the keyfile may be incomplete and the parser may not be able to fully recreate the original profile.

Parameters

connection	the NMConnection to persist to keyfile.
handler_flags	the NMKeyfileHandlerFlags.
handler	optional handler for events and to override the default behavior.	[nullable][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][optional][nullable][transfer none]
out_kf_key_name	if the event is in the context of a keyfile value, the key name.	[out][optional][nullable][transfer none]
out_cur_setting	if the event happens while handling a particular NMSetting instance.	[out][optional][nullable][transfer none]
out_cur_property_name	the property name if applicable.	[out][optional][nullable][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][optional][transfer none]
out_severity	the NMKeyfileWarnSeverity warning severity.	[out][optional]

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