Mailbox search functions

• mail_search

  void mail_search(MAILSTREAM *stream, char *criteria);
  
  void mail_search_full(MAILSTREAM *stream, char *charset, SEARCHPGM *pgm,
       long flags);
  

  
  stream

  Stream to search.

  
  criteria

  Search criteria string.

  
  charset

  MIME character set to use when searching strings.

  
  pgm

  Search program.

  
  flags

  Option flags.

  These functions cause a mailbox search, using the given MIME charset (NIL means the default, US-ASCII) and the given search program. A search program is a structure that holds the following data:

  • SEARCHSET *msgno;

    A set of message sequence numbers.

  • SEARCHSET *uid;

    A set of unique identifiers.

  • SEARCHOR *or;

    OR result of two search programs.

  • SEARCHPGMLIST *not;

    AND result of list of NOT'ed search programs.

  • SEARCHHEADER *header;

    Message headers.

  • STRINGLIST *bcc;

    String(s) appear in bcc list.

  • STRINGLIST *body;

    String(s) appear in message body text.

  • STRINGLIST *cc;

    String(s) appear in cc list.

  • STRINGLIST *from;

    String(s) appear in from.

  • STRINGLIST *keyword;

    User flag string(s) set.

  • STRINGLIST *unkeyword;

    User flag string(s) not set.

  • STRINGLIST *subject;

    String(s) appear in subject.

  • STRINGLIST *text;

    String(s) appear in message header or body.

  • STRINGLIST *to;

    String(s) appear in to list.

  • unsigned long larger;

    Larger than this many octets.

  • unsigned long smaller;

    Smaller than this many octets.

  The dates in the following list take the form:

     ((year - BASEYEAR) << 9) + (month << 5) + day
  

  • unsigned short sentbefore;

    Sent before this date.

  • unsigned short senton;

    Sent on this date.

  • unsigned short sentsince;

    Sent since this date.

  • unsigned short before;

    Received before this date.

  • unsigned short on;

    Received on this date.

  • unsigned short since;

    Received since this date.

  • unsigned int answered : 1;

    Message answered.

  • unsigned int unanswered : 1;

    Message not answered.

  • unsigned int deleted : 1;

    Message deleted.

  • unsigned int undeleted : 1;

    Message not deleted.

  • unsigned int draft : 1;

    Message is a draft.

  • unsigned int undraft : 1;

    Message is not a draft.

  • unsigned int flagged : 1

    Message flagged as urgent.

  • unsigned int unflagged : 1;

    Message not flagged as urgent.

  • unsigned int recent : 1;

    Message recent since last parse of mailbox.

  • unsigned int old : 1;

    Message not recent since last parse of mailbox.

  • unsigned int seen : 1;

    Message read.

  • unsigned int unseen : 1;

    Message not read.

  The following auxillary structures are used by search programs:

  • SEARCHHEADER: header line searching

    • char *line;

      Header line field name.

    • char *text;

      Text header line.

    • SEARCHHEADER *next;

      Next SEARCHHEADER in list (AND'ed).

  • SEARCHSET: message number set

    • unsigned long first;

      First number in set.

    • unsigned long last;

      If non-zero, last number in set.

    • SEARCHSET *next;

      Next SEARCHSET in list (AND'ed).

  • SEARCHOR: two search programs, OR'ed together

    • SEARCHPGM *first;

      First program.

    • SEARCHPGM *second;

      Second program.

    • SEARCHOR *next;

      Next SEARCHOR in list.

  • SEARCHPGMLIST: list of search programs

    • SEARCHPGM *pgm;

      Search program (AND'd with others in list).

    • SEARCHPGMLIST *next;

      Next SEARCHPGM in list.

  mail_search, the older interface, accepts a search criteria argument as a character string in IMAP2 (RFC-1176) format. Do not try to use any IMAP4 search criteria with this interface.

  The application's mm_searched function is called for each message that matches the search criteria. In addition, after the search is completed, the fast information (see mail_fetchfast_full) and envelopes of the searched messages are fetched (this is called pre-fetching).

  If there is any problem in searching, a message will be passed to the application via the mm_log facility.

  The flags for mail_search_full are a bit mask with one or more of the following:

  
  SE_UID

  Return UIDs instead of sequence numbers.

  
  SE_FREE

  Return the search program to free storage after finishing.

  
  SE_NOPREFETCH

  Do not prefetch searched messages.

• mail_sort

  unsigned long *mail_sort(MAILSTREAM *stream, char *charset, SEARCHPGM *spg,
           SORTPGM *pgm, long flags);
  

  
  stream

  Stream to sort.

  
  charset

  MIME character set to use when sorting strings.

  
  spg

  Search program.

  
  pgm

  Sort program.

  
  flags

  Option flags.

  This function is a variant of mail_search_full. It accepts an additional argument, a sort program, which specifies one or more sort rules to be applied to the result. If the searching and sorting are successful, it returns a 0-terminated vector of message sequence numbers (or UIDs if SE_UID is set). This vector is created out of free storage, and must be freed with fs_give when finished with it.

  A sort program is a structure that holds the following data:

  • unsigned int reverse : 1;

    Reverse sorting of this key.

  • short function;

    Sort rule, one of the following:.

    
    SORTDATE

    Message date.

    
    SORTARRIVAL

    Arrival date.

    
    SORTFROM

    Mailbox in first From address.

    
    SORTSUBJECT

    Message Subject.

    
    SORTTO

    Mailbox in first To address.

    
    SORTCC

    Mailbox in first cc address.

    
    SORTSIZE

    Size of message in octets.

  • SORTPGM *next;

    Next sort program to be applied if two or more messages collate identically with this rule.

  The flags for mail_search_full are a bit mask with one or more of the following:

  
  SE_UID

  Return UIDs instead of sequence numbers.

  
  SE_FREE

  Return the search program to free storage after finishing.

  
  SE_NOPREFETCH

  Do not prefetch searched messages.

  
  SO_FREE

  Return the sort program to free storage after finishing.