Add gpgme_set/get_status_cb().
authorBen Kibbey <bjk@luxsci.net>
Fri, 17 Apr 2015 00:23:38 +0000 (20:23 -0400)
committerBen Kibbey <bjk@luxsci.net>
Sat, 15 Aug 2015 22:19:27 +0000 (18:19 -0400)
* src/gpgme.h.in (gpgme_set_status_cb): New.
(gpgme_get_status_cb): New.
(gpgme_status_cb_t): New.
* src/gpgme.c (gpgme_set_status_cb): New.
(gpgme_get_status_cb): New.
* src/context.h (status_cb): New.
(status_cb_value): New.
* src/gpgme.def: Export new symbols.
* src/libgpgme.vers: Ditto.
* doc/gpgme.texi: Document these new functions.

--
This callback function is used to forward status messages from gpg back
to the client.

doc/gpgme.texi
src/context.h
src/gpgme.c
src/gpgme.def
src/gpgme.h.in
src/libgpgme.vers

index ef4936d..bce6aef 100644 (file)
@@ -194,6 +194,7 @@ Context Attributes
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 
 Key Management
@@ -2291,6 +2292,7 @@ started.  In fact, these references are accessed through the
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 @end menu
 
@@ -2675,6 +2677,48 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Status Message Callback
+@subsection Status Message Callback
+@cindex callback, status message
+@cindex status message callback
+
+@deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
+@tindex gpgme_status_cb_t
+The @code{gpgme_status_cb_t} type is the type of function usable as
+a status message callback function.
+
+The argument @var{keyword} is the name of the status message while the
+@var{args} argument contains any arguments for the status message.
+
+The status message may have come from gpg or libgpgme.
+
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value. Otherwise, return @code{0}.
+@end deftp
+
+@deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_status_cb} sets the function that is used when a
+status message is received from gpg to @var{statusfunc}. The function
+@var{statusfunc} needs to implemented by the user, and whenever it is called,
+it is called with its first argument being @var{hook_value}.  By default, no
+status message callback function is set.
+
+The user can disable the use of a status message callback function by calling
+@code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
+@end deftypefun
+
+@deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
+The function @code{gpgme_get_status_cb} returns the function that is used to
+process status messages from gpg in @var{*statusfunc}, and the first argument
+for this function in @var{*hook_value}.  If no status message callback is set,
+or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
+variables.
+
+@var{statusfunc} or @var{hook_value} can be @code{NULL}.  In this case,
+the corresponding value will not be returned.
+@end deftypefun
+
+
 @node Locale
 @subsection Locale
 @cindex locale, default
index 8cd86e9..757d9b4 100644 (file)
@@ -135,6 +135,10 @@ struct gpgme_context
   gpgme_progress_cb_t progress_cb;
   void *progress_cb_value;
 
+  /* The user provided status callback and its hook value.  */
+  gpgme_status_cb_t status_cb;
+  void *status_cb_value;
+
   /* A list of file descriptors in active use by the current
      operation.  */
   struct fd_table fdt;
index c24b620..9c09827 100644 (file)
@@ -656,6 +656,37 @@ gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *r_cb,
 }
 
 
+/* This function sets a callback function to be used as a status
+   message forwarder.  */
+void
+gpgme_set_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t cb, void *cb_value)
+{
+  TRACE2 (DEBUG_CTX, "gpgme_set_status_cb", ctx, "status_cb=%p/%p",
+         cb, cb_value);
+
+  if (!ctx)
+    return;
+
+  ctx->status_cb = cb;
+  ctx->status_cb_value = cb_value;
+}
+
+
+/* This function returns the callback function to be used as a
+   status message forwarder.  */
+void
+gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *r_cb,
+                      void **r_cb_value)
+{
+  TRACE2 (DEBUG_CTX, "gpgme_get_status_cb", ctx, "ctx->status_cb=%p/%p",
+         ctx->status_cb, ctx->status_cb_value);
+  if (r_cb)
+    *r_cb = ctx->status_cb;
+  if (r_cb_value)
+    *r_cb_value = ctx->status_cb_value;
+}
+
+
 /* Set the I/O callback functions for CTX to IO_CBS.  */
 void
 gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
index cf167b4..a3f5fb4 100644 (file)
@@ -220,5 +220,8 @@ EXPORTS
 
     gpgme_set_offline                     @165
     gpgme_get_offline                     @166
+
+    gpgme_set_status_cb                   @167
+    gpgme_get_status_cb                   @168
 ; END
 
index 099cc8a..ffcc7ba 100644 (file)
@@ -839,6 +839,11 @@ typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
                                     int type, int current, int total);
 
+/* Status messages from gpg. */
+typedef gpgme_error_t (*gpgme_status_cb_t) (void *opaque, const char *keyword,
+                                            const char *args);
+
+
 /* Interact with the user about an edit operation.  */
 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
                                          gpgme_status_code_t status,
@@ -936,6 +941,16 @@ void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
                            void **hook_value);
 
+/* Set the status callback function in CTX to CB.  HOOK_VALUE is
+   passed as first argument to thes status callback function.  */
+void gpgme_set_status_cb (gpgme_ctx_t c, gpgme_status_cb_t cb,
+                          void *hook_value);
+
+/* Get the current status callback function in *CB and the current
+   hook value in *HOOK_VALUE.  */
+void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *cb,
+                          void **hook_value);
+
 /* This function sets the locale for the context CTX, or the default
    locale if CTX is a null pointer.  */
 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
index fc2920f..6687571 100644 (file)
@@ -95,6 +95,9 @@ GPGME_1.1 {
 
     gpgme_set_offline;
     gpgme_get_offline;
+
+    gpgme_set_status_cb;
+    gpgme_get_status_cb;
 };