Message store functions

Message data fetching functions

NOTE: There is an important difference between a sequence and a msgno. A sequence is a string representing one or more messages in IMAP4-style sequence format (n, n:m, or combination of these delimited by commas), whereas a msgno is an int representing a single message.

mail_fetchfast
```
void mail_fetchfast(MAILSTREAM *stream, char *sequence);

void mail_fetchfast_full(MAILSTREAM *stream, char *sequence, long flags);
```
stream
Stream to fetch on.

sequence
IMAP-format set of message sequence numbers.

flags
Option flags.

These functions cause a cache load of all the fast information (internal date, RFC 822 size, and flags) for the given sequence. Since all this information is also fetched by mail_fetchstructure, this function is generally not used unless the OP_SHORTCACHE option in the mail_open call is used.
The options for mail_fetchfast_full are a bit mask with one or more of the following:

FT_UID
The sequence argument contains UIDs instead of sequence numbers.
mail_fetchflags
```
void mail_fetchflags(MAILSTREAM *stream, char *sequence);

void mail_fetchflags_full(MAILSTREAM *stream, char *sequence, long flags);
```
stream
Stream to fetch on.

sequence
IMAP-format set of message sequence numbers.

flags
Option flags.

These functions cause a fetch of the flags for the given sequence. This main reason for using them is to update the flags in the local cache in case some other process changed the flags (multiple simultaneous write access is allowed to the flags) as part of a check entire mailbox (as opposed to a check for new messages) operation.
The options for mail_fetchflags_full are a bit mask with one or more of the following:

FT_UID
The sequence argument contains UIDs instead of sequence numbers.
mail_fetchenvelope
```
ENVELOPE *mail_fetchenvelope(MAILSTREAM *stream, unsigned long msgno);

ENVELOPE *mail_fetchstructure(MAILSTREAM *stream, unsigned long msgno,
         BODY **body);

ENVELOPE *mail_fetchstructure_full(MAILSTREAM *stream, unsigned long msgno,
         BODY **body, long flags);
```
stream
Stream to fetch on.

msgno
Message sequence number.

body
Pointer to where to return BODY structure if non-NIL.

flags
Option flags.

These functions causes a fetch of all the structured information (envelope, internal date, RFC 822 size, flags, and body structure) for the given msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a parameter in IMAP2.H) subsequent messages which are not yet in the cache. No fetch is done if the envelope for the given msgno is already in the cache. The ENVELOPE and the BODY for this msgno are returned. It is possible for the BODY to be NIL, in which case no information is available about the structure of the message body.
The options for mail_fetchstructure_full are a bit mask with one or more of the following:

FT_UID
The msgno argument is a UID.

This is the primary function for fetching non-text information about messages, and should be called before any attempt to reference cache information about this message via mail_elt.
mail_fetchheader
```
char *mail_fetchheader(MAILSTREAM *stream, unsigned long msgno);

char *mail_fetchheader_full(MAILSTREAM *stream, unsigned long msgno,
     STRINGLIST *lines, unsigned long *len, long flags);
```
stream
Stream to fetch on.

msgno
Message sequence number.

lines
List of header lines to fetch.

len
Returned length in octets.

flags
Option flags.

These functions cause a fetch of the complete, unfiltered RFC 822 format header of the specified message as a text string and returns that text string.
If the lines argument is non-NIL, it contains a list of header field names to use in subsetting the header text. Only those lines which have that header field name are returned, unless FT_NOT is set, in which case only those lines which do not have that header field name are returned.
If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string.
This function always returns a valid string pointer; if no header exists or if it can not be fetched (for example, by a deceased IMAP stream), an empty string is returned.
The options for mail_fetchheader_full are a bit mask with one or more of the following:

FT_UID
The msgno argument is a UID.

FT_NOT
The returned header lines are those that are not in the lines argument.

FT_INTERNAL
The return string is in ``internal'' format, without any attempt to canonicalize to CR-LF newlines.

FT_PREFETCHTEXT
The RFC822.TEXT should be pre-fetched at the same time. This avoids an extra RTT on an IMAP connection if a full message text is desired (for example, in a save to local file operation).
mail_fetchtext
```
char *mail_fetchtext(MAILSTREAM *stream, unsigned long msgno);

char *mail_fetchtext_full(MAILSTREAM *stream, unsigned long msgno,
     unsigned long *len, long flags);
```
stream
Stream to fetch on.

msgno
Message sequence number.

len
Returned length in octets.

flags
Option flags.

