#ifndef _FOLDER_H_09506d1e_
#define _FOLDER_H_09506d1e_

struct mm_folder;
typedef struct mm_folder FOLDER;

/* Wait/nowait flag to (eg) folder_lock. */
#define FOLDER_WAIT      0x00000001
#define FOLDER_NOWAIT    0x00000002
#define FOLDER_SHARED    0x00000004
#define FOLDER_EXCLUSIVE 0x00000008

/* Arguments to folder_msg() */
#define FM_CUR  1
#define FM_NEXT 2
#define FM_PREV 3

/* Error returns from folder_msg() */
#define FOLDER_SYSCALLERR (-1) /* consult errno */
#define FOLDER_NOSUCH     (-2) /* no such message exists */
#define FOLDER_INVARG     (-3) /* invalid argument */

#include "message.h"

/* Look up a folder, given its user-level string name.  Returns 0 for
   failure, nonzero for success; if success, returns the FOLDER pointer
   by reference.  If the third arg is non-nil, returns a pointer to the
   character that terminated the lookup (this happens regardless of
   success or failure).  The folder is returned unlocked. */
extern int folder_lookup(const char *, FOLDER **, char **);

/* Skip over a folder name, returning a pointer to the character that
   terminated the scan. */
extern char *folder_skipname(const char *);

/* Locks the folder.  Returns -1 and sets errno for failure, 0 for success. */
extern int folder_lock(FOLDER *, unsigned int);

/* Unlocks the lock set by folder_lock().  Nop if not locked. */
extern void folder_unlock(FOLDER *);

/* Hardlinks an existing message file into the folder, allocating a new
   message number.  Returns the MESSAGE object corresponding to it.  The
   folder must be locked; the new message is neither locked nor opened.
   On failure (eg, EXDEV), returns nil and sets errno.  The pathname can
   be arbitrary. */
extern MESSAGE *folder_new_link(FOLDER *, const char *);

/* Creates a new message in the folder, returning the MESSAGE object
   corresponding to it.  The folder must be locked; the new message is
   opened for read/write and locked for exclusive access upon return.
   On failure, returns nil and sets errno. */
extern MESSAGE *folder_new_create(FOLDER *);

/* Check that the folder is locked; if not, bugcheck, reporting the second
   argument for help identifying the problem. */
extern void folder_must_be_locked(FOLDER *, const char *);

/* Like folder_must_be_locked, but the folder must remain locked until a
   folder_may_be_unlocked call is done on the return value.  (The latter
   must be done eventually or memory will be leaked.) */
extern void *folder_must_remain_locked(FOLDER *, const char *);

/* Releases a must-remain-locked hold set with folder_must_remain_locked. */
extern void folder_may_be_unlocked(FOLDER *, void *);

/* Returns the user-level string name of the folder. */
extern const char *folder_name(FOLDER *);

/* Returns the pathname of the folder's directory. */
extern const char *folder_path(FOLDER *);

/* Returns (part of) the list of messages present in a folder.  Call is
   folder_get_msgnos(folder,count,off,vec), in which vec is a place to
   return the message numbers, count is the number of elements available
   in vec, and off is an offset, indicating how many message numbers into
   the list of existing messages to return.  The folder must be locked.
   If off is <0, folder_get_msgnos() behaves as if it were zero, except
   that if off>=0 and the folder has changed since the last call with off<0,
   -1 is returned.  (This normally cannot happen unless the folder has been
   unlocked and relocked since that previous call.)  If off is greater than
   the number of messages in the folder, also, -1 is returned.  Otherwise,
   up to count message numbers, starting at the offth message, are returned
   to vec.  Return value, if not -1 due to the rules above, is the total
   message count of the folder.  The caller can depend on returnvalue - off
   values, maximum count, having been copied into vec in this case.  If
   count is zero, vec may be nil; if -1 is returned, no copying is done. */
extern int folder_get_msgnos(FOLDER *, int, int, int *);

/* Looks up one of the folder's special messages, cur, next, or prev,
   according as the argument is FM_CUR, FM_NEXT, or FM_PREV.  Return value
   is a message number, if positive, or a negative value, which will be one
   of the FOLDER_ errors defined above.  The folder must be locked.
   If the sequence for the desired message doesn't exist or is empty, then:
	FM_PREV: return FOLDER_NOSUCH
	FM_CUR: if the folder contains any messages, return the first;
		otherwise return FOLDER_NOSUCH
	FM_NEXT: if the "cur" sequence is also empty, as for FM_CUR;
		otherwise return FOLDER_NOSUCH
   */
extern int folder_msg(FOLDER *, int);

/* Some number of messages have been deleted from a folder; update the
   folder's sequences (including cur &c) to take this into account.  Entries
   in the vector of message numbers do not have to be valid message numbers;
   in particular, -1 is harmless. */
extern void folder_deleted_messages(FOLDER *, const int *, int);

#endif