File indexing completed on 2022-10-04 16:37:47

0001 /*  -*- c++ -*-
0002     kmime_mdn.h
0003 
0004     KMime, the KDE Internet mail/usenet news message library.
0005     SPDX-FileCopyrightText: 2002 Marc Mutz <mutz@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-or-later
0008 */
0009 /**
0010   @file
0011   This file is part of the API for handling @ref MIME data and
0012   provides functions for supporting Message Disposition Notifications (MDNs),
0013   also known as email return receipts.
0014 
0015   @brief
0016   Provides support for Message Disposition Notifications.
0017 
0018   @authors Marc Mutz \<mutz@kde.org\>
0019 
0020   @glossary @anchor MDN @b MDN:
0021   see @ref Message_Disposition_Notification
0022 
0023   @glossary @anchor Message_Disposition_Notification
0024   @b Message @b Disposition @b Notification:
0025   Return receipts for email are called message disposition notifications.
0026   Their format and usage is outlined in @ref RFC2298.
0027 
0028   @glossary @anchor RFC2298 @anchor rfc2298 @b RFC @b 2298:
0029   RFC that defines the <a href="https://tools.ietf.org/html/rfc2298">
0030   An Extensible Message Format for Message Disposition Notifications</a>.
0031 */
0032 
0033 #pragma once
0034 
0035 #include "kmime_export.h"
0036 #include <QString>
0037 #include <QVector>
0038 
0039 class QByteArray;
0040 
0041 namespace KMime
0042 {
0043 
0044 namespace MDN
0045 {
0046 
0047 /**
0048   The following disposition-types are defined:
0049 
0050   @li Displayed    The message has been displayed by the UA to someone
0051   reading the recipient's mailbox.  There is no guarantee that the
0052   content has been read or understood.
0053 
0054   @li Dispatched   The message has been sent somewhere in some manner
0055   (e.g., printed, faxed, forwarded) without necessarily having been previously
0056   displayed to the user.  The user may or may not see the message later.
0057 
0058   @li Processed    The message has been processed in some manner (i.e., by
0059   some sort of rules or server) without being displayed to the user.  The user
0060   may or may not see the message later, or there may not even be a human user
0061   associated with the mailbox.
0062 
0063   @li Deleted      The message has been deleted.  The recipient may or may not
0064   have seen the message.  The recipient might "undelete" the message at a
0065   later time and read the message.
0066 
0067   @li Denied       The recipient does not wish the sender to be informed of the
0068   message's disposition.  A UA may also silently ignore message disposition
0069   requests in this situation.
0070 
0071   @li Failed       A failure occurred that prevented the proper generation
0072   of an MDN.  More information about the cause of the failure may be contained
0073   in a Failure field.  The "failed" disposition type is not to be used for
0074   the situation in which there is is some problem in processing the message
0075   other than interpreting the request for an MDN.  The "processed" or other
0076   disposition type with appropriate disposition modifiers is to be used in
0077   such situations.
0078 
0079   IOW:
0080   @p Displayed when - well -displayed
0081   @p Dispatched when forwarding unseen ( == new )
0082   @p Processed (maybe) when piping unseen, but probably never used
0083   @p Deleted when deleting unseen
0084   @p Denied on user command
0085   @p Failed on Disposition-Notification-Options containing
0086   unknown required options. ( == @em any required options )
0087   @p Failed needs a description in the @p special parameter.
0088 */
0089 enum DispositionType {
0090     Displayed, Read = Displayed,
0091     Deleted,
0092     Dispatched, Forwarded = Dispatched,
0093     Processed,
0094     Denied,
0095     Failed
0096 };
0097 
0098 /**
0099   The following disposition modifiers are defined:
0100 
0101   @li Error               An error of some sort occurred that prevented
0102   successful processing of the message.  Further information is contained
0103   in an Error field.
0104 
0105   @li Warning             The message was successfully processed but some
0106   sort of exceptional condition occurred.  Further information is contained
0107   in a Warning field.
0108 
0109   @li Superseded          The message has been automatically rendered obsolete
0110   by another message received.  The recipient may still access and read the
0111   message later.
0112 
0113   @li Expired             The message has reached its expiration date and has
0114   been automatically removed from the recipient's mailbox.
0115 
0116   @li MailboxTerminated   The recipient's mailbox has been terminated and all
0117   message in it automatically removed.
0118 */
0119 enum DispositionModifier {
0120     Error,
0121     Warning,
0122     Superseded,
0123     Expired,
0124     MailboxTerminated
0125 };
0126 
0127 /**
0128   The following disposition modes are defined:
0129 
0130   @li ManualAction    The disposition described by the disposition type
0131   was a result of an explicit instruction by the user rather than some sort of
0132   automatically performed action.
0133 
0134   @li AutomaticAction The disposition described by the disposition type was
0135   a result of an automatic action, rather than an explicit instruction by the
0136   user for this message.
0137 
0138   IOW:
0139   @p ManualAction for user-driven actions,
0140   @p AutomanticAction for filtering.
0141 */
0142 enum ActionMode {
0143     ManualAction,
0144     AutomaticAction
0145 };
0146 
0147 /**
0148   @li SentManually      The user explicitly gave permission for this
0149   particular MDN to be sent.
0150 
0151   @li SentAutomatically The MDN was sent because the MUA had previously
0152   been configured to do so automatically.
0153 
0154   IOW:
0155   @p SentManually for when we have asked the user
0156   @p SentAutomatically when we use the default specified by the user
0157 */
0158 enum SendingMode {
0159     SentManually,
0160     SentAutomatically
0161 };
0162 
0163 /**
0164   Generates the content of the message/disposition-notification body part.
0165 */
0166 KMIME_EXPORT extern QByteArray dispositionNotificationBodyContent(
0167     const QString &finalRecipient,
0168     const QByteArray &originalRecipient,
0169     const QByteArray &originalMsgID,
0170     DispositionType disposition,
0171     ActionMode actionMode,
0172     SendingMode sendingMode,
0173     const QVector<DispositionModifier> &dispositionModifers = QVector<DispositionModifier>(),
0174     const QString &special = QString());
0175 
0176 KMIME_EXPORT extern QString descriptionFor(
0177     DispositionType d,
0178     const QVector<DispositionModifier> &m = QVector<DispositionModifier>());
0179 
0180 } // namespace MDN
0181 
0182 } // namespace KMime
0183