mail::account::readMessageAttributes(3x)

1mail::account::readMessmaagielA:t:tarcicbouutnets(N3axtm)iaviel:A:PaIccroeufnetr:e:nrceeadMessageAttributes(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       mail::account *account;
40
41
42
43       account->readMessageAttributes   (const   std::vector<size_t>  msgList,
44       mail::account::MessageAttributes attributes,  myCallbackMessage  &call‐
45       back);
46

USAGE

48       mail::account::readMessageAttributes  requests  metadata of messages in
49       the currently open folder.  msgList specifies a list of messages.  Mes‐
50       sages  are  numbered  starting  with message #0 and up to one less than
51       mail::account::getFolderIndexSize(3x)()    (when    mail::account::get‐
52       FolderIndexSize  returns  6,  the  messages  are numbered 0 through 5).
53       Only the messages that appear in msgList are processed by this request.
54       attributes is a logical-or of the following constants:
55
56       mail::account::ARRIVALDATE
57              When  the message was added to the folder (myCallback.messageAr‐
58              rivalDateCallback).
59
60       mail::account::MESSAGESIZE
61              Estimated message size,  in  bytes  (myCallback.messageSizeCall‐
62              back).
63
64       mail::account::ENVELOPE
65              Message's  envelope headers (myCallback.messageEnvelopeCallback,
66              and possibly myCallback.messageReferencesCallback).   messageEn‐
67              velopeCallback  receives  a mail::envelope object that describes
68              the "envelope", or a message summary (sender,  recipients,  sub‐
69              ject,  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
73              the same information.
74
75              messageReferencesCallback  may  be  invoked  before or after the
76              messageEnvelopeCallback function, if at  all.   The  application
77              should  be  prepared  to merge the information returned by these
78              two callbacks.  As noted below, multiple callback methods may be
79              invoked  in  any  order, and the application should not make any
80              assumption as to the relative order in which these  two  methods
81              will be invoked.
82
83              For  example,  it  is  perfectly  feasible to have a request for
84              envelopes of two messages result in two  messageEnvelopeCallback
85              callbacks,  then two messageReferencesCallback callbacks; or two
86              instances of messageEnvelopeCallback followed by a messageRefer‐
87              encesCallback that refers to the same message.
88
89       mail::account::MIMESTRUCTURE
90              Returns  a mail::mimestruct object that enumerates the message's
91              MIME  content  (myCallback.messageStructureCallback).    myCall‐
92              back.messageStructureCallback   receives   a   reference   to  a
93              mail::mimestruct object that refers to the entire  message.   If
94              the message contains attachments, the mail::mimestruct::getChild
95              method returns pointers to mail::mimestruct objects which  refer
96              to the individual MIME attachments.
97
98       Metadata  information  requested  by  each  one  of  these constants is
99       returned by invoking the corresponding  callback  method  in  callback.
100       When requesting two or more items at once the callback functions may be
101       invoked in any order.  When requesting metadata from more than one mes‐
102       sage the callback functions are invoked one for each requested message.
103       Each callback function receives the requested  metadata  item  together
104       with  messageNumber - which message this metadata item relates to.  The
105       callback functions may be invoked in any message order.
106
107       For example, when requesting both ENVELOPE and MIMESTRUCTURE, the  pos‐
108       sibilities are:
109
110       · ENVELOPEs for all messages first, then all MIMESTRUCTUREs.
111
112       · The  ENVELOPE  and  the MIMESTRUCTURE for the first message, then the
113         ENVELOPE and the MIMESTRUCTURE for the next message, and so on.
114
115         Note: 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 succes‐
122       fully 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: callback's fail method may be  invoked  even  after  other
127              callback  methods were invoked.  This indicates that the request
128              was partially completed before the error was encountered.
129
130              Note: Multiple applications may have the same account and folder
131              opened  at  the same time.  It is possible that a message refer‐
132              enced by this request was already deleted  by  another  applica‐
133              tion.   Depending  on  the underlying server implementation this
134              will result in either a failed request, invoking  callback.fail,
135              or the request completing (callback.success invoked) but without
136              invoking any callback function that refer to the message.
137

NAME

SYNOPSIS

USAGE

RETURN CODES

SEE ALSO