diff --git a/doc/gpgme.texi b/doc/gpgme.texi index ef4936dd..bce6aefd 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -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 diff --git a/src/context.h b/src/context.h index 8cd86e9c..757d9b42 100644 --- a/src/context.h +++ b/src/context.h @@ -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; diff --git a/src/gpgme.c b/src/gpgme.c index c24b6200..9c09827e 100644 --- a/src/gpgme.c +++ b/src/gpgme.c @@ -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) diff --git a/src/gpgme.def b/src/gpgme.def index cf167b4f..a3f5fb4a 100644 --- a/src/gpgme.def +++ b/src/gpgme.def @@ -220,5 +220,8 @@ EXPORTS gpgme_set_offline @165 gpgme_get_offline @166 + + gpgme_set_status_cb @167 + gpgme_get_status_cb @168 ; END diff --git a/src/gpgme.h.in b/src/gpgme.h.in index 099cc8a5..ffcc7bac 100644 --- a/src/gpgme.h.in +++ b/src/gpgme.h.in @@ -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, diff --git a/src/libgpgme.vers b/src/libgpgme.vers index fc2920f8..6687571f 100644 --- a/src/libgpgme.vers +++ b/src/libgpgme.vers @@ -95,6 +95,9 @@ GPGME_1.1 { gpgme_set_offline; gpgme_get_offline; + + gpgme_set_status_cb; + gpgme_get_status_cb; };