File: gpgme.info,  Node: Advanced Key Editing,  Prev: Changing TOFU Data,  Up: Key Management

7.5.12 Advanced Key Editing
---------------------------

 -- Data type: gpgme_error_t (*gpgme_interact_cb_t) (void *HANDLE,
          const char *STATUS, const char *ARGS, int FD)

     SINCE: 1.7.0

     The ‘gpgme_interact_cb_t’ type is the type of functions which GPGME
     calls if it a key interact operation is on-going.  The status
     keyword STATUS and the argument line ARGS are passed through by
     GPGME from the crypto engine.  An empty string represents EOF. The
     file descriptor FD is -1 for normal status messages.  If STATUS
     indicates a command rather than a status message, the response to
     the command should be written to FD.  The HANDLE is provided by the
     user at start of operation.

     The function should return ‘GPG_ERR_FALSE’ if it did not handle the
     status code, ‘0’ for success, or any other error value.

 -- Function: gpgme_error_t gpgme_op_interact (gpgme_ctx_t CTX,
          gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
          void *HANDLE, gpgme_data_t OUT)

     SINCE: 1.7.0

     The function ‘gpgme_op_interact’ processes the key KEY
     interactively, using the interact callback function FNC with the
     handle HANDLE.  The callback is invoked for every status and
     command request from the crypto engine.  The output of the crypto
     engine is written to the data object OUT.

     Note that the protocol between the callback function and the crypto
     engine is specific to the crypto engine and no further support in
     implementing this protocol correctly is provided by GPGME.

     FLAGS modifies the behaviour of the function; the only defined bit
     value is:

     ‘GPGME_INTERACT_CARD’
          SINCE: 1.7.0

          This is used for smartcard based keys and uses gpg’s
          ‘--card-edit’ command.

     The function returns ‘0’ if the edit operation completes
     successfully, ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid
     pointer, and any error returned by the crypto engine or the edit
     callback handler.

 -- Function: gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t CTX,
          gpgme_key_t KEY, unsigned int FLAGS, gpgme_interact_cb_t FNC,
          void *HANDLE, gpgme_data_t OUT)

     SINCE: 1.7.0

     The function ‘gpgme_op_interact_start’ initiates a
     ‘gpgme_op_interact’ operation.  It can be completed by calling
     ‘gpgme_wait’ on the context.  *Note Waiting For Completion::.

     The function returns ‘0’ if the operation was started successfully,
     and ‘GPG_ERR_INV_VALUE’ if CTX or KEY is not a valid pointer.