2.6 Library Version Check

Function: const char * gpgme_check_version (const char *required_version)

The function gpgme_check_version has four purposes. It can be used to retrieve the version number of the library. In addition it can verify that the version number is higher than a certain required version number. In either case, the function initializes some sub-systems, and for this reason alone it must be invoked early in your program, before you make use of the other functions in GPGME. The last purpose is to run selftests.

As a side effect for W32 based systems, the socket layer will get initialized.

If required_version is NULL, the function returns a pointer to a statically allocated string containing the version number of the library.

If required_version is not NULL, it should point to a string containing a version number, and the function checks that the version of the library is at least as high as the version number provided. In this case, the function returns a pointer to a statically allocated string containing the version number of the library. If REQUIRED_VERSION is not a valid version number, or if the version requirement is not met, the function returns NULL.

If you use a version of a library that is backwards compatible with older releases, but contains additional interfaces which your program uses, this function provides a run-time check if the necessary features are provided by the installed version of the library.

If a selftest fails, the function may still succeed. Selftest errors are returned later when invoking gpgme_new or gpgme-data_new, so that a detailed error code can be returned (historically, gpgme_check_version does not return a detailed error code).

Function: int gpgme_set_global_flag (const char *name, const char *value)

SINCE: 1.4.0

On some systems it is not easy to set environment variables and thus hard to use GPGME’s internal trace facility for debugging. This function has been introduced as an alternative way to enable debugging and for a couple of other rarely used tweaks. It is important to assure that only one thread accesses GPGME functions between a call to this function and after the return from the call to gpgme_check_version.

All currently supported features require that this function is called as early as possible — even before gpgme_check_version. The features are identified by the following values for name:

debug

To enable debugging use the string “debug” for name and value identical to the value used with the environment variable GPGME_DEBUG.

disable-gpgconf

Using this feature with any value disables the detection of the gpgconf program and thus forces GPGME to fallback into the simple OpenPGP only mode. It may be used to force the use of GnuPG-1 on systems which have both GPG versions installed. Note that in general the use of gpgme_set_engine_info is a better way to select a specific engine version.

gpgconf-name

gpg-name

Set the name of the gpgconf respective gpg binary. The defaults are GNU/GnuPG/gpgconf and GNU/GnuPG/gpg. Under Unix the leading directory part is ignored. Under Windows the leading directory part is used as the default installation directory; the .exe suffix is added by GPGME. Use forward slashed even under Windows.

require-gnupg

Set the minimum version of the required GnuPG engine. If that version is not met, GPGME fails early instead of trying to use the existent version. The given version must be a string with major, minor, and micro number. Example: "2.1.0".

w32-inst-dir

On Windows GPGME needs to know its installation directory to find its spawn helper. This is in general no problem because a DLL has this information. Some applications however link statically to GPGME and thus GPGME can only figure out the installation directory of this application which may be wrong in certain cases. By supplying an installation directory as value to this flag, GPGME will assume that that directory is the installation directory. This flag has no effect on non-Windows platforms.

This function returns 0 on success. In contrast to other functions the non-zero return value on failure does not convey any error code. For setting “debug” the only possible error cause is an out of memory condition; which would exhibit itself later anyway. Thus the return value may be ignored.

After initializing GPGME, you should set the locale information to the locale required for your output terminal. This locale information is needed for example for the curses and Gtk pinentry. Here is an example of a complete initialization:

#include <locale.h>
#include <gpgme.h>

void
init_gpgme (void)
{
  /* Initialize the locale environment.  */
  setlocale (LC_ALL, "");
  gpgme_check_version (NULL);
  gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
#ifdef LC_MESSAGES
  gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
#endif
}

Note that you are highly recommended to initialize the locale settings like this. GPGME can not do this for you because it would not be thread safe. The conditional on LC_MESSAGES is only necessary for portability to W32 systems.