1 #ifndef	maildirnewshared_h
2 #define	maildirnewshared_h
3 
4 /*
5 ** Copyright 2003-2004 Double Precision, Inc.
6 ** See COPYING for distribution information.
7 */
8 
9 #if	HAVE_CONFIG_H
10 #include	"config.h"
11 #endif
12 
13 #include	<sys/types.h>
14 
15 #if HAVE_SYS_STAT_H
16 #include	<sys/stat.h>
17 #endif
18 
19 #ifdef  __cplusplus
20 extern "C" {
21 #endif
22 
23 
24 /*
25 ** New-style shared folder support.
26 */
27 
28 extern int maildir_newshared_disabled;
29 	/*
30 	** Set this to 1 to effectively disable new-style shared folders.
31 	** The functions below will function normally, but as if there are
32 	** no shared folders configured (the top level configuration file is
33 	** empty).
34 	*/
35 
36 /*
37 ** Read the shared folder index file, which points to everyone else's
38 ** maildirs.
39 **
40 ** maildir_newshared_enum() invokes the callback function for each listed
41 ** shared folder.
42 ** The callback function receives a structure with the following fields:
43 **
44 ** Name, home directory, maildir directory, uid/gid of the shared account, the
45 ** pass-through argument.
46 **
47 ** The maildir directory will get defaulted to "./Maildir", if not
48 ** specified.
49 **
50 ** A NULL home directory means that the administrator configured a hierarchy
51 ** of shared folders, and the maildir argument points to another shared
52 ** folder hierarchy, whose name is given.
53 **
54 ** A nonzero return from the callback function terminates the enumeration,
55 ** and maildir_newshared_enum itself returns non-zero.  A zero return
56 ** continues the enumeration.  After the entire list is enumerated
57 ** maildir_newshared_enum returns 0.
58 **
59 ** maildir_newshared_enum returns -1 if indexfile cannot be opened.
60 */
61 
62 struct maildir_newshared_enum_cb {
63 	off_t startingpos; /* In index file */
64 	const char *name;
65 	const char *homedir;
66 	const char *maildir;
67 	uid_t uid;
68 	gid_t gid;
69 	void *cb_arg;
70 	const char *indexfile;	/* Original index file */
71 	FILE *fp;		/* INTERNAL USE */
72 	size_t linenum;		/* INTERNAL USE */
73 };
74 
75 /*
76 ** Open an index file.  Returns 0 on success, -1 on failure.
77 ** Initializes maildir_newshared_enum_cb structure.
78 */
79 
80 int maildir_newshared_open(const char *indexfile,
81 			   struct maildir_newshared_enum_cb *info);
82 
83 /*
84 ** Read next record from the index file.  Invokes the callback function,
85 ** and returns the return value from the callback function.
86 **
87 ** If reached end of index file, sets *eof to non-zero and returns 0.
88 */
89 
90 int maildir_newshared_next(struct maildir_newshared_enum_cb *info,
91 			   int *eof,
92 			   int (*cb_func)(struct maildir_newshared_enum_cb *),
93 			   void *cb_arg);
94 
95 /*
96 ** Same as maildir_newshared_next, but seeks to the given offset first.
97 */
98 
99 int maildir_newshared_nextAt(struct maildir_newshared_enum_cb *info,
100 			     int *eof,
101 			     int (*cb_func)(struct maildir_newshared_enum_cb*),
102 			     void *cb_arg);
103 
104 /* Close it */
105 
106 void maildir_newshared_close(struct maildir_newshared_enum_cb *info);
107 
108 int maildir_newshared_enum(const char *indexfile,
109 			   int (*cb_func)(struct maildir_newshared_enum_cb *),
110 			   void *cb_arg);
111 
112 
113 /****************************************************************
114  **
115  ** High level access to the shared folder index
116  **
117  ****************************************************************/
118 
119 /*
120 ** Application defines this function that returns the filename of the
121 ** top level shared cache index file:
122 */
123 extern const char *maildir_shared_index_file();
124 
125 /*
126 ** Anticipate common shared folder index usage patterns, buffer levels
127 ** of index cache files in memory.
128 **
129 ** An entire shared folder index cache file is loaded into the following
130 ** structure:
131 */
132 
133 struct maildir_shindex_cache {
134 	struct maildir_shindex_cache *next; /* Next level cached, if any */
135 	char *hierarchy; /* Always "" for the topmost level,
136 			 ** then "foo", "bar", etc... */
137 
138 	struct maildir_newshared_enum_cb indexfile; /* Opened index file */
139 
140 	size_t nrecords; /* # of cached records */
141 	struct maildir_shindex_record *records; /* The cached array */
142 };
143 
144 struct maildir_shindex_record {
145 	char *name;
146 	off_t offset; /* Its starting position in indexfile, get rest of data
147 		      ** there.
148 		      */
149 };
150 
151 /*
152 ** The following function finds a shared index file for the following
153 ** subhierarchy.
154 **
155 ** The subhierarchy is references by its parent loaded hierarchy, and the
156 ** subhierarchy name.
157 **
158 ** If parent's next->hierarchy happens to be the same as the name of the
159 ** requested hierarchy, it's already loaded, and nothing needs to be done.
160 **
161 */
162 
163 struct maildir_shindex_cache *
164 maildir_shared_cache_read(struct maildir_shindex_cache *parent,
165 			  const char *indexfile,
166 			  const char *subhierarchy);
167 /*
168 ** Set all three argument to NULL in order to cache the topmost cache level.
169 **
170 ** Else set 'parent' to an existing entry, indexfile to the index file
171 ** (obtained from maildir_newshared_next's callback), and subhierarchy
172 ** to the subhierarchy name (same source) to read a subhierarchy.
173 **
174 */
175 
176 
177 #ifdef  __cplusplus
178 }
179 #endif
180 
181 
182 #endif
183