Cypher_Stack/libsecret
2
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/libsecret.git synced 2024-12-22 04:38:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Mark most of unstable API as stable

Browse Source 
This is with the exception of the 'path' functions.
This commit is contained in:
Stef Walter 2013-12-11 10:32:25 +01:00
parent 71e2791ea3
commit dd6fcf87bb
18 changed files with 44 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/reference/libsecret/libsecret-using.sgml
View File

@ -64,22 +64,6 @@ var schema = new Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
</programlisting></informalexample>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
It is <emphasis>not</emphasis> recommended that you use these unstable parts
from javascript. Your code <emphasis>will break</emphasis> when the unstable API
changes, and due to the lack of a compiler you will have no way of knowing when
it does. If you must use the unstable API, you would do it like this:
</para>
<informalexample><programlisting language="javascript">
// Warning: if you use the unstable API from javascript, your're going to have a bad time
const SecretUnstable = imports.gi.SecretUnstable;
// ... and a here's sample line of code which uses the import
var collection = SecretUnstable.Collection.for_alias(null, "default", null);
</programlisting></informalexample>
</chapter>
<chapter id="using-python">
@ -98,22 +82,6 @@ schema = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
</programlisting></informalexample>
<para>
Some parts of the <application>libsecret</application> API are not yet stable.
It is <emphasis>not</emphasis> recommended that you use these unstable parts
from python. Your code <emphasis>will break</emphasis> when the unstable API
changes, and due to the lack of a compiler you will have no way of knowing when
it does. If you must use the unstable API, you would do it like this:
</para>
<informalexample><programlisting language="py">
# Warning: if you use the unstable API from python, your're going to have a bad time
from gi.repository import SecretUnstable
# ... and a here's sample line of code which uses the import
collection = SecretUnstable.Collection.for_alias(None, "default", None);
</programlisting></informalexample>
</chapter>
<chapter id="using-vala">

21
libsecret/Makefile.am
View File

@ -39,22 +39,22 @@ BUILT_SOURCES = \
STABLE_FILES = \
secret-attributes.h secret-attributes.c \
secret-password.h secret-password.c \
secret-schema.h secret-schema.c \
secret-schemas.h secret-schemas.c \
secret-types.h \
$(NULL)
UNSTABLE_FILES = \
secret-collection.h secret-collection.c \
secret-item.h secret-item.c \
secret-methods.c \
secret-paths.h secret-paths.c \
secret-password.h secret-password.c \
secret-prompt.h secret-prompt.c \
secret-schema.h secret-schema.c \
secret-schemas.h secret-schemas.c \
secret-service.h secret-service.c \
secret-types.h \
secret-value.h secret-value.c \
$(NULL)
UNSTABLE_FILES = \
secret-paths.h secret-paths.c \
$(NULL)
PRIVATE_FILES = \
secret-private.h \
secret-session.c \
@ -144,7 +144,9 @@ SecretUnstable_0_gir_FILES = $(UNSTABLE_FILES)
SecretUnstable_0_gir_SCANNERFLAGS = --c-include "libsecret/secret.h" --identifier-prefix=Secret --symbol-prefix=secret --include-uninstalled=$(builddir)/Secret-@SECRET_MAJOR@.gir
girdir = $(datadir)/gir-1.0
gir_DATA = $(INTROSPECTION_GIRS)
gir_DATA = Secret-@SECRET_MAJOR@.gir
noinst_DATA = SecretUnstable-0.gir
typelibsdir = $(libdir)/girepository-1.0
typelibs_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
@ -217,6 +219,7 @@ CLEANFILES += \
$(pkgconfig_DATA) \
$(gir_DATA) \
$(typelibs_DATA) \
$(noinst_DATA) \
temp-dbus-generated.c \
temp-dbus-generated.h \
$(NULL)

11
libsecret/secret-collection.c
View File

