NMSecretAgentOld: libnm Reference Manual

## NMSecretAgentOld NMSecretAgentOld |

## Functions

void | (*NMSecretAgentOldGetSecretsFunc) ()
void | (*NMSecretAgentOldSaveSecretsFunc) ()
void | (*NMSecretAgentOldDeleteSecretsFunc) ()
GDBusConnection * | nm_secret_agent_old_get_dbus_connection ()
GMainContext * | nm_secret_agent_old_get_main_context ()
GObject * | nm_secret_agent_old_get_context_busy_watcher ()
const char * | nm_secret_agent_old_get_dbus_name_owner ()
gboolean | nm_secret_agent_old_get_registered ()
void | nm_secret_agent_old_enable ()
void | nm_secret_agent_old_register_async ()
gboolean | nm_secret_agent_old_register_finish ()
void | nm_secret_agent_old_destroy ()
gboolean | nm_secret_agent_old_register ()
gboolean | nm_secret_agent_old_unregister ()
void | nm_secret_agent_old_unregister_async ()
gboolean | nm_secret_agent_old_unregister_finish ()
void | nm_secret_agent_old_get_secrets ()
void | nm_secret_agent_old_save_secrets ()
void | nm_secret_agent_old_delete_secrets ()

## Properties

gboolean | auto-register | Read / Write / Construct
NMSecretAgentCapabilities | capabilities | Read / Write / Construct
GDBusConnection * | dbus-connection | Read / Write / Construct Only
char * | identifier | Read / Write / Construct Only
gboolean | registered | Read

## Types and Values

#define | NM_SECRET_AGENT_OLD_IDENTIFIER
#define | NM_SECRET_AGENT_OLD_AUTO_REGISTER
#define | NM_SECRET_AGENT_OLD_REGISTERED
#define | NM_SECRET_AGENT_OLD_CAPABILITIES
#define | NM_SECRET_AGENT_OLD_DBUS_CONNECTION
| NMSecretAgentOld

## Object Hierarchy

        GObject
        ╰── NMSecretAgentOld

## Implemented Interfaces

NMSecretAgentOld implements GInitable and GAsyncInitable.

## Description

## Functions

### NMSecretAgentOldGetSecretsFunc ()

    void
    (*NMSecretAgentOldGetSecretsFunc) (NMSecretAgentOld *agent,
                                       NMConnection *connection,
                                       GVariant *secrets,
                                       GError *error,
                                       gpointer user_data);

Called as a result of a request by NM to retrieve secrets. When the NMSecretAgentOld subclass has finished retrieving secrets and is ready to return them, or to return an error, this function should be called with those secrets or the error.

To easily create the dictionary to return the Wi-Fi PSK, you could do something like this:

Example 1. Creating a secrets dictionary

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    NMConnection *secrets;
    NMSettingWirelessSecurity *s_wsec;
    GVariant *secrets_dict;

    secrets = nm_simple_connection_new ();
    s_wsec = (NMSettingWirelessSecurity *) nm_setting_wireless_security_new ();
    g_object_set (G_OBJECT (s_wsec),
                  NM_SETTING_WIRELESS_SECURITY_PSK, "my really cool PSK",
                  NULL);
    nm_connection_add_setting (secrets, NM_SETTING (s_wsec));
    secrets_dict = nm_connection_to_dbus (secrets, NM_CONNECTION_SERIALIZE_ALL);

    (call the NMSecretAgentOldGetSecretsFunc with secrets_dict)

    g_object_unref (secrets);
    g_variant_unref (secrets_dict);

#### Parameters

