KCodecs 5.109.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
KCodecs::Codecabstract

An abstract base class of codecs for common mail transfer encodings. More...

#include <KCodecs>

Public Types

enum  NewlineType { NewlineLF , NewlineCRLF }
 

Public Member Functions

virtual ~Codec ()
 Destroys the codec.
 
virtual bool decode (const char *&scursor, const char *const send, char *&dcursor, const char *const dend, NewlineType newline=NewlineLF) const
 Convenience wrapper that can be used for small chunks of data when you can provide a large enough buffer.
 
virtual QByteArray decode (const QByteArray &src, NewlineType newline=NewlineLF) const
 Even more convenient, but also a bit slower and more memory intensive, since it allocates storage for the worst case and then shrinks the result QByteArray to the actual size again.
 
virtual bool encode (const char *&scursor, const char *const send, char *&dcursor, const char *const dend, NewlineType newline=NewlineLF) const
 Convenience wrapper that can be used for small chunks of data when you can provide a large enough buffer.
 
virtual QByteArray encode (const QByteArray &src, NewlineType newline=NewlineLF) const
 Even more convenient, but also a bit slower and more memory intensive, since it allocates storage for the worst case and then shrinks the result QByteArray to the actual size again.
 
virtual DecodermakeDecoder (NewlineType newline=NewlineLF) const =0
 Creates the decoder for the codec.
 
virtual EncodermakeEncoder (NewlineType newline=NewlineLF) const =0
 Creates the encoder for the codec.
 
virtual int maxDecodedSizeFor (int insize, NewlineType newline=NewlineLF) const =0
 Computes the maximum size, in characters, needed for the deccoding.
 
virtual int maxEncodedSizeFor (int insize, NewlineType newline=NewlineLF) const =0
 Computes the maximum size, in characters, needed for the encoding.
 
virtual const char * name () const =0
 Returns the name of the encoding.
 

Static Public Member Functions

static CodeccodecForName (const char *name)
 Returns a codec associated with the specified name.
 
static CodeccodecForName (const QByteArray &name)
 Returns a codec associated with the specified name.
 

Protected Member Functions

 Codec ()
 Constructs the codec.
 

Detailed Description

An abstract base class of codecs for common mail transfer encodings.

Glossary:
MIME: Multipurpose Internet Mail Extensions or MIME is an Internet Standard that extends the format of e-mail to support text in character sets other than US-ASCII, non-text attachments, multi-part message bodies, and header information in non-ASCII character sets. Virtually all human-written Internet e-mail and a fairly large proportion of automated e-mail is transmitted via SMTP in MIME format. Internet e-mail is so closely associated with the SMTP and MIME standards that it is sometimes called SMTP/MIME e-mail. The content types defined by MIME standards are also of growing importance outside of e-mail, such as in communication protocols like HTTP for the World Wide Web. MIME is also a fundamental component of communication protocols such as HTTP, which requires that data be transmitted in the context of e-mail-like messages, even though the data may not actually be e-mail.
Glossary:
codec: a program capable of performing encoding and decoding on a digital data stream. Codecs encode data for storage or encryption and decode it for viewing or editing.
Glossary:
CRLF: a "Carriage Return (0x0D)" followed by a "Line Feed (0x0A)", two ASCII control characters used to represent a newline on some operating systems, notably DOS and Microsoft Windows.
Glossary:
LF: a "Line Feed (0x0A)" ASCII control character used to represent a newline on some operating systems, notably Unix, Unix-like, and Linux.

Provides an abstract base class of codecs like base64 and quoted-printable. Implemented as a singleton.

Author(s):
Marc Mutz <mutz@.nosp@m.kde..nosp@m.org>
Since
5.5

Constructor & Destructor Documentation

◆ ~Codec()

virtual KCodecs::Codec::~Codec ( )
inlinevirtual

Destroys the codec.

◆ Codec()

KCodecs::Codec::Codec ( )
inlineprotected

Constructs the codec.

Member Function Documentation

◆ codecForName() [1/2]

static Codec * KCodecs::Codec::codecForName ( const char *  name)
static

Returns a codec associated with the specified name.

Parameters
namepoints to a character string containing a valid codec name.

◆ codecForName() [2/2]

static Codec * KCodecs::Codec::codecForName ( const QByteArray &  name)
static

Returns a codec associated with the specified name.

Parameters
nameis a QByteArray containing a valid codec name.

◆ decode() [1/2]

virtual bool KCodecs::Codec::decode ( const char *&  scursor,
const char *const  send,
char *&  dcursor,
const char *const  dend,
NewlineType  newline = NewlineLF 
) const
virtual

Convenience wrapper that can be used for small chunks of data when you can provide a large enough buffer.

