1 /* -*- c++ -*- 2 kmime_mdn.h 3 4 KMime, the KDE Internet mail/usenet news message library. 5 SPDX-FileCopyrightText: 2002 Marc Mutz <mutz@kde.org> 6 7 SPDX-License-Identifier: LGPL-2.0-or-later 8 */ 9 /** 10 @file 11 This file is part of the API for handling @ref MIME data and 12 provides functions for supporting Message Disposition Notifications (MDNs), 13 also known as email return receipts. 14 15 @brief 16 Provides support for Message Disposition Notifications. 17 18 @authors Marc Mutz \<mutz@kde.org\> 19 20 @glossary @anchor MDN @b MDN: 21 see @ref Message_Disposition_Notification 22 23 @glossary @anchor Message_Disposition_Notification 24 @b Message @b Disposition @b Notification: 25 Return receipts for email are called message disposition notifications. 26 Their format and usage is outlined in @ref RFC2298. 27 28 @glossary @anchor RFC2298 @anchor rfc2298 @b RFC @b 2298: 29 RFC that defines the <a href="https://tools.ietf.org/html/rfc2298"> 30 An Extensible Message Format for Message Disposition Notifications</a>. 31 */ 32 33 #pragma once 34 35 #include "kmime_export.h" 36 #include <QString> 37 #include <QVector> 38 39 class QByteArray; 40 41 namespace KMime 42 { 43 44 namespace MDN 45 { 46 47 /** 48 The following disposition-types are defined: 49 50 @li Displayed The message has been displayed by the UA to someone 51 reading the recipient's mailbox. There is no guarantee that the 52 content has been read or understood. 53 54 @li Dispatched The message has been sent somewhere in some manner 55 (e.g., printed, faxed, forwarded) without necessarily having been previously 56 displayed to the user. The user may or may not see the message later. 57 58 @li Processed The message has been processed in some manner (i.e., by 59 some sort of rules or server) without being displayed to the user. The user 60 may or may not see the message later, or there may not even be a human user 61 associated with the mailbox. 62 63 @li Deleted The message has been deleted. The recipient may or may not 64 have seen the message. The recipient might "undelete" the message at a 65 later time and read the message. 66 67 @li Denied The recipient does not wish the sender to be informed of the 68 message's disposition. A UA may also silently ignore message disposition 69 requests in this situation. 70 71 @li Failed A failure occurred that prevented the proper generation 72 of an MDN. More information about the cause of the failure may be contained 73 in a Failure field. The "failed" disposition type is not to be used for 74 the situation in which there is is some problem in processing the message 75 other than interpreting the request for an MDN. The "processed" or other 76 disposition type with appropriate disposition modifiers is to be used in 77 such situations. 78 79 IOW: 80 @p Displayed when - well -displayed 81 @p Dispatched when forwarding unseen ( == new ) 82 @p Processed (maybe) when piping unseen, but probably never used 83 @p Deleted when deleting unseen 84 @p Denied on user command 85 @p Failed on Disposition-Notification-Options containing 86 unknown required options. ( == @em any required options ) 87 @p Failed needs a description in the @p special parameter. 88 */ 89 enum DispositionType { 90 Displayed, Read = Displayed, 91 Deleted, 92 Dispatched, Forwarded = Dispatched, 93 Processed, 94 Denied, 95 Failed 96 }; 97 98 /** 99 The following disposition modifiers are defined: 100 101 @li Error An error of some sort occurred that prevented 102 successful processing of the message. Further information is contained 103 in an Error field. 104 105 @li Warning The message was successfully processed but some 106 sort of exceptional condition occurred. Further information is contained 107 in a Warning field. 108 109 @li Superseded The message has been automatically rendered obsolete 110 by another message received. The recipient may still access and read the 111 message later. 112 113 @li Expired The message has reached its expiration date and has 114 been automatically removed from the recipient's mailbox. 115 116 @li MailboxTerminated The recipient's mailbox has been terminated and all 117 message in it automatically removed. 118 */ 119 enum DispositionModifier { 120 Error, 121 Warning, 122 Superseded, 123 Expired, 124 MailboxTerminated 125 }; 126 127 /** 128 The following disposition modes are defined: 129 130 @li ManualAction The disposition described by the disposition type 131 was a result of an explicit instruction by the user rather than some sort of 132 automatically performed action. 133 134 @li AutomaticAction The disposition described by the disposition type was 135 a result of an automatic action, rather than an explicit instruction by the 136 user for this message. 137 138 IOW: 139 @p ManualAction for user-driven actions, 140 @p AutomanticAction for filtering. 141 */ 142 enum ActionMode { 143 ManualAction, 144 AutomaticAction 145 }; 146 147 /** 148 @li SentManually The user explicitly gave permission for this 149 particular MDN to be sent. 150 151 @li SentAutomatically The MDN was sent because the MUA had previously 152 been configured to do so automatically. 153 154 IOW: 155 @p SentManually for when we have asked the user 156 @p SentAutomatically when we use the default specified by the user 157 */ 158 enum SendingMode { 159 SentManually, 160 SentAutomatically 161 }; 162 163 /** 164 Generates the content of the message/disposition-notification body part. 165 */ 166 KMIME_EXPORT extern QByteArray dispositionNotificationBodyContent( 167 const QString &finalRecipient, 168 const QByteArray &originalRecipient, 169 const QByteArray &originalMsgID, 170 DispositionType disposition, 171 ActionMode actionMode, 172 SendingMode sendingMode, 173 const QVector<DispositionModifier> &dispositionModifers = QVector<DispositionModifier>(), 174 const QString &special = QString()); 175 176 KMIME_EXPORT extern QString descriptionFor( 177 DispositionType d, 178 const QVector<DispositionModifier> &m = QVector<DispositionModifier>()); 179 180 } // namespace MDN 181 182 } // namespace KMime 183 184