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