From 0ea2ff67900c243fff9f689658dcb23d1c0961cd Mon Sep 17 00:00:00 2001
From: Werner Koch <wk@gnupg.org>
Date: Sat, 8 Oct 2016 21:14:52 +0200
Subject: [PATCH] core: New helper function gpgme_addrspec_from_uid.

* src/gpgme.h.in: Add gpgme_addrspec_from_uid.
* src/gpgme.def, src/libgpgme.vers: Ditto.
* src/mbox-util.c (gpgme_addrspec_from_uid): New.

Signed-off-by: Werner Koch <wk@gnupg.org>
---
 NEWS              |  6 ++++++
 doc/gpgme.texi    | 17 +++++++++++++++++
 src/gpgme.def     |  2 ++
 src/gpgme.h.in    |  6 +++++-
 src/libgpgme.vers |  2 ++
 src/mbox-util.c   | 18 ++++++++++++++++++
 6 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index b13c3a6c..86e1d4f6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,12 @@
 Noteworthy changes in version 1.7.1 (unreleased) [C26/A15/R_]
 ------------------------------------------------
 
+
+ * Interface changes relative to the 1.7.0 release:
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ gpgme_addrspec_from_uid         NEW.
+
+
 Noteworthy changes in version 1.7.0 (2016-09-21) [C26/A15/R0]
 ------------------------------------------------
 
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 6d6d692e..cc598887 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -5109,6 +5109,23 @@ pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
 any data to decrypt.
 @end deftypefun
 
+When processing mails it is sometimes useful to extract the actual
+mail address (the ``addr-spec'') from a string.  GPGME provides this
+helper function which uses the same semantics as the internal
+functions in GPGME and GnuPG:
+
+@deftypefun @w{char *} gpgme_addrspec_from_uid (@w{const char *@var{uid}})
+
+Return the mail address (called ``addr-spec'' in RFC-5322) from the
+string @var{uid} which is assumed to be a user id (called ``address''
+in RFC-5322).  All plain ASCII characters (i.e. those with bit 7
+cleared) in the result are converted to lowercase.  Caller must free
+the result using @code{gpgme_free}.  Returns @code{NULL} if no valid
+address was found (in which case @code{ERRNO} is set to @code{EINVAL})
+or for other errors.
+
+@end deftypefun
+
 
 @node Sign
 @subsection Sign
diff --git a/src/gpgme.def b/src/gpgme.def
index 9815a834..c94c9607 100644
--- a/src/gpgme.def
+++ b/src/gpgme.def
@@ -244,5 +244,7 @@ EXPORTS
     gpgme_op_interact_start               @184
     gpgme_op_interact                     @185
 
+    gpgme_addrspec_from_uid               @186
+
 ; END
 
diff --git a/src/gpgme.h.in b/src/gpgme.h.in
index 20654db9..5c914ae7 100644
--- a/src/gpgme.h.in
+++ b/src/gpgme.h.in
@@ -846,7 +846,7 @@ struct _gpgme_user_id
 
   /* The mail address (addr-spec from RFC5322) of the UID string.
    * This is general the same as the EMAIL part of this struct but
-   * might be slightly different.  IF no mail address is available
+   * might be slightly different.  If no mail address is available
    * NULL is stored.  */
   char *address;
 
@@ -2471,6 +2471,10 @@ const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
    algorithm ALGO, or NULL if that name is not known.  */
 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
 
+/* Return the addr-spec from a user id.  Caller must free the result
+ * with gpgme_free. */
+char *gpgme_addrspec_from_uid (const char *uid);
+
 
 
 /*
diff --git a/src/libgpgme.vers b/src/libgpgme.vers
index aec9090d..d3962db0 100644
--- a/src/libgpgme.vers
+++ b/src/libgpgme.vers
@@ -117,6 +117,8 @@ GPGME_1.1 {
     gpgme_op_tofu_policy;
     gpgme_op_interact_start;
     gpgme_op_interact;
+
+    gpgme_addrspec_from_uid;
 };
 
 
diff --git a/src/mbox-util.c b/src/mbox-util.c
index 656b5d7b..81e929bd 100644
--- a/src/mbox-util.c
+++ b/src/mbox-util.c
@@ -255,3 +255,21 @@ _gpgme_mailbox_from_userid (const char *userid)
 
 /*   return 1; */
 /* } */
+
+
+/*
+ * Exported public API
+ */
+
+
+/* Return the mail address ("addr-spec" as per RFC-5322) from a string
+ * which is assumed to be an user id ("address" in RFC-5322).  All
+ * plain ASCII characters (those with bit 7 cleared) in the result
+ * are converted to lowercase.  Caller must free the result using
+ * gpgme_free.  Returns NULL if no valid address was found (in which
+ * case ERRNO is set to EINVAL) or for other errors.  */
+char *
+gpgme_addrspec_from_uid (const char *uid)
+{
+  return _gpgme_mailbox_from_userid (uid);
+}