diff options
Diffstat (limited to 'libsecret/secret-service.c')
| -rw-r--r-- | libsecret/secret-service.c | 121 |
1 files changed, 58 insertions, 63 deletions
diff --git a/libsecret/secret-service.c b/libsecret/secret-service.c index 455248c..bdb8bd7 100644 --- a/libsecret/secret-service.c +++ b/libsecret/secret-service.c @@ -30,59 +30,54 @@ #include "egg/egg-secure-memory.h" /** - * SECTION:secret-service - * @title: SecretService - * @short_description: the Secret Service + * SecretService: + * + * A proxy object representing the Secret Service. * * A #SecretService object represents the Secret Service implementation which * runs as a D-Bus service. * * Normally a single #SecretService object can be shared between multiple - * callers. The secret_service_get() method is used to access this #SecretService + * callers. The [func@Service.get] method is used to access this #SecretService * object. If a new independent #SecretService object is required, use - * secret_service_open(). + * [func@Service.open]. * * In order to securely transfer secrets to the Sercret Service, a session * is established. This session can be established while initializing a * #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag - * to the secret_service_get() or secret_service_open() functions. In order to + * to the [func@Service.get] or [func@Service.open] functions. In order to * establish a session on an already existing #SecretService, use the - * secret_service_ensure_session() function. + * [method@Service.ensure_session] function. * - * To search for items, use the secret_service_search() method. + * To search for items, use the [method@Service.search] method. * * Multiple collections can exist in the Secret Service, each of which contains - * secret items. In order to instantiate #SecretCollection objects which + * secret items. In order to instantiate [class@Collection] objects which * represent those collections while initializing a #SecretService then pass - * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or - * secret_service_open() functions. In order to establish a session on an already - * existing #SecretService, use the secret_service_load_collections() function. - * To access the list of collections use secret_service_get_collections(). + * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the [func@Service.get] or + * [func@Service.open] functions. In order to establish a session on an already + * existing #SecretService, use the [method@Service.load_collections] function. + * To access the list of collections use [method@Service.get_collections]. * * Certain actions on the Secret Service require user prompting to complete, * such as creating a collection, or unlocking a collection. When such a prompt - * is necessary, then a #SecretPrompt object is created by this library, and - * passed to the secret_service_prompt() method. In this way it is handled + * is necessary, then a [class@Prompt] object is created by this library, and + * passed to the [method@Service.prompt] method. In this way it is handled * automatically. * - * In order to customize prompt handling, override the <literal>prompt_async</literal> - * and <literal>prompt_finish</literal> virtual methods of the #SecretService class. + * In order to customize prompt handling, override the + * [vfunc@Service.prompt_async] and [vfunc@Service.prompt_finish] virtual + * methods of the #SecretService class. * * Stability: Stable */ /** - * SecretService: - * - * A proxy object representing the Secret Service. - */ - -/** * SecretServiceClass: * @parent_class: the parent class - * @collection_gtype: the #GType of the #SecretCollection objects instantiated + * @collection_gtype: the [alias@GLib.Type] of the [class@Collection] objects instantiated * by the #SecretService proxy - * @item_gtype: the #GType of the #SecretItem objects instantiated by the + * @item_gtype: the [alias@GLib.Type] of the [class@Item] objects instantiated by the * #SecretService proxy * @prompt_async: called to perform asynchronous prompting when necessary * @prompt_finish: called to complete an asynchronous prompt operation @@ -104,7 +99,7 @@ * #SecretService * * Flags which determine which parts of the #SecretService proxy are initialized - * during a secret_service_get() or secret_service_open() operation. + * during a [func@Service.get] or [func@Service.open] operation. */ EGG_SECURE_DEFINE_GLIB_GLOBALS (); @@ -587,15 +582,15 @@ secret_service_class_init (SecretServiceClass *klass) g_object_class_override_property (object_class, PROP_FLAGS, "flags"); /** - * SecretService:collections: + * SecretService:collections: (attributes org.gtk.Property.get=secret_service_get_collections) * - * A list of #SecretCollection objects representing the collections in + * A list of [class@Collection] objects representing the collections in * the Secret Service. This list may be %NULL if the collections have * not been loaded. * * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS - * initialization flag when calling the secret_service_get() or - * secret_service_open() functions. Or call the secret_service_load_collections() + * initialization flag when calling the [func@Service.get] or + * [func@Service.open] functions. Or call the [method@Service.load_collections] * method. */ g_object_class_install_property (object_class, PROP_COLLECTIONS, @@ -1002,7 +997,7 @@ secret_service_get (SecretServiceFlags flags, * Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_finish (GAsyncResult *result, @@ -1058,7 +1053,7 @@ secret_service_get_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_get_sync (SecretServiceFlags flags, @@ -1090,8 +1085,8 @@ secret_service_get_sync (SecretServiceFlags flags, /** * secret_service_disconnect: * - * Disconnect the default #SecretService proxy returned by secret_service_get() - * and secret_service_get_sync(). + * Disconnect the default #SecretService proxy returned by [func@Service.get] + * and [func@Service.get_sync]. * * It is not necessary to call this function, but you may choose to do so at * program exit. It is useful for testing that memory is not leaked. @@ -1117,7 +1112,7 @@ secret_service_disconnect (void) * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get() instead. + * This function is rarely used, see [func@Service.get] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the type * of a derived class. @@ -1155,7 +1150,7 @@ secret_service_open (GType service_gtype, * the Secret Service. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_finish (GAsyncResult *result, @@ -1188,7 +1183,7 @@ secret_service_open_finish (GAsyncResult *result, * * Create a new #SecretService proxy for the Secret Service. * - * This function is rarely used, see secret_service_get_sync() instead. + * This function is rarely used, see [func@Service.get_sync] instead. * * The @service_gtype argument should be set to %SECRET_TYPE_SERVICE or a the * type of a derived class. @@ -1202,7 +1197,7 @@ secret_service_open_finish (GAsyncResult *result, * threads. * * Returns: (transfer full): a new reference to a #SecretService proxy, which - * should be released with g_object_unref(). + * should be released with [method@GObject.Object.unref]. */ SecretService * secret_service_open_sync (GType service_gtype, @@ -1226,7 +1221,7 @@ secret_service_open_sync (GType service_gtype, * Get the flags representing what features of the #SecretService proxy * have been initialized. * - * Use secret_service_ensure_session() or secret_service_load_collections() + * Use [method@Service.ensure_session] or [method@Service.load_collections] * to initialize further features and change the flags. * * Returns: the flags for features initialized @@ -1251,18 +1246,18 @@ secret_service_get_flags (SecretService *self) } /** - * secret_service_get_collections: + * secret_service_get_collections: (attributes org.gtk.Method.get_property=collections) * @self: the secret service proxy * - * Get a list of #SecretCollection objects representing all the collections + * Get a list of [class@Collection] objects representing all the collections * in the secret service. * * If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when * initializing #SecretService proxy object, then this method will return - * %NULL. Use secret_service_load_collections() to load the collections. + * %NULL. Use [method@Service.load_collections] to load the collections. * * Returns: (transfer full) (element-type Secret.Collection) (nullable): a - * list of the collections in the secret service + * list of the collections in the secret service */ GList * secret_service_get_collections (SecretService *self) @@ -1364,7 +1359,7 @@ _secret_service_take_session (SecretService *self, * secret service proxy and the Secret Service itself. * * This will be %NULL if no session has been established. Use - * secret_service_ensure_session() to establish a session. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the algorithms for transferring * secrets @@ -1394,10 +1389,10 @@ secret_service_get_session_algorithms (SecretService *self) * secrets between this secret service proxy and the Secret Service itself. * * This will be %NULL if no session has been established. Use - * secret_service_ensure_session() to establish a session. + * [method@Service.ensure_session] to establish a session. * * Returns: (nullable): a string representing the D-Bus object path of the - * session + * session */ const gchar * secret_service_get_session_dbus_path (SecretService *self) @@ -1428,7 +1423,7 @@ secret_service_get_session_dbus_path (SecretService *self) * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get() in order to ensure that a session has been established + * to [func@Service.get] in order to ensure that a session has been established * by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1500,7 +1495,7 @@ secret_service_ensure_session_finish (SecretService *self, * * It is not normally necessary to call this method, as the session is * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION - * to secret_service_get_sync() in order to ensure that a session has been + * to [func@Service.get_sync] in order to ensure that a session has been * established by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1638,10 +1633,10 @@ on_ensure_collection (GObject *source, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method will return immediately and complete asynchronously. @@ -1735,10 +1730,10 @@ secret_service_load_collections_finish (SecretService *self, * * Ensure that the #SecretService proxy has loaded all the collections present * in the Secret Service. This affects the result of - * secret_service_get_collections(). + * [method@Service.get_collections]. * * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to - * secret_service_get_sync() in order to ensure that the collections have been + * [func@Service.get_sync] in order to ensure that the collections have been * loaded by the time you get the #SecretService proxy. * * This method may block indefinitely and should not be used in user interface @@ -1801,7 +1796,7 @@ secret_service_load_collections_sync (SecretService *self, * @return_type: the variant type of the prompt result * @error: location to place an error on failure * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * Runs a prompt and performs the prompting. Returns a variant result if the * prompt was completed and not dismissed. The type of result depends on the @@ -1811,12 +1806,12 @@ secret_service_load_collections_sync (SecretService *self, * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass <literal>prompt_sync</literal> virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_sync] virtual method * to change the behavior of the prompting. The default behavior is to simply - * run secret_prompt_perform_sync() on the prompt with a %NULL <literal>window_id</literal>. + * run [method@Prompt.perform_sync] on the prompt with a %NULL `window_id`. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_sync (SecretService *self, @@ -1847,14 +1842,14 @@ secret_service_prompt_sync (SecretService *self, * @callback: called when the operation completes * @user_data: data to be passed to the callback * - * Perform prompting for a #SecretPrompt. + * Perform prompting for a [class@Prompt]. * * This function is called by other parts of this library to handle prompts * for the various actions that can require prompting. * - * Override the #SecretServiceClass <literal>prompt_async</literal> virtual method + * Override the #SecretServiceClass [vfunc@Service.prompt_async] virtual method * to change the behavior of the prompting. The default behavior is to simply - * run secret_prompt_perform() on the prompt. + * run [method@Prompt.perform] on the prompt. */ void secret_service_prompt (SecretService *self, @@ -1882,14 +1877,14 @@ secret_service_prompt (SecretService *self, * @result: the asynchronous result passed to the callback * @error: location to place an error on failure * - * Complete asynchronous operation to perform prompting for a #SecretPrompt. + * Complete asynchronous operation to perform prompting for a [class@Prompt]. * * Returns a variant result if the prompt was completed and not dismissed. The * type of result depends on the action the prompt is completing, and is defined * in the Secret Service DBus API specification. * * Returns: (transfer full): %NULL if the prompt was dismissed or an error occurred, - * a variant result if the prompt was successful + * a variant result if the prompt was successful */ GVariant * secret_service_prompt_finish (SecretService *self, @@ -1913,7 +1908,7 @@ secret_service_prompt_finish (SecretService *self, * @self: the secret service * * Get the GObject type for collections instantiated by this service. - * This will always be either #SecretCollection or derived from it. + * This will always be either [class@Collection] or derived from it. * * Returns: the gobject type for collections */ @@ -1941,7 +1936,7 @@ secret_service_get_collection_gtype (SecretService *self) * @self: the service * * Get the GObject type for items instantiated by this service. - * This will always be either #SecretItem or derived from it. + * This will always be either [class@Item] or derived from it. * * Returns: the gobject type for items */ |