Next: , Previous: , Up: Context Attributes   [Contents][Index]

7.4.12 Status Message Callback

Data type: gpgme_error_t (*gpgme_status_cb_t)(void *hook, const char *keyword, const char *args)

The gpgme_status_cb_t type is the type of function usable as a status message callback function.

The argument keyword is the name of the status message while the args argument contains any arguments for the status message.

If an error occurs, return the corresponding gpgme_error_t value. Otherwise, return 0.

Function: void gpgme_set_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t statusfunc, void *hook_value)

SINCE: 1.6.0

The function gpgme_set_status_cb sets the function that is used when a status message is received from gpg to statusfunc. The function statusfunc needs to be implemented by the user, and whenever it is called, it is called with its first argument being 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 gpgme_set_status_cb with statusfunc being NULL.

Function: void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *statusfunc, void **hook_value)

SINCE: 1.6.0

The function gpgme_get_status_cb returns the function that is used to process status messages from gpg in *statusfunc, and the first argument for this function in *hook_value. If no status message callback is set, or ctx is not a valid pointer, NULL is returned in both variables.

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:


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, "", 0);
    while (!err)
        err = gpgme_op_keylist_next (ctx, &key);
        if (err)
        show_key (key);
        gpgme_key_release (key);
    if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s)
      redraw_screen ();
    gpgme_release (ctx);

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.


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.


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.


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 will leak the session key on many platforms via ps(1).


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.


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.


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.


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.


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.

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.

Next: , Previous: , Up: Context Attributes   [Contents][Index]