3.2 Engine Information

Data type: gpgme_engine_info_t

The gpgme_engine_info_t type specifies a pointer to a structure describing a crypto engine. The structure contains the following elements:

gpgme_engine_info_t next

This is a pointer to the next engine info structure in the linked list, or NULL if this is the last element.

gpgme_protocol_t protocol

This is the protocol for which the crypto engine is used. You can convert this to a string with gpgme_get_protocol_name for printing.

const char *file_name

This is a string holding the file name of the executable of the crypto engine. Currently, it is never NULL, but using NULL is reserved for future use, so always check before you use it.

const char *home_dir

This is a string holding the directory name of the crypto engine’s configuration directory. If it is NULL, then the default directory is used. See gpgme_get_dirinfo on how to get the default directory.

const char *version

This is a string containing the version number of the crypto engine. It might be NULL if the version number can not be determined, for example because the executable doesn’t exist or is invalid.

const char *req_version

This is a string containing the minimum required version number of the crypto engine for GPGME to work correctly. This is the version number that gpgme_engine_check_version verifies against. Currently, it is never NULL, but using NULL is reserved for future use, so always check before you use it.

Function: gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)

The function gpgme_get_engine_info returns a linked list of engine info structures in info. Each info structure describes the defaults of one configured backend.

The memory for the info structures is allocated the first time this function is invoked, and must not be freed by the caller.

This function returns the error code GPG_ERR_NO_ERROR if successful, and a system error if the memory could not be allocated.

Here is an example how you can provide more diagnostics if you receive an error message which indicates that the crypto engine is invalid.

gpgme_ctx_t ctx;
gpgme_error_t err;

[...]

if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
  {
    gpgme_engine_info_t info;
    err = gpgme_get_engine_info (&info);
    if (!err)
      {
        while (info && info->protocol != gpgme_get_protocol (ctx))
          info = info->next;
        if (!info)
          fprintf (stderr, "GPGME compiled without support for protocol %s",
                   gpgme_get_protocol_name (info->protocol));
        else if (info->file_name && !info->version)
          fprintf (stderr, "Engine %s not installed properly",
                   info->file_name);
        else if (info->file_name && info->version && info->req_version)
          fprintf (stderr, "Engine %s version %s installed, "
                   "but at least version %s required", info->file_name,
                   info->version, info->req_version);
        else
          fprintf (stderr, "Unknown problem with engine for protocol %s",
                   gpgme_get_protocol_name (info->protocol));
      }
  }