libnm/nm-secret-agent-old.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: t; c-basic-offset: 4 -*- */
   2 /*
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Lesser General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2 of the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the
  15  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16  * Boston, MA 02110-1301 USA.
  17  *
  18  * Copyright 2010 - 2011 Red Hat, Inc.
  19  */
  20
  21 #ifndef __NM_SECRET_AGENT_OLD_H__
  22 #define __NM_SECRET_AGENT_OLD_H__
  23
  24 #include <nm-types.h>
  25
  26 G_BEGIN_DECLS
  27
  28 #define NM_TYPE_SECRET_AGENT_OLD            (nm_secret_agent_old_get_type ())
  29 #define NM_SECRET_AGENT_OLD(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOld))
  30 #define NM_SECRET_AGENT_OLD_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))
  31 #define NM_IS_SECRET_AGENT_OLD(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_SECRET_AGENT_OLD))
  32 #define NM_IS_SECRET_AGENT_OLD_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SECRET_AGENT_OLD))
  33 #define NM_SECRET_AGENT_OLD_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))
  34
  35 #define NM_SECRET_AGENT_OLD_IDENTIFIER          "identifier"
  36 #define NM_SECRET_AGENT_OLD_AUTO_REGISTER       "auto-register"
  37 #define NM_SECRET_AGENT_OLD_REGISTERED          "registered"
  38 #define NM_SECRET_AGENT_OLD_CAPABILITIES        "capabilities"
  39
  40 typedef struct {
  41         GObject parent;
  42 } NMSecretAgentOld;
  43
  44 /**
  45  * NMSecretAgentOldGetSecretsFunc:
  46  * @agent: the secret agent object
  47  * @connection: (transfer none): the connection for which secrets were requested,
  48  * note that this object will be unrefed after the callback has returned, use
  49  * g_object_ref()/g_object_unref() if you want to use this object after the callback
  50  * has returned
  51  * @secrets: the #GVariant of type %NM_VARIANT_TYPE_CONNECTION containing the requested
  52  * secrets (as created by nm_connection_to_dbus() for example).  Each key in @secrets
  53  * should be the name of a #NMSetting object (like "802-11-wireless-security")
  54  * and each value should be an %NM_VARIANT_TYPE_SETTING variant.  The sub-dicts
  55  * map string:value, where the string is the setting property name (like "psk")
  56  * and the value is the secret
  57  * @error: if the secrets request failed, give a descriptive error here
  58  * @user_data: caller-specific data to be passed to the function
  59  *
  60  * Called as a result of a request by NM to retrieve secrets.  When the
  61  * #NMSecretAgentOld subclass has finished retrieving secrets and is ready to
  62  * return them, or to return an error, this function should be called with
  63  * those secrets or the error.
  64  *
  65  * To easily create the dictionary to return the Wi-Fi PSK, you could do
  66  * something like this:
  67  * <example>
  68  *  <title>Creating a secrets dictionary</title>
  69  *  <programlisting>
  70  *   NMConnection *secrets;
  71  *   NMSettingWirelessSecurity *s_wsec;
  72  *   GVariant *secrets_dict;
  73  *
  74  *   secrets = nm_simple_connection_new ();
  75  *   s_wsec = (NMSettingWirelessSecurity *) nm_setting_wireless_security_new ();
  76  *   g_object_set (G_OBJECT (s_wsec),
  77  *                 NM_SETTING_WIRELESS_SECURITY_PSK, "my really cool PSK",
  78  *                 NULL);
  79  *   nm_connection_add_setting (secrets, NM_SETTING (s_wsec));
  80  *   secrets_dict = nm_connection_to_dbus (secrets, NM_CONNECTION_SERIALIZE_ALL);
  81  *
  82  *   (call the NMSecretAgentOldGetSecretsFunc with secrets_dict)
  83  *
  84  *   g_object_unref (secrets);
  85  *   g_variant_unref (secrets_dict);
  86  *  </programlisting>
  87  * </example>
  88  */
  89 typedef void (*NMSecretAgentOldGetSecretsFunc) (NMSecretAgentOld *agent,
  90                                                 NMConnection *connection,
  91                                                 GVariant *secrets,
  92                                                 GError *error,
  93                                                 gpointer user_data);
  94
  95 /**
  96  * NMSecretAgentOldSaveSecretsFunc:
  97  * @agent: the secret agent object
  98  * @connection: (transfer none): the connection for which secrets were to be saved,
  99  * note that this object will be unrefed after the callback has returned, use
 100  * g_object_ref()/g_object_unref() if you want to use this object after the callback
 101  * has returned
 102  * @error: if the saving secrets failed, give a descriptive error here
 103  * @user_data: caller-specific data to be passed to the function
 104  *
 105  * Called as a result of a request by NM to save secrets.  When the
 106  * #NMSecretAgentOld subclass has finished saving the secrets, this function
 107  * should be called.
 108  */
 109 typedef void (*NMSecretAgentOldSaveSecretsFunc) (NMSecretAgentOld *agent,
 110                                                  NMConnection *connection,
 111                                                  GError *error,
 112                                                  gpointer user_data);
 113
 114 /**
 115  * NMSecretAgentOldDeleteSecretsFunc:
 116  * @agent: the secret agent object
 117  * @connection: (transfer none): the connection for which secrets were to be deleted,
 118  * note that this object will be unrefed after the callback has returned, use
 119  * g_object_ref()/g_object_unref() if you want to use this object after the callback
 120  * has returned
 121  * @error: if the deleting secrets failed, give a descriptive error here
 122  * @user_data: caller-specific data to be passed to the function
 123  *
 124  * Called as a result of a request by NM to delete secrets.  When the
 125  * #NMSecretAgentOld subclass has finished deleting the secrets, this function
 126  * should be called.
 127  */
 128 typedef void (*NMSecretAgentOldDeleteSecretsFunc) (NMSecretAgentOld *agent,
 129                                                    NMConnection *connection,
 130                                                    GError *error,
 131                                                    gpointer user_data);
 132
 133 typedef struct {
 134         GObjectClass parent;
 135
 136         /* Virtual methods for subclasses */
 137
 138         /* Called when the subclass should retrieve and return secrets.  Subclass
 139          * must copy or reference any arguments it may require after returning from
 140          * this method, as the arguments will freed (except for 'self', 'callback',
 141          * and 'user_data' of course).  If the request is canceled, the callback
 142          * should still be called, but with the
 143          * NM_SECRET_AGENT_OLD_ERROR_AGENT_CANCELED error.
 144          */
 145         void (*get_secrets) (NMSecretAgentOld *self,
 146                              NMConnection *connection,
 147                              const char *connection_path,
 148                              const char *setting_name,
 149                              const char **hints,
 150                              NMSecretAgentGetSecretsFlags flags,
 151                              NMSecretAgentOldGetSecretsFunc callback,
 152                              gpointer user_data);
 153
 154         /* Called when the subclass should cancel an outstanding request to
 155          * get secrets for a given connection.  Canceling the request MUST
 156          * call the callback that was passed along with the initial get_secrets
 157          * call, sending the NM_SECRET_AGENT_OLD_ERROR/
 158          * NM_SECRET_AGENT_OLD_ERROR_AGENT_CANCELED error to that callback.
 159          */
 160         void (*cancel_get_secrets) (NMSecretAgentOld *self,
 161                                     const char *connection_path,
 162                                     const char *setting_name);
 163
 164         /* Called when the subclass should save the secrets contained in the
 165          * connection to backing storage.  Subclass must copy or reference any
 166          * arguments it may require after returning from this method, as the
 167          * arguments will freed (except for 'self', 'callback', and 'user_data'
 168          * of course).
 169          */
 170         void (*save_secrets) (NMSecretAgentOld *self,
 171                               NMConnection *connection,
 172                               const char *connection_path,
 173                               NMSecretAgentOldSaveSecretsFunc callback,
 174                               gpointer user_data);
 175
 176         /* Called when the subclass should delete the secrets contained in the
 177          * connection from backing storage.  Subclass must copy or reference any
 178          * arguments it may require after returning from this method, as the
 179          * arguments will freed (except for 'self', 'callback', and 'user_data'
 180          * of course).
 181          */
 182         void (*delete_secrets) (NMSecretAgentOld *self,
 183                                 NMConnection *connection,
 184                                 const char *connection_path,
 185                                 NMSecretAgentOldDeleteSecretsFunc callback,
 186                                 gpointer user_data);
 187
 188         /*< private >*/
 189         gpointer padding[8];
 190 } NMSecretAgentOldClass;
 191
 192 GType nm_secret_agent_old_get_type (void);
 193
 194 gboolean nm_secret_agent_old_register        (NMSecretAgentOld *self,
 195                                               GCancellable *cancellable,
 196                                               GError **error);
 197 void     nm_secret_agent_old_register_async  (NMSecretAgentOld *self,
 198                                               GCancellable *cancellable,
 199                                               GAsyncReadyCallback callback,
 200                                               gpointer user_data);
 201 gboolean nm_secret_agent_old_register_finish (NMSecretAgentOld *self,
 202                                               GAsyncResult *result,
 203                                               GError **error);
 204
 205 gboolean nm_secret_agent_old_unregister        (NMSecretAgentOld *self,
 206                                                 GCancellable *cancellable,
 207                                                 GError **error);
 208 void     nm_secret_agent_old_unregister_async  (NMSecretAgentOld *self,
 209                                                 GCancellable *cancellable,
 210                                                 GAsyncReadyCallback callback,
 211                                                 gpointer user_data);
 212 gboolean nm_secret_agent_old_unregister_finish (NMSecretAgentOld *self,
 213                                                 GAsyncResult *result,
 214                                                 GError **error);
 215
 216 gboolean nm_secret_agent_old_get_registered (NMSecretAgentOld *self);
 217
 218 void nm_secret_agent_old_get_secrets (NMSecretAgentOld *self,
 219                                       NMConnection *connection,
 220                                       const char *setting_name,
 221                                       const char **hints,
 222                                       NMSecretAgentGetSecretsFlags flags,
 223                                       NMSecretAgentOldGetSecretsFunc callback,
 224                                       gpointer user_data);
 225
 226 void nm_secret_agent_old_save_secrets (NMSecretAgentOld *self,
 227                                        NMConnection *connection,
 228                                        NMSecretAgentOldSaveSecretsFunc callback,
 229                                        gpointer user_data);
 230
 231 void nm_secret_agent_old_delete_secrets (NMSecretAgentOld *self,
 232                                          NMConnection *connection,
 233                                          NMSecretAgentOldDeleteSecretsFunc callback,
 234                                          gpointer user_data);
 235
 236 G_END_DECLS
 237
 238 #endif /* __NM_SECRET_AGENT_OLD_H__ */