From: Marcus Brinkmann Date: Thu, 6 Oct 2005 10:44:26 +0000 (+0000) Subject: doc/ X-Git-Tag: gpgme-1-1-1~38 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=a336bc6834099b62b17c6e772763328145537dc2;p=gpgme.git doc/ 2005-10-06 Marcus Brinkmann * gpgme.texi (Destroying Data Buffers): Document gpgme_free. gpgme/ 2005-10-06 Marcus Brinkmann * 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 04a3f04..aaf55b1 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 1afd92d..acc5ada 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2005-10-06 Marcus Brinkmann + + * gpgme.texi (Destroying Data Buffers): Document gpgme_free. + 2005-10-02 Marcus Brinkmann * gpgme.texi (Key Management): Add the new member notations of diff --git a/doc/gpgme.texi b/doc/gpgme.texi index a44cc60..fc3a0f3 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 f0e9c41..62c9ba4 100644 --- a/gpgme/ChangeLog +++ b/gpgme/ChangeLog @@ -1,3 +1,10 @@ +2005-10-06 Marcus Brinkmann + + * 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 * util.h (_gpgme_decode_percent_string): Add new argument BINARY diff --git a/gpgme/data-mem.c b/gpgme/data-mem.c index 4045b95..d0896de 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 07a72eb..43ead9f 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 c0e4e23..1fafd16 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 2007303..da90a77 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; };