File: gpgme.info,  Node: Engine Information,  Next: Engine Configuration,  Prev: Engine Version Check,  Up: Protocols and Engines

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));
           }
       }