The default implementation creates a Decoder and uses it.

Decodes a chunk of bytes starting at scursor and extending to send into the buffer described by dcursor and dend.

This function doesn't support chaining of blocks. The returned block cannot be added to, but you don't need to finalize it, too.

Example usage (in contains the input data):

KCodecs::Codec *codec = KCodecs::Codec::codecForName("base64");
if (!codec) {
    qFatal() << "no base64 codec found!?";
}
QByteArray out(in.size()); // good guess for any encoding...
QByteArray::Iterator iit = in.begin();
QByteArray::Iterator oit = out.begin();
if (!codec->decode(iit, in.end(), oit, out.end())) {
    qDebug() << "output buffer too small";
    return;
}
qDebug() << "Size of decoded data:" << oit - out.begin();
Parameters
scursoris a pointer to the start of the input buffer.
sendis a pointer to the end of the input buffer.
dcursoris a pointer to the start of the output buffer.
dendis a pointer to the end of the output buffer.
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
false if the decoded data didn't fit into the output buffer; true otherwise.

◆ decode() [2/2]

virtual QByteArray KCodecs::Codec::decode ( const QByteArray &  src,
NewlineType  newline = NewlineLF 
) const
virtual

Even more convenient, but also a bit slower and more memory intensive, since it allocates storage for the worst case and then shrinks the result QByteArray to the actual size again.

For use with small src.

Parameters
srcis a QByteArray containing the data to decode.
newlinewhether make new lines using CRLF, or LF (default is LF).

◆ encode() [1/2]

virtual bool KCodecs::Codec::encode ( const char *&  scursor,
const char *const  send,
char *&  dcursor,
const char *const  dend,
NewlineType  newline = NewlineLF 
) const
virtual

Convenience wrapper that can be used for small chunks of data when you can provide a large enough buffer.

The default implementation creates an Encoder and uses it.

Encodes a chunk of bytes starting at scursor and extending to send into the buffer described by dcursor and dend.

This function doesn't support chaining of blocks. The returned block cannot be added to, but you don't need to finalize it, too.

Example usage (in contains the input data):

KCodecs::Codec *codec = KCodecs::Codec::codecForName("base64");
if (!codec) {
    qFatal() << "no base64 codec found!?";
}
QByteArray out(in.size() * 1.4); // crude maximal size of b64 encoding
QByteArray::Iterator iit = in.begin();
QByteArray::Iterator oit = out.begin();
if (!codec->encode(iit, in.end(), oit, out.end())) {
    qDebug() << "output buffer too small";
    return;
}
qDebug() << "Size of encoded data:" << oit - out.begin();
Parameters
scursoris a pointer to the start of the input buffer.
sendis a pointer to the end of the input buffer.
dcursoris a pointer to the start of the output buffer.
dendis a pointer to the end of the output buffer.
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
false if the encoded data didn't fit into the output buffer; true otherwise.

◆ encode() [2/2]

virtual QByteArray KCodecs::Codec::encode ( const QByteArray &  src,
NewlineType  newline = NewlineLF 
) const
virtual

Even more convenient, but also a bit slower and more memory intensive, since it allocates storage for the worst case and then shrinks the result QByteArray to the actual size again.

For use with small src.

Parameters
srcis a QByteArray containing the data to encode.
newlinewhether make new lines using CRLF, or LF (default is LF).

◆ makeDecoder()

virtual Decoder * KCodecs::Codec::makeDecoder ( NewlineType  newline = NewlineLF) const
pure virtual

Creates the decoder for the codec.

Parameters
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
a pointer to an instance of the codec's decoder.

◆ makeEncoder()

virtual Encoder * KCodecs::Codec::makeEncoder ( NewlineType  newline = NewlineLF) const
pure virtual

Creates the encoder for the codec.

Parameters
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
a pointer to an instance of the codec's encoder.

◆ maxDecodedSizeFor()

virtual int KCodecs::Codec::maxDecodedSizeFor ( int  insize,
NewlineType  newline = NewlineLF 
) const
pure virtual

Computes the maximum size, in characters, needed for the deccoding.

Parameters
insizeis the number of input characters to be decoded.
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
the maximum number of characters in the decoding.

◆ maxEncodedSizeFor()

virtual int KCodecs::Codec::maxEncodedSizeFor ( int  insize,
NewlineType  newline = NewlineLF 
) const
pure virtual

Computes the maximum size, in characters, needed for the encoding.

Parameters
insizeis the number of input characters to be encoded.
newlinewhether make new lines using CRLF, or LF (default is LF).
Returns
the maximum number of characters in the encoding.

◆ name()

virtual const char * KCodecs::Codec::name ( ) const
pure virtual

Returns the name of the encoding.

Guaranteed to be lowercase.