Name

mail::account::readMessageAttributes — Return message metadata

Synopsis


#include <libmail/mail.H>
#include <libmail/envelope.H>
#include <libmail/structure.H>

class myCallbackMessage : public mail::callback::message {
public:
    void success(std::string msg);
    void fail(std::string msg);

    void messageEnvelopeCallback(size_t messageNumber,
                                 const mail::envelope &envelopeArg);

    void messageReferencesCallback(size_t messageNumber,
                                   const std::vector<std::string> &referencesArg);

    void messageArrivalDateCallback(size_t messageNumber,
                                    time_t datetime);

    void messageSizeCallback(size_t messageNumber,
                             unsigned long size);

    void messageStructureCallback(size_t messageNumber,
                                  const mail::mimestruct &messageStructure);
    void messageTextCallback(size_t messageNumber, std::string text);
};

std::cout << (float)myMessageCallback.messageTextCompleted /
             (float)myMessageCallback.messageTextEstimatedSize * 100
          << "% completed." << endl;


mail::account *account;

account->readMessageAttributes( const std::vector<size_t> msgList,
  mail::account::MessageAttributes attributes,
  myCallbackMessage &callback);
 

USAGE

mail::account::readMessageAttributes requests metadata of messages in the currently open folder. msgList specifies a list of messages. Messages are numbered starting with message #0 and up to one less than mail::account::getFolderIndexSize(3x)() (when mail::account::getFolderIndexSize returns 6, the messages are numbered 0 through 5). Only the messages that appear in msgList are processed by this request. attributes is a logical-or of the following constants:

mail::account::ARRIVALDATE

When the message was added to the folder (myCallback.messageArrivalDateCallback).

mail::account::MESSAGESIZE

Estimated message size, in bytes (myCallback.messageSizeCallback).

mail::account::ENVELOPE

Message's envelope headers (myCallback.messageEnvelopeCallback, and possibly myCallback.messageReferencesCallback). messageEnvelopeCallback receives a mail::envelope object that describes the "envelope", or a message summary (sender, recipients, subject, etc...). In some instances the messageReferencesCallback callback will also be invoked, with an an array of message IDs taken from the References header. In other instances the mail::envelope will already have the references populated with the same information.

messageReferencesCallback may be invoked before or after the messageEnvelopeCallback function, if at all. The application should be prepared to merge the information returned by these two callbacks. As noted below, multiple callback methods may be invoked in any order, and the application should not make any assumption as to the relative order in which these two methods will be invoked.

For example, it is perfectly feasible to have a request for envelopes of two messages result in two messageEnvelopeCallback callbacks, then two messageReferencesCallback callbacks; or two instances of messageEnvelopeCallback followed by a messageReferencesCallback that refers to the same message.

mail::account::MIMESTRUCTURE

Returns a mail::mimestruct object that enumerates the message's MIME content (myCallback.messageStructureCallback). myCallback.messageStructureCallback receives a reference to a mail::mimestruct object that refers to the entire message. If the message contains attachments, the mail::mimestruct::getChild method returns pointers to mail::mimestruct objects which refer to the individual MIME attachments.

Metadata information requested by each one of these constants is returned by invoking the corresponding callback method in callback. When requesting two or more items at once the callback functions may be invoked in any order. When requesting metadata from more than one message the callback functions are invoked one for each requested message. Each callback function receives the requested metadata item together with messageNumber - which message this metadata item relates to. The callback functions may be invoked in any message order.

For example, when requesting both ENVELOPE and MIMESTRUCTURE, the possibilities are:

  • ENVELOPEs for all messages first, then all MIMESTRUCTUREs.

  • The ENVELOPE and the MIMESTRUCTURE for the first message, then the ENVELOPE and the MIMESTRUCTURE for the next message, and so on.

Note

The mail::envelope and mail::mimestruct objects are destroyed immediately after their corresponding callback method terminates. The application should copy any objects it intends to use later.

Return Codes

The application must wait until callback's success or fail method is invoked. The success method is invoked when this request is succesfully processed. The fail method is invoked if this request cannot be processed. The application must not destroy callback until either the success or fail method is invoked.

Note

callback's fail method may be invoked even after other callback methods were invoked. This indicates that the request was partially completed before the error was encountered.

Note

Multiple applications may have the same account and folder opened at the same time. It is possible that a message referenced by this request was already deleted by another application. Depending on the underlying server implementation this will result in either a failed request, invoking callback.fail, or the request completing (callback.success invoked) but without invoking any callback function that refer to the message.