1 /*****************************************************************************/ 2 /* Software Testing Automation Framework (STAF) */ 3 /* (C) Copyright IBM Corp. 2001 */ 4 /* */ 5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ 6 /*****************************************************************************/ 7 8 #ifndef STAF_FileSystem 9 #define STAF_FileSystem 10 11 #include "STAF.h" 12 #include "STAFString.h" 13 14 #ifdef __cplusplus 15 extern "C" 16 { 17 #endif 18 19 /*****************/ 20 /* C Definitions */ 21 /*****************/ 22 23 /**********************************************/ 24 /* Enumeration constants and type definitions */ 25 /**********************************************/ 26 27 typedef enum STAFFSCaseSensitive_e 28 { 29 kSTAFFSCaseDefault = 0, 30 kSTAFFSCaseSensitive = 1, 31 kSTAFFSCaseInsensitive = 2 32 } STAFFSCaseSensitive_t; 33 34 typedef enum STAFFSSortBy_e 35 { 36 kSTAFFSNoSort = 0, 37 kSTAFFSSortByName = 1, 38 kSTAFFSSortBySize = 2, 39 kSTAFFSSortByModTime = 3 40 } STAFFSSortBy_t; 41 42 typedef enum STAFFSDirectoryCreateMode_e 43 { 44 kSTAFFSCreateDirOnly = 0, 45 kSTAFFSCreatePath = 1 46 } STAFFSDirectoryCreateMode_t; 47 48 typedef enum STAFFSInfoType_e 49 { 50 kSTAFFSPathSep = 0, 51 kSTAFFSFileSep = 1, 52 kSTAFFSLineSep = 2, 53 kSTAFFSCaseSensitivity = 3 54 } STAFFSInfoType_t; 55 56 typedef enum STAFFSEntryType_e 57 { 58 kSTAFFSFile = 0x00000001, 59 kSTAFFSDirectory = 0x00000002, 60 kSTAFFSPipe = 0x00000004, 61 kSTAFFSSocket = 0x00000008, 62 kSTAFFSSymLink = 0x00000010, 63 kSTAFFSCharDev = 0x00000020, 64 kSTAFFSBlkDev = 0x00000040, 65 kSTAFFSSpecialDirectory = 0x00000080, 66 kSTAFFSOther = 0x80000000, 67 kSTAFFSNone = 0x00000000, 68 kSTAFFSNormal = 0x00000003, 69 kSTAFFSAll = 0xFFFFFFFF 70 } STAFFSEntryType_t; 71 72 typedef enum STAFFSComparePathResult_e 73 { 74 kSTAFFSDoesNotIncludePath = 0, 75 kSTAFFSDoesIncludePath = 1, 76 kSTAFFSSamePath = 2 77 } STAFFSComparePathResult_t; 78 79 typedef struct STAFFSEnumHandleImpl *STAFFSEnumHandle_t; 80 typedef struct STAFFSEntryImpl *STAFFSEntry_t; 81 typedef struct STAFFSOSFileLockImpl *STAFFSOSFileLock_t; 82 83 /*****************************************************************************/ 84 /* General File System APIs */ 85 /*****************************************************************************/ 86 87 /*****************************************************************************/ 88 /* STAFFSInfo - Returns information about the OS's file system */ 89 /* */ 90 /* Accepts: (Out) Pointer to return data */ 91 /* (In) The type of information to retrieve */ 92 /* */ 93 /* Returns: Standard return codes */ 94 /* */ 95 /* Notes : 1) The types kSTAFFSPathSep, kSTAFFSFileSep, and kSTAFFSLineSep */ 96 /* return data of type STAFString_t. You are responsible for */ 97 /* call STAFStringDestruct on these returned strings. */ 98 /* 2) The type kSTAFFSCaseSensitivity returns data of type */ 99 /* STAFFSCaseSensitive_t. */ 100 /*****************************************************************************/ 101 STAFRC_t STAFFSInfo(void *info, STAFFSInfoType_t infoType); 102 103 104 /*****************************************************************************/ 105 /* STAFFSStringMatchesWildcards - Determines whether a given string matches */ 106 /* a given wildcard string */ 107 /* */ 108 /* Accepts: (In) String to check */ 109 /* (In) String containg wildcards */ 110 /* (In) Case sensitivity indicator */ 111 /* (Out) Result of comparison (0 = no match, 1 = matches) */ 112 /* */ 113 /* Returns: Standard return codes */ 114 /* */ 115 /* Notes : 1) Two wildcard characters are understood. '*' matches zero or */ 116 /* more characters. '?' matches one single character. */ 117 /*****************************************************************************/ 118 STAFRC_t STAFFSStringMatchesWildcards(STAFStringConst_t stringToCheck, 119 STAFStringConst_t wildcardString, 120 STAFFSCaseSensitive_t sensitive, 121 unsigned int *matches); 122 123 /*****************************************************************************/ 124 /* STAFFSComparePaths - Compares two path names after "normalizing" them. */ 125 /* Checks if path1 includes (starts with) path2 or if */ 126 /* path1 is the same as path2. */ 127 /* */ 128 /* Accepts: (In) Path name 1 */ 129 /* (In) Path name 2 */ 130 /* (In) Case sensitivity indicator */ 131 /* (Out) Compare result: */ 132 /* - kSTAFFSDoesNotIncludePath (path1 does not include path2) */ 133 /* - kSTAFFSDoesIncludePath (path1 includes path2) */ 134 /* - kSTAFFSSamePath (path1 and path2 specify the same path) */ 135 /* */ 136 /* Returns: Standard return codes */ 137 /* */ 138 /* Examples: */ 139 /* */ 140 /* 1) If called this API passing in the following arguments: */ 141 /* pathName1: C:/temp/dir1/dir2 */ 142 /* pathName2: C:/temp/dir2 */ 143 /* this API would set result to kSTAFFSDoesNotIncludePath */ 144 /* */ 145 /* 2) If called this API passing in the following arguments: */ 146 /* pathName1: C:/temp/dir1/dir2 */ 147 /* pathName2: C:/temp -OR- C:/temp/dir1 */ 148 /* this API would set result to kSTAFFSDoesIncludePath */ 149 /* */ 150 /* 3) If called this API passing in the following arguments: */ 151 /* pathName1: C:/temp/dir1/dir2 */ 152 /* pathName2: C:/temp/dir1/dir2 */ 153 /* this API would set result to kSTAFFSSamePath */ 154 /*****************************************************************************/ 155 STAFRC_t STAFFSComparePaths(STAFStringConst_t pathName1, 156 STAFStringConst_t pathName2, 157 STAFFSCaseSensitive_t sensitive, 158 STAFFSComparePathResult_t *result); 159 160 /*****************************************************************************/ 161 /* Path APIs */ 162 /*****************************************************************************/ 163 /* In general, any STAFString_t returned from an API must be freed by the */ 164 /* caller. No STAFStringConst_t passed into an API will be freed. */ 165 /*****************************************************************************/ 166 167 /*****************************************************************************/ 168 /* STAFFSAssemblePath - Generates a path string from component pieces */ 169 /* */ 170 /* Accepts: (Out) Pointer to the return string */ 171 /* (In) A string representing the root of the path */ 172 /* (In) The number of directory strings */ 173 /* (In) An array of strings representing directories */ 174 /* (In) A string representing the name of the file system entry */ 175 /* (In) A string representing the extension of the file system */ 176 /* entry */ 177 /* */ 178 /* Returns: Standard return codes */ 179 /*****************************************************************************/ 180 STAFRC_t STAFFSAssemblePath(STAFString_t *path, STAFStringConst_t root, 181 unsigned int numDirs, STAFStringConst_t *dirs, 182 STAFStringConst_t name, 183 STAFStringConst_t extension); 184 185 186 /*****************************************************************************/ 187 /* STAFFSDisassemblePath - Breaks a path string into its component pieces */ 188 /* */ 189 /* Accepts: (In) The path string to disassemble */ 190 /* (Out) Pointer to the string representing the root of the path */ 191 /* (Out) Pointer to the number of directory strings */ 192 /* (Out) Pointer to an array of strings representing the */ 193 /* directories */ 194 /* (Out) Pointer to the string representing the name of the file */ 195 /* system entry */ 196 /* (Out) Pointer to the string representing the extension of the */ 197 /* file system entry */ 198 /* */ 199 /* Returns: Standard return codes */ 200 /* */ 201 /* Notes : 1) Remember to free the directory array with */ 202 /* STAFFSFreePathDirs() */ 203 /*****************************************************************************/ 204 STAFRC_t STAFFSDisassemblePath(STAFStringConst_t path, STAFString_t *root, 205 unsigned int *numDirs, STAFString_t **dirs, 206 STAFString_t *name, STAFString_t *extension); 207 208 209 /*****************************************************************************/ 210 /* STAFFSFreePathDirs - Frees up the the memory associated with the array */ 211 /* of STAFString_t returned from STAFFSDissassemblePath */ 212 /* */ 213 /* Accepts: (In) Pointer to the array of STAFString_t */ 214 /* */ 215 /* Returns: Standard return codes */ 216 /* */ 217 /* Notes : 1) You are still responsible for freeing the individual */ 218 /* STAFString_t that are in the array. This function simply */ 219 /* frees the memory associated with the array itself. */ 220 /*****************************************************************************/ 221 STAFRC_t STAFFSFreePathDirs(STAFString_t *dirs); 222 223 224 /*****************************************************************************/ 225 /* File System Entry APIs */ 226 /*****************************************************************************/ 227 228 /*****************************************************************************/ 229 /* STAFFSExists - Determines whether a given file system entry exists */ 230 /* */ 231 /* Accepts: (In) Path string */ 232 /* (Out) Pointer to unsigned int indicating if the entry exists */ 233 /* (0 = no, 1 = yes) */ 234 /* (Out) Pointer to unsigned int indicating operating system error */ 235 /* */ 236 /* Returns: Standard return codes */ 237 /*****************************************************************************/ 238 STAFRC_t STAFFSExists(STAFStringConst_t path, unsigned int *exists, 239 unsigned int *osRC); 240 241 242 /*****************************************************************************/ 243 /* STAFFSGetEntry - Retrives an entry object representing the file system */ 244 /* entry */ 245 /* */ 246 /* Accepts: (In) Path string */ 247 /* (Out) Pointer to the file system entry */ 248 /* (Out) Pointer to unsigned int indicating operating system error */ 249 /* */ 250 /* Returns: Standard return codes */ 251 /*****************************************************************************/ 252 STAFRC_t STAFFSGetEntry(STAFStringConst_t path, STAFFSEntry_t *entry, 253 unsigned int *osRC); 254 255 256 /*****************************************************************************/ 257 /* STAFFSEntryGetPathString - Gets the path string associated with an entry */ 258 /* */ 259 /* Accepts: (In) File system entry */ 260 /* (Out) Pointer to constant path string */ 261 /* (Out) Pointer to unsigned int indicating operating system error */ 262 /* */ 263 /* Returns: Standard return codes */ 264 /* */ 265 /* Notes : 1) This API returns a canonical path string. This is not */ 266 /* necessarily the same string as used in STAFFSGetEntry(). */ 267 /*****************************************************************************/ 268 STAFRC_t STAFFSEntryGetPathString(STAFFSEntry_t entry, 269 STAFStringConst_t *pathString, 270 unsigned int *osRC); 271 272 273 /*****************************************************************************/ 274 /* STAFFSEntryGetType - Gets the type associated with an entry */ 275 /* */ 276 /* Accepts: (In) File system entry */ 277 /* (Out) Pointer to entry type */ 278 /* (Out) Pointer to unsigned int indicating operating system error */ 279 /* */ 280 /* Returns: Standard return codes */ 281 /*****************************************************************************/ 282 STAFRC_t STAFFSEntryGetType(STAFFSEntry_t entry, STAFFSEntryType_t *type, 283 unsigned int *osRC); 284 285 286 /*****************************************************************************/ 287 /* STAFFSEntryGetSize - Gets the size associated with an entry */ 288 /* */ 289 /* Accepts: (In) File system entry */ 290 /* (Out) Pointer to upper word of size */ 291 /* (Out) Pointer to lower word of size */ 292 /* (Out) Pointer to unsigned int indicating operating system error */ 293 /* */ 294 /* Returns: Standard return codes */ 295 /* */ 296 /* Notes : 1) The size is returned as two 32-bit quantities representing a */ 297 /* 64-bit quantity */ 298 /*****************************************************************************/ 299 STAFRC_t STAFFSEntryGetSize(STAFFSEntry_t entry, unsigned int *upperSize, 300 unsigned int *lowerSize, unsigned int *osRC); 301 302 303 /*****************************************************************************/ 304 /* STAFFSEntryGetSize64 - Gets the size associated with an entry */ 305 /* */ 306 /* Accepts: (In) File system entry */ 307 /* (Out) Pointer to size */ 308 /* (Out) Pointer to unsigned int indicating operating system error */ 309 /* */ 310 /* Returns: Standard return codes */ 311 /* */ 312 /* Notes : 1) The size is returned as a 64-bit size */ 313 /*****************************************************************************/ 314 STAFRC_t STAFFSEntryGetSize64(STAFFSEntry_t entry, STAFUInt64_t *size, 315 unsigned int *osRC); 316 317 318 /*****************************************************************************/ 319 /* STAFFSEntryGetModTime - Gets the modification time associated with an */ 320 /* entry */ 321 /* */ 322 /* Accepts: (In) File system entry */ 323 /* (Out) Pointer to modification time */ 324 /* (Out) Pointer to unsigned int indicating operating system error */ 325 /* */ 326 /* Returns: Standard return codes */ 327 /*****************************************************************************/ 328 STAFRC_t STAFFSEntryGetModTime(STAFFSEntry_t entry, time_t *modTime, 329 unsigned int *osRC); 330 331 332 /*****************************************************************************/ 333 /* STAFFSEntryGetIsLink - Gets a flag indicating if the entry is a link */ 334 /* */ 335 /* Accepts: (In) File system entry */ 336 /* (Out) Pointer to flag indicating if the entry is a link */ 337 /* 1 = link 0 = Not a link */ 338 /* (Out) Pointer to unsigned int indicating operating system error */ 339 /* */ 340 /* Returns: Standard return codes */ 341 /*****************************************************************************/ 342 STAFRC_t STAFFSEntryGetIsLink(STAFFSEntry_t entry, unsigned int *isLink, 343 unsigned int *osRC); 344 345 346 /*****************************************************************************/ 347 /* STAFFSEntryGetLinkTarget - Gets the link target associated with a */ 348 /* symbolic link entry */ 349 /* */ 350 /* Accepts: (In) File system entry */ 351 /* (Out) Pointer to constant to (target) link path string */ 352 /* */ 353 /* Returns: Standard return codes */ 354 /*****************************************************************************/ 355 STAFRC_t STAFFSEntryGetLinkTarget(STAFFSEntry_t entry, 356 STAFString_t *linkTargetString, 357 unsigned int *osRC); 358 359 360 /*****************************************************************************/ 361 /* STAFFSEntryReadLock - Gets a read lock on a file system entry */ 362 /* */ 363 /* Accepts: (In) File system entry */ 364 /* (Out) Pointer to unsigned int indicating operating system error */ 365 /* */ 366 /* Returns: Standard return codes */ 367 /*****************************************************************************/ 368 STAFRC_t STAFFSEntryReadLock(STAFFSEntry_t entry, unsigned int *osRC); 369 370 371 /*****************************************************************************/ 372 /* STAFFSEntryReadUnlock - Releases a read lock on a file system entry */ 373 /* */ 374 /* Accepts: (In) File system entry */ 375 /* (Out) Pointer to unsigned int indicating operating system error */ 376 /* */ 377 /* Returns: Standard return codes */ 378 /*****************************************************************************/ 379 STAFRC_t STAFFSEntryReadUnlock(STAFFSEntry_t entry, unsigned int *osRC); 380 381 382 /*****************************************************************************/ 383 /* STAFFSEntryWriteLock - Gets a write lock on a file system entry */ 384 /* */ 385 /* Accepts: (In) File system entry */ 386 /* (Out) Pointer to unsigned int indicating operating system error */ 387 /* */ 388 /* Returns: Standard return codes */ 389 /*****************************************************************************/ 390 STAFRC_t STAFFSEntryWriteLock(STAFFSEntry_t entry, unsigned int *osRC); 391 392 393 /*****************************************************************************/ 394 /* STAFFSEntryWriteUnlock - Releases a write lock on a file system entry */ 395 /* */ 396 /* Accepts: (In) File system entry */ 397 /* (Out) Pointer to unsigned int indicating operating system error */ 398 /* */ 399 /* Returns: Standard return codes */ 400 /*****************************************************************************/ 401 STAFRC_t STAFFSEntryWriteUnlock(STAFFSEntry_t entry, unsigned int *osRC); 402 403 404 /*****************************************************************************/ 405 /* STAFFSDeleteEntry - Deletes a file system entry */ 406 /* */ 407 /* Accepts: (In) File system entry */ 408 /* (Out) Pointer to unsigned int indicating operating system error */ 409 /* */ 410 /* Returns: Standard return codes */ 411 /* */ 412 /* Notes : 1) This does NOT free the entry itself. You must still call */ 413 /* STAFFSFreeEntry(). */ 414 /*****************************************************************************/ 415 STAFRC_t STAFFSDeleteEntry(STAFFSEntry_t entry, unsigned int *osRC); 416 417 418 /*****************************************************************************/ 419 /* STAFFSCopyEntry - Copies one file system entry to another path */ 420 /* */ 421 /* Accepts: (In) Source file system entry */ 422 /* (In) Target path string */ 423 /* (Out) Pointer to unsigned int indicating operating system error */ 424 /* */ 425 /* Returns: Standard return codes */ 426 /*****************************************************************************/ 427 STAFRC_t STAFFSCopyEntry(STAFFSEntry_t source, STAFStringConst_t target, 428 unsigned int *osRC); 429 430 /*****************************************************************************/ 431 /* STAFFSMoveEntry - Moves one file system entry to another name. If the */ 432 /* target already exists, it is overwritten. */ 433 /* */ 434 /* Accepts: (In) Source file system entry (file to be moved) */ 435 /* (In) Target path string (new file name) */ 436 /* (Out) Pointer to unsigned int indicating operating system error */ 437 /* */ 438 /* Returns: Standard return codes */ 439 /*****************************************************************************/ 440 STAFRC_t STAFFSMoveEntry(STAFFSEntry_t source, STAFStringConst_t target, 441 unsigned int *osRC); 442 443 /*****************************************************************************/ 444 /* STAFFSRenameEntry - Renames one file system entry to another name. The */ 445 /* target must not already exist. */ 446 /* */ 447 /* Accepts: (In) Source file system entry (file to be renamed) */ 448 /* (In) Target path string (new file name) */ 449 /* (Out) Pointer to unsigned int indicating operating system error */ 450 /* */ 451 /* Returns: Standard return codes */ 452 /*****************************************************************************/ 453 STAFRC_t STAFFSRenameEntry(STAFFSEntry_t source, STAFStringConst_t target, 454 unsigned int *osRC); 455 456 457 /*****************************************************************************/ 458 /* STAFFSFreeEntry - Frees a file system entry object */ 459 /* */ 460 /* Accepts: (In) File system entry */ 461 /* */ 462 /* Returns: Standard return codes */ 463 /*****************************************************************************/ 464 STAFRC_t STAFFSFreeEntry(STAFFSEntry_t *entry); 465 466 467 /*****************************************************************************/ 468 /* Directory APIs */ 469 /*****************************************************************************/ 470 471 /*****************************************************************************/ 472 /* STAFFSCreateDirectory - Creates a directory in the file system */ 473 /* */ 474 /* Accepts: (In) Path string */ 475 /* (In) Directory creation flags */ 476 /* (Out) Pointer to unsigned int indicating operating system error */ 477 /* */ 478 /* Returns: Standard return codes */ 479 /*****************************************************************************/ 480 STAFRC_t STAFFSCreateDirectory(STAFStringConst_t path, 481 STAFFSDirectoryCreateMode_t flags, 482 unsigned int *osRC); 483 484 485 /*****************************************************************************/ 486 /* STAFFSGetCurrentDirectory - Retrieves the current directory */ 487 /* */ 488 /* Accepts: (Out) Pointer to current directory string */ 489 /* (Out) Pointer to unsigned int indicating operating system error */ 490 /* */ 491 /* Returns: Standard return codes */ 492 /*****************************************************************************/ 493 STAFRC_t STAFFSGetCurrentDirectory(STAFString_t *path, unsigned int *osRC); 494 495 496 /*****************************************************************************/ 497 /* STAFFSSetCurrentDirectory - Sets the current directory */ 498 /* */ 499 /* Accepts: (In) Current directory string */ 500 /* (Out) Pointer to unsigned int indicating operating system error */ 501 /* */ 502 /* Returns: Standard return codes */ 503 /* */ 504 /* Notes : 1) You should obtain the current directory lock before setting */ 505 /* the current directory */ 506 /*****************************************************************************/ 507 STAFRC_t STAFFSSetCurrentDirectory(STAFStringConst_t path, unsigned int *osRC); 508 509 510 /*****************************************************************************/ 511 /* STAFFSRequestCurrentDirectoryLock - Obtains the lock on the current */ 512 /* directory */ 513 /* */ 514 /* Accepts: Nothing */ 515 /* */ 516 /* Returns: Standard return codes */ 517 /*****************************************************************************/ 518 STAFRC_t STAFFSRequestCurrentDirectoryLock(); 519 520 521 /*****************************************************************************/ 522 /* STAFFSReleaseCurrentDirectoryLock - Releases the lock on the current */ 523 /* directory */ 524 /* */ 525 /* Accepts: Nothing */ 526 /* */ 527 /* Returns: Standard return codes */ 528 /*****************************************************************************/ 529 STAFRC_t STAFFSReleaseCurrentDirectoryLock(); 530 531 532 /*****************************************************************************/ 533 /* STAFFSEnumOpen - Obtains an enumeration handle for an entry object */ 534 /* */ 535 /* Accepts: (Out) Pointer to enumeration handle */ 536 /* (In) File system entry */ 537 /* (In) Pattern used to match names */ 538 /* (In) Pattern used to match extension */ 539 /* (In) Are name/extension patterns case sensitive */ 540 /* (In) The types of entries to enumerate */ 541 /* (In) How should the entries be sorted */ 542 /* (Out) Pointer to unsigned int indicating operating system error */ 543 /* */ 544 /* Returns: Standard return codes */ 545 /* */ 546 /* Notes : 1) The name and extension patterns may contain the '*' and '?' */ 547 /* characters. The '*' character matches zero or more */ 548 /* characters. The '?' character matches one character. */ 549 /* 2) It is legal to enumerate a non-directory entry. You will */ 550 /* simply receive an enumeration with no entries. */ 551 /*****************************************************************************/ 552 STAFRC_t STAFFSEnumOpen(STAFFSEnumHandle_t *enumHandle, STAFFSEntry_t entry, 553 STAFStringConst_t namePattern, 554 STAFStringConst_t extPattern, 555 STAFFSCaseSensitive_t caseSensitivity, 556 STAFFSEntryType_t entryTypes, 557 STAFFSSortBy_t sortBy, unsigned int *osRC); 558 559 560 /*****************************************************************************/ 561 /* STAFFSEnumNext - Retrieves the next entry in the enumeration */ 562 /* */ 563 /* Accepts: (In) Enumeration handle */ 564 /* (Out) Pointer to file system entry (this will zero if there are */ 565 /* no more entries in the enumeration */ 566 /* (Out) Pointer to unsigned int indicating operating system error */ 567 /* */ 568 /* Returns: Standard return codes */ 569 /* */ 570 /* Notes : 1) You must free the entries obtained through this API */ 571 /* 2) No error will be returned when enumeration is complete. You */ 572 /* will simply receive a zero entry. */ 573 /*****************************************************************************/ 574 STAFRC_t STAFFSEnumNext(STAFFSEnumHandle_t enumHandle, STAFFSEntry_t *entry, 575 unsigned int *osRC); 576 577 578 /*****************************************************************************/ 579 /* STAFFSEnumClose - Closes an enumeration handle */ 580 /* */ 581 /* Accepts: (I/O) Pointer to enumeration handle */ 582 /* (Out) Pointer to unsigned int indicating operating system error */ 583 /* */ 584 /* Returns: Standard return codes */ 585 /*****************************************************************************/ 586 STAFRC_t STAFFSEnumClose(STAFFSEnumHandle_t *enumHandle, unsigned int *osRC); 587 588 589 /*****************************************************************************/ 590 /* Internal use only */ 591 /*****************************************************************************/ 592 /* Note: These APIs should not be used directly by the user */ 593 /*****************************************************************************/ 594 595 /*****************************************************************************/ 596 /* STAFFSOSGetExclusiveFileLock - Gets an exclusive lock on a file */ 597 /* */ 598 /* Accepts: (In) Path string */ 599 /* (Out) Pointer to the lock */ 600 /* (Out) Pointer to unsigned int indicating operating system error */ 601 /* */ 602 /* Returns: Standard return codes */ 603 /* */ 604 /* Notes : 1) This API is for internal STAF use only. Users should use */ 605 /* the STAFFSEntry<Read|Write>Lock APIs. */ 606 /* 2) Porters - this need only provide an advisory lock. A */ 607 /* mandatory lock is not required. */ 608 /*****************************************************************************/ 609 STAFRC_t STAFFSOSGetExclusiveFileLock(STAFStringConst_t path, 610 STAFFSOSFileLock_t *lock, 611 unsigned int *osRC); 612 613 614 /*****************************************************************************/ 615 /* STAFFSOSReleaseExclusiveFileLock - Releases an exclusive file lock */ 616 /* */ 617 /* Accepts: (I/O) Pointer to the lock */ 618 /* (Out) Pointer to unsigned int indicating operating system error */ 619 /* */ 620 /* Returns: Standard return codes */ 621 /* */ 622 /* Notes : 1) This API is for internal STAF use only. Users should use */ 623 /* the STAFFSEntry<Read|Write>Unlock APIs. */ 624 /*****************************************************************************/ 625 STAFRC_t STAFFSOSReleaseExclusiveFileLock(STAFFSOSFileLock_t *lock, 626 unsigned int *osRC); 627 628 /* The following definitions are for OS independent versions of the */ 629 /* File System APIs. These should not be used by user applications. */ 630 631 STAFRC_t STAFFSCopyEntryCommon(STAFFSEntry_t source, STAFStringConst_t target, 632 unsigned int *osRC); 633 634 #ifdef __cplusplus 635 } 636 637 #include "STAFString.h" 638 #include "STAFTimestamp.h" 639 #include "STAFRefPtr.h" 640 #include "STAFException.h" 641 #include <deque> 642 643 // C++ Definitions 644 645 // STAFFSPath - This class represents a path in the file system. The path 646 // can be represented as a string, or as its constituent pieces. 647 // These pieces are the root of the path, the directories in the 648 // path, the name of the item, and the extension of the item. 649 // 650 // This class provides numerous methods to build up a path string 651 // from its pieces and to determine a path's pieces from a path 652 // string. 653 // 654 // Given an instance of this class, you can retrieve the file 655 // system entry object associated with it, as well as create the 656 // directory represented by it. 657 658 class STAFFSEntry; 659 typedef STAFRefPtr<STAFFSEntry> STAFFSEntryPtr; 660 typedef std::pair<STAFRC_t, STAFFSEntryPtr> STAFFSEntryRC; 661 662 class STAFFSPath 663 { 664 public: 665 666 // This constructor is designed for building a path piece by piece 667 STAFFSPath(); 668 669 // This constructor is designed for breaking down a path string 670 STAFFSPath(const STAFString &path); 671 672 // These methods allow you to build up a path piece by piece 673 STAFFSPath &setRoot(const STAFString &root = STAFString()); 674 STAFFSPath &addDir(const STAFString &dir); 675 STAFFSPath &setName(const STAFString &name = STAFString()); 676 STAFFSPath &setExtension(const STAFString &extension = STAFString()); 677 678 // Allows you to reset the list of directories in the path 679 STAFFSPath &clearDirList(); 680 681 // Get a path string based on pieces 682 STAFString asString() const; 683 684 // Get various pieces based on path string 685 STAFString root() const; 686 unsigned int numDirs() const; 687 STAFString dir(unsigned int index = 0) const; 688 STAFString name() const; 689 STAFString extension() const; 690 691 unsigned int exists() const; 692 693 STAFFSEntryPtr getEntry() const; 694 STAFFSEntryRC getEntry(unsigned int *osRC) const; 695 696 STAFFSEntryPtr createDirectory(STAFFSDirectoryCreateMode_t mode = 697 kSTAFFSCreateDirOnly) const; 698 STAFFSEntryRC createDirectory(unsigned int *osRC, 699 STAFFSDirectoryCreateMode_t mode = 700 kSTAFFSCreateDirOnly) const; 701 702 private: 703 704 void updatePath(); 705 void updatePieces(); 706 707 unsigned int fPathUpToDate; 708 unsigned int fPiecesUpToDate; 709 710 STAFString fPath; 711 STAFString fRoot; 712 std::deque<STAFString> fDirs; 713 STAFString fName; 714 STAFString fExtension; 715 }; 716 717 718 // STAFFSEntry - This class represents an object that exists (or, at least, has 719 // existed at some time) in the file system. 720 // 721 // Given an instance of this class, you can obtain various details 722 // about the entry, as well as remove (a.k.a, delete), copy, and 723 // rename the entry. You may also obtain an enumeration of this 724 // entries sub-entries (if it is a directory). 725 726 class STAFFSEnumeration; 727 typedef STAFRefPtr<STAFFSEnumeration> STAFFSEnumPtr; 728 729 class STAFFSEntry 730 { 731 public: 732 STAFFSEntry(STAFFSEntry_t entry)733 STAFFSEntry(STAFFSEntry_t entry) : fEntry(entry) 734 { /* Do Nothing */ } 735 736 typedef std::pair<unsigned int, unsigned int> FileSize; 737 738 // XXX: Add a trueType() function for differentiating symlinks 739 // XXX: Add a linkedTo() function to get name of entry linked to 740 741 // Informational methods 742 743 STAFFSPath path() const; 744 STAFFSEntryType_t type() const; 745 FileSize size() const; 746 STAFUInt64_t size64() const; 747 STAFTimestamp modTime() const; 748 unsigned int isLink() const; 749 STAFString linkTarget() const; 750 751 // Lock methods 752 753 void readLock(); 754 void readUnlock(); 755 void writeLock(); 756 void writeUnlock(); 757 758 // Manipulation methods 759 760 void remove(); 761 STAFRC_t remove(unsigned int *osRC); 762 763 void copy(const STAFString &toName); 764 765 void move(const STAFString &toName); 766 767 void rename(const STAFString &toName); 768 769 // Enumeration methods 770 771 STAFFSEnumPtr enumerate(const STAFString &namePat = STAFString(kUTF8_STAR), 772 const STAFString &extPat = STAFString(kUTF8_STAR), 773 STAFFSEntryType_t types = kSTAFFSNormal, 774 STAFFSSortBy_t sortBy = kSTAFFSNoSort, 775 STAFFSCaseSensitive_t caseSensitivity = 776 kSTAFFSCaseDefault) const; 777 778 // Data methods 779 780 STAFFSEntry_t getImpl() const; 781 STAFFSEntry_t adoptImpl(); 782 783 ~STAFFSEntry(); 784 785 private: 786 787 // Disallow copy construction and assignment 788 STAFFSEntry(const STAFFSEntry &); 789 STAFFSEntry &operator=(const STAFFSEntry &); 790 791 STAFFSEntry_t fEntry; 792 }; 793 794 795 // STAFFSEntryRLock - This class is used to acquire and automatically 796 // release the read lock on a STAFFSEntry object 797 798 class STAFFSEntryRLock 799 { 800 public: 801 STAFFSEntryRLock(STAFFSEntryPtr & theEntry)802 STAFFSEntryRLock(STAFFSEntryPtr &theEntry) 803 : fEntry(theEntry) 804 { fEntry->readLock(); } 805 ~STAFFSEntryRLock()806 ~STAFFSEntryRLock() 807 { fEntry->readUnlock(); } 808 809 private: 810 811 // Disallow copy construction and assignment 812 STAFFSEntryRLock(const STAFFSEntryRLock &); 813 STAFFSEntryRLock &operator=(const STAFFSEntryRLock &); 814 815 STAFFSEntryPtr fEntry; 816 }; 817 818 819 // STAFFSEntryWLock - This class is used to acquire and automatically 820 // release the write lock on a STAFFSEntry object 821 822 class STAFFSEntryWLock 823 { 824 public: 825 STAFFSEntryWLock(STAFFSEntryPtr & theEntry)826 STAFFSEntryWLock(STAFFSEntryPtr &theEntry) 827 : fEntry(theEntry) 828 { fEntry->writeLock(); } 829 ~STAFFSEntryWLock()830 ~STAFFSEntryWLock() 831 { fEntry->writeUnlock(); } 832 833 private: 834 835 // Disallow copy construction and assignment 836 STAFFSEntryWLock(const STAFFSEntryWLock &); 837 STAFFSEntryWLock &operator=(const STAFFSEntryWLock &); 838 839 STAFFSEntryPtr fEntry; 840 }; 841 842 843 // STAFFSEnumeration - This class represents the collection of entries that 844 // reside within a given directory. 845 // 846 // You may retrieve the current entry, move to the next 847 // entry, and determine if the enumeration is still valid. 848 849 class STAFFSEnumeration 850 { 851 public: 852 853 STAFFSEnumeration(STAFFSEnumHandle_t handle); 854 855 unsigned int isValid() const; 856 STAFFSEntryPtr entry() const; 857 STAFFSEnumeration &next(); 858 859 ~STAFFSEnumeration(); 860 861 private: 862 863 // Disallow copy construction and assignment 864 STAFFSEnumeration(const STAFFSEnumeration &); 865 STAFFSEnumeration &operator=(const STAFFSEnumeration &); 866 867 STAFFSEnumHandle_t fHandle; 868 unsigned int fIsValid; 869 STAFFSEntryPtr fCurrEntry; 870 }; 871 872 873 874 // STAFFSCurrentDirectoryLock - This class provides a wrapper around the 875 // current directory locking mechanism 876 // 877 // In general, you would create an instance of 878 // this class before setting the current directory. 879 880 class STAFFSCurrentDirectoryLock 881 { 882 public: 883 884 STAFFSCurrentDirectoryLock(); 885 ~STAFFSCurrentDirectoryLock(); 886 887 private: 888 889 // Disallow copy construction and assignment 890 STAFFSCurrentDirectoryLock(const STAFFSCurrentDirectoryLock &); 891 STAFFSCurrentDirectoryLock &operator=(const STAFFSCurrentDirectoryLock &); 892 893 }; 894 895 896 // STAFFileSystem - This class provides some utility functions for interfacing 897 // with the file system. 898 // 899 // You may get and set the current directory, as well as 900 // obtain certain information about the underlying file system. 901 902 class STAFFileSystem 903 { 904 public: 905 906 static STAFString getInfo(STAFFSInfoType_t type); 907 908 static unsigned int matchesWildcards( 909 const STAFString &stringToCheck, const STAFString &wildcardString, 910 STAFFSCaseSensitive_t sensitive = kSTAFFSCaseDefault); 911 912 static STAFFSComparePathResult_t comparePaths( 913 const STAFString &path1, const STAFString &path2, 914 STAFFSCaseSensitive_t sensitive = kSTAFFSCaseDefault); 915 916 // Note: You should own the current directory lock before setting the 917 // current directory 918 919 static STAFString getCurrentDirectory(); 920 static void setCurrentDirectory(const STAFString &dirName); 921 922 private: 923 924 // Disallow copy construction and assignment 925 STAFFileSystem(const STAFFileSystem &); 926 STAFFileSystem &operator=(const STAFFileSystem &); 927 }; 928 929 930 // Begin C++ exception definitions 931 932 STAF_EXCEPTION_DEFINITION(STAFFSException, STAFException); 933 934 // Now include inline definitions 935 936 #ifndef STAF_NATIVE_COMPILER 937 #include "STAFFileSystemInlImpl.cpp" 938 #endif 939 940 // End C++ language definitions 941 942 // End #ifdef __cplusplus 943 #endif 944 945 946 #endif 947 948