Mailbox Access Functions void mail_list (MAILSTREAM *stream,char *ref,char *pat); void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); stream if non-NIL, stream to use ref mailbox reference string pat mailbox pattern string contents contents to search This function returns a list of mailboxes via the mm_list() callback. The reference is applied to the pattern in an implementation dependent fashion, and the resulting string is used to search for matching mailbox names. "*" is a wildcard which matches zero or more characters; "%" is a variant which does not descend a hierarchy level. Read the IMAP specification for more information. mail_scan() is a variant which takes a string to search for in the text of the mailbox. The string is a free-text string, without regard for message boundaries, and thus the choice of strings must be made with care. void mail_lsub (MAILSTREAM *stream,char *ref,char *pat); stream if non-NIL, stream to use ref mailbox reference string pat mailbox pattern string This function returns a list of subscribed mailboxes via the mm_lsub() callback. The reference is applied to the pattern in an implementation dependent fashion, and the resulting string is used to search for matching mailbox names in the subscription list. "*" is a wildcard which matches zero or more characters; "%" is a variant which does not descend a hierarchy level. Read the IMAP specification for more information. long mail_subscribe (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function adds the given name to the subscription list. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. long mail_unsubscribe (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function removes the given name from the subscription list. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. long mail_create (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function creates a mailbox with the given name. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to create INBOX or a mailbox name which already exists. long mail_delete (MAILSTREAM *stream,char *mailbox); stream if non-NIL, stream to use mailbox mailbox name This function deletes the named mailbox. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to delete INBOX or a mailbox name which does not already exist. long mail_rename (MAILSTREAM *stream,char *old,char *newname); stream if non-NIL, stream to use old existing mailbox name newname new (not yet existing) mailbox name This function renames the old mailbox to the new mailbox name. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. It is an error to reanme a mailbox that does not exist, or rename a mailbox to a name that already exists. It is permitted to rename INBOX; a new empty INBOX is created in its place. long mail_status (MAILSTREAM *stream,char *mbx,long flags); stream if non-NIL, stream to use mbx mailbox name flags option flags This function returns the status of the given mailbox name via the mm_status() callback. It returns T if successful, NIL if unsuccessful. If unsuccessful, an error message is returned via the mm_log() callback. The options are a bit mask with one or more of the following, indicating the data which should be returned. SA_MESSAGES number of messages in the mailbox SA_RECENT number of recent messages in the mailbox SA_UNSEEN number of unseen messages in the mailbox SA_UIDNEXT next UID value to be assigned SA_UIDVALIDITY UID validity value Note that, depending upon implementation, some of these values may be more costly to get than others. For example, calculating the number of unseen messages may require opening the mailbox and scanning all of the message flags. A mail_status() call should thus be used with option flags specifying only the data that is actually needed. MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options); oldstream if non-NIL, stream to recycle name mailbox name to open options option flags. This function opens the mailbox and if successful returns a stream suitable for use by the other MAIL functions. If oldstream is non-NIL, an attempt is made to reuse oldstream as the stream for this mailbox; this is useful when you want to open another mailbox to the same IMAP or NNTP server without having to open a new connection. Doing this will close the previously open mailbox. The options are a bit mask with one or more of the following: OP_DEBUG Log IMAP protocol telemetry through mm_debug() OP_READONLY Open mailbox read-only. OP_ANONYMOUS Don't use or update a .newsrc file for news. OP_SHORTCACHE Don't cache envelopes or body structures OP_SILENT Don't pass mailbox events (internal use only) OP_PROTOTYPE Return the "prototype stream" for the driver associated with this mailbox instead of opening the stream OP_HALFOPEN For IMAP and NNTP names, open a connection to the server but don't open a mailbox. OP_EXPUNGE Silently expunge the oldstream before recycling NIL is returned if this function fails for any reason. MAILSTREAM *mail_close (MAILSTREAM *stream); MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options); stream stream to close options option flags This function closes the MAIL stream and frees all resources associated with it that it may have created (subject to any handles existing). The options for mail_close_full() are a bit mask with one or more of the following: CL_EXPUNGE Silently expunge before closing This function always returns NIL, so it can be used as: stream = mail_close (stream);