[git] GPGME - branch, master, updated. gpgme-1.11.0-7-g969700b

[by Werner Koch]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GnuPG Made Easy".

The branch, master has been updated
       via  969700bc56ce3830bdd0ac498c14cd9f9e7db7fe (commit)
      from  ab43d85b9a76fb5ba321f4c7280b4d72bfd67f59 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 969700bc56ce3830bdd0ac498c14cd9f9e7db7fe
Author: Werner Koch <wk at gnupg.org>
Date:   Fri Apr 20 08:56:01 2018 +0200

    doc: Suggest the use of strconcat for recipient strings.
    
    --
    GnuPG-bug-id: 3775
    
    Signed-off-by: Werner Koch <wk at gnupg.org>

diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 20bfa23..c4a29d5 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -6226,7 +6226,62 @@ string.  All keywords are treated as verbatim arguments.
 
 @end table
 
+To create a @var{recpstring} it is often useful to employ a strconcat
+style function.  For example this function creates a string to encrypt
+to two keys:
 
+ at example
+char *
+xbuild_recpstring (const char *key1, const char *key2)
+@{
+  char *result = gpgrt_strconcat ("--\n", key1, "\n", key2, NULL);
+  if (!result)
+    @{ perror ("strconcat failed"); exit (2); @}
+  return result;
+@}
+ at end example
+
+Note the use of the double dash here; unless you want to specify a
+keyword, it is a good idea to avoid any possible trouble with key
+specifications starting with a double dash.  The used strconcat
+function is available in Libgpg-error 1.28 and later; Libgpg-error
+(aka Gpgrt) is a dependency of GPGME.  The number of arguments to
+ at code{gpgrt_strconcat} is limited to 47 but that should always be
+sufficient.  In case a larger and non-fixed number of keys are to be
+supplied the following code can be used:
+
+ at example
+char *
+xbuild_long_recpstring (void)
+@{
+  gpgrt_stream_t memfp;
+  const char *s;
+  void *result;
+
+  memfp = gpgrt_fopenmem (0, "w+b");
+  if (!memfp)
+    @{ perror ("fopenmem failed"); exit (2); @}
+  gpgrt_fputs ("--", memfp);
+  while ((s = get_next_keyspec ()))
+    @{
+      gpgrt_fputc ('\n', memfp);
+      gpgrt_fputs (s, memfp);
+    @}
+  gpgrt_fputc (0, memfp);
+  if (gpgrt_ferror (memfp))
+    @{ perror ("writing to memstream failed"); exit (2); @}
+  if (gpgrt_fclose_snatch (memfp, &result, NULL))
+    @{ perror ("fclose_snatch failed"); exit (2); @}
+  return result;
+@}
+ at end example
+
+In this example @code{get_next_keyspec} is expected to return the next
+key to be added to the string.  Please take care: Encrypting to a
+large number of recipients is often questionable due to security
+reasons and also for the technicality that all keys are currently
+passed on the command line to @command{gpg} which has as a platform
+specific length limitation.
 @end deftypefun
 
 

-----------------------------------------------------------------------

Summary of changes:
 doc/gpgme.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)


hooks/post-receive
-- 
GnuPG Made Easy
http://git.gnupg.org