File: gpgme.info,  Node: Context Flags,  Next: Locale,  Prev: Status Message Callback,  Up: Context Attributes

7.4.13 Context Flags
--------------------

 -- Function: gpgme_error_t gpgme_set_ctx_flag (gpgme_ctx_t CTX,
          const char *NAME, const char *VALUE)

     SINCE: 1.7.0

     Some minor properties of the context can be controlled with flags
     set by this function.  The properties are identified by the
     following values for NAME:

     ‘"redraw"’
          This flag is normally not changed by the caller because GPGME
          sets and clears it automatically: The flag is cleared before
          an operation and set if an operation noticed that the engine
          has launched a Pinentry.  A Curses based application may use
          this information to redraw the screen; for example:

                   err = gpgme_op_keylist_start (ctx, "foo@example.org", 0);
                   while (!err)
                     {
                       err = gpgme_op_keylist_next (ctx, &key);
                       if (err)
                         break;
                       show_key (key);
                       gpgme_key_release (key);
                     }
                   if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s)
                     redraw_screen ();
                   gpgme_release (ctx);

     ‘"full-status"’
          Using a VALUE of "1" the status callback set by
          gpgme_set_status_cb returns all status lines with the
          exception of PROGRESS lines.  With the default of "0" the
          status callback is only called in certain situations.

     ‘"raw-description"’
          Setting the VALUE to "1" returns human readable strings in a
          raw format.  For example the non breaking space characters
          ("~") will not be removed from the ‘description’ field of the
          ‘gpgme_tofu_info_t’ object.

     ‘"export-session-key"’
          Using a VALUE of "1" specifies that the context should try to
          export the symmetric session key when decrypting data.  By
          default, or when using an empty string or "0" for VALUE,
          session keys are not exported.

     ‘"override-session-key"’
          The string given in VALUE is passed to the GnuPG engine to
          override the session key for decryption.  The format of that
          session key is specific to GnuPG and can be retrieved during a
          decrypt operation when the context flag "export-session-key"
          is enabled.  Please be aware that using this feature with
          GnuPG < 2.1.16 or when decrypting an archive will leak the
          session key on many platforms via ps(1).

     ‘"auto-key-retrieve"’
          Setting the VALUE to "1" asks the backend to automatically
          retrieve a key for signature verification if possible.  Note
          that this option makes a "web bug" like behavior possible.
          Keyserver or Web Key Directory operators can see which keys
          you request, so by sending you a message signed by a brand new
          key (which you naturally will not have on your local keyring),
          the operator can tell both your IP address and the time when
          you verified the signature.

     ‘"auto-key-import"’
          Setting the VALUE to "1" forces the GPG backend to
          automatically import a missing key for signature verification
          from the signature.

     ‘"include-key-block"’
          Setting the VALUE to "1" forces the GPG backend to embed the
          signing key as well as an encryption subkey into the the
          signature.

     ‘"request-origin"’
          The string given in VALUE is passed to the GnuPG engines to
          request restrictions based on the origin of the request.
          Valid values are documented in the GnuPG manual and the gpg
          man page under the option ‘--request-origin’.  Requires at
          least GnuPG 2.2.6 to have an effect.

     ‘"no-symkey-cache"’
          For OpenPGP disable the passphrase cache used for symmetrical
          en- and decryption.  This cache is based on the message
          specific salt value.  Requires at least GnuPG 2.2.7 to have an
          effect.

     ‘"ignore-mdc-error"’
          This flag passes the option ‘--ignore-mdc-error’ to gpg.  This
          can be used to force decryption of a message which failed due
          to a missing integrity check.  This flag must be used with
          great caution and only if it is a known non-corrupted old
          message and the decryption result of the former try had the
          decryption result flag ‘legacy_cipher_nomdc’ set.  For
          failsafe reasons this flag is reset after each operation.

     ‘"auto-key-locate"’
          The string given in VALUE is passed to gpg.  This can be used
          to change the behavior of a ‘GPGME_KEYLIST_MODE_LOCATE’
          keylisting.  Valid values are documented in the GnuPG manual
          and the gpg man page under the option ‘--auto-key-locate’.
          Requires at least GnuPG 2.1.18.

          Note: Keys retrieved through ‘auto-key-locate’ are
          automatically imported in the keyring.

     ‘trust-model’
          SINCE: 1.11.2

          Change the trust-model for all GnuPG engine operations.  An
          empty string sets the trust-model back to the users default.
          If the trust-model is not supported by GnuPG the behavior is
          undefined and will likely cause all operations to fail.
          Example: "tofu+pgp".

          This options should be used carefully with a strict version
          requirement.  In some versions of GnuPG setting the
          trust-model changes the default trust-model for future
          operations.  A change in the trust-model also can have
          unintended side effects, like rebuilding the trust-db.

     ‘"extended-edit"’
          This flag passes the option ‘--expert’ to gpg key edit.  This
          can be used to get additional callbacks in ‘gpgme_op_edit’.

     ‘"cert-expire"’
          SINCE: 1.15.2 The string given in VALUE is passed to the GnuPG
          engine to set the expiration time to use for key signature
          expiration.  Valid values are documented in the GnuPG manual
          and the gpg man page under the option ‘--default-cert-expire’.

     ‘"key-origin"’
          SINCE: 1.16.1 The string given in VALUE is passed to the GnuPG
          engine to set the origin of imported keys.  Valid values are
          documented in the GnuPG manual and the gpg man page under the
          option ‘--key-origin’.

     ‘"import-filter"’
          SINCE: 1.16.1 The string given in VALUE is passed to the GnuPG
          engine to use as filter when importing keys.  Valid values are
          documented in the GnuPG manual and the gpg man page under the
          option ‘--import-filter’.

     ‘"no-auto-check-trustdb"’
          SINCE: 1.19.0 Setting the VALUE to "1" forces the GPG backend
          to disable the automatic check of the trust database.

     This function returns ‘0’ on success.

 -- Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t CTX,
          const char *NAME)

     SINCE: 1.8.0

     The value of flags settable by ‘gpgme_set_ctx_flag’ can be
     retrieved by this function.  If NAME is unknown the function
     returns ‘NULL’.  For boolean flags an empty string is returned for
     False and the string "1" is returned for True; either atoi(3) or a
     test for an empty string can be used to get the boolean value.