1        Cone©
2
3MAIL::ACCOUNT::READM(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::READM(3x)
4
5
6

NAME

8       mail::account::readMessageAttributes - Return message metadata
9

SYNOPSIS

11       #include <libmail/mail.H>
12       #include <libmail/envelope.H>
13       #include <libmail/structure.H>
14
15       class myCallbackMessage : public mail::callback::message {
16       public:
17           void success(std::string msg);
18           void fail(std::string msg);
19
20           void messageEnvelopeCallback(size_t messageNumber,
21                                        const mail::envelope &envelopeArg);
22
23           void messageReferencesCallback(size_t messageNumber,
24                                          const std::vector<std::string> &referencesArg);
25
26           void messageArrivalDateCallback(size_t messageNumber,
27                                           time_t datetime);
28
29           void messageSizeCallback(size_t messageNumber,
30                                    unsigned long size);
31
32           void messageStructureCallback(size_t messageNumber,
33                                         const mail::mimestruct &messageStructure);
34           void messageTextCallback(size_t messageNumber, std::string text);
35       };
36
37       std::cout << (float)myMessageCallback.messageTextCompleted /
38                    (float)myMessageCallback.messageTextEstimatedSize * 100
39                 << "% completed." << endl;
40
41
42       mail::account *account;
43
44       account->readMessageAttributes(const std::vector<size_t> msgList,
45                                      mail::account::MessageAttributes attributes,
46                                      myCallbackMessage &callback);
47

USAGE

49       mail::account::readMessageAttributes requests metadata of messages in
50       the currently open folder.  msgList specifies a list of messages.
51       Messages are numbered starting with message #0 and up to one less than
52       mail::account::getFolderIndexSize(3x)() (when
53       mail::account::getFolderIndexSize returns 6, the messages are numbered
54       0 through 5). Only the messages that appear in msgList are processed by
55       this request.  attributes is a logical-or of the following constants:
56
57       mail::account::ARRIVALDATE
58           When the message was added to the folder
59           (myCallback.messageArrivalDateCallback).
60
61       mail::account::MESSAGESIZE
62           Estimated message size, in bytes (myCallback.messageSizeCallback).
63
64       mail::account::ENVELOPE
65           Message's envelope headers (myCallback.messageEnvelopeCallback, and
66           possibly myCallback.messageReferencesCallback).
67           messageEnvelopeCallback receives a mail::envelope object that
68           describes the "envelope", or a message summary (sender, recipients,
69           subject, etc...). In some instances the messageReferencesCallback
70           callback will also be invoked, with an an array of message IDs
71           taken from the References header. In other instances the
72           mail::envelope will already have the references populated with the
73           same information.
74
75           messageReferencesCallback may be invoked before or after the
76           messageEnvelopeCallback function, if at all. The application should
77           be prepared to merge the information returned by these two
78           callbacks. As noted below, multiple callback methods may be invoked
79           in any order, and the application should not make any assumption as
80           to the relative order in which these two methods will be invoked.
81
82           For example, it is perfectly feasible to have a request for
83           envelopes of two messages result in two messageEnvelopeCallback
84           callbacks, then two messageReferencesCallback callbacks; or two
85           instances of messageEnvelopeCallback followed by a
86           messageReferencesCallback that refers to the same message.
87
88       mail::account::MIMESTRUCTURE
89           Returns a mail::mimestruct object that enumerates the message's
90           MIME content (myCallback.messageStructureCallback).
91           myCallback.messageStructureCallback receives a reference to a
92           mail::mimestruct object that refers to the entire message. If the
93           message contains attachments, the mail::mimestruct::getChild method
94           returns pointers to mail::mimestruct objects which refer to the
95           individual MIME attachments.
96
97       Metadata information requested by each one of these constants is
98       returned by invoking the corresponding callback method in callback.
99       When requesting two or more items at once the callback functions may be
100       invoked in any order. When requesting metadata from more than one
101       message the callback functions are invoked one for each requested
102       message. Each callback function receives the requested metadata item
103       together with messageNumber - which message this metadata item relates
104       to. The callback functions may be invoked in any message order.
105
106       For example, when requesting both ENVELOPE and MIMESTRUCTURE, the
107       possibilities are:
108
109       ·   ENVELOPEs for all messages first, then all MIMESTRUCTUREs.
110
111       ·   The ENVELOPE and the MIMESTRUCTURE for the first message, then the
112           ENVELOPE and the MIMESTRUCTURE for the next message, and so on.
113
114           Note
115           The mail::envelope and mail::mimestruct objects are destroyed
116           immediately after their corresponding callback method terminates.
117           The application should copy any objects it intends to use later.
118

RETURN CODES

120       The application must wait until callback's success or fail method is
121       invoked. The success method is invoked when this request is succesfully
122       processed. The fail method is invoked if this request cannot be
123       processed. The application must not destroy callback until either the
124       success or fail method is invoked.
125
126           Note
127           callback's fail method may be invoked even after other callback
128           methods were invoked. This indicates that the request was partially
129           completed before the error was encountered.
130
131           Note
132           Multiple applications may have the same account and folder opened
133           at the same time. It is possible that a message referenced by this
134           request was already deleted by another application. Depending on
135           the underlying server implementation this will result in either a
136           failed request, invoking callback.fail, or the request completing
137           (callback.success invoked) but without invoking any callback
138           function that refer to the message.
139

SEE ALSO

141       mail::account::getFolderIndexSize(3x),
142       mail::account::readMessageContent(3x),
143       mail::account::readMessageContentDecoded(3x),
144       mail::account::getFolderIndexInfo(3x), mail::envelope(3x),
145       mail::mimestruct(3x).
146

AUTHOR

148       Sam Varshavchik
149
150
151
152Cone©                             08/25/2016          MAIL::ACCOUNT::READM(3x)
Impressum