doc/

2005-10-06  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.texi (Destroying Data Buffers): Document gpgme_free.

gpgme/
2005-10-06  Marcus Brinkmann  <marcus@g10code.de>

	* gpgme.h (gpgme_free): New prototype.
	* data-mem.c (gpgme_free): New function.
	* libgpgme.vers (GPGME_1.1): Add gpgme_free.
	* gpgme.def: Add gpgme_free.

diff --git a/NEWS b/NEWS
index 04a3f04c2171e0e6b4d8c1174a580c9c14bcd266..aaf55b17eb70d07a26582c9eace9428c9d3fb5b6 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-Noteworthy changes in version 1.x.y (unreleased)
+Noteworthy changes in version 1.1.1 (unreleased)
 ------------------------------------------------
 
  * Reading signature notations and policy URLs on key signatures is
@@ -6,10 +6,19 @@ Noteworthy changes in version 1.x.y (unreleased)
    gpgme_key_sig_t structure.  This has to be enabled with the keylist
    mode flag GPGME_KEYLIST_MODE_SIG_NOTATIONS.
 
- * Interface changes relative to the 1.0.3 release:
+ * A new gpgme_free() function solves the problem of using different
+   allocators in a single program.  This function should now be used
+   instead calling free() to release the buffer returned by
+   gpgme_data_release_and_get_mem.  It is recommended that you always
+   do this, but it is only necessary on certain platforms, so backwards
+   compatibility is provided.  In other words: If free() worked for
+   you before, it will keep working.
+
+ * Interface changes relative to the 1.1.0 release:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 gpgme_key_sig_t                        EXTENDED: New field notations.
 GPGME_KEYLIST_MODE_SIG_NOTATIONS NEW
+gpgme_free                     NEW
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 1afd92d9b5287e4da93862257e7ef9a0db45a246..acc5adae0085c3945bf0c2dc49530a11ed9fe8e5 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2005-10-06  Marcus Brinkmann  <marcus@g10code.de>
+
+       * gpgme.texi (Destroying Data Buffers): Document gpgme_free.
+
 2005-10-02  Marcus Brinkmann  <marcus@g10code.de>
 
        * gpgme.texi (Key Management): Add the new member notations of

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index a44cc60fc432f3b1e6958673a0904da9247ff892..fc3a0f389685cb4779255bfe96c24ddd63257c9e 100644 (file)
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -1711,15 +1711,23 @@ The function @code{gpgme_data_release_and_get_mem} is like
 @code{gpgme_data_release}, except that it returns the data buffer and
 its length that was provided by the object.
 
-The user has to release the buffer with @code{free}.  In case the user
-provided the data buffer in non-copy mode, a copy will be made for
-this purpose.
+The user has to release the buffer with @code{gpgme_free}.  In case
+the user provided the data buffer in non-copy mode, a copy will be
+made for this purpose.
 
 In case an error returns, or there is no suitable data buffer that can
 be returned to the user, the function will return @code{NULL}.
 @end deftypefun
 
 
+@deftypefun void gpgme_free (@w{void *@var{buffer}})
+The function @code{gpgme_free} releases the memory returned by
+@code{gpgme_data_release_and_get_mem}.  It should be used instead of
+the system libraries @code{free} function in case different allocators
+are used in a single program.
+@end deftypefun
+
+
 @node Manipulating Data Buffers
 @section Manipulating Data Buffers
 @cindex data buffer, manipulation

diff --git a/gpgme/ChangeLog b/gpgme/ChangeLog
index f0e9c417ab6360d3bbba6ece15e6c44af6023b5e..62c9ba49125726856b50f5fea4e76cc0e98dc345 100644 (file)
--- a/gpgme/ChangeLog
+++ b/gpgme/ChangeLog
@@ -1,3 +1,10 @@
+2005-10-06  Marcus Brinkmann  <marcus@g10code.de>
+
+       * gpgme.h (gpgme_free): New prototype.
+       * data-mem.c (gpgme_free): New function.
+       * libgpgme.vers (GPGME_1.1): Add gpgme_free.
+       * gpgme.def: Add gpgme_free.
+
 2005-10-02  Marcus Brinkmann  <marcus@g10code.de>
 
        * util.h (_gpgme_decode_percent_string): Add new argument BINARY

diff --git a/gpgme/data-mem.c b/gpgme/data-mem.c
index 4045b9565732ec6ad78a9db65384b346573f0b69..d0896debb9a26c5a69213a8572a4d2b286dd92a8 100644 (file)
--- a/gpgme/data-mem.c
+++ b/gpgme/data-mem.c
@@ -161,6 +161,7 @@ static struct _gpgme_data_cbs mem_cbs =
   };
 
 \f
+/* Create a new data buffer and return it in R_DH.  */
 gpgme_error_t
 gpgme_data_new (gpgme_data_t *dh)
 {
@@ -200,6 +201,9 @@ gpgme_data_new_from_mem (gpgme_data_t *dh, const char *buffer,
 }
 
 
+/* Destroy the data buffer DH and return a pointer to its content.
+   The memory has be to released with gpgme_free() by the user.  It's
+   size is returned in R_LEN.  */
 char *
 gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len)
 {
@@ -222,3 +226,13 @@ gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len)
 
   return str;
 }
+
+
+/* Release the memory returned by gpgme_data_release_and_get_mem().  */
+void
+gpgme_free (void *buffer)
+{
+  if (buffer)
+    free (buffer);
+}
+

diff --git a/gpgme/gpgme.def b/gpgme/gpgme.def
index 07a72ebba1aea2a326b069ad0416cf58d7cd061d..43ead9f5bef04f428c5a4d43f69a8e874543294e 100644 (file)
--- a/gpgme/gpgme.def
+++ b/gpgme/gpgme.def
@@ -151,5 +151,6 @@ EXPORTS
     gpgme_sig_notation_add               @118
     gpgme_sig_notation_get               @119
 
+    gpgme_free                           @120
 ; END
 

diff --git a/gpgme/gpgme.h b/gpgme/gpgme.h
index c0e4e23c96e3e11490f51f86fc9f664d503587a8..1fafd164bb79b36bb4aadfefe8d9bde8935d3102 100644 (file)
--- a/gpgme/gpgme.h
+++ b/gpgme/gpgme.h
@@ -996,10 +996,13 @@ gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
                                       int copy);
 
 /* Destroy the data buffer DH and return a pointer to its content.
-   The memory has be to released with free by the user.  It's size is
-   returned in R_LEN.  */
+   The memory has be to released with gpgme_free() by the user.  It's
+   size is returned in R_LEN.  */
 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
 
+/* Release the memory returned by gpgme_data_release_and_get_mem().  */
+void gpgme_free (void *buffer);
+
 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
                                       gpgme_data_cbs_t cbs,
                                       void *handle);

diff --git a/gpgme/libgpgme.vers b/gpgme/libgpgme.vers
index 2007303938d12a5879bc65c52bcd6cd955da2e4e..da90a77252b4ec3bb3f336bc623ed9e02b8e7dbf 100644 (file)
--- a/gpgme/libgpgme.vers
+++ b/gpgme/libgpgme.vers
@@ -34,6 +34,8 @@ GPGME_1.1 {
     gpgme_sig_notation_clear;
     gpgme_sig_notation_add;
     gpgme_sig_notation_get;
+
+    gpgme_free;
 };