Miscellaneous mailbox and message functions

• mail_ping

  long mail_ping(MAILSTREAM *stream);
  

  
  stream

  String to ping.

  This function pings the stream to see if it is still active. It may discover new mail; this is the preferred method for a periodic new mail check as well as a keep alive for servers which have an inactivity timeout. It returns T if the stream is still alive, NIL otherwise.

  If new mail is found, the application's mm_exists function is called with the newly-determined number of messages in the mailbox.

• mail_check

  void mail_check(MAILSTREAM *stream);
  

  
  stream

  Stream to checkpoint.

  This function causes a mailstore-defined checkpoint of the mailbox. This may include such things as a writeback to disk, a check for flag changes in a shared mailbox, and so on. It is not a check for new mail; mail_ping performs this function (as potentially does any other function). The status of the check is passed to the application via the mm_log facility.

• mail_expunge

  void mail_expunge (MAILSTREAM *stream);
  

  
  stream

  String to expunge.

  This function causes an expunge (permanent removal of messages which are marked as deleted) of the mailbox. The application's mm_expunged function is called for each message that has been expunged. The application's mm_exists function is called at the start and end of the expunge to ensure synchronization. The status of the expunge is passed to the application via the mm_log facility.

  Note that the decrementing of msgno's for subsequent messages happens immediately; for example, if three consecutive messages starting at msgno 5 are expunged, mm_expunged will be called three times with a msgno of 5.

• mail_copy

  long mail_copy(MAILSTREAM *stream, char *sequence, char *mailbox);
  
  long mail_move(MAILSTREAM *stream, char *sequence, char *mailbox);
  
  long mail_copy_full(MAILSTREAM *stream, char *sequence, char *mailbox,
       long options);
  

  
  stream

  Stream to copy.

  
  sequence

  IMAP-format set of message numbers.

  
  mailbox

  Destination mailbox name.

  
  options

  Option flags.

  These functions cause the messages in the specified sequence to be copied to the specified mailbox. T is returned if the copy is successful. mail_move is equivalent to setting CP_MOVE in the options.

  If there is any problem in copying, a message will be passed to the application via the mm_log facility and the function returns NIL. No copying is actually done in this case.

  Note that the mailbox must be on the same host as the stream and is a mailbox of the type of the source mailbox only.

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

  
  CP_UID

  The sequence argument contains UIDs instead of sequence numbers.

  
  CP_MOVE

  Delete the messages from the current mailbox after copying to the destination.

• mail_append

  long mail_append(MAILSTREAM *stream, char *mailbox, STRING *message);
  
  long mail_append_full(MAILSTREAM *stream, char *mailbox, char *flags,
       char *date, STRING *message);
  

  
  stream

  Stream to use if non-NIL (in the IMAP case).

  
  mailbox

  Destination mailbox name.

  
  flags

  Flags to set on message if non-NIL.

  
  date

  Internal date (received date) to set on message if non-NIL.

  
  message

  String structure of message to write.

  These functions write the message in the string structure to the destination mailbox, along with the flags and date if specified. This is useful in those cases where you cannot use mail_copy, for example, when copying from one server to another; you can always fetch the message and then mail_append it to the destination. It may also be useful for maintaining an outbox of your outgoing mail.

• mail_gc

  void mail_gc(MAILSTREAM *stream, long gcflags);
  

  
  stream

  Stream to GC if non-NIL (else GC's all streams).

  
  gcflags

  Option flags.

  This function garbage collects (purges) the cache of entries of a specific type. Some drivers do not allow purging of particular cache types, and an attempt to do so is ignored.

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

  
  GC_ELT

  Message cache elements.

  
  GC_ENV

  ENVELOPEs and BODYs.

  
  GC_TEXTS

  Cached texts.