diff options
Diffstat (limited to 'docs/tutorial')
| -rw-r--r-- | docs/tutorial/Makefile.am | 24 | ||||
| -rw-r--r-- | docs/tutorial/Makefile.in | 438 | ||||
| -rw-r--r-- | docs/tutorial/gmime-tut.sgml | 681 |
3 files changed, 1143 insertions, 0 deletions
diff --git a/docs/tutorial/Makefile.am b/docs/tutorial/Makefile.am new file mode 100644 index 0000000..13e713d --- /dev/null +++ b/docs/tutorial/Makefile.am @@ -0,0 +1,24 @@ +.PHONY: html + +EXTRA_DIST = gmime-tut.sgml + +html: +if HAVE_DOCBOOK + if test -w $(srcdir); then \ + (cd $(srcdir); \ + $(DB2HTML) -o html gmime-tut.sgml); \ + fi +else + echo "***" + echo "*** Warning: Tutorial not built" + echo "***" +endif + +dist-hook: html +if HAVE_DOCBOOK + cp -Rp $(srcdir)/html $(distdir) +else + echo "*** DISTRIBUTION IS INCOMPLETE" + echo "***" +endif + diff --git a/docs/tutorial/Makefile.in b/docs/tutorial/Makefile.in new file mode 100644 index 0000000..e8763f9 --- /dev/null +++ b/docs/tutorial/Makefile.in @@ -0,0 +1,438 @@ +# Makefile.in generated by automake 1.11.3 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software +# Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +target_triplet = @target@ +subdir = docs/tutorial +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +SOURCES = +DIST_SOURCES = +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +ACLOCAL_AMFLAGS = @ACLOCAL_AMFLAGS@ +AMTAR = @AMTAR@ +API_VERSION = @API_VERSION@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CSC = @CSC@ +CYGPATH_W = @CYGPATH_W@ +DB2HTML = @DB2HTML@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DOLT_BASH = @DOLT_BASH@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GACUTIL = @GACUTIL@ +GAPI_CODEGEN = @GAPI_CODEGEN@ +GAPI_FIXUP = @GAPI_FIXUP@ +GAPI_PARSER = @GAPI_PARSER@ +GAPI_TOOLS_CFLAGS = @GAPI_TOOLS_CFLAGS@ +GAPI_TOOLS_LIBS = @GAPI_TOOLS_LIBS@ +GLIB_CFLAGS = @GLIB_CFLAGS@ +GLIB_COMPILE_RESOURCES = @GLIB_COMPILE_RESOURCES@ +GLIB_GENMARSHAL = @GLIB_GENMARSHAL@ +GLIB_LIBS = @GLIB_LIBS@ +GLIB_MKENUMS = @GLIB_MKENUMS@ +GLIB_SHARP_CFLAGS = @GLIB_SHARP_CFLAGS@ +GLIB_SHARP_LIBS = @GLIB_SHARP_LIBS@ +GMIME_API_VERSION = @GMIME_API_VERSION@ +GMIME_BINARY_AGE = @GMIME_BINARY_AGE@ +GMIME_CFLAGS = @GMIME_CFLAGS@ +GMIME_INCLUDEDIR = @GMIME_INCLUDEDIR@ +GMIME_INTERFACE_AGE = @GMIME_INTERFACE_AGE@ +GMIME_LIBDIR = @GMIME_LIBDIR@ +GMIME_LIBS = @GMIME_LIBS@ +GMIME_LIBS_PRIVATE = @GMIME_LIBS_PRIVATE@ +GMIME_MAJOR_VERSION = @GMIME_MAJOR_VERSION@ +GMIME_MICRO_VERSION = @GMIME_MICRO_VERSION@ +GMIME_MINOR_VERSION = @GMIME_MINOR_VERSION@ +GMIME_VERSION = @GMIME_VERSION@ +GOBJECT_QUERY = @GOBJECT_QUERY@ +GPGME_CONFIG = @GPGME_CONFIG@ +GPGME_PTHREAD_CFLAGS = @GPGME_PTHREAD_CFLAGS@ +GPGME_PTHREAD_LIBS = @GPGME_PTHREAD_LIBS@ +GREP = @GREP@ +GTKDOC_CHECK = @GTKDOC_CHECK@ +GTKDOC_DEPS_CFLAGS = @GTKDOC_DEPS_CFLAGS@ +GTKDOC_DEPS_LIBS = @GTKDOC_DEPS_LIBS@ +GTKDOC_MKPDF = @GTKDOC_MKPDF@ +GTKDOC_REBASE = @GTKDOC_REBASE@ +HTML_DIR = @HTML_DIR@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBICONV = @LIBICONV@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_EXE_MACHINE_FLAG = @LIB_EXE_MACHINE_FLAG@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTCOMPILE = @LTCOMPILE@ +LTCXXCOMPILE = @LTCXXCOMPILE@ +LTLIBICONV = @LTLIBICONV@ +LTLIBOBJS = @LTLIBOBJS@ +LT_AGE = @LT_AGE@ +LT_CURRENT = @LT_CURRENT@ +LT_CURRENT_MINUS_AGE = @LT_CURRENT_MINUS_AGE@ +LT_RELEASE = @LT_RELEASE@ +LT_REVISION = @LT_REVISION@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +MV = @MV@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PKG_CONFIG = @PKG_CONFIG@ +PKG_CONFIG_LIBDIR = @PKG_CONFIG_LIBDIR@ +PKG_CONFIG_PATH = @PKG_CONFIG_PATH@ +RANLIB = @RANLIB@ +RM = @RM@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TAR = @TAR@ +VERSION = @VERSION@ +WINDRES = @WINDRES@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +gacdir = @gacdir@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +ms_librarian = @ms_librarian@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target = @target@ +target_alias = @target_alias@ +target_cpu = @target_cpu@ +target_os = @target_os@ +target_vendor = @target_vendor@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +EXTRA_DIST = gmime-tut.sgml +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/tutorial/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/tutorial/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-hook +check-am: all-am +check: check-am +all-am: Makefile +installdirs: +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html-am: + +info: info-am + +info-am: + +install-data-am: + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + dist-hook distclean distclean-generic distclean-libtool \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am + +.PHONY: html + +html: +@HAVE_DOCBOOK_TRUE@ if test -w $(srcdir); then \ +@HAVE_DOCBOOK_TRUE@ (cd $(srcdir); \ +@HAVE_DOCBOOK_TRUE@ $(DB2HTML) -o html gmime-tut.sgml); \ +@HAVE_DOCBOOK_TRUE@ fi +@HAVE_DOCBOOK_FALSE@ echo "***" +@HAVE_DOCBOOK_FALSE@ echo "*** Warning: Tutorial not built" +@HAVE_DOCBOOK_FALSE@ echo "***" + +dist-hook: html +@HAVE_DOCBOOK_TRUE@ cp -Rp $(srcdir)/html $(distdir) +@HAVE_DOCBOOK_FALSE@ echo "*** DISTRIBUTION IS INCOMPLETE" +@HAVE_DOCBOOK_FALSE@ echo "***" + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/docs/tutorial/gmime-tut.sgml b/docs/tutorial/gmime-tut.sgml new file mode 100644 index 0000000..57b3c61 --- /dev/null +++ b/docs/tutorial/gmime-tut.sgml @@ -0,0 +1,681 @@ +<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ +<!notation PNG system "PNG"> +<!entity % local.notation.class "| PNG"> +]> +<book id="gmime-tut"> + + <bookinfo> + <title>GMime 2.6 tutorial</title> + <date>Oct 28, 2010</date> + <authorgroup> + <author> + <firstname>Jeffrey</firstname> + <surname>Stedfast</surname> + <affiliation> + <address> + <email>fejj@gnome.org</email> + </address> + </affiliation> + </author> + </authorgroup> + <abstract> + <para>This tutorial is meant to demonstrate how to use the GMime + C API.</para> + </abstract> + </bookinfo> + + <toc></toc> + + <!-- ***************************************************************** --> + <chapter id="ch-availability"> + <title>Tutorial Availability</title> + + <para>A copy of this tutorial is distributed with each source-code +release of GMime in both SGML and HTML formats. For binary +distributions, please check with your vendor.</para> + + <para>An online version of this tutorial is also available at <ulink +url="http://spruce.sourceforge.net/gmime/tutorial/">http://spruce.sourceforge.net/gmime/tutorial/</ulink>. + </para> + + </chapter> + + <!-- ***************************************************************** --> + <chapter id="ch-introduction"> + <title>Introduction</title> + + <para>GMime is a library for parsing and creating messages using the +Multipurpose Internet Mail Extension (MIME) format. It is licensed +under the <ulink +url="http://http://www.gnu.org/licenses/licenses.html#LGPL">GNU Lesser General +Public License (LGPL)</ulink> so you are free to develop your Free +Software applications using GMime without having to spend anything for +licenses or royalties.</para> + + <para>The primary author and maintainer of GMime is:</para> + + <itemizedlist> + <listitem> + <simpara>Jeffrey Stedfast <ulink url="mailto:fejj@gnome.org">fejj@gnome.org</ulink></simpara> + </listitem> + </itemizedlist> + + <para>GMime is essentially an object-oriented application programmers +interface (API). Although written completely in C, it is implemented +using the idea of classes and callback functions (pointers to +functions).</para> + + <para>GMime is built upon another library called GLib which also +serves as the foundation for such libraries as the GIMP ToolKit +(Gtk+). GLib is mostly a portability layer but also contains +additional functionality such as hash tables, linked lists, etc. For +more information on GLib, you should see the API reference at <ulink +url="http://library.gnome.org/devel/glib/stable/">http://library.gnome.org/devel/glib/stable/</ulink>.</para> + + </chapter> + + <!-- ***************************************************************** --> + <chapter id="ch-getting-started"> + <title>Getting Started</title> + + <para>The first thing you need to do, of course, is download the +GMime source and install it. You can always get the latest version +from <ulink url="http://download.gnome.org/pub/GNOME/sources/gmime/">http://download.gnome.org/pub/GNOME/sources/gmime/</ulink>. GMime +uses GNU autoconf for configuration. Once untar'd, type +<literal>./configure --help</literal> to see a list of options.</para> + + <para>More information about building GMime is available in either the +source distribution under <filename>docs/reference/</filename> or via +the online reference at <ulink +url="http://library.gnome.org/devel/gmime/stable/gmime-building.html">http://library.gnome.org/devel/gmime/stable/gmime-building.html</ulink>.</para> + + </chapter> + + <!-- ***************************************************************** --> + <chapter id="ch-basics"> + <title>Getting Down to the Basics</title> + + <!-- ----------------------------------------------------------------- --> + <sect1 id="sec-compiling"> + <title>Compiling</title> + + <para>The first thing you need to learn how to do is compile + your program with the proper compiler flags so that your program + will include the correct GMime headers and linker flags.</para> + + <para>To compile and link a simple program, you'll want to do + the following:</para> + + <para> + <literallayout> + <literal>gcc -g -Wall -o simple simple.c `pkg-config --cflags --libs gmime-2.4`</literal> + </literallayout> + </para> + </sect1> + + <!-- ----------------------------------------------------------------- --> + <sect1 id="sec-stream-basics"> + <title>GMimeStream Basics</title> + + <para>Before we get too deep into using GMime, it is important + to understand how to use the underlying I/O classes since GMime + is so very heavily dependant upon them.</para> + + <para>If you've looked at the API at all already, you will have + probably noticed that the stream functions work very much like + those of the standard low-level UNIX I/O functions (those that + use file descriptors) but with a few extras taken from the + higher-level Standard C I/O API.</para> + + <para>Let's take a moment to regres back to our early days of + programming where we learned how to write "Hello World!" on the + console:</para> + + <programlisting role="C"> +#include <stdio.h> + +int main (int argc, char **argv) +{ + fprintf (stdout, "Hello World!\n"); + fflush (stdout); + + return 0; +} + </programlisting> + + <para>Everyone should recognize what that program does. The + above program, rewritten to use GMime's stream classes would + look something like this:</para> + + <programlisting role="C"> +#include <stdio.h> +#include <gmime/gmime.h> + +int main (int argc, char **argv) +{ + GMimeStream *stream; + + /* initialize GMime */ + g_mime_init (0); + + /* create a stream around stdout */ + stream = g_mime_stream_file_new (stdout); + + /* 'printf' */ + g_mime_stream_printf (stream, "Hello World!\n"); + + /* flush stdout */ + g_mime_stream_flush (stream); + + /* free/close the stream */ + g_object_unref (stream); + + return 0; +} + </programlisting> + + <para>Hopefully, the only thing that may be new to you in either + of the above examples is the flushing of the stream after + writing to it. Most likely, in both examples, it is an unneeded + call, however it is there for completeness and you should + probably get into the habbit of flushing a stream after you've + finished writing to it. Like fflush(), g_mime_stream_flush() + will flush any write-buffers that the previous write-calls may + have left.</para> + + <para>The first function called in the second example is + <literal>g_mime_init</literal> with a value of + <literal>0</literal>. If you haven't guessed, + <literal>g_mime_init</literal> initializes the GMime library. It + takes a single bit-mask argument specifying which options to + enable. Currently there is only one optional bit-flag, + <literal>GMIME_INIT_FLAG_UTF8</literal> which is the default + anyway, so a value of <literal>0</literal> is used here. The + UTF-8 flag only exists for historical reasons.</para> + + <para>The only other line that should need explaining might be:</para> + + <programlisting role="C"> + stream = g_mime_stream_file_new (stdout); + </programlisting> + + <para>This line creates a new object of type GMimeStreamFile which + takes a <literal>FILE*</literal> argument. Once the + GMimeStreamFile is created, it takes ownership of the + <literal>FILE*</literal> so be careful if you want to be able to + ever use that <literal>FILE*</literal> handle again later in + your program or if you do not wish for it to be closed when the + GMimeStreamFile is closed later.</para> + + <para>One way of working around this is to do something like the + following example:</para> + + <programlisting role="C"> +#include <stdio.h> +#include <unistd.h> +#include <gmime/gmime.h> + +int main (int argc, char **argv) +{ + GMimeStream *stream; + + /* initialize GMime */ + g_mime_init (0); + + /* create a stream around stdout */ + stream = g_mime_stream_fs_new (dup (fileno (stdout))); + + /* 'printf' */ + g_mime_stream_printf (stream, "Hello World!\n"); + + /* flush stdout */ + g_mime_stream_flush (stream); + + /* free/close the stream */ + g_object_unref (stream); + + return 0; +} + </programlisting> + + <para>Here we have made a duplicate copy of stdout to give to + <literal>g_mime_stream_fs_new()</literal>. GMimeStreamFs is the + second type of stream meant for basic I/O, but instead of using + a <literal>FILE*</literal> handle, it instead uses an integer + file descriptor. The <literal>fileno()</literal> function + returns the integer file descriptor for a given + <literal>FILE*</literal> handle. The <literal>dup()</literal> + function makes a duplicate of the file descriptor passed to + it. More information can be read about these 2 functions by + using <literal>man</literal> on your local UNIX system or by + reading the Reference Manual for your libc.</para> + + <para>There are also some functions to tell GMimeStreamFile, + GMimeStreamFs and GMimeStreamMem that they are not the owners of + the backend storage and so when they are destroyed, they should + not close the file or free the memory buffer + (respectively). These functions are:</para> + + <programlisting role="C"> +void g_mime_stream_file_set_owner (GMimeStreamFile *stream, gboolean owner); +void g_mime_stream_fs_set_owner (GMimeStreamFs *stream, gboolean owner); +void g_mime_stream_mem_set_owner (GMimeStreamMem *stream, gboolean owner); + </programlisting> + + <para>Next, let's examine some of the other stream + functions.</para> + + <programlisting role="C"> + g_mime_stream_eos (stream); + </programlisting> + + <para>This function is useful for finding out if the + End-Of-Stream has been reached. This is similar in functionality + to Standard C's <literal>feof()</literal> function.</para> + + <programlisting role="C"> + g_mime_stream_reset (stream); + </programlisting> + + <para>This function will reset the state of a stream. Usually + this only means 'rewinding' to the beginning of the file. For + more complex streams, such as GMimeStreamFilter, however, this + will also reset the state of all of the filters that have been + attached to it (more on this later).</para> + + <programlisting role="C"> + g_mime_stream_length (stream); + </programlisting> + + <para>This function will return the length of the stream if + known, or -1 otherwise. For the most part, this function should + be avoided unless you absolutely need to know the stream length + and there is no other way to get it. The reason to avoid using + it is that it may be inaccurate if any filters are to be applied + as well as possibly being slow depending on the underlying + storage device.</para> + + <programlisting role="C"> + g_mime_stream_substream (stream, start, end); + </programlisting> + + <para>This function will return a substream of the original + stream, where the beginning of the new substream is the start + offset and the end is the end offset. These start and end + offsets MUST be within the bounds of the original + stream. Substreams can be useful if you want to only allow + reading and writing to a subsection of the original + stream.</para> + + <programlisting role="C"> + g_mime_stream_read (stream, buf, n); + </programlisting> + + <para>Like POSIX <literal>read()</literal>, this function will + try to read <literal>n</literal> bytes from the stream + into <literal>buf</literal>, but be warned that it is not + guaranteed to read the full requested buffer size if that much + data is not currently available.</para> + + <programlisting role="C"> + g_mime_stream_write (stream, buf, n); + </programlisting> + + <para>Like POSIX <literal>write()</literal> and standard + C's <literal>fwrite()</literal>, this function will write a + buffer of the specified length to the underlying + stream. However, unlike the POSIX <literal>write()</literal> + function, it will only fail if an irrecoverable error has + occurred and so it is not necessary to loop write attempts until + the entire buffer is written.</para> + + <programlisting role="C"> + g_mime_stream_seek (stream, offset, GMIME_STREAM_SEEK_SET); + g_mime_stream_seek (stream, offset, GMIME_STREAM_SEEK_CUR); + g_mime_stream_seek (stream, offset, GMIME_STREAM_SEEK_END); + </programlisting> + + <para>This function works exactly like the + POSIX <literal>lseek()</literal> or standard + C's <literal>fseek()</literal> functions.</para> + + </sect1> + + <!-- ----------------------------------------------------------------- --> + <sect1 id="sec-stream-classes"> + <title>Stream Class Overview</title> + + <para>There are a number of stream classes included with GMime, + but we are only going to go over the more widely useful stream + classes. You should be able to figure out the others on your + own.</para> + + <para>We've already seen GMimeStreamFile and GMimeStreamFs in + action in the prevous chapter, so let's skip them and start with + GMimeStreamMem.</para> + + <para>GMimeStremMem is a stream abstraction that reads and + writes to a memory buffer. Like any other stream, the basic + stream functions (read, write, seek, substream, eos, etc) apply + here as well. Internally, GMimeStreamMem uses the GLib + GByteArray structure for storage so you may want to read up on + that.</para> + + <para>There are several ways to instantiate a GMimeStreamMem + object. You will probably use + <literal>g_mime_stream_mem_new()</literal> most of the + time. There may be times, however, when you will already have a + memory buffer that you'd like to use as a stream. There are + several ways to create a GMimeStreamMem object to use this + buffer (or a copy of it).</para> + + <para>The first is + <literal>g_mime_stream_mem_new_with_byte_array()</literal>. This + assumes that you are already using a GByteArray and want to use + it as a stream. As explained in the previous chapter about + GMimeStreamFile and ownership, the same applies here. When the + GMimeStreamMem is destroyed, so is the GByteArray structure and + the memory buffer it contained. To get around this, create a new + GMimeStreamMem object using + <literal>g_mime_stream_mem_new()</literal> and then use + <literal>g_mime_stream_mem_set_byte_array()</literal> to set the + GByteArray as the memory buffer. This will make it so that + GMimeStreamMem does not own the GByteArray, so when the + GMimeStremMem object is destroyed, the GByteArray will + remain.</para> + + <para>Also at your disposal for creating GMimeStreamMem objects + with an initial buffer is + <literal>g_mime_stream_mem_new_with_buffer()</literal>. This + function, however, will duplicate the buffer passed to it so if + you have memory quotas you are trying to keep, you may wish to + find a way to use one of the above methods.</para> + + <para>That pretty much sums up how to use GMimeStreamMem. The + next most widely used stream class is probably + GMimeStreamBuffer. This stream class actually wraps another + stream object adding additional functionality such as read and + write buffering and a few additional read methods.</para> + + <para>As you may or may not know, buffering reads and writes is + a great way to improve I/O performance in applications. The time + it takes to do a lot of small reads and writes accumulates + fast.</para> + + <para>When using a GMimeStreamBuffer in + <literal>GMIME_STREAM_BUFFER_BLOCK_READ</literal> mode, a block + of 4K (4096 bytes) will be read into an intermediate + buffer. Each time your application performs a read on this + GMimeStreamBuffer stream, a chunk of that intermediate buffer + will be copied to your read buffer until all 4K have been read, + at which point GMimeStreamBuffer will pre-scan the next 4K and so + on.</para> + + <para>Similarly, using mode + <literal>GMIME_STREAM_BUFFER_BLOCK_WRITE</literal> will copy + each of your application write-buffers into an intermediate 4K + buffer. When that 4K buffer fills up, it will be flushed to the + underlying stream. You may also use + <literal>g_mime_stream_flush()</literal> to force the + intermediate buffer to be written to the underlying + stream.</para> + + <para>Note that the intermediate buffer size is 4096 bytes. You + should be aware that if you will mostly be reading and writing + blocks of larger than 4K, it is probably best to avoid using + GMimeStreamBuffer as it will not likely gain you any performance + and may decrease performance instead.</para> + + <para>GMimeStreamBuffer also adds 2 convenience functions for + reading. While they will both work with any stream class, they + are obviously much faster if used with a GMimeStreamBuffer in + mode <literal>GMIME_STREAM_BUFFER_BLOCK_READ</literal>. These + functions are:</para> + + <programlisting role="C"> +ssize_t g_mime_stream_buffer_gets (GMimeStream *stream, char *buf, size_t max); + +void g_mime_stream_buffer_readln (GMimeStream *stream, GByteArray *buffer); + </programlisting> + + <para>The first function is similar to Standard C's + <literal>fgets()</literal> function (although the arguments are + in a slightly different order). It reads up to the first + <literal>max - 1</literal> bytes, stopping after a + <literal>\n</literal> character, if found. <literal>buf</literal> + will always be nul-terminated.</para> + + <para>The second function, + <literal>g_mime_stream_buffer_readln()</literal>, has no + Standard C equivalent that I am aware of, but you should get the + idea of what it does based on the function name (I hope). It + reads exactly one (1) line (including the <literal>\n</literal> + character) and appends it to the end of + <literal>buffer</literal>.</para> + + <para>The last stream class you really need to know (and the + last one I have the patience to explain) is + GMimeStreamFilter. This is a special stream class which you can + attach GMimeFilters to so that reading/writing to this stream + will automagically convert the stream from one form to + another. GMime uses this stream internally for converting base64 + encoded attachments into their raw form and vice versa.</para> + + <note> + <para>As previously mentioned in the last chapter concerning + <literal>g_mime_stream_reset()</literal>, resetting a + GMimeStreamFilter stream will also reset all of the filters + applied.</para> + </note> + + <para>A great example usage of GMimeStreamFilter can be found in + the <filename>src/uuencode.c</filename> source file found in the + source distribution. Here's a clip of that source file + illustrating how to use stream filters:</para> + + <programlisting role="C"> + GMimeStream *istream, *ostream, *fstream; + GMimeFilter *filter; + int fd; + + ... + + if (g_mime_stream_printf (ostream, "begin %.3o %s\n", st.st_mode & 0777, name) == -1) { + fprintf (stderr, "%s: %s\n", progname, strerror (errno)); + g_object_unref (ostream); + exit (1); + } + + istream = g_mime_stream_fs_new (fd); + + fstream = g_mime_stream_filter_new (ostream); + + filter = g_mime_filter_basic_new (GMIME_CONTENT_ENCODING_UUENCODE, TRUE); + g_mime_stream_filter_add ((GMimeStreamFilter *) fstream, filter); + g_object_unref (filter); + + if (g_mime_stream_write_to_stream (istream, fstream) == -1) { + fprintf (stderr, "%s: %s\n", progname, strerror (errno)); + g_object_unref (fstream); + g_object_unref (istream); + g_object_unref (ostream); + exit (1); + } + + g_mime_stream_flush (fstream); + g_object_unref (fstream); + g_object_unref (istream); + + if (g_mime_stream_write_string (ostream, "end\n") == -1) { + fprintf (stderr, "%s: %s\n", progname, strerror (errno)); + g_object_unref (ostream); + exit (1); + } + + g_object_unref (ostream); + </programlisting> + + <para>The above snippet of code will read the contents of the input + stream (<literal>istream</literal>) and write it to our output + stream (<literal>ostream</literal>), but only after it has + passed through our filter-stream + (<literal>fstream</literal>). The filter attached to + <literal>fstream</literal> is one of the basic MIME filters that + encodes data in the traditional UUCP format. You have probably + run a program to do this many times in the past using the UNIX + command <literal>uuencode</literal>. Never thought writing a + replacement for <literal>uuencode</literal> could be so easy, + did you? Well, it is. And not only is it <emphasis>that + easy</emphasis>, but it also runs faster than the + <literal>uuencode</literal> shipped with GNU Sharutils (at least + up to and including the 4.2.1 release).</para> + + </sect1> + + <!-- ----------------------------------------------------------------- --> + <sect1 id="sec-filter-classes"> + <title>Filter Class Overview</title> + + <para>GMime comes pre-bundled with a number of stream filters + for your convenience and more may be added in the future. For + now, let's breeze through a summary of some of the more important + ones:</para> + + <para>GMimeFilterBasic is used quite a lot internally in GMime + for encoding and decoding the content of MIME parts. This class + contains a mode for encoding and decoding each of Base64, + Quoted-Printable, and Uuencode.</para> + + <para>If you are interested in converting between charsets for + your users, you will likely want to become familiar with + GMimeFilterCharset which provides a convenient way to convert + text streams of one charset into another charset.</para> + + <para>GMimeFilterCRLF will likely become very useful to you if + you are implementing any internet standards or DOS/UNIX + compatability. This filter is meant for converting line endings + from the traditional UNIX sequence (LF) to the internet standard + (and DOS) sequence, CRLF, and vice versa. Also included in this + filter is a way to escape and unescape lines beginning with '.' + in the method used by the SMTP and POP protocols.</para> + + <para>GMimeFilterFrom is one you will likely need to use if ever + you need to write to an mbox-formatted mail spool. At present, + it has 2 modes: <literal>GMIME_FILTER_FROM_MODE_ESCAPE</literal> + and <literal>GMIME_FILTER_FROM_MODE_ARMOR</literal>. If you are + writing to an mbox-formatted spool, you will always want to use + the <literal>ESCAPE</literal> mode which will escape lines + beginning with "From " by prepending a '>' character, resulting + in ">From ". The other mode might come in handy if you are + implementing a multipart/signed method where you are + quoted-printable encoding a text stream and need to special-case + From-lines in order to protect against UNIX systems which will + alter the message when writing it to an mbox file such as the + previously mentioned filter mode. The result is something like + "=46rom " which prevents the need to prepend a '>' character + when the message arrives at a UNIX machine.</para> + + <para>Also included are: GMimeFilterBest (which will likely not + concern you), GMimeFilterEnriched (which will convert + text/enriched and/or text/rtf to text/html), and GMimeFilterHTML + which will convert text/plain into text/html with options to + wrap strings that appear to be hyperlinks with appropriate <a + href=...> tags; GMimeFilterStrip (again, likely this won't + concern you), and finally GMimeFilterYenc which will encode or + decode the YEncode encoding.</para> + + <para>For an example on how to use filters, please see the end + of the previous chapter where it talks about GMimeStreamFilter + and provides a snippet from + <filename>src/uuencode.c</filename></para> + + <note> + <para>Note: Since it may be non-obvious, filters are applied + to a stream in the same order that they are added to the + GMimeFilterStream. This means that if you add a base64 encode + filter and then add a CRLF filter, the stream will first be + base64 encoded and then the end-of-line formatting will be + canonicalised to CRLF.</para> + </note> + + </sect1> + + </chapter> + + <!-- ***************************************************************** --> + <chapter id="ch-mime"> + <title>MIME, MIME, and more MIME</title> + + <!-- ----------------------------------------------------------------- --> + <sect1 id="sec-mime-part"> + <title>GMimePart</title> + + <para>Since most people seem to want to know how to "save an + attachment", let's start there.</para> + + <para>Given a GMimePart object, the first step to saving an + attachment is probably going to be figuring out what the + filename is. To do that, you'll likely want to do something + like:</para> + + <programlisting role="C"> +static void +save_attachment (GMimePart *part) +{ + GMimeDataWrapper *content; + const char *filename; + GMimeStream *stream; + int fd; + + filename = g_mime_part_get_filename (part); + ... + </programlisting> + + <para>The <literal>g_mime_part_get_filename()</literal> function + will first check for a <literal>filename</literal> parameter in + the Content-Disposition header. If that parameter exists, + it will return the value as the filename. However, if that does + not exist, it will fall back to checking for the + <literal>name</literal> parameter sometimes found in the + Content-Type header and return that value if it exists + (Microsoft Outlook, for example, will set the name parameter, + but will not set the filename parameter). If neither of these + param values are found, it will simply return + <literal>NULL</literal>.</para> + + <para>Now that you've got a filename for the MIME part (well, + assuming that it isn't NULL - in which case you'll have to + prompt the user or make up your own filename or something), the + next step is to open an output stream and write the MIME part's + content to disk:</para> + + <programlisting role="C"> + ... + if ((fd = open (filename, O_CREAT | O_WRONLY, 0666)) == -1) + return; + + stream = g_mime_stream_fs_new (fd); + + content = g_mime_part_get_content_object (part); + g_mime_data_wrapper_write_to_stream (content, stream); + g_mime_stream_flush (stream); + g_object_unref (stream); +} + </programlisting> + + <para>In order to get the content of a MIME part (eg. the body + of a part, not including the headers), you'll want to use + <literal>g_mime_part_get_content_object()</literal>. To write + the content object to a stream, you can use + <literal>g_mime_data_wrapper_write_to_stream()</literal>. On + fail, this function will return <literal>-1</literal>, otherwise + it will return some positive value which will usually equate to + the number of bytes written (but not always, due to filter + transformations); generally it's a good idea to not rely on the + returned value for anything other than error-checking.</para> + + </sect1> + + </chapter> + +</book> |