![]() | ![]() | ![]() | GMime Reference Manual | ![]() |
---|
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.
<<< GMime Fundamentals | GMime Stream Filters >>> |