* Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA * @section_id: libpurple-keyring * @short_description: <filename>keyring.h</filename> #define PURPLE_TYPE_KEYRING (purple_keyring_get_type()) * PURPLE_DEFAULT_KEYRING: #define PURPLE_DEFAULT_KEYRING "keyring-internal" * Keyring subsystem error domain. #define PURPLE_KEYRING_ERROR purple_keyring_error_domain() /**************************************************************************/ /* Data structures and types */ /**************************************************************************/ typedef struct _PurpleKeyring PurpleKeyring; /**************************************************************************/ /* Callbacks for keyrings access functions */ /**************************************************************************/ * PurpleKeyringReadCallback: * @password: The password. * @error: Error that may have occurred. * @data: Data passed to the callback. * Callback for once a password is read. * If there was a problem, the password will be NULL, and the error set. typedef void (*PurpleKeyringReadCallback)(PurpleAccount *account, const gchar *password, GError *error, gpointer data); * PurpleKeyringSaveCallback: * @error: Error that may have occurred. * @data: Data passed to the callback. * Callback for once a password has been stored. * If there was a problem, the error will be set. typedef void (*PurpleKeyringSaveCallback)(PurpleAccount *account, GError *error, * PurpleKeyringChangeMasterCallback: * @error: Error that has occurred. * @data: Data passed to the callback. * Callback for once the master password for a keyring has been changed. typedef void (*PurpleKeyringChangeMasterCallback)(GError *error, gpointer data); * PurpleKeyringSetInUseCallback: * @error: An error that might have occurred. * @data: A pointer to user supplied data. * Callback for when we change the keyring. typedef void (*PurpleKeyringSetInUseCallback)(GError *error, gpointer data); /**************************************************************************/ /* Keyrings access functions */ /**************************************************************************/ * @cb: A callback for once the password is found. * @data: Data to be passed to the callback. * Read the password for an account. typedef void (*PurpleKeyringRead)(PurpleAccount *account, PurpleKeyringReadCallback cb, gpointer data); * @password: The password to be stored. If the password is NULL, this * means that the keyring should forget about that password. * @cb: A callback for once the password is saved. * @data: Data to be passed to the callback. * Store a password in the keyring. typedef void (*PurpleKeyringSave)(PurpleAccount *account, const gchar *password, PurpleKeyringSaveCallback cb, gpointer data); * PurpleKeyringCancelRequests: * Cancel all running requests. * After calling that, all queued requests should run their callbacks (most * probably, with failure result). typedef void (*PurpleKeyringCancelRequests)(void); * This will be called so the keyring can do any cleanup it needs. typedef void (*PurpleKeyringClose)(void); * PurpleKeyringImportPassword: * @mode: A keyring specific option that was stored. Can be NULL. * @data: Data that was stored. Can be NULL. * @error: Error that may have occurred. * Import serialized (and maybe encrypted) password. * This is not async because it is not meant to prompt for a master password and * Returns: TRUE on success, FALSE on failure. typedef gboolean (*PurpleKeyringImportPassword)(PurpleAccount *account, const gchar *mode, const gchar *data, GError **error); * PurpleKeyringExportPassword: * @mode: An option field that can be used by the plugin. This is * expected to be a static string. * @data: The data to be stored in the XML node. This string will be * freed using destroy() once not needed anymore. * @error: Will be set if a problem occured. * @destroy: A function to be called, if non NULL, to free data. * Export serialized (and maybe encrypted) password. * Returns: TRUE on success, FALSE on failure. typedef gboolean (*PurpleKeyringExportPassword)(PurpleAccount *account, const gchar **mode, gchar **data, GError **error, GDestroyNotify *destroy); * PurpleKeyringReadSettings: * Returns: New copy of current settings (must be free'd with * purple_request_fields_destroy). typedef PurpleRequestFields * (*PurpleKeyringReadSettings)(void); * PurpleKeyringApplySettings: * @notify_handle: A handle that can be passed to purple_notify_message. * @fields: Modified settings (originally taken from * PurpleKeyringReadSettings). * Applies modified keyring settings. * Returns: TRUE, if succeeded, FALSE otherwise. typedef gboolean (*PurpleKeyringApplySettings)(void *notify_handle, PurpleRequestFields *fields); /**************************************************************************/ /* Setting used keyrings */ /**************************************************************************/ * purple_keyring_find_keyring_by_id: * @id: The id for the keyring. * Find a keyring by an id. * Returns: The keyring, or NULL if not found. purple_keyring_find_keyring_by_id(const gchar *id); * purple_keyring_get_inuse: * Get the keyring being used. purple_keyring_get_inuse(void); * purple_keyring_set_inuse: * @newkeyring: The new keyring to use. * @force: %FALSE if the change can be cancelled. If this is %TRUE * and an error occurs, data might be lost. * @cb: (scope call): A callback for once the change is complete. * @data: Data to be passed to the callback. * Set the keyring to use. This function will move all passwords from * the old keyring to the new one. * If it fails, it will cancel all changes, close the new keyring, and notify * the callback. If it succeeds, it will remove all passwords from the old safe purple_keyring_set_inuse(PurpleKeyring *newkeyring, gboolean force, PurpleKeyringSetInUseCallback cb, gpointer data); * purple_keyring_register: * @keyring: The keyring to register. * Register a keyring plugin. purple_keyring_register(PurpleKeyring *keyring); * purple_keyring_unregister: * @keyring: The keyring to unregister. * Unregister a keyring plugin. * In case the keyring is in use, passwords will be moved to a fallback safe, * and the keyring to unregister will be properly closed. purple_keyring_unregister(PurpleKeyring *keyring); * purple_keyring_get_options: * Returns a GList containing the IDs and names of the registered * Returns: (element-type utf8) (transfer container): The list of IDs and names. purple_keyring_get_options(void); /**************************************************************************/ /* Keyring plugin wrappers */ /**************************************************************************/ * purple_keyring_import_password: * @keyring_id: The plugin ID that was stored in the xml file. Can be NULL. * @mode: A keyring specific option that was stored. Can be NULL. * @data: Data that was stored, can be NULL. * @error: Error that may have occurred. * Import serialized (and maybe encrypted) password into current keyring. * It's used by account.c while reading a password from xml. * Returns: TRUE if the input was accepted, FALSE otherwise. purple_keyring_import_password(PurpleAccount *account, const gchar *keyring_id, const gchar *mode, const gchar *data, GError **error); * purple_keyring_export_password: * @account: The account for which we want the info. * @keyring_id: The plugin id to be stored in the XML node. This will be * NULL or a string that can be considered static. * @mode: An option field that can be used by the plugin. This will * be NULL or a string that can be considered static. * @data: The data to be stored in the XML node. This string must be * freed using destroy() once not needed anymore if it is not * @error: Will be set if a problem occured. * @destroy: A function to be called, if non NULL, to free data. * Export serialized (and maybe encrypted) password out of current keyring. * It's used by account.c while syncing accounts to xml. * Returns: TRUE if the info was exported successfully, FALSE otherwise. purple_keyring_export_password(PurpleAccount *account, const gchar **keyring_id, const gchar **mode, gchar **data, GError **error, GDestroyNotify *destroy); * purple_keyring_get_password: * @cb: (scope call): A callback for once the password is read. * @data: Data passed to the callback. * Read a password from the current keyring. purple_keyring_get_password(PurpleAccount *account, PurpleKeyringReadCallback cb, gpointer data); * purple_keyring_set_password: * @password: The password to save. * @cb: (scope call): A callback for once the password is saved. * @data: Data to be passed to the callback. * Save a password to the current keyring. purple_keyring_set_password(PurpleAccount *account, const gchar *password, PurpleKeyringSaveCallback cb, gpointer data); * purple_keyring_read_settings: * Reads settings from current keyring. * Returns: New copy of current settings (must be free'd with * purple_request_fields_destroy). purple_keyring_read_settings(void); * purple_keyring_apply_settings: * @notify_handle: A handle that can be passed to purple_notify_message. * @fields: Modified settings (originally taken from * PurpleKeyringReadSettings). * Applies modified settings to current keyring. * Returns: TRUE, if succeeded, FALSE otherwise. purple_keyring_apply_settings(void *notify_handle, PurpleRequestFields *fields); /**************************************************************************/ /* PurpleKeyring accessors */ /**************************************************************************/ * purple_keyring_get_type: * Returns: The #GType for the #PurpleKeyring boxed structure. GType purple_keyring_get_type(void); * Creates a new keyring wrapper. purple_keyring_new(void); * @keyring: Keyring wrapper struct. * Frees all data allocated with purple_keyring_new. purple_keyring_free(PurpleKeyring *keyring); * purple_keyring_get_name: * Gets friendly user name. * Returns: Friendly user name. purple_keyring_get_name(const PurpleKeyring *keyring); purple_keyring_get_id(const PurpleKeyring *keyring); purple_keyring_get_read_password(const PurpleKeyring *keyring); purple_keyring_get_save_password(const PurpleKeyring *keyring); PurpleKeyringCancelRequests purple_keyring_get_cancel_requests(const PurpleKeyring *keyring); purple_keyring_get_close_keyring(const PurpleKeyring *keyring); PurpleKeyringImportPassword purple_keyring_get_import_password(const PurpleKeyring *keyring); PurpleKeyringExportPassword purple_keyring_get_export_password(const PurpleKeyring *keyring); PurpleKeyringReadSettings purple_keyring_get_read_settings(const PurpleKeyring *keyring); PurpleKeyringApplySettings purple_keyring_get_apply_settings(const PurpleKeyring *keyring); * purple_keyring_set_name: * @name: Friendly user name. * Sets friendly user name. * This field is required. purple_keyring_set_name(PurpleKeyring *keyring, const gchar *name); * This field is required. purple_keyring_set_id(PurpleKeyring *keyring, const gchar *id); * purple_keyring_set_read_password: * @read_cb: (scope call): Read password method. * Sets read password method. * This field is required. purple_keyring_set_read_password(PurpleKeyring *keyring, PurpleKeyringRead read_cb); * purple_keyring_set_save_password: * @save_cb: (scope call): Save password method. * Sets save password method. * This field is required. purple_keyring_set_save_password(PurpleKeyring *keyring, PurpleKeyringSave save_cb); * purple_keyring_set_cancel_requests: * @cancel_requests: (scope call): Cancel requests method. * Sets cancel requests method. purple_keyring_set_cancel_requests(PurpleKeyring *keyring, PurpleKeyringCancelRequests cancel_requests); * purple_keyring_set_close_keyring: * @close_cb: (scope call): Close keyring method. * Sets close keyring method. purple_keyring_set_close_keyring(PurpleKeyring *keyring, PurpleKeyringClose close_cb); * purple_keyring_set_import_password: * @import_password: (scope call): Import password method. * Sets import password method. purple_keyring_set_import_password(PurpleKeyring *keyring, PurpleKeyringImportPassword import_password); * purple_keyring_set_export_password: * @export_password: (scope call): Export password method. * Sets export password method. purple_keyring_set_export_password(PurpleKeyring *keyring, PurpleKeyringExportPassword export_password); * purple_keyring_set_read_settings: * @read_settings: (scope call): Read settings method. * Sets read settings method. purple_keyring_set_read_settings(PurpleKeyring *keyring, PurpleKeyringReadSettings read_settings); * purple_keyring_set_apply_settings: * @apply_settings: (scope call): Apply settings method. * Sets apply settings method. purple_keyring_set_apply_settings(PurpleKeyring *keyring, PurpleKeyringApplySettings apply_settings); /**************************************************************************/ /**************************************************************************/ * purple_keyring_error_domain: * Gets keyring subsystem error domain. * Returns: keyring subsystem error domain. purple_keyring_error_domain(void); * @PURPLE_KEYRING_ERROR_UNKNOWN: Unknown error. * @PURPLE_KEYRING_ERROR_NOKEYRING: No keyring configured. * @PURPLE_KEYRING_ERROR_INTERNAL: Internal keyring system error. * @PURPLE_KEYRING_ERROR_BACKENDFAIL: Failed to communicate with the backend * or internal backend error. * @PURPLE_KEYRING_ERROR_NOPASSWORD: No password stored for the specified * @PURPLE_KEYRING_ERROR_ACCESSDENIED: Access denied for the specified keyring * @PURPLE_KEYRING_ERROR_CANCELLED: Operation was cancelled. * Error codes for keyring subsystem. PURPLE_KEYRING_ERROR_UNKNOWN = 0, PURPLE_KEYRING_ERROR_NOKEYRING = 10, PURPLE_KEYRING_ERROR_INTERNAL, PURPLE_KEYRING_ERROR_BACKENDFAIL, PURPLE_KEYRING_ERROR_NOPASSWORD = 20, PURPLE_KEYRING_ERROR_ACCESSDENIED, PURPLE_KEYRING_ERROR_CANCELLED /**************************************************************************/ /**************************************************************************/ * Initializes the keyring subsystem. purple_keyring_init(void); * Uninitializes the keyring subsystem. purple_keyring_uninit(void); * purple_keyring_get_handle: * Returns the keyring subsystem handle. * Returns: The keyring subsystem handle. purple_keyring_get_handle(void); #endif /* PURPLE_KEYRING_H */