doc/
authorMarcus Brinkmann <mb@g10code.com>
Thu, 6 Oct 2005 10:44:26 +0000 (10:44 +0000)
committerMarcus Brinkmann <mb@g10code.com>
Thu, 6 Oct 2005 10:44:26 +0000 (10:44 +0000)
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.

NEWS
doc/ChangeLog
doc/gpgme.texi
gpgme/ChangeLog
gpgme/data-mem.c
gpgme/gpgme.def
gpgme/gpgme.h
gpgme/libgpgme.vers

diff --git a/NEWS b/NEWS
index 04a3f04..aaf55b1 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
index 1afd92d..acc5ada 100644 (file)
@@ -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
index a44cc60..fc3a0f3 100644 (file)
@@ -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
index f0e9c41..62c9ba4 100644 (file)
@@ -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
index 4045b95..d0896de 100644 (file)
@@ -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);
+}
+
index 07a72eb..43ead9f 100644 (file)
@@ -151,5 +151,6 @@ EXPORTS
     gpgme_sig_notation_add               @118
     gpgme_sig_notation_get               @119
 
+    gpgme_free                           @120
 ; END
 
index c0e4e23..1fafd16 100644 (file)
@@ -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);
index 2007303..da90a77 100644 (file)
@@ -34,6 +34,8 @@ GPGME_1.1 {
     gpgme_sig_notation_clear;
     gpgme_sig_notation_add;
     gpgme_sig_notation_get;
+
+    gpgme_free;
 };