agent | the secret agent object |
connection | the connection for which secrets were requested, note that this object will be unrefed after the callback has returned, use `g_object_ref()`/`g_object_unref()` if you want to use this object after the callback has returned. | [transfer none]
secrets | the GVariant of type `NM_VARIANT_TYPE_CONNECTION` containing the requested secrets (as created by `nm_connection_to_dbus()` for example). Each key in `secrets` should be the name of a NMSetting object (like "802-11-wireless-security") and each value should be an `NM_VARIANT_TYPE_SETTING` variant. The sub-dicts map string:value, where the string is the setting property name (like "psk") and the value is the secret. | [nullable]
error | if the secrets request failed, give a descriptive error here. | [nullable]
user_data | caller-specific data to be passed to the function |

### NMSecretAgentOldSaveSecretsFunc ()

    void
    (*NMSecretAgentOldSaveSecretsFunc) (NMSecretAgentOld *agent,
                                        NMConnection *connection,
                                        GError *error,
                                        gpointer user_data);

Called as a result of a request by NM to save secrets. When the NMSecretAgentOld subclass has finished saving the secrets, this function should be called.

#### Parameters

agent | the secret agent object |
connection | the connection for which secrets were to be saved, note that this object will be unrefed after the callback has returned, use `g_object_ref()`/`g_object_unref()` if you want to use this object after the callback has returned. | [transfer none]
error | if the saving secrets failed, give a descriptive error here. | [nullable]
user_data | caller-specific data to be passed to the function |

### NMSecretAgentOldDeleteSecretsFunc ()

    void
    (*NMSecretAgentOldDeleteSecretsFunc) (NMSecretAgentOld *agent,
                                          NMConnection *connection,
                                          GError *error,
                                          gpointer user_data);

Called as a result of a request by NM to delete secrets. When the NMSecretAgentOld subclass has finished deleting the secrets, this function should be called.

#### Parameters

agent | the secret agent object |
connection | the connection for which secrets were to be deleted, note that this object will be unrefed after the callback has returned, use `g_object_ref()`/`g_object_unref()` if you want to use this object after the callback has returned. | [transfer none]
error | if the deleting secrets failed, give a descriptive error here. | [nullable]
user_data | caller-specific data to be passed to the function |

### nm_secret_agent_old_get_dbus_connection ()

    GDBusConnection *
    nm_secret_agent_old_get_dbus_connection
                                   (NMSecretAgentOld *self);

#### Parameters

self | the NMSecretAgentOld instance |

#### Returns

the GDBusConnection used by the secret agent. You may either set this as construct property `NM_SECRET_AGENT_OLD_DBUS_CONNECTION`, or it will automatically set during initialization.

[transfer none]

Since: 1.24

### nm_secret_agent_old_get_main_context ()

    GMainContext *
    nm_secret_agent_old_get_main_context (NMSecretAgentOld *self);

#### Parameters

self | the NMSecretAgentOld instance |

#### Returns

the GMainContext instance associate with the instance. This is the `g_main_context_get_thread_default()` at the time when creating the instance.

[transfer none]

Since: 1.24

### nm_secret_agent_old_get_context_busy_watcher ()

    GObject *
    nm_secret_agent_old_get_context_busy_watcher
                                   (NMSecretAgentOld *self);

Returns a GObject that stays alive as long as there are pending requests in the GDBusConnection. Such requests keep the GMainContext alive, and thus you may want to keep iterating the context as long until a weak reference indicates that this object is gone. This is useful because even when you destroy the instance right away (and all the internally pending requests get cancelled), any pending `g_dbus_connection_call()` requests will still invoke the result on the GMainContext. Hence, this allows you to know how long you must iterate the context to know that all remains are cleaned up.

#### Parameters

self | the NMSecretAgentOld instance |

#### Returns

a GObject that you may register a weak pointer to know that the GMainContext is still kept busy by `self` .

[transfer none]

Since: 1.24

### nm_secret_agent_old_get_dbus_name_owner ()

    const char *
    nm_secret_agent_old_get_dbus_name_owner
                                   (NMSecretAgentOld *self);

#### Parameters

self | the NMSecretAgentOld instance |

#### Returns

