[svn] gpgme - r1377 - in trunk: . doc src
svn author marcus
cvs at cvs.gnupg.org
Tue Jun 16 16:43:39 CEST 2009
Author: marcus
Date: 2009-06-16 16:43:38 +0200 (Tue, 16 Jun 2009)
New Revision: 1377
Modified:
trunk/NEWS
trunk/doc/ChangeLog
trunk/doc/gpgme.texi
trunk/src/ChangeLog
trunk/src/gpgme.c
Log:
doc/
2009-06-16 Marcus Brinkmann <marcus at g10code.de>
* gpgme.texi (Result Management): New section.
src/
2009-06-16 Marcus Brinkmann <marcus at g10code.de>
* gpgme.c (result_ref_lock): New global variable.
(gpgme_result_ref, gpgme_result_unref): use it.
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2009-06-16 11:42:21 UTC (rev 1376)
+++ trunk/doc/ChangeLog 2009-06-16 14:43:38 UTC (rev 1377)
@@ -1,3 +1,7 @@
+2009-06-16 Marcus Brinkmann <marcus at g10code.de>
+
+ * gpgme.texi (Result Management): New section.
+
2009-06-16 Werner Koch <wk at g10code.com>
* gpgme.texi (Exporting Keys): Document gpgme_op_export_keys.
Modified: trunk/src/ChangeLog
===================================================================
--- trunk/src/ChangeLog 2009-06-16 11:42:21 UTC (rev 1376)
+++ trunk/src/ChangeLog 2009-06-16 14:43:38 UTC (rev 1377)
@@ -1,3 +1,8 @@
+2009-06-16 Marcus Brinkmann <marcus at g10code.de>
+
+ * gpgme.c (result_ref_lock): New global variable.
+ (gpgme_result_ref, gpgme_result_unref): use it.
+
2009-06-16 Werner Koch <wk at g10code.com>
* gpgme.h.in (gpgme_op_export_keys_start, gpgme_op_export_keys): New.
Modified: trunk/NEWS
===================================================================
--- trunk/NEWS 2009-06-16 11:42:21 UTC (rev 1376)
+++ trunk/NEWS 2009-06-16 14:43:38 UTC (rev 1377)
@@ -1,4 +1,4 @@
-Noteworthy changes in version 1.2.0
+Noteworthy changes in version 1.2.0 (unreleased)
------------------------------------------------
* New encryption flag GPGME_ENCRYPT_NO_ENCRYPT_TO to disable default
@@ -11,6 +11,16 @@
* New functions gpgme_io_read and gpgme_io_write for use with
gpgme_passphrase_cb_t and gpgme_edit_cb_t functions.
+ * New functions gpgme_result_ref and gpgme_result_unref to detach
+ result structures from a context.
+
+ * New functions gpgme_op_export_keys_start and gpgme_op_export_keys
+ that allow to specify exported keys through gpgme_key_t objects
+ instead of patterns.
+
+ * New mode of operation gpgme_export_mode_t that allows exporting
+ external keys.
+
* Interface changes relative to the 1.1.7 release:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
GPGME_KEYLIST_MODE_EPHEMERAL NEW.
Modified: trunk/doc/gpgme.texi
===================================================================
--- trunk/doc/gpgme.texi 2009-06-16 11:42:21 UTC (rev 1376)
+++ trunk/doc/gpgme.texi 2009-06-16 14:43:38 UTC (rev 1377)
@@ -173,6 +173,7 @@
* Creating Contexts:: Creating new @acronym{GPGME} contexts.
* Destroying Contexts:: Releasing @acronym{GPGME} contexts.
+* Result Management:: Managing the result of crypto operations.
* Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
@@ -1971,6 +1972,7 @@
@menu
* Creating Contexts:: Creating new @acronym{GPGME} contexts.
* Destroying Contexts:: Releasing @acronym{GPGME} contexts.
+* Result Management:: Managing the result of crypto operations.
* Context Attributes:: Setting properties of a context.
* Key Management:: Managing keys with @acronym{GPGME}.
* Trust Item Management:: Managing trust items with @acronym{GPGME}.
@@ -2008,6 +2010,38 @@
@end deftypefun
+ at node Result Management
+ at section Result Management
+ at cindex context, result of operation
+
+The detailed result of an operation is returned in operation-specific
+structures such as @code{gpgme_decrypt_result_t}. The corresponding
+retrieval functions such as @code{gpgme_op_decrypt_result} provide
+static access to the results after an operation completes. The
+following interfaces make it possible to detach a result structure
+from its associated context and give it a lifetime beyond that of the
+current operation or context.
+
+ at deftypefun void gpgme_result_ref (@w{void *@var{result}})
+The function @code{gpgme_result_ref} acquires an additional reference
+for the result @var{result}, which may be of any type
+ at code{gpgme_*_result_t}. As long as the user holds a reference, the
+result structure is guaranteed to be valid and unmodified.
+ at end deftypefun
+
+ at deftypefun void gpgme_result_unref (@w{void *@var{result}})
+The function @code{gpgme_result_unref} releases a reference for the
+result @var{result}. If this was the last reference, the result
+structure will be destroyed and all resources associated to it will be
+released.
+ at end deftypefun
+
+Note that a context may hold its own references to result structures,
+typically until the context is destroyed or the next operation is
+started. In fact, these references are accessed through the
+ at code{gpgme_op_*_result} functions.
+
+
@node Context Attributes
@section Context Attributes
@cindex context, attributes
Modified: trunk/src/gpgme.c
===================================================================
--- trunk/src/gpgme.c 2009-06-16 11:42:21 UTC (rev 1376)
+++ trunk/src/gpgme.c 2009-06-16 14:43:38 UTC (rev 1377)
@@ -45,6 +45,10 @@
gpgme_error_t _gpgme_selftest = GPG_ERR_NOT_OPERATIONAL;
+/* Protects all reference counters in result structures. All other
+ accesses to a key are read only. */
+DEFINE_STATIC_LOCK (result_ref_lock);
+
/* Create a new context as an environment for GPGME crypto
operations. */
@@ -178,29 +182,39 @@
void
gpgme_result_ref (void *result)
{
- struct ctx_op_data *data = result - sizeof (struct ctx_op_data);
+ struct ctx_op_data *data;
if (! result)
return;
+ data = result - sizeof (struct ctx_op_data);
+
+ LOCK (result_ref_lock);
data->references++;
+ UNLOCK (result_ref_lock);
}
void
gpgme_result_unref (void *result)
{
- struct ctx_op_data *data = result - sizeof (struct ctx_op_data);
+ struct ctx_op_data *data;
if (! result)
return;
- if (--data->references == 0)
+ data = result - sizeof (struct ctx_op_data);
+
+ LOCK (result_ref_lock);
+ if (--data->references)
{
- if (data->cleanup)
- (*data->cleanup) (data->hook);
- free (data);
+ UNLOCK (result_ref_lock);
+ return;
}
+
+ if (data->cleanup)
+ (*data->cleanup) (data->hook);
+ free (data);
}
More information about the Gnupg-commits
mailing list