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