@ -40,10 +40,7 @@
* lookup the items in the collection. There may not be any items exposed when
* the collection is locked.
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
/**
@ -1467,7 +1464,7 @@ secret_collection_search (SecretCollection *self,
*
* Complete asynchronous operation to search for items in a collection.
*
* Returns: (transfer full) (element-type SecretUnstable.Item):
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
*/
GList *
@ -1557,7 +1554,7 @@ collection_load_items_sync (SecretCollection *self,
* This function may block indefinetely. Use the asynchronous version
* in user interface threads.
*
* Returns: (transfer full) (element-type SecretUnstable.Item):
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
*/
GList *
@ -1778,7 +1775,7 @@ secret_collection_get_flags (SecretCollection *self)
*
* Get the list of items in this collection.
*
* Returns: (transfer full) (element-type SecretUnstable.Item): a list of items,
* Returns: (transfer full) (element-type Secret.Item): a list of items,
* when done, the list should be freed with g_list_free, and each item should
* be released with g_object_unref()
*/

9
libsecret/secret-item.c
View File

@ -50,10 +50,7 @@
*
* Items can be created with secret_item_create() or secret_service_store().
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
/**
@ -1405,7 +1402,7 @@ on_loads_secrets_session (GObject *source,
/**
* secret_item_load_secrets:
* @items: (element-type SecretUnstable.Item): the items to retrieve secrets for
* @items: (element-type Secret.Item): the items to retrieve secrets for
* @cancellable: optional cancellation object
* @callback: called when the operation completes
* @user_data: data to pass to the callback
@ -1504,7 +1501,7 @@ secret_item_load_secrets_finish (GAsyncResult *result,
/**
* secret_item_load_secrets_sync:
* @items: (element-type SecretUnstable.Item): the items to retrieve secrets for
* @items: (element-type Secret.Item): the items to retrieve secrets for
* @cancellable: optional cancellation object
* @error: location to place an error on failure
*

4
libsecret/secret-methods.c
View File

@ -342,7 +342,7 @@ secret_service_search (SecretService *service,
*
* Complete asynchronous operation to search for items.
*
* Returns: (transfer full) (element-type SecretUnstable.Item):
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
*/
GList *
@ -432,7 +432,7 @@ service_load_items_sync (SecretService *service,
* This function may block indefinetely. Use the asynchronous version
* in user interface threads.
*
* Returns: (transfer full) (element-type SecretUnstable.Item):
* Returns: (transfer full) (element-type Secret.Item):
* a list of items that matched the search
*/
GList *

5
libsecret/secret-password.c
View File

@ -39,10 +39,7 @@
* Each of the functions accept a variable list of attributes names and their
* values. Include a %NULL to terminate the list of attributes.
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
/**

7
libsecret/secret-paths.c
View File

@ -36,9 +36,6 @@
* service using the DBus API directly, and only wish to use a few calls
* in libsecret.
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
*/
@ -906,7 +903,7 @@ secret_service_get_secrets_for_dbus_paths (SecretService *self,
*
* Items that are locked will not be included the results.
*
* Returns: (transfer full) (element-type utf8 SecretUnstable.Value): a newly
* Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue
* values.
*/
@ -949,7 +946,7 @@ secret_service_get_secrets_for_dbus_paths_finish (SecretService *self,
*
* Items that are locked will not be included the results.
*
* Returns: (transfer full) (element-type utf8 SecretUnstable.Value): a newly
* Returns: (transfer full) (element-type utf8 Secret.Value): a newly
* allocated hash table of item_path keys to #SecretValue
* values.
*/

5
libsecret/secret-prompt.c
View File

@ -38,10 +38,7 @@
* SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
* virtual methods of the #SecretService class.
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
/**

7
libsecret/secret-service.c
View File

@ -66,10 +66,7 @@
* In order to customize prompt handling, override the <literal>prompt_async</literal>
* and <literal>prompt_finish</literal> virtual methods of the #SecretService class.
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
/**
@ -1101,7 +1098,7 @@ secret_service_get_flags (SecretService *self)
* initializing #SecretService proxy object, then this method will return
* %NULL. Use secret_service_load_collections() to load the collections.
*
* Returns: (transfer full) (element-type SecretUnstable.Collection) (allow-none): a
* Returns: (transfer full) (element-type Secret.Collection) (allow-none): a
* list of the collections in the secret service
*/
GList *

7
libsecret/secret-value.c
View File

@ -38,10 +38,7 @@
* #SecretValue is reference counted and immutable. The secret data is only
* freed when all references have been released via secret_value_unref().
*
* These functions have an unstable API and may change across versions. Use
* <literal>libsecret-unstable</literal> package to access them.
*
* Stability: Unstable
* Stability: Stable
*/
static gboolean is_password_value (SecretValue *value);
@ -226,7 +223,7 @@ secret_value_ref (SecretValue *value)
/**
* secret_value_unref:
* @value: (type SecretUnstable.Value) (allow-none): value to unreference
* @value: (type Secret.Value) (allow-none): value to unreference
*
* Unreference a #SecretValue. When the last reference is gone, then
* the value will be freed.

12
libsecret/secret.h
View File

@ -20,10 +20,16 @@
#define __SECRET_INSIDE_HEADER__
#include <libsecret/secret-attributes.h>
#include <libsecret/secret-collection.h>
#include <libsecret/secret-enum-types.h>
#include <libsecret/secret-item.h>
#include <libsecret/secret-password.h>
#include <libsecret/secret-prompt.h>
#include <libsecret/secret-schema.h>
#include <libsecret/secret-schemas.h>
#include <libsecret/secret-service.h>
#include <libsecret/secret-types.h>
#include <libsecret/secret-value.h>
/* SECRET_WITH_UNSTABLE is defined in the secret-unstable.pc pkg-config file */
#if defined(SECRET_WITH_UNSTABLE) || defined(SECRET_API_SUBJECT_TO_CHANGE)
@ -32,13 +38,7 @@
#warning "Some parts of the libsecret API are unstable. Define SECRET_API_SUBJECT_TO_CHANGE to acknowledge"
#endif
#include <libsecret/secret-collection.h>
#include <libsecret/secret-enum-types.h>
#include <libsecret/secret-item.h>
#include <libsecret/secret-paths.h>
#include <libsecret/secret-prompt.h>
#include <libsecret/secret-service.h>
#include <libsecret/secret-value.h>
#endif /* SECRET_WITH_UNSTABLE || SECRET_API_SUBJECT_TO_CHANGE */

4
libsecret/tests/Makefile.am
View File

@ -59,7 +59,7 @@ JS_TESTS = \
test-lookup-password.js \
test-clear-password.js \
test-store-password.js \
test-unstable.js
$(NULL)
JS_ENV = \
LD_LIBRARY_PATH=$(builddir)/../.libs:$(builddir)/.libs \
@ -69,7 +69,7 @@ PY_TESTS = \
test-lookup-password.py \
test-clear-password.py \
test-store-password.py \
test-unstable.py
$(NULL)
PY_ENV = $(JS_ENV)

4
libsecret/tests/test-clear-password.py
View File

@ -15,7 +15,7 @@ import sys
import unittest
from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib
from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE,
@ -31,7 +31,7 @@ class TestRemove(unittest.TestCase):
Mock.start("mock-service-normal.py")
def tearDown(self):
SecretUnstable.Service.disconnect()
Secret.Service.disconnect()
Mock.stop()
def testSynchronous(self):

4
libsecret/tests/test-lookup-password.py
View File

@ -14,7 +14,7 @@
import unittest
from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib
from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE,
@ -30,7 +30,7 @@ class TestLookup(unittest.TestCase):
Mock.start("mock-service-normal.py")
def tearDown(self):
SecretUnstable.Service.disconnect()
Secret.Service.disconnect()
Mock.stop()
def testSynchronous(self):

4
libsecret/tests/test-store-password.py
View File

@ -14,7 +14,7 @@
import unittest
from gi.repository import MockService as Mock
from gi.repository import Secret, SecretUnstable, GLib
from gi.repository import Secret, GLib
STORE_SCHEMA = Secret.Schema.new("org.mock.Schema",
Secret.SchemaFlags.NONE,
@ -30,7 +30,7 @@ class TestStore(unittest.TestCase):
Mock.start("mock-service-normal.py")
def tearDown(self):
SecretUnstable.Service.disconnect()
Secret.Service.disconnect()
Mock.stop()
def testSynchronous(self):

27
libsecret/tests/test-unstable.js
View File

@ -1,27 +0,0 @@
/*
* Copyright 2012 Red Hat Inc.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published
* by the Free Software Foundation; either version 2.1 of the licence or (at
* your option) any later version.
*
* See the included COPYING file for more information.
*/
const Mock = imports.gi.MockService;
const Secret = imports.gi.SecretUnstable;
const GLib = imports.gi.GLib;
const JsUnit = imports.jsUnit;
const assertNotEquals = JsUnit.assertNotEquals;
Mock.start("mock-service-normal.py");
var service = Secret.Service.get_sync(Secret.ServiceFlags.NONE, null);
var path = service.read_alias_dbus_path_sync("default", null);
/* Just running this without error is good enough for us to test the unstable gir */
assertNotEquals(path, null);
Mock.stop();

63
libsecret/tests/test-unstable.py
View File

@ -1,63 +0,0 @@
#!/usr/bin/env python
#
# Copyright 2012 Red Hat Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation; either version 2.1 of the licence or (at
# your option) any later version.
#
# See the included COPYING file for more information.
#
import unittest
from gi.repository import MockService as Mock
from gi.repository import SecretUnstable, Secret, GLib
EXAMPLE_SCHEMA = Secret.Schema.new('org.mock.type.Store',
Secret.SchemaFlags.NONE,
{
'number': Secret.SchemaAttributeType.INTEGER,
'string': Secret.SchemaAttributeType.STRING,
'even': Secret.SchemaAttributeType.BOOLEAN,
}
)
attributes = {
'number': '8',
'string': 'eight',
'even': 'true'
}
class TestStore(unittest.TestCase):
def setUp(self):
Mock.start("mock-service-normal.py")
def tearDown(self):
SecretUnstable.Service.disconnect()
Mock.stop()
def testSynchronous(self):
service = SecretUnstable.Service.get_sync(SecretUnstable.ServiceFlags.NONE, None);
path = service.read_alias_dbus_path_sync("default", None);
# Just running this without error is good enough for us to test the unstable gir
self.assertNotEqual(path, None);
def testValueGet(self):
Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
'the label', 'the password', None)
service = SecretUnstable.Service.get_sync(SecretUnstable.ServiceFlags.NONE, None)
items = service.search_sync(EXAMPLE_SCHEMA, { 'even': 'true' },
SecretUnstable.SearchFlags.ALL | SecretUnstable.SearchFlags.LOAD_SECRETS,
None)
item = items[0]
item_secret = item.get_secret()
self.assertEqual(item_secret.get(), "the password")
if __name__ == '__main__':
unittest.main()

2
libsecret/tests/test-vala-unstable.vala
View File

@ -12,7 +12,7 @@
private void test_read_alias () {
try {
var service = Secret.Service.get_sync(Secret.ServiceFlags.NONE);
var path = service.read_alias_dbus_path_sync("default", null);
var path = Secret.service_read_alias_dbus_path_sync(service, "default", null);
GLib.assert (path != null);
} catch ( GLib.Error e ) {
GLib.error (e.message);