[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To use GPGME, you have to perform some changes to your sources and the build system. The necessary changes are small and explained in the following sections. At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.
2.1 Header What header file you need to include. 2.2 Building the Source Compiler options to be used. 2.3 Using Automake Compiler options to be used the easy way. 2.4 Library Version Check Getting and verifying the library version. 2.5 Multi Threading How GPGME can be used in an MT environment.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All interfaces (data types and functions) of the library are defined in the header file `gpgme.h'. You must include this in all programs using the library, either directly or through some other header file, like this:
#include <gpgme.h> |
The name space of GPGME is gpgme_*
for function
names, Gpgme*
for data types and GPGME_*
for other
symbols. Symbols internal to GPGME take the form
_gpgme_*
.
Because GPGME links to the Assuan library, linking to
GPGME will also use the assuan_*
and _assuan_*
name space indirectly.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
If you want to compile a source file including the `gpgme.h' header file, you must make sure that the compiler can find it in the directory hierarchy. This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the `-I' option).
However, the path to the include file is determined at the time the
source is configured. To solve this problem, gpgme ships with a small
helper program gpgme-config
that knows about the path to the
include file and other configuration options. The options that need
to be added to the compiler invocation at compile time are output by
the `--cflags' option to gpgme-config
. The following
example shows how it can be used at the command line:
gcc -c foo.c `gpgme-config --cflags` |
Adding the output of `gpgme-config --cflags' to the compilers command line will ensure that the compiler can find the GPGME header file.
A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files. For this to work,
the path to the library files has to be added to the library search
path (via the `-L' option). For this, the option
`--libs' to gpgme-config
can be used. For
convenience, this option also outputs all other options that are
required to link the program with GPGME (in particular, the
`-lgpgme' option). The example shows how to link `foo.o'
with the GPGME library to a program foo
.
gcc -o foo foo.o `gpgme-config --libs` |
Of course you can also combine both examples to a single command by
specifying both options to gpgme-config
:
gcc -o foo foo.c `gpgme-config --cflags --libs` |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is much easier if you use GNU Automake instead writing your own
Makefiles. If you do that you don't have to worry about finding and
invoking the gpgme-config
script at all. GPGME
provides an extension to Automake that does all the work for you.
Additionally, the function defines GPGME_CFLAGS
to the flags
needed for compilation of the program to find the `gpgme.h'
header file, and GPGME_LIBS
to the linker flags needed to link
the program to the GPGME library.
You can use the defined Autoconf variables like this in your `Makefile.am':
AM_CPPFLAGS = $(GPGME_CFLAGS) LDADD = $(GPGME_LIBS) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gpgme_check_version
has three 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.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The GPGME library is not entirely thread-safe, but it can still be used in a multi-threaded environment if some care is taken. If the following requirements are met, there should be no race conditions to worry about:
Support for other thread libraries is very easy to add. Please contact us if you have the need.
gpgme_check_version
must be called before any
other function in the library, because it initializes the thread
support subsystem in GPGME. To achieve this in all
generality, it is necessary to synchronize the call to this function
with all other calls to functions in the library, using the
synchronization mechanisms available in your thread library.
Otherwise, specific compiler or CPU memory cache optimizations could
lead to the situation where a thread is started and uses
GPGME before the effects of the initialization are visible
for this thread. It doesn't even suffice to call
gpgme_check_version
before creating this other
thread(1).
For example, if you are using POSIX threads, each thread that wants to call functions in GPGME could call the following function before any function in the library:
#include <pthread.h> void initialize_gpgme (void) { static int gpgme_init; static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER; pthread_mutex_lock (&gpgme_init_lock); if (!gpgme_init) { gpgme_check_version (); gpgme_init = 1; } pthread_mutex_unlock (&gpgme_init_lock); } |
GpgmeData
, GpgmeCtx
and GpgmeRecipients
object must only be accessed by one thread at a time. If multiple
threads want to deal with the same object, the caller has to make sure
that operations on this object are fully synchronized.
gpgme_wait
. If
multiple threads call this function, the caller must make sure that
all invocations are fully synchronized.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |