From 5c0d1852e47796699d817ab3ad90708f0c7347d1 Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Tue, 16 Jun 2009 14:43:38 +0000 Subject: [PATCH] doc/ 2009-06-16 Marcus Brinkmann * gpgme.texi (Result Management): New section. src/ 2009-06-16 Marcus Brinkmann * gpgme.c (result_ref_lock): New global variable. (gpgme_result_ref, gpgme_result_unref): use it. --- trunk/NEWS | 12 +++++++++++- trunk/doc/ChangeLog | 4 ++++ trunk/doc/gpgme.texi | 34 ++++++++++++++++++++++++++++++++++ trunk/src/ChangeLog | 5 +++++ trunk/src/gpgme.c | 26 ++++++++++++++++++++------ 5 files changed, 74 insertions(+), 7 deletions(-) diff --git a/trunk/NEWS b/trunk/NEWS index 232ff53..2f6c437 100644 --- a/trunk/NEWS +++ b/trunk/NEWS @@ -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 @@ Noteworthy changes in version 1.2.0 * 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. diff --git a/trunk/doc/ChangeLog b/trunk/doc/ChangeLog index 5138a57..6bc623b 100644 --- a/trunk/doc/ChangeLog +++ b/trunk/doc/ChangeLog @@ -1,3 +1,7 @@ +2009-06-16 Marcus Brinkmann + + * gpgme.texi (Result Management): New section. + 2009-06-16 Werner Koch * gpgme.texi (Exporting Keys): Document gpgme_op_export_keys. diff --git a/trunk/doc/gpgme.texi b/trunk/doc/gpgme.texi index a6f15d1..8ecb449 100644 --- a/trunk/doc/gpgme.texi +++ b/trunk/doc/gpgme.texi @@ -173,6 +173,7 @@ Contexts * 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 @@ cryptographic operations. @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 @@ The function @code{gpgme_release} destroys the context with the handle @end deftypefun +@node Result Management +@section Result Management +@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. + +@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 +@code{gpgme_*_result_t}. As long as the user holds a reference, the +result structure is guaranteed to be valid and unmodified. +@end deftypefun + +@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. +@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 +@code{gpgme_op_*_result} functions. + + @node Context Attributes @section Context Attributes @cindex context, attributes diff --git a/trunk/src/ChangeLog b/trunk/src/ChangeLog index dc1e116..6861913 100644 --- a/trunk/src/ChangeLog +++ b/trunk/src/ChangeLog @@ -1,3 +1,8 @@ +2009-06-16 Marcus Brinkmann + + * gpgme.c (result_ref_lock): New global variable. + (gpgme_result_ref, gpgme_result_unref): use it. + 2009-06-16 Werner Koch * gpgme.h.in (gpgme_op_export_keys_start, gpgme_op_export_keys): New. diff --git a/trunk/src/gpgme.c b/trunk/src/gpgme.c index 2372a06..73788e7 100644 --- a/trunk/src/gpgme.c +++ b/trunk/src/gpgme.c @@ -45,6 +45,10 @@ static char *def_lc_messages; 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 @@ gpgme_release (gpgme_ctx_t ctx) 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); } -- 2.26.2