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
53class QByteArray;
54
55namespace KMime {
56
57namespace 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*/
101enum 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*/
131enum 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*/
154enum 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*/
170enum SendingMode {
171 SentManually,
172 SentAutomatically
173};
174
175/**
176 Generates the content of the message/disposition-notification body part.
177*/
178KMIME_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
188KMIME_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