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.] 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 This function causes 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 void mail_fetchflags (MAILSTREAM *stream,char *sequence); void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags); This function causes a fetch of the flags for the given sequence. This main reason for using this function 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 "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 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 This function 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 is 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(). 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 This function causes 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 (e.g. 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 CRLF 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 (e.g. in a "save to local file" operation) 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 This function causes a fetch of the non-header text of the specified message as a text string and returns 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. This function always returns a valid string pointer; if no header exists or if it can not be fetched (e.g. 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 CRLF newlines 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 This function causes 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 rfc822_base64() and rfc822_quotedprintable(). 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 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 CRLF newlines 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. 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 "@", 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); 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. LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno); MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno); stream stream to access msgno message sequence number This function returns the cache entry for the specified message. Although it will create a cache entry if it does not already exist, that functionality is for internal use only. This function 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(). BEWARE: the behavior of mail_lelt() is undefined if the stream is open with OP_SHORTCACHE. mail_lelt() is extremely special purpose, and should only be used in sophisticated special purpose applications after discussing its use with the c-client 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.