mail::account::readMessageAttributes
Prev | mail::account Native API reference | Next

## 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:

- `ENVELOPE`s for all messages first, then all `MIMESTRUCTURE`s.

- 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.

## SEE ALSO

mail::account::getFolderIndexSize(3x), mail::account::readMessageContent(3x), mail::account::readMessageContentDecoded(3x), mail::account::getFolderIndexInfo(3x), mail::envelope(3x), mail::mimestruct(3x).

Prev | Up | Next
mail::account::process | Home | ToC | mail::account::readMessageContent