summaryrefslogtreecommitdiffstats
path: root/libkmime/kmime_util.h
blob: 4619446a43e0d45989158fe2cb2bbd8a898d3a76 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
/*  -*- c++ -*-
    kmime_util.h

    KMime, the KDE internet mail/usenet news message library.
    Copyright (c) 2001 the KMime authors.
    See file AUTHORS for details

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software Foundation,
    Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, US
*/
#ifndef __KMIME_UTIL_H__
#define __KMIME_UTIL_H__

#include "tqdatetime.h"
#include "tqstring.h"
#include "tqcstring.h"
#include "tqvaluelist.h"
#include "time.h"
#include <tdepimmacros.h>

typedef TQValueList<TQCString> QCStringList;

namespace KMime {

  /** Consult the charset cache. Only used for reducing mem usage by
      keeping strings in a common repository.*/
  extern const char* cachedCharset(const TQCString &name) KDE_EXPORT;

  /** Consult the language cache. Only used for reducing mem usage by
      keeping strings in a common repository.*/
  extern const char* cachedLanguage(const TQCString &name) KDE_EXPORT;

  /** checks whether @p s contains any non-us-ascii characters */
  extern bool isUsAscii(const TQString &s) KDE_EXPORT;

  inline bool isOfSet(const uchar map[16], unsigned char ch) {
    Q_ASSERT( ch < 128 );
    return ( map[ ch/8 ] & 0x80 >> ch%8 );
  }

  extern const uchar specialsMap[16];
  extern const uchar tSpecialsMap[16];
  extern const uchar aTextMap[16];
  extern const uchar tTextMap[16];
  extern const uchar eTextMap[16];

  inline bool isSpecial(char ch) {
    return isOfSet( specialsMap, ch );
  }
  inline bool isTSpecial(char ch) {
    return isOfSet( tSpecialsMap, ch );
  }
  inline bool isAText(char ch) {
    return isOfSet( aTextMap, ch );
  }
  inline bool isTText(char ch) {
    return isOfSet( tTextMap, ch );
  }
  inline bool isEText(char ch) {
    return isOfSet( eTextMap, ch );
  }

  /** Decode string @p src according to RFC2047 (ie. the
      =?charset?[qb]?encoded?= construct).
      @param src       source string.
      @param usedCS    the detected charset is returned here
      @param defaultCS the charset to use in case the detected
                       one isn't known to us.
      @param forceCS   force the use of the default charset.
      @return the decoded string.
  */
  extern TQString decodeRFC2047String(const TQCString &src, const char **usedCS,
				     const TQCString &defaultCS, bool forceCS) KDE_EXPORT;

  /** Decode string @p src according to RFC2047 (ie. the
      =?charset?[qb]?encoded?= construct).
      @param src       source string.
      @return the decoded string.
  */
  extern TQString decodeRFC2047String(const TQCString &src) KDE_EXPORT;

  /** Encode string @p src according to RFC2047 using charset
      @p charset.
      @param src           source string.
      @param charset       charset to use.
      @param addressheader if this flag is true, all special chars
                           like <,>,[,],... will be encoded, too.
      @param allow8BitHeaders if this flag is true, 8Bit headers
                           are allowed.
      @return the encoded string.
  */
  extern TQCString encodeRFC2047String(const TQString &src, const char *charset,
				      bool addressHeader=false, bool allow8bitHeaders=false) KDE_EXPORT;

  /** Uses current time, pid and random numbers to construct a string
      that aims to be unique on a per-host basis (ie. for the local
      part of a message-id or for multipart boundaries.
      @return the unique string.
      @see multiPartBoundary
  */
  extern TQCString uniqueString() KDE_EXPORT;

  /** Constructs a random string (sans leading/trailing "--") that can
      be used as a multipart delimiter (ie. as @p boundary parameter
      to a multipart/... content-type).
      @return the randomized string.
      @see uniqueString
  */
  extern TQCString multiPartBoundary() KDE_EXPORT;

  /** Tries to extract the header with name @p name from the string
      @p src, unfolding it if necessary.
      @param src  the source string.
      @param name the name of the header to search for.
      @return the first instance of the header @p name in @p src
              or a null TQCString if no such header was found.
  */
  extern TQCString extractHeader(const TQCString &src, const char *name) KDE_EXPORT;
  /** Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).

      This function is expensive and should be used only if the mail
      will be stored locally. All decode functions can cope with both
      line endings.
      @param s source string containing CRLF's
      @return the string with CRLF's substitued for LF's
      @see CRLFtoLF(const char*) LFtoCRLF
  */
  extern TQCString CRLFtoLF(const TQCString &s) KDE_EXPORT;
  /** Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).

      This function is expensive and should be used only if the mail
      will be stored locally. All decode functions can cope with both
      line endings.
      @param s source string containing CRLF's
      @return the string with CRLF's substitued for LF's
      @see CRLFtoLF(const TQCString&) LFtoCRLF
  */
  extern TQCString CRLFtoLF(const char *s) KDE_EXPORT;
  /** Converts all occurrences of "\n" (LF) in @p s to "\r\n" (CRLF).

      This function is expensive and should be used only if the mail
      will be transmitted as an RFC822 message later. All decode
      functions can cope with and all encode functions can optionally
      produce both line endings, which is much faster.

      @param s source string containing CRLF's
      @return the string with CRLF's substitued for LF's
      @see CRLFtoLF(const TQCString&) LFtoCRLF
  */
  extern TQCString LFtoCRLF(const TQCString &s) KDE_EXPORT;

