• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • Sitemap
  • Contact Us
 

KMIME Library

KMime::Decoder

KMime::Decoder Class Reference

Stateful CTE decoder class. More...

#include <kmime_codecs.h>

Inherited by KMime::Base64Decoder, KMime::IdentityEnDecoder, KMime::QuotedPrintableDecoder, and KMime::UUDecoder.

List of all members.

Public Member Functions

virtual bool decode (const char *&scursor, const char *const send, char *&dcursor, const char *const dend)=0
virtual bool finish (char *&dcursor, const char *const dend)=0
virtual ~Decoder ()

Protected Member Functions

 Decoder (bool withCRLF=false)

Detailed Description

Stateful CTE decoder class.

Stateful decoder class, modelled after QTextDecoder.

Overview

KMime decoders are designed to be able to process encoded data in chunks of arbitrary size and to work with output buffers of also arbitrary size. They maintain any state necessary to go on where the previous call left off.

The class consists of only two methods of interest: see decode, which decodes an input block and finalize, which flushes any remaining data to the output stream.

Typically, you will create a decoder instance, call decode as often as necessary, then call finalize (most often a single call suffices, but it might be that during that call the output buffer is filled, so you should be prepared to call finalize as often as necessary, ie. until it returns true).

Values

Both methods return true to indicate that they've finished their job. For decode, a return value of true means that the current input block has been finished (false most often means that the output buffer is full, but that isn't required behavior. The decode call is free to return at arbitrary times during processing).

For finalize, a return value of true means that all data implicitly or explicitly stored in the decoder instance has been flushed to the output buffer. A false return value should be interpreted as "check if the output buffer is full and call me again", just as with decode.

Pattern

Since the decoder maintains state, you can only use it once. After a sequence of input blocks has been processed, you finalize the output and then delete the decoder instance. If you want to process another input block sequence, you create a new instance.

Typical usage (in contains the (base64-encoded) input data), taking into account all the conventions detailed above:

  KMime::Codec *codec = KMime::Codec::codecForName( "base64" );
  kFatal( !codec ) << "No codec found for base64!";
  KMime::Decoder *dec = codec->makeDecoder();
  assert( dec ); // should not happen
  QByteArray out( 256 ); // small buffer is enough ;-)
  QByteArray::Iterator iit = in.begin();
  QByteArray::Iterator oit = out.begin();
decode the chunk
  while ( !dec->decode( iit, in.end(), oit, out.end() ) )
    if ( oit == out.end() ) { // output buffer full, process contents
      do_something_with( out );
      oit = out.begin();
    }
repeat while loop for each input block
...
finish (flush remaining data from decoder):
  while ( !dec->finish( oit, out.end() ) )
    if ( oit == out.end() ) { // output buffer full, process contents
      do_something_with( out );
      oit = out.begin();
    }
now process last chunk:
  out.resize( oit - out.begin() );
  do_something_with( out );
_delete_ the decoder, but not the codec:
  delete dec;
  

Definition at line 341 of file kmime_codecs.h.


Constructor & Destructor Documentation

KMime::Decoder::Decoder ( bool  withCRLF = false  )  [inline, protected]

Protected constructor.

Use KMime::Codec::makeDecoder to create an instance.

Parameters:
withCRLF if true, make the newlines CRLF; else use LF.

Definition at line 351 of file kmime_codecs.h.

virtual KMime::Decoder::~Decoder (  )  [inline, virtual]

Destroys the decoder.

Definition at line 358 of file kmime_codecs.h.


Member Function Documentation

virtual bool KMime::Decoder::decode ( const char *&  scursor,
const char *const   send,
char *&  dcursor,
const char *const   dend 
) [pure virtual]

Decodes a chunk of data, maintaining state information between calls.

See class decumentation for calling conventions.

Parameters:
scursor is a pointer to the start of the input buffer.
send is a pointer to the end of the input buffer.
dcursor is a pointer to the start of the output buffer.
dend is a pointer to the end of the output buffer.
virtual bool KMime::Decoder::finish ( char *&  dcursor,
const char *const   dend 
) [pure virtual]

Call this method to finalize the output stream.

Writes all remaining data and resets the decoder. See KMime::Codec for calling conventions.

Parameters:
dcursor is a pointer to the start of the output buffer.
dend is a pointer to the end of the output buffer.

The documentation for this class was generated from the following file:
  • kmime_codecs.h

KMIME Library

Skip menu "KMIME Library"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  • kabc
  • kblog
  • kcal
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  • kldap
  • kmime
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal