File indexing completed on 2024-04-28 13:12: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 <QList> 0037 #include <QString> 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, const QByteArray &originalRecipient, 0168 const QByteArray &originalMsgID, DispositionType disposition, 0169 ActionMode actionMode, SendingMode sendingMode, 0170 const QList<DispositionModifier> &dispositionModifers = 0171 QList<DispositionModifier>(), 0172 const QString &special = QString()); 0173 0174 KMIME_EXPORT extern QString descriptionFor( 0175 DispositionType d, 0176 const QList<DispositionModifier> &m = QList<DispositionModifier>()); 0177 0178 } // namespace MDN 0179 0180 } // namespace KMime 0181