Back to index

courier  0.68.2
maildirnewshared.h
Go to the documentation of this file.
00001 #ifndef       maildirnewshared_h
00002 #define       maildirnewshared_h
00003 
00004 /*
00005 ** Copyright 2003-2004 Double Precision, Inc.
00006 ** See COPYING for distribution information.
00007 */
00008 
00009 #if    HAVE_CONFIG_H
00010 #include      "config.h"
00011 #endif
00012 
00013 #include      <sys/types.h>
00014 
00015 #if HAVE_SYS_STAT_H
00016 #include      <sys/stat.h>
00017 #endif
00018 
00019 #ifdef  __cplusplus
00020 extern "C" {
00021 #endif
00022 
00023 
00024 /*
00025 ** New-style shared folder support.
00026 */
00027 
00028 extern int maildir_newshared_disabled;
00029        /*
00030        ** Set this to 1 to effectively disable new-style shared folders.
00031        ** The functions below will function normally, but as if there are
00032        ** no shared folders configured (the top level configuration file is
00033        ** empty).
00034        */
00035 
00036 /*
00037 ** Read the shared folder index file, which points to everyone else's
00038 ** maildirs.
00039 **
00040 ** maildir_newshared_enum() invokes the callback function for each listed
00041 ** shared folder.
00042 ** The callback function receives a structure with the following fields:
00043 **
00044 ** Name, home directory, maildir directory, uid/gid of the shared account, the
00045 ** pass-through argument.
00046 **
00047 ** The maildir directory will get defaulted to "./Maildir", if not
00048 ** specified.
00049 **
00050 ** A NULL home directory means that the administrator configured a hierarchy
00051 ** of shared folders, and the maildir argument points to another shared
00052 ** folder hierarchy, whose name is given.
00053 **
00054 ** A nonzero return from the callback function terminates the enumeration,
00055 ** and maildir_newshared_enum itself returns non-zero.  A zero return
00056 ** continues the enumeration.  After the entire list is enumerated
00057 ** maildir_newshared_enum returns 0.
00058 **
00059 ** maildir_newshared_enum returns -1 if indexfile cannot be opened.
00060 */
00061 
00062 struct maildir_newshared_enum_cb {
00063        off_t startingpos; /* In index file */
00064        const char *name;
00065        const char *homedir;
00066        const char *maildir;
00067        uid_t uid;
00068        gid_t gid;
00069        void *cb_arg;
00070        const char *indexfile;      /* Original index file */
00071        FILE *fp;            /* INTERNAL USE */
00072        size_t linenum;             /* INTERNAL USE */
00073 };
00074 
00075 /*
00076 ** Open an index file.  Returns 0 on success, -1 on failure.
00077 ** Initializes maildir_newshared_enum_cb structure.
00078 */
00079 
00080 int maildir_newshared_open(const char *indexfile,
00081                         struct maildir_newshared_enum_cb *info);
00082 
00083 /*
00084 ** Read next record from the index file.  Invokes the callback function,
00085 ** and returns the return value from the callback function.
00086 **
00087 ** If reached end of index file, sets *eof to non-zero and returns 0.
00088 */
00089 
00090 int maildir_newshared_next(struct maildir_newshared_enum_cb *info,
00091                         int *eof,
00092                         int (*cb_func)(struct maildir_newshared_enum_cb *),
00093                         void *cb_arg);
00094 
00095 /*
00096 ** Same as maildir_newshared_next, but seeks to the given offset first.
00097 */
00098 
00099 int maildir_newshared_nextAt(struct maildir_newshared_enum_cb *info,
00100                           int *eof,
00101                           int (*cb_func)(struct maildir_newshared_enum_cb*),
00102                           void *cb_arg);
00103 
00104 /* Close it */
00105 
00106 void maildir_newshared_close(struct maildir_newshared_enum_cb *info);
00107 
00108 int maildir_newshared_enum(const char *indexfile,
00109                         int (*cb_func)(struct maildir_newshared_enum_cb *),
00110                         void *cb_arg);
00111 
00112 
00113 /****************************************************************
00114  **
00115  ** High level access to the shared folder index
00116  **
00117  ****************************************************************/
00118 
00119 /*
00120 ** Application defines this function that returns the filename of the
00121 ** top level shared cache index file:
00122 */
00123 extern const char *maildir_shared_index_file();
00124 
00125 /*
00126 ** Anticipate common shared folder index usage patterns, buffer levels
00127 ** of index cache files in memory.
00128 **
00129 ** An entire shared folder index cache file is loaded into the following
00130 ** structure:
00131 */
00132 
00133 struct maildir_shindex_cache {
00134        struct maildir_shindex_cache *next; /* Next level cached, if any */
00135        char *hierarchy; /* Always "" for the topmost level,
00136                       ** then "foo", "bar", etc... */
00137 
00138        struct maildir_newshared_enum_cb indexfile; /* Opened index file */
00139 
00140        size_t nrecords; /* # of cached records */
00141        struct maildir_shindex_record *records; /* The cached array */
00142 };
00143 
00144 struct maildir_shindex_record {
00145        char *name;
00146        off_t offset; /* Its starting position in indexfile, get rest of data
00147                     ** there.
00148                     */
00149 };
00150 
00151 /*
00152 ** The following function finds a shared index file for the following
00153 ** subhierarchy.
00154 **
00155 ** The subhierarchy is references by its parent loaded hierarchy, and the
00156 ** subhierarchy name.
00157 **
00158 ** If parent's next->hierarchy happens to be the same as the name of the
00159 ** requested hierarchy, it's already loaded, and nothing needs to be done.
00160 **
00161 */
00162 
00163 struct maildir_shindex_cache *
00164 maildir_shared_cache_read(struct maildir_shindex_cache *parent,
00165                        const char *indexfile,
00166                        const char *subhierarchy);
00167 /*
00168 ** Set all three argument to NULL in order to cache the topmost cache level.
00169 **
00170 ** Else set 'parent' to an existing entry, indexfile to the index file
00171 ** (obtained from maildir_newshared_next's callback), and subhierarchy
00172 ** to the subhierarchy name (same source) to read a subhierarchy.
00173 **
00174 */
00175 
00176 
00177 #ifdef  __cplusplus
00178 }
00179 #endif
00180 
00181 
00182 #endif