]> Jeffrey Stedfast

fejj@helixcode.com

2000-2002 Jeffrey Stedfast Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. This manual documents the interfaces of the gmime library and has some short notes to help get you up to speed with using the library. GMime is a powerful MIME (Multipurpose Internet Mail Extension) utility library. It is meant for creating, editing, and parsing MIME messages and structures. Streams are the fundamental method for reading and writing data used by GMime. The three (3) basic stream types are: GMimeStreamFile, GMimeStreamFs and GMimeStreamMem. You can manipulate all three streams using the GMimeStream interfaces. In addition, some of these streams have extended interfaces to allow more fine grained manipulation. GMimeStreamFile and GMimeStreamFs are very similar in that they are both meant for reading and writing data to the file system (in the form of files). Since GMimeStreamFile is an abstracted layer above the libc FILE type, one of the added benefits is buffered I/O. GMimeStreamFs, on the other hand, is an abstracted layer above UNIX file descriptors. While a GMimeStreamFs can be used on top of a UNIX socket, you must be careful because sockets are not seekable. It is suggested that you use a GMimeStreamBuffer in cache mode if you intend to be able to seek, we will get to this advanced stream type later. Unlike the previous 2 stream types, GMimeStreamMem does not interact with the file system at all (except maybe the swap partition/file indirectly). Memory streams are handy when you want reads and writes to be nearly instantaneous and/or if you don't want to create a temporary file on disk. The four (4) advanced stream types are GMimeStreamMmap, GMimeStreamNull, GMimeStreamBuffer (as was mentioned previously) and GMimeStreamFilter. Our most simple stream, GMimeStreamNull, is the stream equivalent of /dev/null on Unix systems. The main difference is that GMimeStreamNull records the number of bytes written to it. GMimeStreamMmap is a memory-mapped stream. This isn't guarenteed to work on all systems since not all systems support the POSIX mmap system call, but for those that do - this might present a faster stream than GMimeStreamFs and/or GMimeStreamFile. The GMimeStreamBuffer type inherits from any other type of stream and has 3 modes: block reads, block writes, and cached reads. Block reads are especially useful if you will be making a lot of small reads from a stream that accesses the file system. Block writes are useful for very much the same reason. The final mode, cached reads, can become memory intensive but can be very helpful when inheriting from a stream that does not support seeking. Our final stream type, GMimeStreamFilter, also inherits from another stream. This stream, as you may have guessed, filters reads and writes to its inherited stream. For example, one could write a compression filter and apply it to a GMimeStreamFilter and any further reads or writes would be compressed. Stream filters are an efficient way of converting data from one format to another. To use a stream filter, you must first construct a GMimeStreamFilter stream and then add the desired filters to it. GMime comes equipped with some basic filters: GMimeFilterBasic, GMimeFilterCharset, GMimeFilterCRLF, GMimeFilterFrom and GMimeFilterHTML. The GMimeFilterBasic filter is actually a collection of filters for common transfer encodings used by MIME. So far, it is able to handle encoding and decoding of base64, quoted-printable and (x-)uuencode. For internationalization support, GMime also includes a filter for converting between any 2 charsets, GMimeFilterCharset. With this filter, mail user agents can allow the user to read the message content in his or her own charset. A common conversion needed for text is CRLF -> LF and LF -> CRLF which is needed for most (all?) internet protocols. Luckily, GMime comes equipped with a filter to handle this for you, GMimeFilterCRLF. You'll notice that GMimeFilterCRLF can also handle dot-escaping, which is especially useful for SMTP (rfc821). On Unix systems, mail often resides in spools in mbox format. Mbox uses a line that starts with "From " to delimit messages which means that message bodies are forbidden to contain lines starting with "From ". The common way to escape these from lines in message bodies is to prepend the line with a greater-than character ('>') producing ">From ". You'll find GMimeFilterFrom handy when dealing with this. The GMimeFilterHTML filter converts a normal text stream into an html stream. This is especially useful if you are using a widget such as GtkHTML to display the contents of an email message. Data wrappers are a very simple concept. They wrap data. Actually, they wrap around a source stream and contain information about the format of the source stream. This makes writing a data wrapper to a stream incredibly easy because it will decode the data into it's raw form before writing it to the output stream for you. This section contains the complete API reference for libgmime. All the public interfaces are documented here. This reference guide is built by extracting Gtk-Doc comments from the source code. All public functions that return const pointers are not to be free'd, they point to data internal to the structure. Functions that don't return const pointers MUST be free'd by the caller - the ONLY exception to this are functions that return GList structures - for these functions, you must read the documentation for the particular function to know for sure whther you need to free it or not and how. &gmime; &gmime-stream; &gmime-stream-buffer; &gmime-stream-file; &gmime-stream-fs; &gmime-stream-mem; &gmime-stream-mmap; &gmime-stream-null; &gmime-stream-filter; &gmime-filter; &gmime-filter-basic; &gmime-filter-charset; &gmime-filter-crlf; &gmime-filter-from; &gmime-filter-html; &gmime-filter-yenc; &gmime-param; &gmime-header; &gmime-content-type; &gmime-disposition; &gmime-object; &gmime-data-wrapper; &gmime-part; &gmime-message; &gmime-utils; &internet-address; &gmime-parser; &gmime-charset; &gmime-iconv; &gmime-iconv-utils;