File: gpgme.info,  Node: Waiting For Completion,  Next: Using External Event Loops,  Up: Run Control

7.8.1 Waiting For Completion
----------------------------

 -- Function: gpgme_ctx_t gpgme_wait (gpgme_ctx_t CTX,
          gpgme_error_t *STATUS, int HANG)
     The function ‘gpgme_wait’ continues the pending operation within
     the context CTX.  In particular, it ensures the data exchange
     between GPGME and the crypto backend and watches over the run time
     status of the backend process.

     If HANG is true, the function does not return until the operation
     is completed or cancelled.  Otherwise the function will not block
     for a long time.

     The error status of the finished operation is returned in STATUS if
     ‘gpgme_wait’ does not return ‘NULL’.

     The CTX argument can be ‘NULL’.  In that case, ‘gpgme_wait’ waits
     for any context to complete its operation.

     ‘gpgme_wait’ can be used only in conjunction with any context that
     has a pending operation initiated with one of the
     ‘gpgme_op_*_start’ functions except ‘gpgme_op_keylist_start’ and
     ‘gpgme_op_trustlist_start’ (for which you should use the
     corresponding ‘gpgme_op_*_next’ functions).  If CTX is ‘NULL’, all
     of such contexts are waited upon and possibly returned.
     Synchronous operations running in parallel, as well as key and
     trust item list operations, do not affect ‘gpgme_wait’.

     In a multi-threaded environment, only one thread should ever call
     ‘gpgme_wait’ at any time, regardless of whether CTX is specified or
     not.  This means that all calls to this function should be fully
     synchronized by locking primitives.  It is safe to start
     asynchronous operations while a thread is running in ‘gpgme_wait’.

     The function returns the CTX of the context which has finished the
     operation.  If HANG is false, and the timeout expires, ‘NULL’ is
     returned and ‘*status’ will be set to 0.  If an error occurs,
     ‘NULL’ is returned and the error is returned in ‘*status’.