KMime

kmime_mdn.h
Go to the documentation of this file.
1 /* -*- c++ -*-
2  kmime_mdn.h
3 
4  KMime, the KDE Internet mail/usenet news message library.
5  SPDX-FileCopyrightText: 2002 Marc Mutz <[email protected]>
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 <[email protected]>
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 */
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 */
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 */
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 */
159  SentManually,
160  SentAutomatically
161 };
162 
163 /**
164  Generates the content of the message/disposition-notification body part.
165 */
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,
179 
180 } // namespace MDN
181 
182 } // namespace KMime
183 
ActionMode
The following disposition modes are defined:
Definition: kmime_mdn.h:142
QByteArray dispositionNotificationBodyContent(const QString &r, const QByteArray &o, const QByteArray &omid, DispositionType d, ActionMode a, SendingMode s, const QVector< DispositionModifier > &m, const QString &special)
Generates the content of the message/disposition-notification body part.
Definition: kmime_mdn.cpp:243
DispositionModifier
The following disposition modifiers are defined:
Definition: kmime_mdn.h:119
DispositionType
The following disposition-types are defined:
Definition: kmime_mdn.h:89
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Sep 27 2021 23:15:57 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.