// -*- C++ -*-
//
// ufcodec.h
// 
// API for Codecs of UniFEP
// 

#ifndef __UFCODEC_H
#define __UFCODEC_H

#include <e32std.h>
#include <e32base.h>
#include <badesca.h>

class RFs;


typedef TText16 TUniChar;

const TUid KUniEncoderUid={ 0x10000e25 };

const TUid KEncodingUidUtf8 = { 0x10001852 };
const TUid KEncodingUidShiftJIS = { 0x10000e26 };
const TUid KEncodingUidJIS = { 0x10000e28 };
const TUid KEncodingUidUcs2 = { 0x10000e27 };
const TUid KEncodingUidEucJp = { 0x10000e29 };
const TUid KEncodingUidMacRoman = { 0x10001851 };
const TUid KEncodingUidCP1252 = { 0x10001850 };
const TUid KEncodingUidLatin1 = { 0x10001853 };
const TUid KEncodingUidBig5 = { 0x1000185c };
const TUid KEncodingUidGb = { 0x10001860 };
const TUid KEncodingUidEucKr = { 0x1000185d };
const TUid KEncodingUidJohab = { 0x1000186a };
const TUid KEncodingUidCp949 = { 0x1000186b };
const TUid KEncodingUidIsoKr = { 0x1000186c };

const TUid KEncodingUidEmailSend = { 0x10000d3d };
const TUid KEncodingUidEmailRecv = { 0x10000d3e };
const TUid KEncodingUidVCard     = { 0x10000d3f };

// this API is available in UniFEP V1 and V2

class CUniEncoder: public CBase {
public:
  virtual TUniChar DecodeWChar(TText16 aChar) = 0;
  // takes a character in this encoding and returns the corresponding
  // Unicode point.  Returns U+FFFD if aChar is an illegal or unassigned
  // code point.
  virtual TText16 EncodeWChar(TUniChar aChar) = 0;
  // returns the character corresponding to Unicode aChar in this
  // encoding.  Returns zero if aChar cannot be expressed in this
  // encoding. (Yes, this is ambiguous, as 0 is a legal character
  // in Unicode and most encodings.  A historical accident.)
  virtual HBufC8 *EncodeTextL(const TDesC8 &aText, TBool aSkipUnknown) = 0;
  // converts aText in UniFEPs internal encoding into this encoding.
  // Not representable Unicode characters are expressed with a
  // Java-style escape \uXXXX, unless aSkipUnknown is true, in which 
  // case they are simply ignored.
  virtual HBufC8 *DecodeTextL(const TDesC8 &aText) = 0;
  // converts text from this encoding into UniFEPs internal encoding
};

// --------------------------------------------------------------------

// the following API is only available in UniFEP V3

class MUniCodecUnicodeSource {
public:
  virtual TInt GetL() = 0;
  // get one unicode character from stream
  // if < 0, chunk has ended, otherwise in 0..0xffff
};

// All sink methods return a TBool. If ETrue is returned,
// the current conversion will return after a "unit" (a smallest
// indivisible series of characters or bytes) has been written
// E.g. MUniCodecNativeSink::PutL cannot stop conversion in the middle 
// of a multi-byte sequence representing a single character
// (of course it could just leave)

class MUniCodecNativeSink {
public:
  virtual TBool PutL(TInt byte) = 0;
  // write one byte on stream.
  virtual TBool LossyL(TUniChar wc) = 0;
  // This wc cannot be encoded to this native encoding.  To do
  // anything useful in this function, it has to know something about
  // the encoding.  E.g. in all encodings suppored by UniFEP codecs it
  // is fine to write 7-bit ASCII to the output stream (except in
  // UCS2, where this function is never called.)
};

// --------------------------------------------------------------------

class MUniCodecNativeSource {
public:
  virtual TInt GetL(TBool first) = 0;
  // Get one byte from stream. The argument 'first' will be ETrue when
  // the codec is expecting the first byte of a new character.
  // If < 0, chunk has ended, otherwise in 0..0xff.
};

class MUniCodecUnicodeSink {
public:
  virtual TBool PutL(TUniChar wc) = 0;
  // write one Unicode character on stream.
  virtual TBool IllegalL(TUint32 bytes) = 0;
  // an illegal input sequence has been found
};

// --------------------------------------------------------------------

class CUniCodec: public CUniEncoder {
public:
  virtual TUid Uid() const = 0;
  // to be on the safe side, you can check the UID of an encoding
  virtual TInt ApiLevel() const = 0;
  // returns the number of methods implemented by the codec.
  // Currently always 17.  Would be 4 for the CUniEncoder API. 
  // Future extensions may have more methods.
  virtual TTime Version() const = 0;  
  // returns the time this encoder was last modified
  // --------------------------------------------------------------------
  virtual TInt MaximumSizeInBytes() const = 0;
  // when encoding, the maximum number of bytes that could be generated
  // after reading one Unicode character.
  virtual TInt MaximumSizeOfUnicodeRepresentation() const = 0;
  // when decoding, the maximum number of Unicode characters that 
  // could be generated after reading one character in this encoding. 
  // --------------------------------------------------------------------

