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

## Name

mail::account::readMessageContent — Read messages

## 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->readMessageContent(` | const std::vector<size_t> & | msgList,
| bool | peek,
| mail::readMode | requestType,
| myCallbackMessage & | callback`)`;

`account->readMessageContent(` | size_t | messageNum,
| bool | peek,
| mail::mimestruct & | msginfo,
| mail::readMode | requestType,
| myCallbackMessage & | callback`)`;

## USAGE

`mail::account::readMessagesContent` reads messages in the currently open folder. There are two alternative versions of this method.

- The first version receives a list of message numbers. `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. This version is capable of returning headers and/or content of multiple messages.

- The second version receives a single message number, and a mail::mimestruct object that refers to a single MIME attachment or a section of this message. The `mail::account::MIMESTRUCTURE` argument to mail::account::readMessageAttributes(3x) returns a recursive tree of mail::mimestruct objects which enumerates the individual MIME sections in the message. `msgInfo` must be a reference to one of these objects (or to a copy of these objects).

Setting `peek` to true does not reset the `unread` message status flag for this message. Otherwise the `unread` message status flag will be reset.

### Note

The application is notified about when a message's status changes by by invoking the `messageChanged` callback method of the currently opened folder's mail::folderCallback object. Depending on the mail server, the `messageChanged` method may be invoked as part of processing this request, or some time later after this request is completed, and `callback`'s `success` method was invoked.

The `mail::callback::message::messageTextCallback` method receives the requested content, which is determined by the remaining parameters.

`requestType` identifies the type of information to return from the selected MIME section, and must be set to one of the following values:

The callback method may not receive the entire requested content at once. Typically the method will be invoked multiple times; each time the method receives the next portion of the requested content. When requesting headers and/or content of multiple messages, they may be returned in any order, and the `messageNumber` parameter indicates which message's contents are being returned (note, however, that the entire contents of a given message are returned in their entirety, even when the callback method gets invoked multiple times for that message, before content from the next message are returned).

`mail::readHeadersFolded`

  Return only the headers of the MIME section. Folded headers are unfolded (the newline and the leading space on the next line are replaced with a single space character).

`mail::readHeaders`

  Return only the headers of the MIME section. The headers are returned as-is, without unfolding them.

`mail::readContents`

  Return the content of the MIME section.

  ### Note

  The MIME section is not decoded. Check the `Content-Transfer-Encoding` header to know what you're getting.

`mail::readBoth`

  Return the entire MIME section, as is: its headers, a blank line, then the contents.

## 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::readMessageAttributes(3x), mail::account::readMessageContentDecoded(3x).

Prev | Up | Next
mail::account::readMessageAttributes | Home | ToC | mail::account::readMessageContentDecoded