NMSecretAgentOld: libnm Reference Manual

## NMSecretAgentOld NMSecretAgentOld |

## Functions

void | (*NMSecretAgentOldGetSecretsFunc) ()
void | (*NMSecretAgentOldSaveSecretsFunc) ()
void | (*NMSecretAgentOldDeleteSecretsFunc) ()
gboolean | nm_secret_agent_old_register ()
void | nm_secret_agent_old_register_async ()
gboolean | nm_secret_agent_old_register_finish ()
gboolean | nm_secret_agent_old_unregister ()
void | nm_secret_agent_old_unregister_async ()
gboolean | nm_secret_agent_old_unregister_finish ()
gboolean | nm_secret_agent_old_get_registered ()
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
gchar * | 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
| 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 |
error | if the secrets request failed, give a descriptive error here |
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 |
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 |
user_data | caller-specific data to be passed to the function |

### nm_secret_agent_old_register ()

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

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.

It is a programmer error to attempt to register an agent that is already registered, or in the process of registering.

#### 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.

### 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.

It is a programmer error to attempt to register an agent that is already registered, or in the process of registering.

#### 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.

### nm_secret_agent_old_unregister ()

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

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

### nm_secret_agent_old_unregister_async ()

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

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.

#### 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);

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.

### nm_secret_agent_old_get_registered ()

    gboolean
    nm_secret_agent_old_get_registered (NMSecretAgentOld *self);

#### Parameters

self | a NMSecretAgentOld |

#### Returns

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

### 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]
user_data | caller-specific data to be passed to `callback` . | [closure]

### 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]
user_data | caller-specific data to be passed to `callback` . | [closure]

### 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]
user_data | caller-specific data to be passed to `callback` . | [closure]

## 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"

### 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 fail with an error if the agent is unable to register itself.

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

Calling `nm_secret_agent_old_unregister()` will suppress auto-registration until `nm_secret_agent_old_register()` is called, which re-enables auto-registration. This ensures that the agent remains un-registered when you expect it to be unregistered.

Flags: Read / Write / Construct

Default value: TRUE

### The `“capabilities”` property

      “capabilities”             NMSecretAgentCapabilities

A bitfield of `NMSecretAgentCapabilities`.

Flags: Read / Write / Construct

### The `“identifier”` property

      “identifier”               gchar *

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).

Flags: Read / Write / Construct Only

Default value: NULL

### The `“registered”` property

      “registered”               gboolean

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

Flags: Read

Default value: FALSE