  virtual void EncodingContextReset() = 0;
  // resets the encoding context

  virtual TBool EncodingContextNonTrivial() const = 0;
  // returns ETrue if the encoding context is not equal to the 
  // default context (i.e. always returns EFalse after EncodingContextReset) 
  // If this is EFalse, flushing is a no op.
  
  virtual TInt EncodingContextData() const = 0;
  // returns the number of Unicode chars stored in the encoding context.
  // Even if this is zero, flushing is a not necessarily a no op
  // (e.g. ISO-2022-KR and ISO-2022-JP reset the stream to ASCII mode
  // on flush)

  virtual void DecodingContextReset() = 0;
  // resets the decoding context

  virtual TBool DecodingContextNonTrivial() const = 0;
  // returns ETrue if the decoding context is not equal to the 
  // default context (i.e. always returns EFalse after DecodingContextReset) 
  // If this is EFalse, flushing is a no op.
  
  virtual TInt DecodingContextData() const = 0;
  // returns the number of bytes stored in the decoding context.
  // These may be partially read characters, but also complete characters
  // for which no output can be produced yet.
  
  // EncodeL and DecodeL
  // convert a source stream, writing result to sink stream.
  // Leaves only if source or sink method leave.
  // The conversion is depending on the context, and the context will
  // be updated by the conversion.
  // A source of NULL means end of stream, flush context.
  // The context HAS to be reset after a flush.

  virtual void EncodeL(MUniCodecUnicodeSource *source,
		       MUniCodecNativeSink &sink) = 0;

  virtual TInt DecodeL(MUniCodecNativeSource *source,
                       MUniCodecUnicodeSink &sink) = 0;
  // returns the number of bytes at the end of the chunk that did not
  // form a complete character. Zero indicates that conversion stopped
  // between two characters in the source encoding. However, data
  // might still be saved in the context before it can be written out.
  // If non-zero, a subsequent flush will call
  // MUniCodecUnicodeSink::IllegalL.
};

// --------------------------------------------------------------------

class CUniCodecList;

class TUniCodecInfo {
public:
  inline const TDesC &Name() const;
  inline TUid Uid() const;
  inline const CDesCArray *MimeNames() const;
  inline const TPtrC PreferredMimeName() const;
  inline TBool SevenBits() const;
  inline CUniCodec *CodecL();
private:
  RLibrary iDll;
  TFileName iDllName;
  TInt iEntryPoint;
  CUniCodec *iCodec;
  TUid iUid;
  TBool iSevenBits;
  CDesCArray *iMimeNames;
  HBufC *iName;
  CUniCodecList *iList;
  friend class CUniCodecListImp;
};

class CUniCodecList : public CBase, public MDesCArray {
public:
  virtual void ConstructL(RFs &aFs) = 0;
  virtual TInt ApiLevel() const = 0;
  // Currently always 1. 

  // Find Encodings supported
  virtual TInt NumCodecs() const = 0;
  virtual TUniCodecInfo &CodecInfo(TInt aIndex) const = 0;

  // Find returns KErrNotFound, Index returns 0 (UTF-8) if not found
  virtual TInt Find(TUid aUid) const = 0;
  inline TInt Index(TUid aUid) const;

  // returns 0 if not found
  virtual TUniCodecInfo *FindMimeName(const TDesC &aName) = 0;
  // returns 0 if not found
  inline TUniCodecInfo *CodecInfo(TUid aUid);
  // falls back on UTF-8 if not found
  inline TUniCodecInfo *CodecInfoFallback(TUid aUid);

  virtual void Release(TUniCodecInfo &aInfo) = 0;
  virtual CUniCodec *CodecL(TUniCodecInfo &aInfo) = 0;
};

// --------------------------------------------------------------------

inline const TDesC &TUniCodecInfo::Name() const
{
  return *iName;
}

inline TUid TUniCodecInfo::Uid() const
{
  return iUid;
}

inline const CDesCArray *TUniCodecInfo::MimeNames() const
{
  return iMimeNames;
}

inline const TPtrC TUniCodecInfo::PreferredMimeName() const
{
  return (*iMimeNames)[0];
}

inline TBool TUniCodecInfo::SevenBits() const
{
  return iSevenBits;
}

inline CUniCodec *TUniCodecInfo::CodecL() 
{
  return iList->CodecL(*this);
}

// --------------------------------------------------------------------

inline TInt CUniCodecList::Index(TUid aUid) const
{
  TInt idx = Find(aUid);
  return (idx >= 0 ? idx : 0);
}

inline TUniCodecInfo *CUniCodecList::CodecInfo(TUid aUid)
{
  TInt idx = Find(aUid);
  return (idx >= 0 ? &CodecInfo(idx) : 0);
}

inline TUniCodecInfo *CUniCodecList::CodecInfoFallback(TUid aUid)
{
  return &CodecInfo(Index(aUid));
}

#endif __UFCODEC_H