mail::account::readMessageAttributes(3x)

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

NAME

6       mail::account::readMessageAttributes - Return message metadata
7

SYNOPSIS

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

USAGE

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

RETURN CODES

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

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO