doc/

2005-10-06  Marcus Brinkmann  <[email protected]>

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

gpgme/
2005-10-06  Marcus Brinkmann  <[email protected]>

	* 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.

8 files changed, 55 insertions, 7 deletions

diff --git a/NEWS b/NEWS
index 04a3f04c..aaf55b17 100644
--- 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 1afd92d9..acc5adae 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2005-10-06  Marcus Brinkmann  <[email protected]>
+
+	* gpgme.texi (Destroying Data Buffers): Document gpgme_free.
+
 2005-10-02  Marcus Brinkmann  <[email protected]>
 
 	* gpgme.texi (Key Management): Add the new member notations of
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index a44cc60f..fc3a0f38 100644
--- 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 f0e9c417..62c9ba49 100644
--- a/gpgme/ChangeLog
+++ b/gpgme/ChangeLog
@@ -1,3 +1,10 @@
+2005-10-06  Marcus Brinkmann  <[email protected]>
+
+	* 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  <[email protected]>
 
 	* util.h (_gpgme_decode_percent_string): Add new argument BINARY
diff --git a/gpgme/data-mem.c b/gpgme/data-mem.c
index 4045b956..d0896deb 100644
--- a/gpgme/data-mem.c
+++ b/gpgme/data-mem.c
@@ -161,6 +161,7 @@ static struct _gpgme_data_cbs mem_cbs =
   };
 
 
+/* 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 07a72ebb..43ead9f5 100644
--- 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 c0e4e23c..1fafd164 100644
--- 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 20073039..da90a772 100644
--- 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;
 };