File: gpgme.info,  Node: Library Version Check,  Next: Signal Handling,  Prev: Using Libtool,  Up: Preparation

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".

     ‘inst-type’
          The installation type is used to prefer a certain GnuPG
          installation.  The value is interpreted as an integer: A value
          of 0 is ignored, a value of 1 indicates an installation scheme
          as used by Gpg4win, a value of 2 indicates an installation
          scheme as used by GnuPG Desktop on Windows.  All other values
          are reserved.

     ‘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 
     #include 

     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.