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

@@ -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]
 ------------------------------------------------
 

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

src/gpgme.def

@@ -244,5 +244,7 @@ EXPORTS
     gpgme_op_interact_start               @184
     gpgme_op_interact                     @185
 
+    gpgme_addrspec_from_uid               @186
+
 ; END
 

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);
+
 
 
 /*

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;
 };
 
 

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);
+}