NMSecretAgentOld

NMSecretAgentOld

Synopsis

#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;
void                (*NMSecretAgentOldGetSecretsFunc)   (NMSecretAgentOld *agent,
                                                         NMConnection *connection,
                                                         GVariant *secrets,
                                                         GError *error,
                                                         gpointer user_data);
void                (*NMSecretAgentOldSaveSecretsFunc)  (NMSecretAgentOld *agent,
                                                         NMConnection *connection,
                                                         GError *error,
                                                         gpointer user_data);
void                (*NMSecretAgentOldDeleteSecretsFunc)
                                                        (NMSecretAgentOld *agent,
                                                         NMConnection *connection,
                                                         GError *error,
                                                         gpointer user_data);
                    NMSecretAgentOldClass;
gboolean            nm_secret_agent_old_register        (NMSecretAgentOld *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                nm_secret_agent_old_register_async  (NMSecretAgentOld *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            nm_secret_agent_old_register_finish (NMSecretAgentOld *self,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            nm_secret_agent_old_unregister      (NMSecretAgentOld *self,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                nm_secret_agent_old_unregister_async
                                                        (NMSecretAgentOld *self,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            nm_secret_agent_old_unregister_finish
                                                        (NMSecretAgentOld *self,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            nm_secret_agent_old_get_registered  (NMSecretAgentOld *self);
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);
void                nm_secret_agent_old_save_secrets    (NMSecretAgentOld *self,
                                                         NMConnection *connection,
                                                         NMSecretAgentOldSaveSecretsFunc callback,
                                                         gpointer user_data);
void                nm_secret_agent_old_delete_secrets  (NMSecretAgentOld *self,
                                                         NMConnection *connection,
                                                         NMSecretAgentOldDeleteSecretsFunc callback,
                                                         gpointer user_data);

Object Hierarchy

  GObject
   +----NMSecretAgentOld

Implemented Interfaces

NMSecretAgentOld implements GInitable and GAsyncInitable.

Properties

  "auto-register"            gboolean              : Read / Write / Construct
  "capabilities"             NMSecretAgentCapabilities  : Read / Write / Construct
  "identifier"               gchar*                : Read / Write / Construct Only
  "registered"               gboolean              : Read

Description

Details

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;

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


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.

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.

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

NMSecretAgentOldClass

typedef struct {
	GObjectClass parent;

	/* Virtual methods for subclasses */

	/* Called when the subclass should retrieve and return secrets.  Subclass
	 * must copy or reference any arguments it may require after returning from
	 * this method, as the arguments will freed (except for 'self', 'callback',
	 * and 'user_data' of course).  If the request is canceled, the callback
	 * should still be called, but with the
	 * NM_SECRET_AGENT_OLD_ERROR_AGENT_CANCELED error.
	 */
	void (*get_secrets) (NMSecretAgentOld *self,
	                     NMConnection *connection,
	                     const char *connection_path,
	                     const char *setting_name,
	                     const char **hints,
	                     NMSecretAgentGetSecretsFlags flags,
	                     NMSecretAgentOldGetSecretsFunc callback,
	                     gpointer user_data);

	/* Called when the subclass should cancel an outstanding request to
	 * get secrets for a given connection.  Canceling the request MUST
	 * call the callback that was passed along with the initial get_secrets
	 * call, sending the NM_SECRET_AGENT_OLD_ERROR/
	 * NM_SECRET_AGENT_OLD_ERROR_AGENT_CANCELED error to that callback.
	 */
	void (*cancel_get_secrets) (NMSecretAgentOld *self,
	                            const char *connection_path,
	                            const char *setting_name);

	/* Called when the subclass should save the secrets contained in the
	 * connection to backing storage.  Subclass must copy or reference any
	 * arguments it may require after returning from this method, as the
	 * arguments will freed (except for 'self', 'callback', and 'user_data'
	 * of course).
	 */
	void (*save_secrets) (NMSecretAgentOld *self,
	                      NMConnection *connection,
	                      const char *connection_path,
	                      NMSecretAgentOldSaveSecretsFunc callback,
	                      gpointer user_data);

	/* Called when the subclass should delete the secrets contained in the
	 * connection from backing storage.  Subclass must copy or reference any
	 * arguments it may require after returning from this method, as the
	 * arguments will freed (except for 'self', 'callback', and 'user_data'
	 * of course).
	 */
	void (*delete_secrets) (NMSecretAgentOld *self,
	                        NMConnection *connection,
	                        const char *connection_path,
	                        NMSecretAgentOldDeleteSecretsFunc callback,
	                        gpointer user_data);
} NMSecretAgentOldClass;

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.

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.

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

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.

It is a programmer error to attempt to unregister an agent that is not registered.

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.

It is a programmer error to attempt to unregister an agent that is not registered.

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

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

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

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

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

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]

Property Details

The "auto-register" property

  "auto-register"            gboolean              : Read / Write / Construct

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.

Default value: TRUE


The "capabilities" property

  "capabilities"             NMSecretAgentCapabilities  : Read / Write / Construct

A bitfield of NMSecretAgentCapabilities.


The "identifier" property

  "identifier"               gchar*                : Read / Write / Construct Only

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

Default value: NULL


The "registered" property

  "registered"               gboolean              : Read

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

Default value: FALSE