|
ferencd@0
|
1 \chapter{Getting Started}
|
|
ferencd@0
|
2
|
|
ferencd@0
|
3 % ============================================================================
|
|
ferencd@0
|
4 \section{Using VMime in your programs}
|
|
ferencd@0
|
5
|
|
ferencd@0
|
6 First, make sure you have successfully compiled and installed VMime using the
|
|
ferencd@0
|
7 instructions described in Chapter \ref{chapter_building}. To use VMime in your
|
|
ferencd@0
|
8 program, you simply have to include VMime headers:
|
|
ferencd@0
|
9
|
|
ferencd@0
|
10 \begin{lstlisting}
|
|
ferencd@0
|
11 #include <vmime/vmime.hpp>
|
|
ferencd@0
|
12 \end{lstlisting}
|
|
ferencd@0
|
13
|
|
ferencd@0
|
14 \vnote{for versions older than 0.6.1, include $<$vmime/vmime$>$.}
|
|
ferencd@0
|
15
|
|
ferencd@0
|
16 As of version 0.6.1, VMime uses {\vcode pkg-config} to simplify compiling and
|
|
ferencd@0
|
17 linking with VMime. The {\vcode pkg-config} utility is used to detect the
|
|
ferencd@0
|
18 appropriate compiler and linker flags needed for a library.
|
|
ferencd@0
|
19
|
|
ferencd@0
|
20 You can simply build your program with:
|
|
ferencd@0
|
21
|
|
ferencd@0
|
22 \begin{verbatim}
|
|
ferencd@0
|
23 $ g++ `pkg-config --cflags --libs vmime` -static -o myprog myprog.cpp
|
|
ferencd@0
|
24 \end{verbatim}
|
|
ferencd@0
|
25
|
|
ferencd@0
|
26 to use the static version, or with:
|
|
ferencd@0
|
27
|
|
ferencd@0
|
28 \begin{verbatim}
|
|
ferencd@0
|
29 $ g++ `pkg-config --cflags --libs vmime` -o myprog myprog.cpp
|
|
ferencd@0
|
30 \end{verbatim}
|
|
ferencd@0
|
31
|
|
ferencd@0
|
32 to use the shared version.
|
|
ferencd@0
|
33
|
|
ferencd@0
|
34 \vnote{it is highly recommended that you link your program against the shared
|
|
ferencd@0
|
35 version of the library.}
|
|
ferencd@0
|
36
|
|
ferencd@0
|
37 All VMime classes and global functions are defined in the namespace
|
|
ferencd@0
|
38 {\vcode vmime}, so prefix explicitely all your declarations which use VMime
|
|
ferencd@0
|
39 with {\vcode vmime::}, or import the {\vcode vmime} namespace into the global
|
|
ferencd@0
|
40 namespace with the C++ keywork {\vcode using} (not recommended, though).
|
|
ferencd@0
|
41
|
|
ferencd@0
|
42
|
|
ferencd@0
|
43 % ============================================================================
|
|
ferencd@0
|
44 \section{If you can not (or do not want to) use {\vcode pkg-config}}
|
|
ferencd@0
|
45
|
|
ferencd@0
|
46 {\bf Linking with the shared library (.so):} compile your program with the
|
|
ferencd@0
|
47 {\vcode -lvmime} flag. You can use the -L path flag if the library file is
|
|
ferencd@0
|
48 not in a standard path (ie. not in /usr/lib or /usr/local/lib).
|
|
ferencd@0
|
49
|
|
ferencd@0
|
50 \vnote{if you want to link your program with the shared version of VMime
|
|
ferencd@0
|
51 library, make sure the library has been compiled using CMake build system
|
|
ferencd@0
|
52 ({\vcode make}, then {\vcode make install}). When you compile with SCons,
|
|
ferencd@0
|
53 only the static library is built and installed.}
|
|
ferencd@0
|
54
|
|
ferencd@0
|
55 {\bf Linking with the static library (.a):} follow the same procedure as for
|
|
ferencd@0
|
56 shared linking and append the flag -static to force static linking. Although
|
|
ferencd@0
|
57 static linking is possible, you are encouraged to use the shared (dynamic)
|
|
ferencd@0
|
58 version of the library.
|
|
ferencd@0
|
59
|
|
ferencd@0
|
60
|
|
ferencd@0
|
61 % ============================================================================
|
|
ferencd@0
|
62 \section{Platform-dependent code}
|
|
ferencd@0
|
63
|
|
ferencd@0
|
64 While the most part of VMime code is pure ANSI C++, there are some features
|
|
ferencd@0
|
65 that are platform-specific: file management (opening/reading/writing files),
|
|
ferencd@0
|
66 network code (socket, DNS resolution) and time management. All the
|
|
ferencd@0
|
67 non-portable stuff is done by a bridge object called a platform handler (see
|
|
ferencd@0
|
68 {\vcode vmime::platform}).
|
|
ferencd@0
|
69
|
|
ferencd@0
|
70 If your platform is POSIX-compatible (eg. GNU/Linux, *BSD) or is Windows,
|
|
ferencd@0
|
71 then you are lucky: VMime has built-in support for these platforms. If not,
|
|
ferencd@0
|
72 don't worry, the sources of the built-in platform handlers are very well
|
|
ferencd@0
|
73 documented, so writing you own should not be very difficult.
|
|
ferencd@0
|
74
|
|
ferencd@0
|
75 If your VMime version is $<=$ 0.9.1, you should tell VMime which platform
|
|
ferencd@0
|
76 handler you want to use at the beginning of your program (before using
|
|
ferencd@0
|
77 \emph{any} VMime object, or calling \emph{any} VMime global function).
|
|
ferencd@0
|
78
|
|
ferencd@0
|
79 So, if your platform is POSIX, your program should look like this:
|
|
ferencd@0
|
80
|
|
ferencd@0
|
81 \begin{lstlisting}[caption={Initializing VMime and the platform handler}]
|
|
ferencd@0
|
82 #include <vmime/vmime.hpp>
|
|
ferencd@0
|
83 #include <vmime/platforms/posix/posixHandler.hpp>
|
|
ferencd@0
|
84
|
|
ferencd@0
|
85 int main()
|
|
ferencd@0
|
86 {
|
|
ferencd@0
|
87 vmime::platform::
|
|
ferencd@0
|
88 setHandler <vmime::platforms::posix::posixHandler>();
|
|
ferencd@0
|
89
|
|
ferencd@0
|
90 // Now, you can use VMime
|
|
ferencd@0
|
91 // ...do what you want, it's your program...
|
|
ferencd@0
|
92 }
|
|
ferencd@0
|
93 \end{lstlisting}
|
|
ferencd@0
|
94
|
|
ferencd@0
|
95 For using VMime on Windows, include
|
|
ferencd@0
|
96 {\vcode vmime/platforms/windows/windowsHandler.hpp} and use the following line
|
|
ferencd@0
|
97 to initialize the platform handler:
|
|
ferencd@0
|
98
|
|
ferencd@0
|
99 \begin{lstlisting}
|
|
ferencd@0
|
100 vmime::platform::
|
|
ferencd@0
|
101 setHandler <vmime::platforms::windows::windowsHandler>();
|
|
ferencd@0
|
102 \end{lstlisting}
|
|
ferencd@0
|
103
|
|
ferencd@0
|
104 \vnote{since version 0.9.2, this is not needed any more: the platform
|
|
ferencd@0
|
105 handler is installed automatically using the platform detected during the
|
|
ferencd@0
|
106 build configuration.}
|
|
ferencd@0
|
107
|
|
ferencd@0
|
108 \vnote{since version 0.8.1, {\vcode vmime::platformDependant} was renamed
|
|
ferencd@0
|
109 to {\vcode vmime::platform}. The old name has been kept for compatibility
|
|
ferencd@0
|
110 but it is recommended that you update your code, if needed.}
|
|
ferencd@0
|
111
|
