1 /**
2  * @file libcomprex/directory.h Directory structures
3  *
4  * $Id: directory.h,v 1.19 2003/01/01 06:22:35 chipx86 Exp $
5  *
6  * @Copyright (C) 2001-2003 The GNUpdate Project.
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Library General Public
10  * License as published by the Free Software Foundation; either
11  * version 2 of the License, or (at your option) any later version.
12  *
13  * This library is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
16  * Library General Public License for more details.
17  *
18  * You should have received a copy of the GNU Library General Public
19  * License along with this library; if not, write to the
20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21  * Boston, MA  02111-1307, USA.
22  */
23 #ifndef _LIBCOMPREX_DIRECTORY_H_
24 #define _LIBCOMPREX_DIRECTORY_H_
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 typedef struct _CxFsNode        CxDirectory;     /**< CxDirectory */
31 typedef struct _CxDirectoryData CxDirectoryData; /**< Directory data. */
32 
33 #include <libcomprex/fsnode.h>
34 #include <libcomprex/file.h>
35 
36 /**
37  * The data specific to a directory node.
38  */
39 struct _CxDirectoryData
40 {
41 	char *physPath;           /**< Physical path to the directory */
42 
43 	CxFsNode *children;       /**< First child node.              */
44 	CxFsNode *lastChild;      /**< Last child node.               */
45 
46 	unsigned int subdirCount; /**< Number of subdirectories.      */
47 	unsigned int fileCount;   /**< Number of files.               */
48 };
49 
50 /**************************************************************************/
51 /** @name Structure (De)allocation Functions                              */
52 /**************************************************************************/
53 /*@{*/
54 
55 /**
56  * Creates a new CxDirectory structure.
57  *
58  * This does NOT create a new directory. For that, use cxMkDir().
59  *
60  * @return A new, empty CxDirectory structure.
61  *
62  * @see cxDestroyDirectory()
63  */
64 CxDirectory *cxNewDirectory(void);
65 
66 /**
67  * Destroys a CxDirectory structure.
68  *
69  * @param dir The CxDirectory to destroy.
70  *
71  * @see cxNewDirectory()
72  */
73 void cxDestroyDirectory(CxDirectory *dir);
74 
75 /*@}*/
76 
77 /**************************************************************************/
78 /** @name Attribute Modification Functions                                */
79 /**************************************************************************/
80 /*@{*/
81 
82 /**
83  * Sets the archive that owns the directory.
84  *
85  * This should only be used by libcomprex.
86  *
87  * @param dir     The directory.
88  * @param archive The archive that owns this directory.
89  *
90  * @see cxGetDirArchive()
91  */
92 void cxSetDirArchive(CxDirectory *dir, CxArchive *archive);
93 
94 /**
95  * Sets the specified directory's parent directory.
96  *
97  * @param dir    The directory.
98  * @param parent The parent directory.
99  *
100  * @see cxGetDirParent()
101  */
102 void cxSetDirParent(CxDirectory *dir, CxDirectory *parent);
103 
104 /**
105  * Sets the base directory name of this directory.
106  *
107  * @param dir  The directory.
108  * @param name The base directory name.
109  *
110  * @see cxGetDirName()
111  */
112 void cxSetDirName(CxDirectory *dir, const char *name);
113 
114 /**
115  * Sets the full physical path to the directory.
116  *
117  * @param dir  The directory.
118  * @param path The physical path to the directory.
119  *
120  * @see cxSetDirPath()
121  * @see cxGetDirPhysicalPath()
122  * @see cxGetDirPath()
123  */
124 void cxSetDirPhysicalPath(CxDirectory *dir, const char *path);
125 
126 /**
127  * Sets the mode of the specified directory.
128  *
129  * @param dir  The directory.
130  * @param mode The mode to be set.
131  *
132  * @see cxGetDirMode()
133  */
134 void cxSetDirMode(CxDirectory *dir, mode_t mode);
135 
136 /**
137  * Sets the group ID of the specified directory.
138  *
139  * @param dir  The directory.
140  * @param gid  The group ID.
141  *
142  * @see cxGetFileGid()
143  */
144 void cxSetDirGid(CxDirectory *dir, gid_t gid);
145 
146 /**
147  * Sets the user ID of the specified directory.
148  *
149  * @param dir  The directory.
150  * @param uid  The user ID.
151  *
152  * @see cxGetDirUid()
153  */
154 void cxSetDirUid(CxDirectory *dir, uid_t uid);
155 
156 /**
157  * Set the timestamp of the specified directory.
158  *
159  * @param dir  The directory.
160  * @param date The date/time timestamp in seconds since the epoch.
161  *
162  * @see cxGetDirDate()
163  */
164 void cxSetDirDate(CxDirectory *dir, time_t date);
165 
166 /**
167  * Sets whether or not the file is stored locally.
168  *
169  * If the directory is located online, or within an archive, this should be 0.
170  * Otherwise, this should be 1.
171  *
172  * @param dir     The directory.
173  * @param isLocal 1 if the file is stored locally; 0 otherwise.
174  *
175  * @see cxIsDirLocal()
176  */
177 void cxSetDirLocal(CxDirectory *dir, char isLocal);
178 
179 /*@}*/
180 
181 /**************************************************************************/
182 /** @name Attribute Retrieval Functions                                   */
183 /**************************************************************************/
184 /*@{*/
185 
186 /**
187  * Returns the archive that owns the specified directory.
188  *
189  * @param dir The directory.
190  *
191  * @return The archive that owns this directory.
192  *
193  * @see cxSetDirArchive()
194  */
195 CxArchive *cxGetDirArchive(CxDirectory *dir);
196 
197 /**
198  * Returns the specified directory's parent directory.
199  *
200  * @param dir The directory.
201  *
202  * @return The specified directory's parent directory.
203  *
204  * @see cxSetDirParent()
205  */
206 CxDirectory *cxGetDirParent(CxDirectory *dir);
207 
208 /**
209  * Returns the base directory name of the specified directory.
210  *
211  * @param dir The directory.
212  *
213  * @return The base directory name of the specified directory.
214  *
215  * @see cxSetDirName()
216  */
217 const char *cxGetDirName(CxDirectory *dir);
218 
219 /**
220  * Returns the full path name of the specified directory.
221  *
222  * @param dir The directory.
223  *
224  * @return The full path name.
225  *
226  * @see cxSetDirPath()
227  */
228 const char *cxGetDirPath(CxDirectory *dir);
229 
230 /**
231  * Returns the number of files in the specified directory.
232  *
233  * @param dir The directory.
234  *
235  * @return The number of files in the specified directory.
236  *
237  * @see cxGetSubDirCount()
238  */
239 unsigned int cxGetFileCount(CxDirectory *dir);
240 
241 /**
242  * Returns the full physical path to the directory.
243  *
244  * If the directory is non-local, this will be a temporary directory.
245  *
246  * @param dir The directory.
247  *
248  * @return The physical path to the directory.
249  *
250  * @see cxSetDirPhysicalPath()
251  * @see cxGetDirPath()
252  * @see cxSetDirPath()
253  */
254 const char *cxGetDirPhysicalPath(CxDirectory *dir);
255 
256 /**
257  * Return the mode of the specified directory.
258  *
259  * @param dir  The directory.
260  *
261  * @return The directory's mode.
262  *
263  * @see cxSetDirMode()
264  */
265 mode_t cxGetDirMode(CxDirectory *dir);
266 
267 /**
268  * Returns the user ID of the specified directory.
269  *
270  * @param dir  The directory.
271  *
272  * @return The user ID of the specified directory.
273  *
274  * @see cxSetDirUid()
275  */
276 uid_t cxGetDirUid(CxDirectory *dir);
277 
278 /**
279  * Returns the group ID of the specified directory.
280  *
281  * @param dir The directory.
282  *
283  * @returns The group ID of the specified directory.
284  *
285  * @see cxSetDirGid()
286  */
287 gid_t cxGetDirGid(CxDirectory *dir);
288 
289 /**
290  * Returns the timestamp of the specified directory.
291  *
292  * @param dir The directory.
293  *
294  * @return The date/time timestamp in seconds since the epoch.
295  *
296  * @see cxSetDirDate(CxDirectory *dir)
297  */
298 time_t cxGetDirDate(CxDirectory *dir);
299 
300 /**
301  * Returns whether or not the directory is stored locally
302  *
303  * If the directory is located online, or within an archive, this will be 0.
304  * Otherwise, this will be 1.
305  *
306  * @param dir The directory.
307  *
308  * @return 1 if the file is stored locally; 0 otherwise.
309  *
310  * @see cxSetDirLocal()
311  */
312 char cxIsDirLocal(CxDirectory *dir);
313 
314 /**
315  * Returns the number of subdirectories in the specified directory.
316  *
317  * @param dir The directory.
318  *
319  * @return The number of subdirectories in the specified directory.
320  *
321  * @see cxGetFileCount()
322  */
323 unsigned int cxGetSubDirCount(CxDirectory *dir);
324 
325 /*@}*/
326 
327 /**************************************************************************/
328 /** @name Directory Processing Functions                                  */
329 /**************************************************************************/
330 /*@{*/
331 
332 /**
333  * Returns the subdirectory specified in the path.
334  *
335  * @param base The base directory.
336  * @param path The path.
337  *
338  * @return The subdirectory, or @c NULL if not found.
339  *
340  * @see cxGetFile()
341  */
342 CxDirectory *cxGetDirectory(CxDirectory *base, const char *path);
343 
344 /**
345  * Returns the file specified in the path.
346  *
347  * @param base The base directory.
348  * @param path The path.
349  *
350  * @return The file, or @c NULL if not found.
351  *
352  * @see cxGetDirectory()
353  */
354 CxFile *cxGetFile(CxDirectory *base, const char *path);
355 
356 /*@}*/
357 
358 /**************************************************************************/
359 /** @name Directory Modification Functions                                */
360 /**************************************************************************/
361 /*@{*/
362 
363 /**
364  * Creates a directory.
365  *
366  * This is equivalent to mkdir -p. That is, it will create each directory
367  * in the path if they don't exist.
368  *
369  * @param base The base directory.
370  * @param path The path of directories to create.
371  *
372  * @return The inner-most subdirectory.
373  */
374 CxDirectory *cxMkDir(CxDirectory *base, const char *path);
375 
376 /**
377  * Adds a file to the directory.
378  *
379  * Note that this won't actually create a file in that directory.
380  * This just modifies the structure itself!
381  *
382  * The directory will claim the reference on @a file, and will delete
383  * the structure when @a dir is deleted. If you wish to keep @a file
384  * intact, you must claim a reference to it using CX_LINK().
385  *
386  * @param dir  The directory.
387  * @param file The file to add.
388  *
389  * @see CxFile
390  * @see cxDirAddSubDir()
391  * @see cxDirRemoveFile()
392  * @see cxDirRemoveSubDir()
393  */
394 void cxDirAddFile(CxDirectory *dir, CxFile *file);
395 
396 /**
397  * Adds a subdirectory to a directory.
398  *
399  * Note that this won't actually create a subdirectory in that directory.
400  * This just modifies the structure itself!
401  *
402  * The directory will claim the reference on @a subdir, and will delete
403  * the structure when @a dir is deleted. If you wish to keep @a subdir
404  * intact, you must claim a reference to it using CX_LINK().
405  *
406  * @param dir    The directory.
407  * @param subdir The subdirectory to add.
408  *
409  * @see CxDirectory
410  * @see cxDirAddFile()
411  * @see cxDirRemoveFile()
412  * @see cxDirRemoveSubDir()
413  */
414 void cxDirAddSubDir(CxDirectory *dir, CxDirectory *subdir);
415 
416 /**
417  * Removes a file from the directory.
418  *
419  * Note that this won't actually remove the file from the archive.
420  * This just modifies the structure itself!
421  *
422  * @param dir  The directory.
423  * @param file The file to remove.
424  *
425  * @see CxFile
426  * @see cxDirAddFile()
427  * @see cxDirAddSubDir()
428  * @see cxDirRemoveSubDir()
429  */
430 void cxDirRemoveFile(CxDirectory *dir, CxFile *file);
431 
432 /**
433  * Removes a subdirectory from the directory.
434  *
435  * Note that this won't actually remove the subdirectory from the archive.
436  * This just modifies the structure itself!
437  *
438  * @param dir    The directory.
439  * @param subdir The subdirectory to remove.
440  *
441  * @see CxFile
442  * @see cxDirAddFile()
443  * @see cxDirAddSubDir()
444  * @see cxDirRemoveFile()
445  */
446 void cxDirRemoveSubDir(CxDirectory *dir, CxDirectory *subdir);
447 
448 /*@}*/
449 
450 /**************************************************************************/
451 /** @name Iteration Functions                                             */
452 /**************************************************************************/
453 /*@{*/
454 
455 /**
456  * Returns the first file in the directory.
457  *
458  * @param dir The directory.
459  *
460  * @return The first file in the directory.
461  *
462  * @see cxGetFirstSubDir()
463  * @see cxGetNextFile()
464  * @see cxGetPreviousFile()
465  */
466 CxFile *cxGetFirstFile(CxDirectory *dir);
467 
468 /**
469  * Returns the first subdirectory in the directory.
470  *
471  * @param dir The directory.
472  *
473  * @return The first subdirectory in the directory.
474  *
475  * @see cxGetFirstFile()
476  * @see cxGetNextDir()
477  * @see cxGetPreviousDir()
478  */
479 CxDirectory *cxGetFirstSubDir(CxDirectory *dir);
480 
481 /**
482  * Returns the previous directory in a list of directories.
483  *
484  * @param dir The current directory.
485  *
486  * @return The previous directory in the list.
487  *
488  * @see cxGetFirstSubDir()
489  * @see cxGetNextDir()
490  */
491 CxDirectory *cxGetPreviousDir(CxDirectory *dir);
492 
493 /**
494  * Returns the next directory in a list of directories.
495  *
496  * @param dir The current directory.
497  *
498  * @return The next directory in the list.
499  *
500  * @see cxGetFirstSubDir()
501  * @see cxGetPreviousDir()
502  */
503 CxDirectory *cxGetNextDir(CxDirectory *dir);
504 
505 /*@}*/
506 
507 #ifdef __cplusplus
508 }
509 #endif
510 
511 #endif /* _LIBCOMPREX_DIRECTORY_H_ */
512 
513