NetworkManager/libnm/nm-secret-agent-old.h

// SPDX-License-Identifier: LGPL-2.1+
/*
 * Copyright (C) 2010 - 2011 Red Hat, Inc.
 */

#ifndef __NM_SECRET_AGENT_OLD_H__
#define __NM_SECRET_AGENT_OLD_H__

#include "nm-types.h"

G_BEGIN_DECLS

#define NM_TYPE_SECRET_AGENT_OLD            (nm_secret_agent_old_get_type ())
#define NM_SECRET_AGENT_OLD(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOld))
#define NM_SECRET_AGENT_OLD_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))
#define NM_IS_SECRET_AGENT_OLD(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_SECRET_AGENT_OLD))
#define NM_IS_SECRET_AGENT_OLD_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), NM_TYPE_SECRET_AGENT_OLD))
#define NM_SECRET_AGENT_OLD_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SECRET_AGENT_OLD, NMSecretAgentOldClass))

#define NM_SECRET_AGENT_OLD_IDENTIFIER          "identifier"
#define NM_SECRET_AGENT_OLD_AUTO_REGISTER       "auto-register"
#define NM_SECRET_AGENT_OLD_REGISTERED          "registered"
#define NM_SECRET_AGENT_OLD_CAPABILITIES        "capabilities"
#define NM_SECRET_AGENT_OLD_DBUS_CONNECTION     "dbus-connection"

/**
 * NMSecretAgentOld:
 */
typedef struct {
	GObject parent;
} NMSecretAgentOld;

/**
 * NMSecretAgentOldGetSecretsFunc:
 * @agent: the secret agent object
 * @connection: (transfer none): 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
 * @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
 *
 * 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>
 *  <title>Creating a secrets dictionary</title>
 *  <programlisting>
 *   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);
 *  </programlisting>
 * </example>
 */
typedef void (*NMSecretAgentOldGetSecretsFunc) (NMSecretAgentOld *agent,
                                                NMConnection *connection,
                                                GVariant *secrets,
                                                GError *error,
                                                gpointer user_data);

/**
 * NMSecretAgentOldSaveSecretsFunc:
 * @agent: the secret agent object
 * @connection: (transfer none): 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
 * @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
 * #NMSecretAgentOld subclass has finished saving the secrets, this function
 * should be called.
 */
typedef void (*NMSecretAgentOldSaveSecretsFunc) (NMSecretAgentOld *agent,
                                                 NMConnection *connection,
                                                 GError *error,
                                                 gpointer user_data);

/**
 * NMSecretAgentOldDeleteSecretsFunc:
 * @agent: the secret agent object
 * @connection: (transfer none): 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
 * @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
 * #NMSecretAgentOld subclass has finished deleting the secrets, this function
 * should be called.
 */
typedef void (*NMSecretAgentOldDeleteSecretsFunc) (NMSecretAgentOld *agent,
                                                   NMConnection *connection,
                                                   GError *error,
                                                   gpointer user_data);

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).
	 *
	 * Before version 1.24, if the request is canceled, the callback
	 * should still be called, but with the NM_SECRET_AGENT_ERROR_AGENT_CANCELED
	 * error. Since 1.24, invoking the callback has no effect during cancellation
	 * and may be omitted.
	 */
	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.
	 *
	 * Before version 1.24, canceling the request MUST call the callback that was
	 * passed along with the initial get_secrets call, sending the NM_SECRET_AGENT_ERROR/
	 * NM_SECRET_AGENT_ERROR_AGENT_CANCELED error to that callback. Since 1.24,
	 * the get_secrets callback will be ignored during cancellation and may be omitted.
	 */
	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);

	/*< private >*/
	gpointer padding[8];
} NMSecretAgentOldClass;

GType nm_secret_agent_old_get_type (void);

NM_AVAILABLE_IN_1_24
GDBusConnection *nm_secret_agent_old_get_dbus_connection (NMSecretAgentOld *self);

NM_AVAILABLE_IN_1_24
GMainContext *nm_secret_agent_old_get_main_context (NMSecretAgentOld *self);

NM_AVAILABLE_IN_1_24
GObject *nm_secret_agent_old_get_context_busy_watcher (NMSecretAgentOld *self);

NM_AVAILABLE_IN_1_24
const char *nm_secret_agent_old_get_dbus_name_owner (NMSecretAgentOld *self);

gboolean nm_secret_agent_old_get_registered (NMSecretAgentOld *self);

/*****************************************************************************/

NM_AVAILABLE_IN_1_24
void nm_secret_agent_old_enable (NMSecretAgentOld *self,
                                 gboolean enable);

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

NM_AVAILABLE_IN_1_24
void nm_secret_agent_old_destroy (NMSecretAgentOld *self);

/*****************************************************************************/

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

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

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

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

/*****************************************************************************/

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

G_END_DECLS

#endif /* __NM_SECRET_AGENT_OLD_H__ */