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