aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMarcus Brinkmann <[email protected]>2004-02-24 23:08:48 +0000
committerMarcus Brinkmann <[email protected]>2004-02-24 23:08:48 +0000
commited314ff7665c452389c34163c6b82eea9b3b804f (patch)
treeda7b3c881d580f57b0c68bdcaa1646ea4c21d4c6 /doc
parent* configure.ac: Make the check for funopen fail with just a (diff)
downloadgpgme-ed314ff7665c452389c34163c6b82eea9b3b804f.tar.gz
gpgme-ed314ff7665c452389c34163c6b82eea9b3b804f.zip
doc/
2004-02-24 Marcus Brinkmann <[email protected]> * gpgme.texi (cancellation): New section. gpgme/ 2004-02-24 Marcus Brinkmann <[email protected]> * gpgme.c (gpgme_cancel): New function. * engine-backend.h (struct engine_ops): New member cancel. * engine.h (_gpgme_engine_cancel): New prototype. * engine.c (_gpgme_engine_cancel): New function. * engine-gpgsm.c: Add new member cancel. (gpgsm_cancel): New function. (gpgsm_release): Use it. * rungpg.c: Add new member cancel.
Diffstat (limited to 'doc')
-rw-r--r--doc/ChangeLog4
-rw-r--r--doc/gpgme.texi39
2 files changed, 43 insertions, 0 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 809cc14d..4bad3c37 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2004-02-24 Marcus Brinkmann <[email protected]>
+
+ * gpgme.texi (cancellation): New section.
+
2004-02-17 Werner Koch <[email protected]>
* gpgme.texi (Key Listing Mode): Doc KEYLIST_MODE_VALIDATE.
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 3e5e8989..4edf9edc 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -201,6 +201,7 @@ Run Control
* Waiting For Completion:: Waiting until an operation is completed.
* Using External Event Loops:: Advanced control over what happens when.
+* Cancellation:: How to end pending operations prematurely.
Using External Event Loops
@@ -4315,6 +4316,7 @@ time.
@menu
* Waiting For Completion:: Waiting until an operation is completed.
* Using External Event Loops:: Advanced control over what happens when.
+* Cancellation:: How to end pending operations prematurely.
@end menu
@@ -4898,6 +4900,43 @@ my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
@end example
+@node Cancellation
+@subsection Cancellation
+@cindex cryptographic operation, aborting
+@cindex cryptographic operation, cancelling
+@cindex aborting operations
+@cindex cancelling operations
+
+Sometimes you do not want to wait for an operation to finish. If you
+use external I/O callbacks, you can cancel a pending operation.
+However, you must ensure that no other thread is currently using the
+context in which the operation you want to cancel runs. This includes
+callback handlers. So your external event loop must either be halted
+or otherwise it must be guaranteed that no installed I/O callbacks are
+run for this context.
+
+@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}. This only works if you use the
+global event loop or your own event loop.
+
+If you use the global event loop, you must not call @code{gpgme_wait}
+or @code{gpgme_wait} during cancellation. After successful
+cancellation, you can call @code{gpgme_wait} (optionally waiting on
+@var{ctx}), and the context @var{ctx} will appear as if it had
+finished with the error code @code{GPG_ERR_CANCEL}.
+
+If you use your an external event loop, you must ensure that no I/O
+callbacks are invoked for this context (for example by halting the
+event loop). On successful cancellation, all registered I/O callbacks
+for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
+event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
+
+
@include gpl.texi