doc/

2009-05-28  Marcus Brinkmann  <[email protected]>

	* gpgme.texi (Library Version Check): Document selftest error.
	(Creating Contexts): Likewise.

src/
2009-05-28  Marcus Brinkmann  <[email protected]>

	* gpgme.h.in (gpgme_check_version_internal): New prototype.
	(gpgme_check_version): New macro, overriding function of the same
	name.
	* libgpgme.vers, gpgme.def: Add gpgme_check_version_internal.o
	* context.h (_gpgme_selftest): New variable declaration.
	* version.c: Include "context.h".
	(gpgme_check_version): Set _gpgme_selftest on success.
	(gpgme_check_version_internal): New function.
	* gpgme.c (_gpgme_selftest): Define it.
	(gpgme_new): Check the selftest result.

2 files changed, 17 insertions, 3 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index e1f36225..e1bb4a59 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2009-05-28  Marcus Brinkmann  <[email protected]>
+
+	* gpgme.texi (Library Version Check): Document selftest error.
+	(Creating Contexts): Likewise.
+
 2009-05-18  Marcus Brinkmann  <[email protected]>
 
 	* gpgme.texi (Encrypting a Plaintext): Document
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 0d5435f9..871575a2 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -577,13 +577,13 @@ automatically by Libtool.
 @cindex version check, of the library
 
 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
-The function @code{gpgme_check_version} has three purposes.  It can be
+The function @code{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
-@acronym{GPGME}. 
+@acronym{GPGME}.  The last purpose is to run selftests.
 
 As a side effect for W32 based systems, the socket layer will get
 initialized.
@@ -606,6 +606,11 @@ 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 @code{gpgme_new}, so that a detailed
+error code can be returned (historically, @code{gpgme_check_version}
+does not return a detailed error code).
 @end deftypefun
 
 
@@ -1985,7 +1990,11 @@ and returns a handle for it in @var{ctx}.
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 context was successfully created, @code{GPG_ERR_INV_VALUE} if
 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
-enough memory is available.
+enough memory is available.  Also, it returns
+@code{GPG_ERR_NOT_OPERATIONAL} if @code{gpgme_check_version} was not
+called to initialize GPGME, and @code{GPG_ERR_SELFTEST_FAILED} if a
+selftest failed.  Currently, the only selftest is for Windows MingW32
+targets to see if @code{-mms-bitfields} was used (as required).
 @end deftypefun