ferencd@0: \chapter{Getting Started}
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{Using VMime in your programs}
ferencd@0: 
ferencd@0: First, make sure you have successfully compiled and installed VMime using the
ferencd@0: instructions described in Chapter \ref{chapter_building}. To use VMime in your
ferencd@0: program, you simply have to include VMime headers:
ferencd@0: 
ferencd@0: \begin{lstlisting}
ferencd@0: #include <vmime/vmime.hpp>
ferencd@0: \end{lstlisting}
ferencd@0: 
ferencd@0: \vnote{for versions older than 0.6.1, include $<$vmime/vmime$>$.}
ferencd@0: 
ferencd@0: As of version 0.6.1, VMime uses {\vcode pkg-config} to simplify compiling and
ferencd@0: linking with VMime. The {\vcode pkg-config} utility is used to detect the
ferencd@0: appropriate compiler and linker flags needed for a library.
ferencd@0: 
ferencd@0: You can simply build your program with:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    $ g++ `pkg-config --cflags --libs vmime` -static -o myprog myprog.cpp
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: to use the static version, or with:
ferencd@0: 
ferencd@0: \begin{verbatim}
ferencd@0:    $ g++ `pkg-config --cflags --libs vmime` -o myprog myprog.cpp
ferencd@0: \end{verbatim}
ferencd@0: 
ferencd@0: to use the shared version.
ferencd@0: 
ferencd@0: \vnote{it is highly recommended that you link your program against the shared
ferencd@0: version of the library.}
ferencd@0: 
ferencd@0: All VMime classes and global functions are defined in the namespace
ferencd@0: {\vcode vmime}, so prefix explicitely all your declarations which use VMime
ferencd@0: with {\vcode vmime::}, or import the {\vcode vmime} namespace into the global
ferencd@0: namespace with the C++ keywork {\vcode using} (not recommended, though).
ferencd@0: 
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{If you can not (or do not want to) use {\vcode pkg-config}}
ferencd@0: 
ferencd@0: {\bf Linking with the shared library (.so):} compile your program with the
ferencd@0: {\vcode -lvmime} flag. You can use the -L path flag if the library file is
ferencd@0: not in a standard path (ie. not in /usr/lib or /usr/local/lib).
ferencd@0: 
ferencd@0: \vnote{if you want to link your program with the shared version of VMime
ferencd@0: library, make sure the library has been compiled using CMake build system
ferencd@0: ({\vcode make}, then {\vcode make install}). When you compile with SCons,
ferencd@0: only the static library is built and installed.}
ferencd@0: 
ferencd@0: {\bf Linking with the static library (.a):} follow the same procedure as for
ferencd@0: shared linking and append the flag -static to force static linking. Although
ferencd@0: static linking is possible, you are encouraged to use the shared (dynamic)
ferencd@0: version of the library.
ferencd@0: 
ferencd@0: 
ferencd@0: % ============================================================================
ferencd@0: \section{Platform-dependent code}
ferencd@0: 
ferencd@0: While the most part of VMime code is pure ANSI C++, there are some features
ferencd@0: that are platform-specific: file management (opening/reading/writing files),
ferencd@0: network code (socket, DNS resolution) and time management. All the
ferencd@0: non-portable stuff is done by a bridge object called a platform handler (see
ferencd@0: {\vcode vmime::platform}).
ferencd@0: 
ferencd@0: If your platform is POSIX-compatible (eg. GNU/Linux, *BSD) or is Windows,
ferencd@0: then you are lucky: VMime has built-in support for these platforms. If not,
ferencd@0: don't worry, the sources of the built-in platform handlers are very well
ferencd@0: documented, so writing you own should not be very difficult.
ferencd@0: 
ferencd@0: If your VMime version is $<=$ 0.9.1, you should tell VMime which platform
ferencd@0: handler you want to use at the beginning of your program (before using
ferencd@0: \emph{any} VMime object, or calling \emph{any} VMime global function).
ferencd@0: 
ferencd@0: So, if your platform is POSIX, your program should look like this:
ferencd@0: 
ferencd@0: \begin{lstlisting}[caption={Initializing VMime and the platform handler}]
ferencd@0: #include <vmime/vmime.hpp>
ferencd@0: #include <vmime/platforms/posix/posixHandler.hpp>
ferencd@0: 
ferencd@0: int main()
ferencd@0: {
ferencd@0:    vmime::platform::
ferencd@0:       setHandler <vmime::platforms::posix::posixHandler>();
ferencd@0: 
ferencd@0:    // Now, you can use VMime
ferencd@0:    // ...do what you want, it's your program...
ferencd@0: }
ferencd@0: \end{lstlisting}
ferencd@0: 
ferencd@0: For using VMime on Windows, include
ferencd@0: {\vcode vmime/platforms/windows/windowsHandler.hpp} and use the following line
ferencd@0: to initialize the platform handler:
ferencd@0: 
ferencd@0: \begin{lstlisting}
ferencd@0: vmime::platform::
ferencd@0:    setHandler <vmime::platforms::windows::windowsHandler>();
ferencd@0: \end{lstlisting}
ferencd@0: 
ferencd@0: \vnote{since version 0.9.2, this is not needed any more: the platform
ferencd@0: handler is installed automatically using the platform detected during the
ferencd@0: build configuration.}
ferencd@0: 
ferencd@0: \vnote{since version 0.8.1, {\vcode vmime::platformDependant} was renamed
ferencd@0: to {\vcode vmime::platform}. The old name has been kept for compatibility
ferencd@0: but it is recommended that you update your code, if needed.}
ferencd@0: