nm-keyfile: libnm Reference Manual

## nm-keyfile 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` 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. | [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