the current D-Bus name owner. While this property is set while registering, it really only makes sense when the `nm_secret_agent_old_get_registered()` indicates that registration is successful.

Since: 1.24

### nm_secret_agent_old_get_registered ()

    gboolean
    nm_secret_agent_old_get_registered (NMSecretAgentOld *self);

Note that the secret agent transparently registers and re-registers as the D-Bus name owner appears. Hence, this property is not really useful. Also, to be graceful against races during registration, the instance will already accept requests while being in the process of registering. If you need to avoid races and want to wait until `self` is registered, call `nm_secret_agent_old_register_async()`. If that function completes with success, you know the instance is registered.

#### Parameters

self | a NMSecretAgentOld |

#### Returns

a `TRUE` if the agent is registered, `FALSE` if it is not.

### nm_secret_agent_old_enable ()

    void
    nm_secret_agent_old_enable (NMSecretAgentOld *self,
                                gboolean enable);

This has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` property.

Unlike most other functions, you may already call this function before initialization completes.

#### Parameters

self | the NMSecretAgentOld instance |
enable | whether to enable or disable the listener. |

Since: 1.24

### nm_secret_agent_old_register_async ()

    void
    nm_secret_agent_old_register_async (NMSecretAgentOld *self,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Asynchronously registers the NMSecretAgentOld with the NetworkManager secret manager, indicating to NetworkManager that the agent is able to provide and save secrets for connections on behalf of its user.

Since 1.24, registration cannot fail and is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `TRUE` or `nm_secret_agent_old_enable()`.

Since 1.24, the asynchronous result indicates whether the instance is successfully registered. In any case, this call enables the agent and it will automatically try to register and handle secret requests. A failure of this function only indicates that currently the instance might not be ready (but since it will automatically try to recover, it might be ready in a moment afterwards). Use this function if you want to check and ensure that the agent is registered.

#### Parameters

self | a NMSecretAgentOld |
cancellable | a GCancellable, or `NULL` |
callback | callback to call when the agent is registered |
user_data | data for `callback` |

### nm_secret_agent_old_register_finish ()

    gboolean
    nm_secret_agent_old_register_finish (NMSecretAgentOld *self,
                                         GAsyncResult *result,
                                         GError **error);

Gets the result of a call to `nm_secret_agent_old_register_async()`.

#### Parameters

self | a NMSecretAgentOld |
result | the result passed to the GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if registration was successful, `FALSE` on error.

Since 1.24, registration cannot fail and is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `TRUE` or `nm_secret_agent_old_enable()`.

### nm_secret_agent_old_destroy ()

    void
    nm_secret_agent_old_destroy (NMSecretAgentOld *self);

Since 1.24, the instance will already register a D-Bus object on the D-Bus connection during initialization. That object will stay registered until `self` gets unrefed (destroyed) or this function is called. This function performs the necessary cleanup to tear down the instance. Afterwards, the function can not longer be used. This is optional, but necessary to ensure unregistering the D-Bus object at a define point, when other users might still have a reference on `self` .

You may call this function any time and repeatedly. However, after destroying the instance, it is a bug to still use the instance for other purposes. The instance becomes defunct and cannot re-register.

#### Parameters

self | the NMSecretAgentOld instance. |

Since: 1.24

### nm_secret_agent_old_register ()

    gboolean
    nm_secret_agent_old_register (NMSecretAgentOld *self,
                                  GCancellable *cancellable,
                                  GError **error);

`nm_secret_agent_old_register` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `nm_secret_agent_old_enable()` or `nm_secret_agent_old_register_async()`.

Registers the NMSecretAgentOld with the NetworkManager secret manager, indicating to NetworkManager that the agent is able to provide and save secrets for connections on behalf of its user.

#### Parameters

self | a NMSecretAgentOld |
cancellable | a GCancellable, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if registration was successful, `FALSE` on error.

Since 1.24, this can no longer fail unless the `cancellable` gets cancelled. Contrary to `nm_secret_agent_old_register_async()`, this also does not wait for the registration to succeed. You cannot synchronously (without iterating the caller's GMainContext) wait for registration.

Since 1.24, registration is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `TRUE` or `nm_secret_agent_old_enable()`.

### nm_secret_agent_old_unregister ()

    gboolean
    nm_secret_agent_old_unregister (NMSecretAgentOld *self,
                                    GCancellable *cancellable,
                                    GError **error);

`nm_secret_agent_old_unregister` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `nm_secret_agent_old_enable()`.

Unregisters the NMSecretAgentOld with the NetworkManager secret manager, indicating to NetworkManager that the agent will no longer provide or store secrets on behalf of this user.

#### Parameters

self | a NMSecretAgentOld |
cancellable | a GCancellable, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if unregistration was successful, `FALSE` on error

Since 1.24, registration cannot fail and is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `FALSE` or `nm_secret_agent_old_enable()`.

### nm_secret_agent_old_unregister_async ()

    void
    nm_secret_agent_old_unregister_async (NMSecretAgentOld *self,
                                          GCancellable *cancellable,
                                          GAsyncReadyCallback callback,
                                          gpointer user_data);

`nm_secret_agent_old_unregister_async` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `nm_secret_agent_old_enable()`.

Asynchronously unregisters the NMSecretAgentOld with the NetworkManager secret manager, indicating to NetworkManager that the agent will no longer provide or store secrets on behalf of this user.

Since 1.24, registration cannot fail and is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `FALSE` or `nm_secret_agent_old_enable()`.

#### Parameters

self | a NMSecretAgentOld |
cancellable | a GCancellable, or `NULL` |
callback | callback to call when the agent is unregistered |
user_data | data for `callback` |

### nm_secret_agent_old_unregister_finish ()

    gboolean
    nm_secret_agent_old_unregister_finish (NMSecretAgentOld *self,
                                           GAsyncResult *result,
                                           GError **error);

`nm_secret_agent_old_unregister_finish` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `nm_secret_agent_old_enable()`.

Gets the result of a call to `nm_secret_agent_old_unregister_async()`.

#### Parameters

self | a NMSecretAgentOld |
result | the result passed to the GAsyncReadyCallback |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if unregistration was successful, `FALSE` on error.

Since 1.24, registration cannot fail and is idempotent. It has the same effect as setting `NM_SECRET_AGENT_OLD_AUTO_REGISTER` to `FALSE` or `nm_secret_agent_old_enable()`.

### nm_secret_agent_old_get_secrets ()

    void
    nm_secret_agent_old_get_secrets (NMSecretAgentOld *self,
                                     NMConnection *connection,
                                     const char *setting_name,
                                     const char **hints,
                                     NMSecretAgentGetSecretsFlags flags,
                                     NMSecretAgentOldGetSecretsFunc callback,
                                     gpointer user_data);

Asynchronously retrieves secrets belonging to `connection` for the setting `setting_name` . `flags` indicate specific behavior that the secret agent should use when performing the request, for example returning only existing secrets without user interaction, or requesting entirely new secrets from the user.

[virtual get_secrets]

#### Parameters

self | a NMSecretAgentOld |
connection | the NMConnection for which we're asked secrets |
setting_name | the name of the secret setting |
hints | hints to the agent. | [array zero-terminated=1]
flags | flags that modify the behavior of the request |
callback | a callback, to be invoked when the operation is done. | [scope async][closure user_data]
user_data | caller-specific data to be passed to `callback` |

### nm_secret_agent_old_save_secrets ()

    void
    nm_secret_agent_old_save_secrets (NMSecretAgentOld *self,
                                      NMConnection *connection,
                                      NMSecretAgentOldSaveSecretsFunc callback,
                                      gpointer user_data);

Asynchronously ensures that all secrets inside `connection` are stored to disk.

[virtual save_secrets]

#### Parameters

self | a NMSecretAgentOld |
connection | a NMConnection |
callback | a callback, to be invoked when the operation is done. | [scope async][closure user_data]
user_data | caller-specific data to be passed to `callback` |

### nm_secret_agent_old_delete_secrets ()

    void
    nm_secret_agent_old_delete_secrets (NMSecretAgentOld *self,
                                        NMConnection *connection,
                                        NMSecretAgentOldDeleteSecretsFunc callback,
                                        gpointer user_data);

Asynchronously asks the agent to delete all saved secrets belonging to `connection` .

[virtual delete_secrets]

#### Parameters

self | a NMSecretAgentOld |
connection | a NMConnection |
callback | a callback, to be invoked when the operation is done. | [scope async][closure user_data]
user_data | caller-specific data to be passed to `callback` |

## Types and Values

### NM_SECRET_AGENT_OLD_IDENTIFIER

    #define NM_SECRET_AGENT_OLD_IDENTIFIER      "identifier"

### NM_SECRET_AGENT_OLD_AUTO_REGISTER

    #define NM_SECRET_AGENT_OLD_AUTO_REGISTER   "auto-register"

### NM_SECRET_AGENT_OLD_REGISTERED

    #define NM_SECRET_AGENT_OLD_REGISTERED      "registered"

### NM_SECRET_AGENT_OLD_CAPABILITIES

    #define NM_SECRET_AGENT_OLD_CAPABILITIES    "capabilities"

### NM_SECRET_AGENT_OLD_DBUS_CONNECTION

    #define NM_SECRET_AGENT_OLD_DBUS_CONNECTION "dbus-connection"

### NMSecretAgentOld

    typedef struct _NMSecretAgentOld NMSecretAgentOld;

## Property Details

### The `“auto-register”` property

      “auto-register”            gboolean

If `TRUE` (the default), the agent will always be registered when NetworkManager is running; if NetworkManager exits and restarts, the agent will re-register itself automatically.

In particular, if this property is `TRUE` at construct time, then the agent will register itself with NetworkManager during construction/initialization and initialization will only complete after registration is completed (either successfully or unsuccessfully). Since 1.24, a failure to register will no longer cause initialization of NMSecretAgentOld to fail.

If the property is `FALSE`, the agent will not automatically register with NetworkManager, and `nm_secret_agent_old_enable()` or `nm_secret_agent_old_register_async()` must be called to register it.

Calling `nm_secret_agent_old_enable()` has the same effect as setting this property.

Owner: NMSecretAgentOld

Flags: Read / Write / Construct

Default value: TRUE

### The `“capabilities”` property

      “capabilities”             NMSecretAgentCapabilities

A bitfield of `NMSecretAgentCapabilities`.

Changing this property is possible at any time. In case the secret agent is currently registered, this will cause a re-registration.

Owner: NMSecretAgentOld

Flags: Read / Write / Construct

### The `“dbus-connection”` property

      “dbus-connection”          GDBusConnection *

The GDBusConnection used by the instance. You may either set this as construct-only property, or otherwise NMSecretAgentOld will choose a connection via `g_bus_get()` during initialization.

Owner: NMSecretAgentOld

Flags: Read / Write / Construct Only

Since: 1.24

### The `“identifier”` property

      “identifier”               char *

Identifies this agent; only one agent in each user session may use the same identifier. Identifier formatting follows the same rules as D-Bus bus names with the exception that the ':' character is not allowed. The valid set of characters is "A-Z[0-9]_-." and the identifier is limited in length to 255 characters with a minimum of 3 characters. An example valid identifier is 'org.gnome.nm-applet' (without quotes).

Owner: NMSecretAgentOld

Flags: Read / Write / Construct Only

Default value: NULL

### The `“registered”` property

      “registered”               gboolean

`TRUE` if the agent is registered with NetworkManager, `FALSE` if not.

Owner: NMSecretAgentOld

Flags: Read

Default value: FALSE