Warning, file /pim/kmime/src/kmime_util.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*  -*- c++ -*-
0002     kmime_util.h
0003 
0004     KMime, the KDE Internet mail/usenet news message library.
0005     SPDX-FileCopyrightText: 2001 the KMime authors.
0006     See file AUTHORS for details
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 #pragma once
0011 
0012 #include "kmime_export.h"
0013 #include "kmime_headers.h"
0014 #include "kmime_content.h"
0015 
0016 #include <QString>
0017 #include <QVector>
0018 
0019 namespace KMime
0020 {
0021 
0022 class Message;
0023 
0024 /**
0025   Checks whether @p s contains any non-us-ascii characters.
0026   @param s
0027 */
0028 KMIME_EXPORT extern bool isUsAscii(const QString &s);
0029 
0030 /**
0031   Returns a user-visible string for a contentEncoding, for example
0032   "quoted-printable" for CEquPr.
0033   @param enc the contentEncoding to return string for
0034   @ since 4.4
0035   TODO should they be i18n'ed?
0036 */
0037 KMIME_EXPORT extern QString nameForEncoding(KMime::Headers::contentEncoding enc);
0038 
0039 /**
0040   Returns a list of encodings that can correctly encode the @p data.
0041   @param data the data to check encodings for
0042   @ since 4.4
0043 */
0044 Q_REQUIRED_RESULT KMIME_EXPORT QVector<KMime::Headers::contentEncoding> encodingsForData(const QByteArray &data);
0045 
0046 /**
0047   * Set whether or not to use outlook compatible attachment filename encoding. Outlook
0048   *  fails to properly adhere to the RFC2322 standard for parametrized header fields, and
0049   *  instead is only able to read and write attachment filenames encoded in RFC2047-style.
0050   *  This will create mails that are not standards-compliant!
0051   *
0052   * @param violateStandard      Whether or not to use outlook-compatible attachment
0053   *                              filename encodings.
0054   *
0055   * @since 4.5
0056   */
0057 KMIME_EXPORT extern void setUseOutlookAttachmentEncoding(bool violateStandard);
0058 
0059 /**
0060  * Retrieve whether or not to use outlook compatible encodings for attachments.
0061  */
0062 KMIME_EXPORT extern bool useOutlookAttachmentEncoding();
0063 
0064 /**
0065   Constructs a random string (sans leading/trailing "--") that can
0066   be used as a multipart delimiter (ie. as @p boundary parameter
0067   to a multipart/... content-type).
0068 
0069   @return the randomized string.
0070   @see uniqueString
0071 */
0072 KMIME_EXPORT extern QByteArray multiPartBoundary();
0073 
0074 /**
0075   Unfolds the given header if necessary.
0076   @param header The header to unfold.
0077 */
0078 
0079 KMIME_EXPORT extern QByteArray unfoldHeader(const QByteArray &header);
0080 KMIME_EXPORT extern QByteArray unfoldHeader(const char *header, size_t headerSize);
0081 
0082 /**
0083   Folds the given header if necessary.
0084   @param header The header to fold.
0085 */
0086 KMIME_EXPORT extern QByteArray foldHeader(const QByteArray &header);
0087 
0088 /**
0089   Tries to extract the header with name @p name from the string
0090   @p src, unfolding it if necessary.
0091 
0092   @param src  the source string.
0093   @param name the name of the header to search for.
0094 
0095   @return the first instance of the header @p name in @p src
0096           or a null QByteArray if no such header was found.
0097 */
0098 KMIME_EXPORT extern QByteArray extractHeader(const QByteArray &src,
0099         const QByteArray &name);
0100 
0101 /**
0102   Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).
0103 
0104   This function is expensive and should be used only if the mail
0105   will be stored locally. All decode functions can cope with both
0106   line endings.
0107 
0108   @param s source string containing CRLF's
0109 
0110   @return the string with CRLF's substituted for LF's
0111   @see CRLFtoLF(const char*) LFtoCRLF
0112 */
0113 KMIME_EXPORT extern QByteArray CRLFtoLF(const QByteArray &s);
0114 
0115 /**
0116   Converts all occurrences of "\r\n" (CRLF) in @p s to "\n" (LF).
0117 
0118   This function is expensive and should be used only if the mail
0119   will be stored locally. All decode functions can cope with both
0120   line endings.
0121 
0122   @param s source string containing CRLF's
0123 
0124   @return the string with CRLF's substituted for LF's
0125   @see CRLFtoLF(const QByteArray&) LFtoCRLF
0126 */
0127 KMIME_EXPORT extern QByteArray CRLFtoLF(const char *s);
0128 
0129 /**
0130   Converts all occurrences of "\n" (LF) in @p s to "\r\n" (CRLF).
0131 
0132   This function is expensive and should be used only if the mail
0133   will be transmitted as an RFC822 message later. All decode
0134   functions can cope with and all encode functions can optionally
0135   produce both line endings, which is much faster.
0136 
0137   @param s source string containing CRLF's
0138 
0139   @return the string with CRLF's substituted for LF's
0140   @see CRLFtoLF(const QByteArray&) LFtoCRLF
0141 */
0142 KMIME_EXPORT extern QByteArray LFtoCRLF(const QByteArray &s);
0143 
0144 /**
0145   Converts all occurrences of "\r" (CR) in @p s to "\n" (LF).
0146 
0147   This function is expensive and should be used only if the mail
0148   will be stored locally. All decode functions can cope with both
0149   line endings.
0150 
0151   @param s source string containing CR's
0152 
0153   @return the string with CR's substituted for LF's
0154   @see CRtoLF(const QByteArray&) CRtoLF
0155 */
0156 KMIME_EXPORT extern QByteArray CRtoLF(const char *s);
0157 
0158 /**
0159   Converts all occurrences of "\r" (CR) in @p s to "\n" (LF).
0160 
0161   This function is expensive and should be used only if the mail
0162   will be transmitted as an RFC822 message later. All decode
0163   functions can cope with and all encode functions can optionally
0164   produce both line endings, which is much faster.
0165 
0166   @param s source string containing CR's
0167 
0168   @return the string with CR's substituted for LF's
0169   @see CRtoLF(const QByteArray&) CRtoLF
0170 */
0171 KMIME_EXPORT extern QByteArray CRtoLF(const QByteArray &s);
0172 
0173 
0174 /**
0175   Removes quote (DQUOTE) characters and decodes "quoted-pairs"
0176   (ie. backslash-escaped characters)
0177 
0178   @param str the string to work on.
0179   @see addQuotes
0180 */
0181 KMIME_EXPORT extern void removeQuotes(QByteArray &str);
0182 
0183 /**
0184   Removes quote (DQUOTE) characters and decodes "quoted-pairs"
0185   (ie. backslash-escaped characters)
0186 
0187   @param str the string to work on.
0188   @see addQuotes
0189 */
0190 KMIME_EXPORT extern void removeQuotes(QString &str);
0191 
0192 /**
0193   Converts the given string into a quoted-string if the string contains
0194   any special characters (ie. one of ()<>@,.;:[]=\").
0195 
0196   @param str us-ascii string to work on.
0197   @param forceQuotes if @c true, always add quote characters.
0198 */
0199 KMIME_EXPORT extern void addQuotes(QByteArray &str, bool forceQuotes);
0200 
0201 /**
0202  * Overloaded method, behaves same as the above.
0203  * @param str us-ascii string to work on.
0204  * @param forceQuotes if @c true, always add quote characters.
0205  * @since 4.5
0206  */
0207 KMIME_EXPORT extern void addQuotes(QString &str, bool forceQuotes);
0208 
0209 /**
0210  * Makes sure that the bidirectional state at the end of the string is the
0211  * same as at the beginning of the string.
0212  *
0213  * This is useful so that Unicode control characters that can change the text
0214  * direction can not spill over to following strings.
0215  *
0216  * As an example, consider a mailbox in the form "display name" <local@domain.com>.
0217  * If the display name here contains unbalanced control characters that change the
0218  * text direction, it would also have an effect on the addrspec, which could lead to
0219  * spoofing.
0220  *
0221  * By passing the display name to this function, one can make sure that no change of
0222  * the bidi state can spill over to the next strings, in this case the addrspec.
0223  *
0224  * Example: The string "Hello <RLO>World" is unbalanced, as it contains a right-to-left
0225  *          override character, which is never followed by a <PDF>, the "pop directional
0226  *          formatting" character. This function adds the missing <PDF> at the end, and
0227  *          the output of this function would be "Hello <RLO>World<PDF>".
0228  *
0229  * Example of spoofing:
0230  *   Consider "Firstname Lastname<RLO>" <moc.mitciv@attacker.com>. Because of the RLO,
0231  *   it is displayed as "Firstname Lastname <moc.rekcatta@victim.com>", which spoofs the
0232  *   domain name.
0233  *   By passing "Firstname Lastname<RLO>" to this function, one can balance the <RLO>,
0234  *   leading to "Firstname Lastname<RLO><PDF>", so the whole mailbox is displayed
0235  *   correctly as "Firstname Lastname" <moc.mitciv@attacker.com> again.
0236  *
0237  * See https://unicode.org/reports/tr9 for more information on bidi control chars.
0238  *
0239  * @param input the display name of a mailbox, which is checked for unbalanced Unicode
0240  *              direction control characters
0241  * @return the display name which now contains a balanced state of direction control
0242  *         characters
0243  *
0244  * Note that this function does not do any parsing related to mailboxes, it only works
0245  * on plain strings. Therefore, passing the complete mailbox will not lead to any results,
0246  * only the display name should be passed.
0247  *
0248  * @since 4.5
0249  */
0250 KMIME_EXPORT QString balanceBidiState(const QString &input);
0251 
0252 /**
0253  * Similar to the above function. Instead of trying to balance the Bidi chars, it outright
0254  * removes them from the string.
0255  *
0256  * @param input the display name of a mailbox, which is checked for unbalanced Unicode
0257  * direction control characters
0258  * Reason: KHTML seems to ignore the PDF character, so adding them doesn't fix things :(
0259  */
0260 KMIME_EXPORT QString removeBidiControlChars(const QString &input);
0261 
0262 /**
0263  * Returns whether or not the given MIME node is an attachment part.
0264  * @param content the MIME node to parse
0265  * @see hasAttachment()
0266  */
0267 KMIME_EXPORT bool isAttachment(Content *content);
0268 
0269 /**
0270  * Returns whether or not the given MIME node contains an attachment part. This function will
0271  *  recursively parse the MIME tree looking for a suitable attachment and return true if one is found.
0272  * @param content the MIME node to parse
0273  * @see isAttachment()
0274  */
0275 KMIME_EXPORT bool hasAttachment(Content *content);
0276 
0277 /**
0278  * Returns whether or not the given MIME node contains an invitation part. This function will
0279  *  recursively parse the MIME tree looking for a suitable invitation and return true if one is found.
0280  * @param content the MIME node to parse
0281  * @since 4.14.6
0282  */
0283 KMIME_EXPORT bool hasInvitation(Content *content);
0284 
0285 /**
0286  * Returns whether or not the given @p message is partly or fully signed.
0287  *
0288  * @param message the message to check for being signed
0289  * @since 4.6
0290  */
0291 KMIME_EXPORT bool isSigned(Message *message);
0292 
0293 /**
0294  * Returns whether or not the given @p message is partly or fully encrypted.
0295  *
0296  * @param message the message to check for being encrypted
0297  * @since 4.6
0298  */
0299 KMIME_EXPORT bool isEncrypted(Message *message);
0300 
0301 /**
0302  * Determines if the MIME part @p content is a crypto part.
0303  * This is, is either an encrypted part or a signature part.
0304  */
0305 KMIME_EXPORT bool isCryptoPart(Content *content);
0306 
0307 /**
0308  * Returns whether or not the given MIME @p content is an invitation
0309  * message of the iTIP protocol.
0310  *
0311  * @since 4.6
0312  */
0313 KMIME_EXPORT bool isInvitation(Content *content);
0314 
0315 } // namespace KMime
0316