  /** Removes quote (DQUOTE) characters and decodes "quoted-pairs"
      (ie. backslash-escaped characters)
      @param str the string to work on.
      @see addQuotes
  */
  KDE_EXPORT extern void removeQuots(TQCString &str);
  /** Removes quote (DQUOTE) characters and decodes "quoted-pairs"
      (ie. backslash-escaped characters)
      @param str the string to work on.
      @see addQuotes
  */
  KDE_EXPORT extern void removeQuots(TQString &str);
  /** Converts the given string into a quoted-string if
      the string contains any special characters
      (ie. one of ()<>@,.;:[]=\").
      @param str us-ascii string to work on.
      @param forceQuotes if @p true, always add quote characters.
  */
  KDE_EXPORT extern void addQuotes(TQCString &str, bool forceQuotes);


  /**
   * @short class abstracting date formatting
   *
   * DateFormatter deals with different kinds of date
   * display formats. The formats supported by the class include:
   * <ul>
   *     <li> fancy "Today 02:08:35"
   *     <li> ctime "Sun Mar 31 02:08:35 2002"
   *     <li> localized "2002-03-31 02:08"
   *     <li> iso  "2002-03-31 02:08:35"
   *     <li> rfc2822 "Sun, 31 Mar 2002 02:08:35 -0500"
   *     <li> custom "whatever you like"
   * </ul>
   *
   *
   */
  class KDE_EXPORT DateFormatter {
  public:
    enum FormatType {
      CTime,      //< ctime "Sun Mar 31 02:08:35 2002"
      Localized,  //< localized "2002-03-31 02:08"
      Fancy,      //< fancy "Today 02:08:35"
      Iso,        //< iso  "2002-03-31 02:08:35"
      Custom      //< custom "whatever you like"
    };

    /**
     * constructor
     * @param fType default format used by the class
     */
    DateFormatter(FormatType fType = DateFormatter::Fancy);

    ~DateFormatter();

    /**
     * returns the currently set format
     */
    FormatType getFormat() const;
    /**
     * sets the currently used format
     */
    void setFormat(FormatType t);

    /**
     * returns formatted date string in a currently
     * set format.
     * @param otime time to format
     * @param lang used  <em>only</em> by the Localized format, sets the used language
     * @param shortFormat used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     * @param includeSecs used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     */
    TQString dateString(time_t otime, const TQString& lang = TQString(),
		       bool shortFormat = true, bool includeSecs=false) const;
    /**
     * overloaded, does exactly what #dateString does (it's slower)
     */
    TQString dateString(const TQDateTime& dtime, const TQString& lang = TQString(),
		       bool shortFormat = true, bool includeSecs=false) const;


    /**
     * makes the class use the custom format for
     * date to string conversions.
     * Method accepts the same arguments
     * as TQDateTime::toString method and adds
     * "Z" expression which is substituted with the
     * RFC-822 style numeric timezone (-0500)
     * @param format the custom format
     */
    void    setCustomFormat(const TQString& format);
    TQString getCustomFormat() const;

    /**
     * returns rfc2822 formatted string
     * @param otime time to use for formatting
     */
    TQCString rfc2822(time_t otime) const;
    /**
     * resets the internal clock
     */
    void reset();

    //statics
    /** convenience function dateString
     * @param t specifies the FormatType to use
     * @param time time to format
     * @param data is either the format when FormatType is Custom, or language
     * when FormatType is Localized
     * @param shortFormat used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     * @param includeSecs used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     */
    static TQString  formatDate( DateFormatter::FormatType t, time_t time,
				const TQString& data = TQString(),
				bool shortFormat = true, bool includeSecs=false);

    /** convenience function, same as #formatDate
     * but returns the current time formatted
     * @param t specifies the FormatType to use
     * @param data is either the format when FormatType is Custom, or language
     * when FormatType is Localized
     * @param shortFormat used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     * @param includeSecs used <em>only</em> by the Localized format, is passed to TDELocale::formatDateTime
     */
    static TQString  formatCurrentDate( DateFormatter::FormatType t,
				       const TQString& data = TQString(),
				       bool shortFormat = true, bool includeSecs=false);

    /** convenience function, same as #rfc2822 */
    static TQCString rfc2822FormatDate( time_t time );
    static bool     isDaylight();
  protected:
    /**
     * returns fancy formatted date string
     * @param otime time to format
     * @internal
     */
    TQString fancy(time_t otime) const ;
    /**
     * returns localized formatted date string
     * @param otime time to format
     * @param shortFormat
     * @param includeSecs
     * @param localeLanguage language used for formatting
     * @internal
     */
    TQString localized(time_t otime, bool shortFormat = true, bool includeSecs = false,
		      const TQString& localeLanguage=TQString() ) const;
    /**
     * returns string as formatted with ctime function
     * @internal
     */
    TQString cTime(time_t otime) const;
    /**
     * returns a string in the "%Y-%m-%d %H:%M:%S" format
     * @internal
     */
    TQString isoDate(time_t otime) const;

    /**
     * returns date formatted with the earlier
     * given custom format
     * @param t time used for formatting
     * @internal
     */
    TQString custom(time_t t) const;
    /**
     * returns a string identifying the timezone (eg."-0500")
     * @internal
     */
    TQCString zone(time_t otime) const;

    time_t qdateToTimeT(const TQDateTime& dt) const;
  private:
    FormatType 		mFormat;
    mutable time_t 	mCurrentTime;
    mutable TQDateTime 	mDate;
    TQString 		mCustomFormat;
    static int          mDaylight;
  };

} // namespace KMime

#endif /* __KMIME_UTIL_H__ */