These functions cause a fetch of the non-header text of the specified message as a text string and return that text string. No attempt is made to segregate individual body parts.
If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string.
The functions always return a valid string pointer; if no header exists or if it can not be fetched (for example, by a deceased IMAP stream), an empty string is returned.
The options for mail_fetchtext_full are a bit mask with one or more of the following:

FT_UID
The msgno argument is a UID.

FT_PEEK
Do not set the \Seen flag if it not already set.

FT_INTERNAL
The return string is in ``internal'' format, without any attempt to canonicalize to CR-LF newlines.
mail_fetchbody
```
char *mail_fetchbody(MAILSTREAM *stream, unsigned long msgno, char *sec,
      unsigned long *len);

char *mail_fetchbody_full(MAILSTREAM *stream, unsigned long msgno,
      char *sec, unsigned long *len, long flags);
```
stream
Stream to fetch on.

msgno
Message sequence number.

sec
Section specifier.

len
Returned length in octets.

flags
Option flags.

These functions cause a fetch of the particular section of the body of the specified message as a text string and returns that text string. The section specification is a string of integers delimited by period which index into a body part list as per the IMAP4 specification. Body parts are not decoded by this function; see the descriptions of rfc822_base64 and rfc822_quotedprintable in ``NNTP functions''.
If the len argument is non-NIL, it holds a pointer in which the length of the string in octets is returned. This is useful in cases where there may be an embedded null in the string.
These functions may return NIL on error.
The options for mail_fetchbody_full are a bit mask with one or more of the following:

FT_UID
The msgno argument is a UID .

FT_PEEK
Do not set the \Seen flag if it not already set.

FT_INTERNAL
The return string is in ``internal'' format, without any attempt to canonicalize to CR-LF newlines.
mail_uid
```
unsigned long mail_uid(MAILSTREAM *stream, unsigned long msgno);
```
stream
Stream to fetch on.

msgno
Message sequence number.

This function returns the UID for the given message sequence number.
mail_fetchfrom
```
void mail_fetchfrom(char *s, MAILSTREAM *stream, unsigned long msgno,
     long length);
```
s
Destination string.

stream
Stream to fetch on.

msgno
Message sequence number.

length
Maximum field length.

This function writes a ``from'' string of the specified length for the specified message, suitable for display to the user in a menu line, into the string pointed to by s.
If the personal name of the first address in the envelope's from item is non-NIL, it is used; otherwise a string is created by appending the mailbox of the first address, an at sign (@), and the host of the first address. The string is trimmed or padded with trailing spaces as necessary to make its length match the length argument.
mail_fetchsubject
```
void mail_fetchsubject(char *s, MAILSTREAM *stream, unsigned long msgno,
     long length);
```
s
Destination string.

stream
Stream to fetch on.

msgno
Message sequence number.

length
Maximum field length.

This function returns a ``subject'' string of the specified length for the specified message, suitable for display to the user in a menu line.
The envelope's subject item is copied and trimmed as necessary to make its length be no more what the caller requested. Unlike mail_fetchfrom, this function can return a string of shorter length than what the caller requested.
mail_lelt
```
LONGCACHE *mail_lelt(MAILSTREAM *stream, unsigned long msgno);

MESSAGECACHE *mail_elt(MAILSTREAM *stream, unsigned long msgno);
```
stream
Stream to access.

msgno
Message sequence number.

These functions return the cache entry for the specified message. Although they will create a cache entry if it does not already exist, that functionality is for internal use only. The functions should never be called without having first called mail_fetchfast or mail_fetchstructure on the message first.
A cache entry holds the internal date/time, flags, and RFC 822 size of a message. It holds other data as well, but that is for internal use only.
mail_lelt is a variant that returns a long cache entry, which consists of an cache entry (as a structure, not a pointer), an envelope pointer, and a body pointer. This is used in conjunction with the elt lock count functionality, to allow an application to associate the cached envelope and body of a message with an open window even if the message is subsequently expunged or if the stream is closed.
Unless your application wants to look at cached envelopes and bodies even after the message is expunged or the stream is closed, it should not use mail_lelt. Instead, it should use a returned elt from mail_elt and use the elt->msgsno as the argument to mail_fetchstructure.
WARNING: The behavior of mail_lelt is undefined if the stream is open with OP_SHORTCACHE. mail_lelt is for extremely specialised use, and should only be used in sophisticated, special-purpose applications after discussing its use with the C client application's author. If you think you need this function, you are probably mistaken. In almost all cases, you should use mail_elt and mail_fetchstructure instead.