From 724df841a28ccea04de17d446e691cc48dff4760 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Thu, 26 Jan 2012 12:20:52 -0600 Subject: [PATCH] docs: update docs for NMSecretAgent callbacks --- libnm-glib/nm-secret-agent.c | 6 ++-- libnm-glib/nm-secret-agent.h | 62 ++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 3 deletions(-) diff --git a/libnm-glib/nm-secret-agent.c b/libnm-glib/nm-secret-agent.c index 1b4131710c..4d0a825a53 100644 --- a/libnm-glib/nm-secret-agent.c +++ b/libnm-glib/nm-secret-agent.c @@ -655,7 +655,7 @@ auto_register_cb (gpointer user_data) * @setting_name: the name of the secret setting * @hints: (array zero-terminated=1): hints to the agent * @flags: flags that modify the behavior of the request - * @callback: (scope async): a callback, invoked when the operation is done + * @callback: (scope async): a callback, to be invoked when the operation is done * @user_data: (closure): caller-specific data to be passed to @callback * * Asyncronously retrieve secrets belonging to @connection for the @@ -698,7 +698,7 @@ nm_secret_agent_get_secrets (NMSecretAgent *self, * nm_secret_agent_save_secrets: * @self: a #NMSecretAgent * @connection: a #NMConnection - * @callback: (scope async): a callback, invoked when the operation is done + * @callback: (scope async): a callback, to be invoked when the operation is done * @user_data: (closure): caller-specific data to be passed to @callback * * Asyncronously ensure that all secrets inside @connection @@ -729,7 +729,7 @@ nm_secret_agent_save_secrets (NMSecretAgent *self, * nm_secret_agent_delete_secrets: * @self: a #NMSecretAgent * @connection: a #NMConnection - * @callback: (scope async): a callback, invoked when the operation is done + * @callback: (scope async): a callback, to be invoked when the operation is done * @user_data: (closure): caller-specific data to be passed to @callback * * Asynchronously ask the agent to delete all saved secrets belonging to diff --git a/libnm-glib/nm-secret-agent.h b/libnm-glib/nm-secret-agent.h index 2e0cce407d..6c80fa1979 100644 --- a/libnm-glib/nm-secret-agent.h +++ b/libnm-glib/nm-secret-agent.h @@ -77,17 +77,79 @@ typedef struct { GObject parent; } NMSecretAgent; +/** + * NMSecretAgentGetSecretsFunc: + * @agent: the secret agent object + * @connection: the connection for which secrets were requested + * @secrets: (element-type utf8 GLib.HashTable): the #GHashTable containing + * the requested secrets in the same format as an #NMConnection hash (as + * created by nm_connection_to_hash() for example). Each key in @secrets + * should be the name of a #NMSetting object (like "802-11-wireless-security") + * and each value should be a #GHashTable. The sub-hashes map string:#GValue + * 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 + * + * Called as a result of a request by NM to retrieve secrets. When the + * #NMSecretAgent 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 hash table to return the WiFi PSK, you could do + * something like this: + * + * Creating a secrets hash + * + * NMConnection *secrets; + * NMSettingWirelessSecurity *s_wsec; + * GHashTable *secrets_hash; + * + * secrets = nm_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_hash = nm_connection_to_hash (secrets); + * + * (call the NMSecretAgentGetSecretsFunc with secrets_hash) + * + * + */ typedef void (*NMSecretAgentGetSecretsFunc) (NMSecretAgent *agent, NMConnection *connection, GHashTable *secrets, GError *error, gpointer user_data); +/** + * NMSecretAgentSaveSecretsFunc: + * @agent: the secret agent object + * @connection: the connection for which secrets were to be saved + * @error: if the saving secrets failed, give a descriptive error here + * @user_data: caller-specific data to be passed to the function + * + * Called as a result of a request by NM to save secrets. When the + * #NMSecretAgent subclass has finished saving the secrets, this function + * should be called. + */ typedef void (*NMSecretAgentSaveSecretsFunc) (NMSecretAgent *agent, NMConnection *connection, GError *error, gpointer user_data); +/** + * NMSecretAgentDeleteSecretsFunc: + * @agent: the secret agent object + * @connection: the connection for which secrets were to be deleted + * @error: if the deleting secrets failed, give a descriptive error here + * @user_data: caller-specific data to be passed to the function + * + * Called as a result of a request by NM to delete secrets. When the + * #NMSecretAgent subclass has finished deleting the secrets, this function + * should be called. + */ typedef void (*NMSecretAgentDeleteSecretsFunc) (NMSecretAgent *agent, NMConnection *connection, GError *error,