docs/reference/streams.sgml

   1 <refentry id="gmime-streams">
   2   <refmeta>
   3     <refentrytitle>GMime Streams</refentrytitle>
   4     <refmiscinfo>GMime Library</refmiscinfo>
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>GMime Streams</refname>
   9     <refpurpose>How to use GMime Streams</refpurpose>
  10   </refnamediv>
  11   <refsect1 id="stream-overview">
  12     <title>Overview of Streams</title>
  13     <para>Streams are the fundamental method for reading and writing
  14     data used by GMime. You'll probably notice that the basic API is
  15     similar to that of the low-level Unix I/O layer (read(), write(),
  16     lseek(), etc) with some additional nicities such as a printf-like
  17     function.</para>
  18
  19     <para>The three (3) basic stream types are: GMimeStreamFile,
  20     GMimeStreamFs and GMimeStreamMem. You can manipulate all three
  21     streams using the GMimeStream interfaces. In addition, some of
  22     these streams have extended interfaces to allow more fine grained
  23     manipulation.</para>
  24
  25     <para>GMimeStreamFile and GMimeStreamFs are very similar in that
  26     they are both meant for reading and writing data to the file
  27     system (in the form of files). Since GMimeStreamFile is an
  28     abstracted layer above the standard libc FILE type, one of the
  29     added benefits is buffered I/O. GMimeStreamFs, on the other hand,
  30     is an abstracted layer above Unix file descriptors. While a
  31     GMimeStreamFs can be used on top of a UNIX socket or pipe, you
  32     must be careful because sockets and pipes are not seekable.</para>
  33
  34     <para>Unlike the previous 2 stream types, GMimeStreamMem does not
  35     interact with the file system at all (except maybe the swap
  36     partition/file indirectly). Memory streams are handy when you want
  37     reads and writes to be nearly instantaneous and/or if you don't
  38     want to create a temporary file on disk.</para>
  39
  40     <para>The four (4) advanced stream types are GMimeStreamMmap,
  41     GMimeStreamNull, GMimeStreamBuffer and GMimeStreamFilter.</para>
  42
  43     <para>Our most simple stream, GMimeStreamNull, is the stream
  44     equivalent of /dev/null on Unix systems. The main difference is
  45     that GMimeStreamNull records the number of bytes written to it -
  46     you may find this useful if you need to know the number of bytes a
  47     GMimeObject (for example) will require.</para>
  48
  49     <para>GMimeStreamMmap is a memory-mapped stream. This isn't
  50     guarenteed to work on all systems since not all systems support
  51     the POSIX mmap system call, but for those that do - this might
  52     present a faster stream than GMimeStreamFs and/or
  53     GMimeStreamFile. You'll have to do some experimentation to know
  54     for sure.</para>
  55
  56     <para>The GMimeStreamBuffer can be used on top of any other type
  57     of stream and has 3 modes: block reads, block writes, and cached
  58     reads. Block reads are especially useful if you will be making a
  59     lot of small reads from a stream that accesses the file
  60     system. Block writes are useful for very much the same reason. The
  61     final mode, cached reads, can become memory intensive but can be
  62     very helpful when inheriting from a stream that does not support
  63     seeking (Note: this mode is the least tested so be careful using
  64     it).</para>
  65
  66     <para>Our final stream type, GMimeStreamFilter, can also be used
  67     on top of another stream. This stream, as you may have guessed,
  68     filters reads and writes to its inherited stream. For example, one
  69     could write a compression filter and apply it to a
  70     GMimeStreamFilter and any further reads or writes would be
  71     (un)compressed.</para>
  72   </refsect1>
  73 </refentry>