|
|
int
representing
a single message.
void mail_fetchfast(MAILSTREAM *stream, char *sequence);void mail_fetchfast_full(MAILSTREAM *stream, char *sequence, long 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:
void mail_fetchflags(MAILSTREAM *stream, char *sequence);void mail_fetchflags_full(MAILSTREAM *stream, char *sequence, long 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:
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);
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:
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.
char *mail_fetchheader(MAILSTREAM *stream, unsigned long msgno);char *mail_fetchheader_full(MAILSTREAM *stream, unsigned long msgno, STRINGLIST *lines, unsigned long *len, long 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:
char *mail_fetchtext(MAILSTREAM *stream, unsigned long msgno);char *mail_fetchtext_full(MAILSTREAM *stream, unsigned long msgno, unsigned long *len, long 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:
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);
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:
unsigned long mail_uid(MAILSTREAM *stream, unsigned long msgno);
This function returns the UID for the given message sequence number.
void mail_fetchfrom(char *s, MAILSTREAM *stream, unsigned long msgno, long 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.
void mail_fetchsubject(char *s, MAILSTREAM *stream, unsigned long msgno, long 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.
LONGCACHE *mail_lelt(MAILSTREAM *stream, unsigned long msgno);MESSAGECACHE *mail_elt(MAILSTREAM *stream, unsigned long msgno);
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.