1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 /** @HTML */ 25 26 #ifndef _OSL_FILE_H_ 27 #define _OSL_FILE_H_ 28 29 #include <osl/time.h> 30 # include <rtl/ustring.h> 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** @file 37 38 Main goals and usage hints 39 40 The main intentention of this interface is to provide an universal portable and 41 high performance access to file system issues on any operating system.<p> 42 43 There are a few main goals:<p> 44 45 1.The path specifications always has to be absolut. Any usage of relative path 46 specifications is forbidden. Exceptions are <code>osl_getSystemPathFromFileURL</code>, 47 <code>osl_getFileURLFromSystemPath</code> and <code>osl_getAbsoluteFileURL</code>. Most operating systems 48 provide a "Current Directory" per process. This is the reason why relative path 49 specifications can cause problems in multithreading environments.<p> 50 51 2.Proprietary notations of file paths are not supported. Every path notation 52 must the file URL specification. File URLs must be encoded in UTF8 and 53 after that escaped. Although the URL parameter is a unicode string, the must 54 contain only ASCII characters<p> 55 56 3.The caller cannot get any information whether a file system is case sensitive, 57 case preserving or not. The operating system implementation itself should 58 determine if it can map case-insensitive paths. The case correct notation of 59 a filename or file path is part of the "File Info". This case correct name 60 can be used as a unique key if necessary.<p> 61 62 4. Obtaining information about files or volumes is controlled by a 63 bitmask which specifies which fields are of interest. Due to performance 64 issues it is not recommended to obtain information which is not needed. 65 But if the operating system provides more information anyway the 66 implementation can set more fields on output as were requested. It is in the 67 responsibility of the caller to decide if he uses this additional information 68 or not. But he should do so to prevent further unnecessary calls if the information 69 is already there.<br> 70 71 The input bitmask supports a flag <code>osl_FileStatus_Mask_Validate</code> which 72 can be used to force retrieving uncached validated information. Setting this flag 73 when calling <code>osl_getFileStatus</code> in combination with no other flag is 74 a synonym for a "FileExists". This should only be done when processing a single file 75 (f.e. before opening) and NEVER during enumeration of directory contents on any step 76 of information processing. This would change the runtime behaviour from O(n) to 77 O(n*n/2) on nearly every file system.<br> 78 On Windows NT reading the contents of an directory with 7000 entries and 79 getting full information about every file only takes 0.6 seconds. Specifying the 80 flag <code>osl_FileStatus_Mask_Validate</code> for each entry will increase the 81 time to 180 seconds (!!!). 82 83 */ 84 85 86 87 /* Error codes according to errno */ 88 89 typedef enum { 90 osl_File_E_None, 91 osl_File_E_PERM, 92 osl_File_E_NOENT, 93 osl_File_E_SRCH, 94 osl_File_E_INTR, 95 osl_File_E_IO, 96 osl_File_E_NXIO, 97 osl_File_E_2BIG, 98 osl_File_E_NOEXEC, 99 osl_File_E_BADF, 100 osl_File_E_CHILD, 101 osl_File_E_AGAIN, 102 osl_File_E_NOMEM, 103 osl_File_E_ACCES, 104 osl_File_E_FAULT, 105 osl_File_E_BUSY, 106 osl_File_E_EXIST, 107 osl_File_E_XDEV, 108 osl_File_E_NODEV, 109 osl_File_E_NOTDIR, 110 osl_File_E_ISDIR, 111 osl_File_E_INVAL, 112 osl_File_E_NFILE, 113 osl_File_E_MFILE, 114 osl_File_E_NOTTY, 115 osl_File_E_FBIG, 116 osl_File_E_NOSPC, 117 osl_File_E_SPIPE, 118 osl_File_E_ROFS, 119 osl_File_E_MLINK, 120 osl_File_E_PIPE, 121 osl_File_E_DOM, 122 osl_File_E_RANGE, 123 osl_File_E_DEADLK, 124 osl_File_E_NAMETOOLONG, 125 osl_File_E_NOLCK, 126 osl_File_E_NOSYS, 127 osl_File_E_NOTEMPTY, 128 osl_File_E_LOOP, 129 osl_File_E_ILSEQ, 130 osl_File_E_NOLINK, 131 osl_File_E_MULTIHOP, 132 osl_File_E_USERS, 133 osl_File_E_OVERFLOW, 134 osl_File_E_NOTREADY, 135 osl_File_E_invalidError, /* unmapped error: always last entry in enum! */ 136 osl_File_E_TIMEDOUT, 137 osl_File_E_NETWORK, 138 osl_File_E_FORCE_EQUAL_SIZE, 139 osl_File_E_LOCKED = SAL_MAX_ENUM 140 } oslFileError; 141 142 typedef void *oslDirectory; 143 typedef void *oslDirectoryItem; 144 145 146 /** Open a directory for enumerating its contents. 147 148 @param pustrDirectoryURL [in] 149 The full qualified URL of the directory. 150 151 @param pDirectory [out] 152 On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem(). 153 The handle has to be released by a call to osl_closeDirectory(). 154 155 @return 156 osl_File_E_None on success<br> 157 osl_File_E_INVAL the format of the parameters was not valid<br> 158 osl_File_E_NOENT the specified path doesn't exist<br> 159 osl_File_E_NOTDIR the specified path is not an directory <br> 160 osl_File_E_NOMEM not enough memory for allocating structures <br> 161 osl_File_E_ACCES permission denied<br> 162 osl_File_E_MFILE too many open files used by the process<br> 163 osl_File_E_NFILE too many open files in the system<br> 164 osl_File_E_NAMETOOLONG File name too long<br> 165 osl_File_E_LOOP Too many symbolic links encountered<p> 166 167 @see osl_getNextDirectoryItem() 168 @see osl_closeDirectory() 169 */ 170 171 oslFileError SAL_CALL osl_openDirectory( rtl_uString *pustrDirectoryURL, oslDirectory *pDirectory); 172 173 174 /** Retrieve the next item of a previously opened directory. 175 176 Retrieves the next item of a previously opened directory. 177 All handles have an initial refcount of 1. 178 179 @param Directory [in] 180 A directory handle received from a previous call to osl_openDirectory(). 181 182 @param pItem [out] 183 On success it receives a handle that can be used for subsequent calls to osl_getFileStatus(). 184 The handle has to be released by a call to osl_releaseDirectoryItem(). 185 186 @param uHint [in] 187 With this parameter the caller can tell the implementation that (s)he 188 is going to call this function uHint times afterwards. This enables the implementation to 189 get the information for more than one file and cache it until the next calls. 190 191 @return 192 osl_File_E_None on success<br> 193 osl_File_E_INVAL the format of the parameters was not valid<br> 194 osl_File_E_NOMEM not enough memory for allocating structures <br> 195 osl_File_E_NOENT no more entries in this directory<br> 196 osl_File_E_BADF invalid oslDirectory parameter<br> 197 osl_File_E_OVERFLOW the value too large for defined data type 198 199 @see osl_releaseDirectoryItem() 200 @see osl_acquireDirectoryItem() 201 @see osl_getDirectoryItem() 202 @see osl_getFileStatus() 203 */ 204 205 oslFileError SAL_CALL osl_getNextDirectoryItem( 206 oslDirectory Directory, 207 oslDirectoryItem *pItem, 208 sal_uInt32 uHint 209 ); 210 211 212 /** Release a directory handle. 213 214 @param Directory [in] 215 A handle received by a call to osl_openDirectory(). 216 217 @return 218 osl_File_E_None on success<br> 219 osl_File_E_INVAL the format of the parameters was not valid<br> 220 osl_File_E_NOMEM not enough memory for allocating structures<br> 221 osl_File_E_BADF invalid oslDirectory parameter<br> 222 osl_File_E_INTR the function call was interrupted<p> 223 224 @see osl_openDirectory() 225 */ 226 227 oslFileError SAL_CALL osl_closeDirectory(oslDirectory Directory); 228 229 230 /** Retrieve a single directory item. 231 232 Retrieves a single directory item. The returned handle has an initial refcount of 1. 233 Due to performance issues it is not recommended to use this function while 234 enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead. 235 236 @param pustrFileURL [in] 237 An absolute file URL. 238 239 @param pItem [out] 240 On success it receives a handle which can be used for subsequent calls to osl_getFileStatus(). 241 The handle has to be released by a call to osl_releaseDirectoryItem(). 242 243 @return 244 osl_File_E_None on success<br> 245 osl_File_E_INVAL the format of the parameters was not valid<br> 246 osl_File_E_NOMEM not enough memory for allocating structures <br> 247 osl_File_E_ACCES permission denied<br> 248 osl_File_E_MFILE too many open files used by the process<br> 249 osl_File_E_NFILE too many open files in the system<br> 250 osl_File_E_NOENT no such file or directory<br> 251 osl_File_E_LOOP too many symbolic links encountered<br> 252 osl_File_E_NAMETOOLONG the file name is too long<br> 253 osl_File_E_NOTDIR a component of the path prefix of path is not a directory<br> 254 osl_File_E_IO on I/O errors<br> 255 osl_File_E_MULTIHOP multihop attempted<br> 256 osl_File_E_NOLINK link has been severed<br> 257 osl_File_E_FAULT bad address<br> 258 osl_File_E_INTR the function call was interrupted<p> 259 260 @see osl_releaseDirectoryItem() 261 @see osl_acquireDirectoryItem() 262 @see osl_getFileStatus() 263 @see osl_getNextDirectoryItem() 264 */ 265 266 oslFileError SAL_CALL osl_getDirectoryItem( 267 rtl_uString *pustrFileURL, 268 oslDirectoryItem *pItem 269 ); 270 271 272 /** Increase the refcount of a directory item handle. 273 274 The caller responsible for releasing the directory item handle using osl_releaseDirectoryItem(). 275 276 @param Item [in] 277 A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). 278 279 @return 280 osl_File_E_None on success<br> 281 osl_File_E_NOMEM not enough memory for allocating structures<br> 282 osl_File_E_INVAL the format of the parameters was not valid<br> 283 284 @see osl_getDirectoryItem() 285 @see osl_getNextDirectoryItem() 286 @see osl_releaseDirectoryItem() 287 */ 288 289 oslFileError SAL_CALL osl_acquireDirectoryItem( oslDirectoryItem Item ); 290 291 292 /** Decrease the refcount of a directory item handle. 293 294 Decreases the refcount of a directory item handle. 295 If the refcount reaches 0 the data associated with 296 this directory item handle will be released. 297 298 @param Item [in] 299 A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). 300 301 @return 302 osl_File_E_None on success<br> 303 osl_File_E_NOMEM not enough memory for allocating structures<br> 304 osl_File_E_INVAL the format of the parameters was not valid<br> 305 306 @see osl_getDirectoryItem() 307 @see osl_getNextDirectoryItem() 308 @see osl_acquireDirectoryItem() 309 */ 310 311 oslFileError SAL_CALL osl_releaseDirectoryItem( oslDirectoryItem Item ); 312 313 /* File types */ 314 315 typedef enum { 316 osl_File_Type_Directory, 317 osl_File_Type_Volume, 318 osl_File_Type_Regular, 319 osl_File_Type_Fifo, 320 osl_File_Type_Socket, 321 osl_File_Type_Link, 322 osl_File_Type_Special, 323 osl_File_Type_Unknown 324 } oslFileType; 325 326 /* File attributes */ 327 #define osl_File_Attribute_ReadOnly 0x00000001 328 #define osl_File_Attribute_Hidden 0x00000002 329 #define osl_File_Attribute_Executable 0x00000010 330 #define osl_File_Attribute_GrpWrite 0x00000020 331 #define osl_File_Attribute_GrpRead 0x00000040 332 #define osl_File_Attribute_GrpExe 0x00000080 333 #define osl_File_Attribute_OwnWrite 0x00000100 334 #define osl_File_Attribute_OwnRead 0x00000200 335 #define osl_File_Attribute_OwnExe 0x00000400 336 #define osl_File_Attribute_OthWrite 0x00000800 337 #define osl_File_Attribute_OthRead 0x00001000 338 #define osl_File_Attribute_OthExe 0x00002000 339 340 /* Flags specifying which fields to retrieve by osl_getFileStatus */ 341 342 #define osl_FileStatus_Mask_Type 0x00000001 343 #define osl_FileStatus_Mask_Attributes 0x00000002 344 #define osl_FileStatus_Mask_CreationTime 0x00000010 345 #define osl_FileStatus_Mask_AccessTime 0x00000020 346 #define osl_FileStatus_Mask_ModifyTime 0x00000040 347 #define osl_FileStatus_Mask_FileSize 0x00000080 348 #define osl_FileStatus_Mask_FileName 0x00000100 349 #define osl_FileStatus_Mask_FileURL 0x00000200 350 #define osl_FileStatus_Mask_LinkTargetURL 0x00000400 351 #define osl_FileStatus_Mask_All 0x7FFFFFFF 352 #define osl_FileStatus_Mask_Validate 0x80000000 353 354 355 typedef 356 357 /** Structure containing information about files and directories 358 359 @see osl_getFileStatus() 360 @see oslFileType 361 */ 362 363 struct _oslFileStatus { 364 /** Must be initialized with the size in bytes of the structure before passing it to any function */ 365 sal_uInt32 uStructSize; 366 /** Determines which members of the structure contain valid data */ 367 sal_uInt32 uValidFields; 368 /** The type of the file (file, directory, volume). */ 369 oslFileType eType; 370 /** File attributes */ 371 sal_uInt64 uAttributes; 372 /** First creation time in nanoseconds since 1/1/1970. Can be the last modify time depending on 373 platform or file system. */ 374 TimeValue aCreationTime; 375 /** Last access time in nanoseconds since 1/1/1970. Can be the last modify time depending on 376 platform or file system. */ 377 TimeValue aAccessTime; 378 /** Last modify time in nanoseconds since 1/1/1970. */ 379 TimeValue aModifyTime; 380 /** Size in bytes of the file. Zero for directories and volumes. */ 381 sal_uInt64 uFileSize; 382 /** Case correct name of the file. Should be set to zero before calling <code>osl_getFileStatus</code> 383 and released after usage. */ 384 rtl_uString *ustrFileName; 385 /** Full URL of the file. Should be set to zero before calling <code>osl_getFileStatus</code> 386 and released after usage. */ 387 rtl_uString *ustrFileURL; 388 /** Full URL of the target file if the file itself is a link. 389 Should be set to zero before calling <code>osl_getFileStatus</code> 390 and released after usage. */ 391 rtl_uString *ustrLinkTargetURL; 392 } oslFileStatus; 393 394 395 /** Retrieve information about a single file or directory. 396 397 @param Item [in] 398 A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). 399 400 @param pStatus [in|out] 401 Points to a structure which receives the information of the file or directory 402 represented by the handle Item. The member uStructSize has to be initialized to 403 sizeof(oslFileStatus) before calling this function. 404 405 @param uFieldMask [in] 406 Specifies which fields of the structure pointed to by pStatus are of interest to the caller. 407 408 @return 409 osl_File_E_None on success<br> 410 osl_File_E_NOMEM not enough memory for allocating structures <br> 411 osl_File_E_INVAL the format of the parameters was not valid<br> 412 osl_File_E_LOOP too many symbolic links encountered<br> 413 osl_File_E_ACCES permission denied<br> 414 osl_File_E_NOENT no such file or directory<br> 415 osl_File_E_NAMETOOLONG file name too long<br> 416 osl_File_E_BADF invalid oslDirectoryItem parameter<br> 417 osl_File_E_FAULT bad address<br> 418 osl_File_E_OVERFLOW value too large for defined data type<br> 419 osl_File_E_INTR function call was interrupted<br> 420 osl_File_E_NOLINK link has been severed<br> 421 osl_File_E_MULTIHOP components of path require hopping to multiple remote machines and the file system does not allow it<br> 422 osl_File_E_MFILE too many open files used by the process<br> 423 osl_File_E_NFILE too many open files in the system<br> 424 osl_File_E_NOSPC no space left on device<br> 425 osl_File_E_NXIO no such device or address<br> 426 osl_File_E_IO on I/O errors<br> 427 osl_File_E_NOSYS function not implemented<p> 428 429 @see osl_getDirectoryItem() 430 @see osl_getNextDirectoryItem() 431 @see oslFileStatus 432 */ 433 434 oslFileError SAL_CALL osl_getFileStatus( oslDirectoryItem Item, oslFileStatus *pStatus, sal_uInt32 uFieldMask ); 435 436 437 typedef void *oslVolumeDeviceHandle; 438 439 440 /** Unmount a volume device. 441 442 Unmount the volume specified by the given oslVolumeDeviceHandle. 443 444 @param Handle [in] 445 An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). 446 447 @return 448 osl_File_E_None on success<br> 449 450 @todo 451 specify all error codes that may be returned 452 453 @see osl_getVolumeInformation() 454 */ 455 456 oslFileError SAL_CALL osl_unmountVolumeDevice( oslVolumeDeviceHandle Handle ); 457 458 459 /** Automount a volume device. 460 461 Automount the volume device specified by the given oslVolumeDeviceHandle. 462 463 @param Handle [in] 464 An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). 465 466 @return 467 osl_File_E_None on success<br> 468 469 @todo 470 specify all error codes that may be returned 471 472 @see osl_getVolumeInformation() 473 */ 474 475 oslFileError SAL_CALL osl_automountVolumeDevice( oslVolumeDeviceHandle Handle ); 476 477 478 /** Release a volume device handle. 479 480 Releases the given oslVolumeDeviceHandle which was acquired by a call to 481 osl_getVolumeInformation() or osl_acquireVolumeDeviceHandle(). 482 483 @param Handle [in] 484 An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). 485 486 @return 487 osl_File_E_None on success<br> 488 489 @todo 490 specify all error codes that may be returned 491 492 @see osl_acquireVolumeDeviceHandle() 493 @see osl_getVolumeInformation() 494 */ 495 496 oslFileError SAL_CALL osl_releaseVolumeDeviceHandle( oslVolumeDeviceHandle Handle ); 497 498 /** Acquire a volume device handle. 499 500 Acquires the given oslVolumeDeviceHandle which was acquired by a call to 501 osl_getVolumeInformation(). The caller is responsible for releasing the 502 acquired handle by calling osl_releaseVolumeDeviceHandle(). 503 504 @param Handle [in] 505 An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). 506 507 @return 508 osl_File_E_None on success<br> 509 510 @todo 511 specify all error codes that may be returned 512 513 @see osl_getVolumeInformation() 514 */ 515 516 oslFileError SAL_CALL osl_acquireVolumeDeviceHandle( oslVolumeDeviceHandle Handle ); 517 518 519 /** Get the full qualified URL where a device is mounted to. 520 521 @param Handle [in] 522 An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). 523 524 @param ppustrDirectoryURL [out] 525 Receives the full qualified URL where the device is mounted to. 526 527 @return 528 osl_File_E_None on success<br> 529 osl_File_E_NOMEM not enough memory for allocating structures <br> 530 osl_File_E_INVAL the format of the parameters was not valid<br> 531 osl_File_E_ACCES permission denied<br> 532 osl_File_E_NXIO no such device or address<br> 533 osl_File_E_NODEV no such device<br> 534 osl_File_E_NOENT no such file or directory<br> 535 osl_File_E_FAULT bad address<br> 536 osl_FilE_E_INTR function call was interrupted<br> 537 osl_File_E_IO on I/O errors<br> 538 osl_File_E_MULTIHOP multihop attempted<br> 539 osl_File_E_NOLINK link has been severed<br> 540 osl_File_E_EOVERFLOW value too large for defined data type<br> 541 542 @see osl_getVolumeInformation() 543 @see osl_automountVolumeDevice() 544 @see osl_unmountVolumeDevice() 545 */ 546 547 oslFileError SAL_CALL osl_getVolumeDeviceMountPath( oslVolumeDeviceHandle Handle, rtl_uString **ppustrDirectoryURL); 548 549 /* Volume attributes */ 550 551 #define osl_Volume_Attribute_Removeable 0x00000001L 552 #define osl_Volume_Attribute_Remote 0x00000002L 553 #define osl_Volume_Attribute_CompactDisc 0x00000004L 554 #define osl_Volume_Attribute_FixedDisk 0x00000008L 555 #define osl_Volume_Attribute_RAMDisk 0x00000010L 556 #define osl_Volume_Attribute_FloppyDisk 0x00000020L 557 558 #define osl_Volume_Attribute_Case_Is_Preserved 0x00000040L 559 #define osl_Volume_Attribute_Case_Sensitive 0x00000080L 560 561 /* Flags specifying which fields to retrieve by osl_getVolumeInfo */ 562 563 #define osl_VolumeInfo_Mask_Attributes 0x00000001L 564 #define osl_VolumeInfo_Mask_TotalSpace 0x00000002L 565 #define osl_VolumeInfo_Mask_UsedSpace 0x00000004L 566 #define osl_VolumeInfo_Mask_FreeSpace 0x00000008L 567 #define osl_VolumeInfo_Mask_MaxNameLength 0x00000010L 568 #define osl_VolumeInfo_Mask_MaxPathLength 0x00000020L 569 #define osl_VolumeInfo_Mask_FileSystemName 0x00000040L 570 #define osl_VolumeInfo_Mask_DeviceHandle 0x00000080L 571 #define osl_VolumeInfo_Mask_FileSystemCaseHandling 0x00000100L 572 573 typedef 574 575 /** Structure containing information about volumes 576 577 @see osl_getVolumeInformation() 578 @see oslFileType 579 */ 580 581 struct _oslVolumeInfo { 582 /** Must be initialized with the size in bytes of the structure before passing it to any function */ 583 sal_uInt32 uStructSize; 584 /** Determines which members of the structure contain valid data */ 585 sal_uInt32 uValidFields; 586 /** Attributes of the volume (remote and/or removable) */ 587 sal_uInt32 uAttributes; 588 /** Total available space on the volume for the current process/user */ 589 sal_uInt64 uTotalSpace; 590 /** Used space on the volume for the current process/user */ 591 sal_uInt64 uUsedSpace; 592 /** Free space on the volume for the current process/user */ 593 sal_uInt64 uFreeSpace; 594 /** Maximum length of file name of a single item */ 595 sal_uInt32 uMaxNameLength; 596 /** Maximum length of a full quallified path in system notation */ 597 sal_uInt32 uMaxPathLength; 598 /** Points to a string that receives the name of the file system type. String should be set to zero before calling <code>osl_getVolumeInformation</code> 599 and released after usage. */ 600 rtl_uString *ustrFileSystemName; 601 /** Pointer to handle the receives underlying device. Handle should be set to zero before calling <code>osl_getVolumeInformation</code>*/ 602 oslVolumeDeviceHandle *pDeviceHandle; 603 } oslVolumeInfo; 604 605 606 /** Retrieve information about a volume. 607 608 Retrieves information about a volume. A volume can either be a mount point, a network 609 resource or a drive depending on Operating System and File System. Before calling this 610 function osl_getFileStatus() should be called to determine if the type is 611 osl_file_Type_Volume. 612 613 @param pustrDirectoryURL [in] 614 Full qualified URL of the volume 615 616 @param pInfo [out] 617 On success it receives information about the volume. 618 619 @param uFieldMask [in] 620 Specifies which members of the structure should be filled 621 622 @return 623 osl_File_E_None on success<br> 624 osl_File_E_NOMEM not enough memory for allocating structures <br> 625 osl_File_E_INVAL the format of the parameters was not valid<br> 626 osl_File_E_NOTDIR not a directory<br> 627 osl_File_E_NAMETOOLONG file name too long<br> 628 osl_File_E_NOENT no such file or directory<br> 629 osl_File_E_ACCES permission denied<br> 630 osl_File_E_LOOP too many symbolic links encountered<br> 631 ols_File_E_FAULT Bad address<br> 632 osl_File_E_IO on I/O errors<br> 633 osl_File_E_NOSYS function not implemented<br> 634 osl_File_E_MULTIHOP multihop attempted<br> 635 osl_File_E_NOLINK link has been severed<br> 636 osl_File_E_INTR function call was interrupted<br> 637 638 @see osl_getFileStatus() 639 @see oslVolumeInfo 640 */ 641 642 oslFileError SAL_CALL osl_getVolumeInformation( 643 rtl_uString *pustrDirectoryURL, 644 oslVolumeInfo *pInfo, 645 sal_uInt32 uFieldMask ); 646 647 typedef void *oslFileHandle; 648 649 /* Open flags */ 650 651 #define osl_File_OpenFlag_Read 0x00000001L 652 #define osl_File_OpenFlag_Write 0x00000002L 653 #define osl_File_OpenFlag_Create 0x00000004L 654 #define osl_File_OpenFlag_NoLock 0x00000008L 655 656 /** Open a regular file. 657 658 Open a file. Only regular files can be openend. 659 660 @param pustrFileURL [in] 661 The full qualified URL of the file to open. 662 663 @param pHandle [out] 664 On success it receives a handle to the open file. 665 666 @param uFlags [in] 667 Specifies the open mode. 668 669 @return 670 osl_File_E_None on success<br> 671 osl_File_E_NOMEM not enough memory for allocating structures <br> 672 osl_File_E_INVAL the format of the parameters was not valid<br> 673 osl_File_E_NAMETOOLONG pathname was too long<br> 674 osl_File_E_NOENT no such file or directory<br> 675 osl_File_E_ACCES permission denied<br> 676 osl_File_E_AGAIN a write lock could not be established<br> 677 osl_File_E_NOTDIR not a directory<br> 678 osl_File_E_NXIO no such device or address<br> 679 osl_File_E_NODEV no such device<br> 680 osl_File_E_ROFS read-only file system<br> 681 osl_File_E_TXTBSY text file busy<br> 682 osl_File_E_FAULT bad address<br> 683 osl_File_E_LOOP too many symbolic links encountered<br> 684 osl_File_E_NOSPC no space left on device<br> 685 osl_File_E_ISDIR is a directory<br> 686 osl_File_E_MFILE too many open files used by the process<br> 687 osl_File_E_NFILE too many open files in the system<br> 688 osl_File_E_DQUOT quota exceeded<br> 689 osl_File_E_EXIST file exists<br> 690 osl_FilE_E_INTR function call was interrupted<br> 691 osl_File_E_IO on I/O errors<br> 692 osl_File_E_MULTIHOP multihop attempted<br> 693 osl_File_E_NOLINK link has been severed<br> 694 osl_File_E_EOVERFLOW value too large for defined data type<br> 695 696 @see osl_closeFile() 697 @see osl_setFilePos() 698 @see osl_getFilePos() 699 @see osl_readFile() 700 @see osl_writeFile() 701 @see osl_setFileSize() 702 @see osl_getFileSize() 703 */ 704 705 oslFileError SAL_CALL osl_openFile( rtl_uString *pustrFileURL, oslFileHandle *pHandle, sal_uInt32 uFlags ); 706 707 #define osl_Pos_Absolut 1 708 #define osl_Pos_Current 2 709 #define osl_Pos_End 3 710 711 /** Set the internal position pointer of an open file. 712 713 @param Handle [in] 714 Handle to a file received by a previous call to osl_openFile(). 715 716 @param uHow [in] 717 Distance to move the internal position pointer (from uPos). 718 719 @param uPos [in] 720 Absolute position from the beginning of the file. 721 722 @return 723 osl_File_E_None on success<br> 724 osl_File_E_INVAL the format of the parameters was not valid<br> 725 osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br> 726 727 @see osl_openFile() 728 @see osl_getFilePos() 729 */ 730 731 oslFileError SAL_CALL osl_setFilePos( oslFileHandle Handle, sal_uInt32 uHow, sal_Int64 uPos ); 732 733 734 /** Retrieve the current position of the internal pointer of an open file. 735 736 @param Handle [in] 737 Handle to a file received by a previous call to osl_openFile(). 738 739 @param pPos [out] 740 On success receives the current position of the file pointer. 741 742 @return 743 osl_File_E_None on success<br> 744 osl_File_E_INVAL the format of the parameters was not valid<br> 745 osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br> 746 747 @see osl_openFile() 748 @see osl_setFilePos() 749 @see osl_readFile() 750 @see osl_writeFile() 751 */ 752 753 oslFileError SAL_CALL osl_getFilePos( oslFileHandle Handle, sal_uInt64 *pPos ); 754 755 756 /** Set the file size of an open file. 757 758 Sets the file size of an open file. The file can be truncated or enlarged by the function. 759 The position of the file pointer is not affeced by this function. 760 761 @param Handle [in] 762 Handle to a file received by a previous call to osl_openFile(). 763 764 @param uSize [in] 765 New size in bytes. 766 767 @return 768 osl_File_E_None on success<br> 769 osl_File_E_INVAL the format of the parameters was not valid<br> 770 osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br> 771 772 @see osl_openFile() 773 @see osl_setFilePos() 774 @see osl_getFileStatus() 775 @see osl_getFileSize() 776 */ 777 778 oslFileError SAL_CALL osl_setFileSize( oslFileHandle Handle, sal_uInt64 uSize ); 779 780 781 /** Get the file size of an open file. 782 783 Gets the file size of an open file. 784 The position of the file pointer is not affeced by this function. 785 786 @param Handle [in] 787 Handle to a file received by a previous call to osl_openFile(). 788 789 @param pSize [out] 790 Current size in bytes. 791 792 @return 793 osl_File_E_None on success<br> 794 osl_File_E_INVAL the format of the parameters was not valid<br> 795 osl_File_E_OVERFLOW the resulting file offset would be a value which cannot be represented correctly for regular files<br> 796 797 @see osl_openFile() 798 @see osl_setFilePos() 799 @see osl_getFileStatus() 800 */ 801 802 oslFileError SAL_CALL osl_getFileSize( oslFileHandle Handle, sal_uInt64 *pSize ); 803 804 805 /** Map flags. 806 807 @since UDK 3.2.10 808 */ 809 #define osl_File_MapFlag_RandomAccess ((sal_uInt32)(0x1)) 810 811 /** Map flag denoting that the mapped address space will be accessed by the 812 process soon (and it is advantageous for the operating system to already 813 start paging in the data). 814 815 @since UDK 3.2.12 816 */ 817 #define osl_File_MapFlag_WillNeed ((sal_uInt32)(0x2)) 818 819 /** Map a shared file into memory. 820 821 @since UDK 3.2.10 822 */ 823 oslFileError 824 SAL_CALL osl_mapFile ( 825 oslFileHandle Handle, 826 void** ppAddr, 827 sal_uInt64 uLength, 828 sal_uInt64 uOffset, 829 sal_uInt32 uFlags 830 ); 831 832 833 /** Unmap a shared file from memory. 834 835 @since UDK 3.2.10 836 */ 837 oslFileError 838 SAL_CALL osl_unmapFile ( 839 void* pAddr, 840 sal_uInt64 uLength 841 ); 842 843 844 /** Read a number of bytes from a file. 845 846 Reads a number of bytes from a file. The internal file pointer is 847 increased by the number of bytes read. 848 849 @param Handle [in] 850 Handle to a file received by a previous call to osl_openFile(). 851 852 @param pBuffer [out] 853 Points to a buffer which receives data. The buffer must be large enough 854 to hold uBytesRequested bytes. 855 856 @param uBytesRequested [in] 857 Number of bytes which should be retrieved. 858 859 @param pBytesRead [out] 860 On success the number of bytes which have actually been retrieved. 861 862 @return 863 osl_File_E_None on success<br> 864 osl_File_E_INVAL the format of the parameters was not valid<br> 865 osl_File_E_INTR function call was interrupted<br> 866 osl_File_E_IO on I/O errors<br> 867 osl_File_E_ISDIR is a directory<br> 868 osl_File_E_BADF bad file<br> 869 osl_File_E_FAULT bad address<br> 870 osl_File_E_AGAIN operation would block<br> 871 osl_File_E_NOLINK link has been severed<br> 872 873 @see osl_openFile() 874 @see osl_writeFile() 875 @see osl_readLine() 876 @see osl_setFilePos() 877 */ 878 879 oslFileError SAL_CALL osl_readFile( oslFileHandle Handle, void *pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 *pBytesRead ); 880 881 882 /** Test if the end of a file is reached. 883 884 @param Handle [in] 885 Handle to a file received by a previous call to osl_openFile(). 886 887 @param pIsEOF [out] 888 Points to a variable that receives the end-of-file status. 889 890 @return 891 osl_File_E_None on success <br> 892 osl_File_E_INVAL the format of the parameters was not valid<br> 893 osl_File_E_INTR function call was interrupted<br> 894 osl_File_E_IO on I/O errors<br> 895 osl_File_E_ISDIR is a directory<br> 896 osl_File_E_BADF bad file<br> 897 osl_File_E_FAULT bad address<br> 898 osl_File_E_AGAIN operation would block<br> 899 osl_File_E_NOLINK link has been severed<p> 900 901 @see osl_openFile() 902 @see osl_readFile() 903 @see osl_readLine() 904 @see osl_setFilePos() 905 */ 906 907 oslFileError SAL_CALL osl_isEndOfFile( oslFileHandle Handle, sal_Bool *pIsEOF ); 908 909 910 /** Write a number of bytes to a file. 911 912 Writes a number of bytes to a file. 913 The internal file pointer is increased by the number of bytes read. 914 915 @param Handle [in] 916 Handle to a file received by a previous call to osl_openFile(). 917 918 @param pBuffer [in] 919 Points to a buffer which contains the data. 920 921 @param uBytesToWrite [in] 922 Number of bytes which should be written. 923 924 @param pBytesWritten [out] 925 On success the number of bytes which have actually been written. 926 927 @return 928 osl_File_E_None on success<br> 929 osl_File_E_INVAL the format of the parameters was not valid<br> 930 osl_File_E_FBIG file too large<br> 931 osl_File_E_DQUOT quota exceeded<p> 932 osl_File_E_AGAIN operation would block<br> 933 osl_File_E_BADF bad file<br> 934 osl_File_E_FAULT bad address<br> 935 osl_File_E_INTR function call was interrupted<br> 936 osl_File_E_IO on I/O errosr<br> 937 osl_File_E_NOLCK no record locks available<br> 938 osl_File_E_NOLINK link has been severed<br> 939 osl_File_E_NOSPC no space left on device<br> 940 osl_File_E_NXIO no such device or address<br> 941 942 @see osl_openFile() 943 @see osl_readFile() 944 @see osl_setFilePos() 945 */ 946 947 oslFileError SAL_CALL osl_writeFile( oslFileHandle Handle, const void *pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 *pBytesWritten ); 948 949 /** Read a number of bytes from a specified offset in a file. 950 951 The current position of the internal file pointer may or may not be changed. 952 953 @since UDK 3.2.10 954 */ 955 oslFileError SAL_CALL osl_readFileAt( 956 oslFileHandle Handle, 957 sal_uInt64 uOffset, 958 void* pBuffer, 959 sal_uInt64 uBytesRequested, 960 sal_uInt64* pBytesRead 961 ); 962 963 964 /** Write a number of bytes to a specified offset in a file. 965 966 The current position of the internal file pointer may or may not be changed. 967 968 @since UDK 3.2.10 969 */ 970 oslFileError SAL_CALL osl_writeFileAt( 971 oslFileHandle Handle, 972 sal_uInt64 uOffset, 973 const void* pBuffer, 974 sal_uInt64 uBytesToWrite, 975 sal_uInt64* pBytesWritten 976 ); 977 978 979 /** Read a line from a file. 980 981 Reads a line from a file. The new line delimiter is NOT returned! 982 983 @param Handle [in] 984 Handle to a file received by a previous call to osl_openFile(). 985 986 @param ppSequence [in/out] 987 A pointer pointer to a sal_Sequence that will hold the line read on success. 988 989 @return 990 osl_File_E_None on success<br> 991 osl_File_E_INVAL the format of the parameters was not valid<br> 992 osl_File_E_INTR function call was interrupted<br> 993 osl_File_E_IO on I/O errors<br> 994 osl_File_E_ISDIR is a directory<br> 995 osl_File_E_BADF bad file<br> 996 osl_File_E_FAULT bad address<br> 997 osl_File_E_AGAIN operation would block<br> 998 osl_File_E_NOLINK link has been severed<p> 999 1000 @see osl_openFile() 1001 @see osl_readFile() 1002 @see osl_writeFile() 1003 @see osl_setFilePos() 1004 */ 1005 1006 oslFileError SAL_CALL osl_readLine( oslFileHandle Handle, sal_Sequence** ppSequence ); 1007 1008 /** Synchronize the memory representation of a file with that on the physical medium. 1009 1010 The function ensures that all modified data and attributes of the file associated with 1011 the given file handle have been written to the physical medium. 1012 In case the hard disk has a write cache enabled, the data may not really be on 1013 permanent storage when osl_syncFile returns. 1014 1015 @param Handle 1016 [in] Handle to a file received by a previous call to osl_openFile(). 1017 1018 @return 1019 <dl> 1020 <dt>osl_File_E_None</dt> 1021 <dd>On success</dd> 1022 <dt>osl_File_E_INVAL</dt> 1023 <dd>The value of the input parameter is invalid</dd> 1024 </dl> 1025 <br><p><strong>In addition to these error codes others may occur as well, for instance:</strong></p><br> 1026 <dl> 1027 <dt>osl_File_E_BADF</dt> 1028 <dd>The file associated with the given file handle is not open for writing</dd> 1029 <dt>osl_File_E_IO</dt> 1030 <dd>An I/O error occurred</dd> 1031 <dt>osl_File_E_NOSPC</dt> 1032 <dd>There is no enough space on the target device</dd> 1033 <dt>osl_File_E_ROFS</dt> 1034 <dd>The file associated with the given file handle is located on a read only file system</dd> 1035 <dt>osl_File_E_TIMEDOUT</dt> 1036 <dd>A remote connection timed out. This may happen when a file is on a remote location</dd> 1037 </dl> 1038 1039 @see osl_openFile() 1040 @see osl_writeFile() 1041 */ 1042 oslFileError SAL_CALL osl_syncFile(oslFileHandle Handle); 1043 1044 /** Close an open file. 1045 1046 @param Handle [in] 1047 Handle to a file received by a previous call to osl_openFile(). 1048 1049 @return 1050 osl_File_E_None on success<br> 1051 osl_File_E_INVAL the format of the parameters was not valid<br> 1052 osl_File_E_BADF Bad file<br> 1053 osl_File_E_INTR function call was interrupted<br> 1054 osl_File_E_NOLINK link has been severed<br> 1055 osl_File_E_NOSPC no space left on device<br> 1056 osl_File_E_IO on I/O errors<br> 1057 1058 @see osl_openFile() 1059 */ 1060 1061 oslFileError SAL_CALL osl_closeFile( oslFileHandle Handle ); 1062 1063 1064 /** Create a directory. 1065 1066 @param pustrDirectoryURL [in] 1067 Full qualified URL of the directory to create. 1068 1069 @return 1070 osl_File_E_None on success<br> 1071 osl_File_E_INVAL the format of the parameters was not valid<br> 1072 osl_File_E_NOMEM not enough memory for allocating structures <br> 1073 osl_File_E_EXIST file exists<br> 1074 osl_File_E_ACCES permission denied<br> 1075 osl_File_E_NAMETOOLONG file name too long<br> 1076 osl_File_E_NOENT no such file or directory<br> 1077 osl_File_E_NOTDIR not a directory<br> 1078 osl_File_E_ROFS read-only file system<br> 1079 osl_File_E_NOSPC no space left on device<br> 1080 osl_File_E_DQUOT quota exceeded<br> 1081 osl_File_E_LOOP too many symbolic links encountered<br> 1082 osl_File_E_FAULT bad address<br> 1083 osl_FileE_IO on I/O errors<br> 1084 osl_File_E_MLINK too many links<br> 1085 osl_File_E_MULTIHOP multihop attempted<br> 1086 osl_File_E_NOLINK link has been severed<br> 1087 1088 @see osl_removeDirectory() 1089 */ 1090 1091 oslFileError SAL_CALL osl_createDirectory( rtl_uString* pustrDirectoryURL ); 1092 1093 1094 /** Remove an empty directory. 1095 1096 @param pustrDirectoryURL [in] 1097 Full qualified URL of the directory. 1098 1099 @return 1100 osl_File_E_None on success<br> 1101 osl_File_E_INVAL the format of the parameters was not valid<br> 1102 osl_File_E_NOMEM not enough memory for allocating structures <br> 1103 osl_File_E_PERM operation not permitted<br> 1104 osl_File_E_ACCES permission denied<br> 1105 osl_File_E_NOENT no such file or directory<br> 1106 osl_File_E_NOTDIR not a directory<br> 1107 osl_File_E_NOTEMPTY directory not empty<br> 1108 osl_File_E_FAULT bad address<br> 1109 osl_File_E_NAMETOOLONG file name too long<br> 1110 osl_File_E_BUSY device or resource busy<br> 1111 osl_File_E_ROFS read-only file system<br> 1112 osl_File_E_LOOP too many symbolic links encountered<br> 1113 osl_File_E_BUSY device or resource busy<br> 1114 osl_File_E_EXIST file exists<br> 1115 osl_File_E_IO on I/O errors<br> 1116 osl_File_E_MULTIHOP multihop attempted<br> 1117 osl_File_E_NOLINK link has been severed<br> 1118 1119 @see osl_createDirectory() 1120 */ 1121 1122 oslFileError SAL_CALL osl_removeDirectory( rtl_uString* pustrDirectoryURL ); 1123 1124 /** Function pointer representing a function that will be called by osl_createDirectoryPath 1125 if a directory has been created. 1126 1127 To avoid unpredictable results the callee must not access the directory whose 1128 creation is just notified. 1129 1130 @param pData 1131 [in] User specified data given in osl_createDirectoryPath. 1132 1133 @param aDirectoryUrl 1134 [in] The absolute file URL of the directory that was just created by 1135 osl_createDirectoryPath. 1136 1137 @see osl_createDirectoryPath 1138 */ 1139 typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uString* aDirectoryUrl); 1140 1141 /** Create a directory path. 1142 1143 The osl_createDirectoryPath function creates a specified directory path. 1144 All nonexisting sub directories will be created. 1145 <p><strong>PLEASE NOTE:</strong> You cannot rely on getting the error code 1146 osl_File_E_EXIST for existing directories. Programming against this error 1147 code is in general a strong indication of a wrong usage of osl_createDirectoryPath.</p> 1148 1149 @param aDirectoryUrl 1150 [in] The absolute file URL of the directory path to create. 1151 A relative file URL will not be accepted. 1152 1153 @param aDirectoryCreationFunc 1154 [in] Pointer to a function that will be called synchronously 1155 for each sub directory that was created. The value of this 1156 parameter may be NULL, in this case notifications will not be 1157 sent. 1158 1159 @param pData 1160 [in] User specified data to be passed to the directory creation 1161 callback function. The value of this parameter may be arbitrary 1162 and will not be interpreted by osl_createDirectoryPath. 1163 1164 @return 1165 <dl> 1166 <dt>osl_File_E_None</dt> 1167 <dd>On success</dd> 1168 <dt>osl_File_E_INVAL</dt> 1169 <dd>The format of the parameters was not valid</dd> 1170 <dt>osl_File_E_ACCES</dt> 1171 <dd>Permission denied</dd> 1172 <dt>osl_File_E_EXIST</dt> 1173 <dd>The final node of the specified directory path already exist</dd> 1174 <dt>osl_File_E_NAMETOOLONG</dt> 1175 <dd>The name of the specified directory path exceeds the maximum allowed length</dd> 1176 <dt>osl_File_E_NOTDIR</dt> 1177 <dd>A component of the specified directory path already exist as file in any part of the directory path</dd> 1178 <dt>osl_File_E_ROFS</dt> 1179 <dd>Read-only file system</dd> 1180 <dt>osl_File_E_NOSPC</dt> 1181 <dd>No space left on device</dd> 1182 <dt>osl_File_E_DQUOT</dt> 1183 <dd>Quota exceeded</dd> 1184 <dt>osl_File_E_FAULT</dt> 1185 <dd>Bad address</dd> 1186 <dt>osl_File_E_IO</dt> 1187 <dd>I/O error</dd> 1188 <dt>osl_File_E_LOOP</dt> 1189 <dd>Too many symbolic links encountered</dd> 1190 <dt>osl_File_E_NOLINK</dt> 1191 <dd>Link has been severed</dd> 1192 <dt>osl_File_E_invalidError</dt> 1193 <dd>An unknown error occurred</dd> 1194 </dl> 1195 1196 @see oslDirectoryCreationFunc 1197 @see oslFileError 1198 @see osl_createDirectory 1199 */ 1200 oslFileError SAL_CALL osl_createDirectoryPath( 1201 rtl_uString* aDirectoryUrl, 1202 oslDirectoryCreationCallbackFunc aDirectoryCreationCallbackFunc, 1203 void* pData); 1204 1205 /** Remove a regular file. 1206 1207 @param pustrFileURL [in] 1208 Full qualified URL of the file to remove. 1209 1210 @return 1211 osl_File_E_None on success<br> 1212 osl_File_E_INVAL the format of the parameters was not valid<br> 1213 osl_File_E_NOMEM not enough memory for allocating structures <br> 1214 osl_File_E_ACCES permission denied<br> 1215 osl_File_E_PERM operation not permitted<br> 1216 osl_File_E_NAMETOOLONG file name too long<br> 1217 osl_File_E_NOENT no such file or directory<br> 1218 osl_File_E_ISDIR is a directory<br> 1219 osl_File_E_ROFS read-only file system<br> 1220 osl_File_E_FAULT bad address<br> 1221 osl_File_E_LOOP too many symbolic links encountered<br> 1222 osl_File_E_IO on I/O errors<br> 1223 osl_File_E_BUSY device or resource busy<br> 1224 osl_File_E_INTR function call was interrupted<br> 1225 osl_File_E_LOOP too many symbolic links encountered<br> 1226 osl_File_E_MULTIHOP multihop attempted<br> 1227 osl_File_E_NOLINK link has been severed<br> 1228 osl_File_E_TXTBSY text file busy<br> 1229 1230 @see osl_openFile() 1231 */ 1232 1233 oslFileError SAL_CALL osl_removeFile( rtl_uString* pustrFileURL ); 1234 1235 1236 /** Copy a file to a new destination. 1237 1238 Copies a file to a new destination. Copies only files not directories. 1239 No assumptions should be made about preserving attributes or file time. 1240 1241 @param pustrSourceFileURL [in] 1242 Full qualified URL of the source file. 1243 1244 @param pustrDestFileURL [in] 1245 Full qualified URL of the destination file. A directory is NOT a valid destination file! 1246 1247 @return 1248 osl_File_E_None on success<br> 1249 osl_File_E_INVAL the format of the parameters was not valid<br> 1250 osl_File_E_NOMEM not enough memory for allocating structures <br> 1251 osl_File_E_ACCES permission denied<br> 1252 osl_File_E_PERM operation not permitted<br> 1253 osl_File_E_NAMETOOLONG file name too long<br> 1254 osl_File_E_NOENT no such file or directory<br> 1255 osl_File_E_ISDIR is a directory<br> 1256 osl_File_E_ROFS read-only file system<p> 1257 1258 @see osl_moveFile() 1259 @see osl_removeFile() 1260 */ 1261 1262 oslFileError SAL_CALL osl_copyFile( rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL ); 1263 1264 1265 /** Move a file or directory to a new destination or renames it. 1266 1267 Moves a file or directory to a new destination or renames it. 1268 File time and attributes are preserved. 1269 1270 @param pustrSourceFileURL [in] 1271 Full qualified URL of the source file. 1272 1273 @param pustrDestFileURL [in] 1274 Full qualified URL of the destination file. An existing directory is NOT a valid destination ! 1275 1276 @return 1277 osl_File_E_None on success<br> 1278 osl_File_E_INVAL the format of the parameters was not valid<br> 1279 osl_File_E_NOMEM not enough memory for allocating structures <br> 1280 osl_File_E_ACCES permission denied<br> 1281 osl_File_E_PERM operation not permitted<br> 1282 osl_File_E_NAMETOOLONG file name too long<br> 1283 osl_File_E_NOENT no such file or directory<br> 1284 osl_File_E_ROFS read-only file system<br> 1285 1286 @see osl_copyFile() 1287 */ 1288 1289 oslFileError SAL_CALL osl_moveFile( rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL ); 1290 1291 1292 /** Determine a valid unused canonical name for a requested name. 1293 1294 Determines a valid unused canonical name for a requested name. 1295 Depending on the Operating System and the File System the illegal characters are replaced by valid ones. 1296 If a file or directory with the requested name already exists a new name is generated following 1297 the common rules on the actual Operating System and File System. 1298 1299 @param pustrRequestedURL [in] 1300 Requested name of a file or directory. 1301 1302 @param ppustrValidURL [out] 1303 On success receives a name which is unused and valid on the actual Operating System and 1304 File System. 1305 1306 @return 1307 osl_File_E_None on success<br> 1308 osl_File_E_INVAL the format of the parameters was not valid<br> 1309 1310 @see osl_getFileStatus() 1311 */ 1312 1313 oslFileError SAL_CALL osl_getCanonicalName( rtl_uString *pustrRequestedURL, rtl_uString **ppustrValidURL); 1314 1315 1316 /** Convert a path relative to a given directory into an full qualified file URL. 1317 1318 Convert a path relative to a given directory into an full qualified file URL. 1319 The function resolves symbolic links if possible and path ellipses, so on success 1320 the resulting absolute path is fully resolved. 1321 1322 @param pustrBaseDirectoryURL [in] 1323 Base directory URL to which the relative path is related to. 1324 1325 @param pustrRelativeFileURL [in] 1326 An URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL 1327 or an absolute path. 1328 If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored. 1329 1330 @param ppustrAbsoluteFileURL [out] 1331 On success it receives the full qualified absoulte file URL. 1332 1333 @return 1334 osl_File_E_None on success<br> 1335 osl_File_E_INVAL the format of the parameters was not valid<br> 1336 osl_File_E_NOMEM not enough memory for allocating structures <br> 1337 osl_File_E_NOTDIR not a directory<br> 1338 osl_File_E_ACCES permission denied<br> 1339 osl_File_E_NOENT no such file or directory<br> 1340 osl_File_E_NAMETOOLONG file name too long<br> 1341 osl_File_E_OVERFLOW value too large for defined data type<br> 1342 osl_File_E_FAULT bad address<br> 1343 osl_File_E_INTR function call was interrupted<br> 1344 osl_File_E_LOOP too many symbolic links encountered<br> 1345 osl_File_E_MULTIHOP multihop attempted<br> 1346 osl_File_E_NOLINK link has been severed<br> 1347 1348 @see osl_getFileStatus() 1349 */ 1350 1351 oslFileError SAL_CALL osl_getAbsoluteFileURL( 1352 rtl_uString* pustrBaseDirectoryURL, 1353 rtl_uString *pustrRelativeFileURL, 1354 rtl_uString **ppustrAbsoluteFileURL ); 1355 1356 1357 /** Convert a system dependend path into a file URL. 1358 1359 @param pustrSystemPath [in] 1360 A System dependent path of a file or directory. 1361 1362 @param ppustrFileURL [out] 1363 On success it receives the file URL. 1364 1365 @return 1366 osl_File_E_None on success<br> 1367 osl_File_E_INVAL the format of the parameters was not valid<br> 1368 1369 @see osl_getSystemPathFromFileURL() 1370 */ 1371 1372 oslFileError SAL_CALL osl_getFileURLFromSystemPath( rtl_uString *pustrSystemPath, rtl_uString **ppustrFileURL); 1373 1374 1375 /** Searche a full qualified system path or a file URL. 1376 1377 @param pustrFileName [in] 1378 A system dependent path, a file URL, a file or relative directory. 1379 1380 @param pustrSearchPath [in] 1381 A list of system paths, in which a given file has to be searched. The Notation of a path list is 1382 system dependend, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH". 1383 These paths are only for the search of a file or a relative path, otherwise it will be ignored. 1384 If pustrSearchPath is NULL or while using the search path the search failed, the function searches for 1385 a matching file in all system directories and in the directories listed in the PATH environment 1386 variable. 1387 The value of an environment variable should be used (e.g. LD_LIBRARY_PATH) if the caller is not 1388 aware of the Operating System and so doesn't know which path list delimiter to use. 1389 1390 @param ppustrFileURL [out] 1391 On success it receives the full qualified file URL. 1392 1393 @return 1394 osl_File_E_None on success<br> 1395 osl_File_E_INVAL the format of the parameters was not valid<br> 1396 osl_File_E_NOTDIR not a directory<br> 1397 osl_File_E_NOENT no such file or directory not found<br> 1398 1399 @see osl_getFileURLFromSystemPath() 1400 @see osl_getSystemPathFromFileURL() 1401 */ 1402 1403 oslFileError SAL_CALL osl_searchFileURL( rtl_uString *pustrFileName, rtl_uString *pustrSearchPath, rtl_uString **ppustrFileURL ); 1404 1405 1406 /** Convert a file URL into a system dependend path. 1407 1408 @param pustrFileURL [in] 1409 A File URL. 1410 1411 @param ppustrSystemPath [out] 1412 On success it receives the system path. 1413 1414 @return 1415 osl_File_E_None on success 1416 osl_File_E_INVAL the format of the parameters was not valid 1417 1418 @see osl_getFileURLFromSystemPath() 1419 */ 1420 1421 oslFileError SAL_CALL osl_getSystemPathFromFileURL( rtl_uString *pustrFileURL, rtl_uString **ppustrSystemPath); 1422 1423 1424 /** Function pointer representing the function called back from osl_abbreviateSystemPath 1425 1426 @param ustrText [in] 1427 Text to calculate the width for 1428 1429 @return 1430 The width of the text specified by ustrText, e.g. it can return the width in pixel 1431 or the width in character count. 1432 1433 @see osl_abbreviateSystemPath() 1434 */ 1435 1436 typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText ); 1437 1438 1439 /** Abbreviate a system notation path. 1440 1441 @param ustrSystemPath [in] 1442 The full system path to abbreviate 1443 1444 @param pustrCompacted [out] 1445 Receives the compacted system path on output 1446 1447 @param pfnCalcWidth [in] 1448 Function ptr that calculates the width of a string. Can be zero. 1449 1450 @param uMaxWidth [in] 1451 Maximum width allowed that is retunrned from pfnCalcWidth. 1452 If pfnCalcWidth is zero the character count is assumed as width. 1453 1454 @return 1455 osl_File_E_None on success<br> 1456 1457 @see oslCalcTextWidthFunc 1458 */ 1459 1460 oslFileError SAL_CALL osl_abbreviateSystemPath( 1461 rtl_uString *ustrSystemPath, 1462 rtl_uString **pustrCompacted, 1463 sal_uInt32 uMaxWidth, 1464 oslCalcTextWidthFunc pCalcWidth ); 1465 1466 1467 /** Set file attributes. 1468 1469 @param pustrFileURL [in] 1470 The full qualified file URL. 1471 1472 @param uAttributes [in] 1473 Attributes of the file to be set. 1474 1475 @return 1476 osl_File_E_None on success<br> 1477 osl_File_E_INVAL the format of the parameters was not valid<br> 1478 1479 @see osl_getFileStatus() 1480 */ 1481 1482 oslFileError SAL_CALL osl_setFileAttributes( rtl_uString *pustrFileURL, sal_uInt64 uAttributes ); 1483 1484 1485 /** Set the file time. 1486 1487 @param pustrFileURL [in] 1488 The full qualified URL of the file. 1489 1490 @param aCreationTime [in] 1491 Creation time of the given file. 1492 1493 @param aLastAccessTime [in] 1494 Time of the last access of the given file. 1495 1496 @param aLastWriteTime [in] 1497 Time of the last modifying of the given file. 1498 1499 @return 1500 osl_File_E_None on success<br> 1501 osl_File_E_INVAL the format of the parameters was not valid<br> 1502 osl_File_E_NOENT no such file or directory not found<br> 1503 1504 @see osl_getFileStatus() 1505 */ 1506 1507 oslFileError SAL_CALL osl_setFileTime( 1508 rtl_uString *pustrFileURL, 1509 const TimeValue *aCreationTime, 1510 const TimeValue *aLastAccessTime, 1511 const TimeValue *aLastWriteTime); 1512 1513 1514 /** Retrieves the file URL of the system's temporary directory path 1515 1516 @param pustrTempDirURL[out] 1517 On success receives the URL of system's temporary directory path. 1518 1519 @return 1520 osl_File_E_None on success 1521 osl_File_E_NOENT no such file or directory not found 1522 */ 1523 1524 oslFileError SAL_CALL osl_getTempDirURL( rtl_uString **pustrTempDirURL ); 1525 1526 1527 /** Creates a temporary file in the directory provided by the caller or the 1528 directory returned by osl_getTempDirURL. 1529 1530 Creates a temporary file in the directory provided by the caller or the 1531 directory returned by osl_getTempDirURL. 1532 Under UNIX Operating Systems the file will be created with read and write 1533 access for the user exclusively. 1534 If the caller requests only a handle to the open file but not the name of 1535 it, the file will be automatically removed on close else the caller is 1536 responsible for removing the file on success. 1537 1538 @param pustrDirectoryURL [in] 1539 Specifies the full qualified URL where the temporary file should be created. 1540 If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used. 1541 1542 @param pHandle [out] 1543 On success receives a handle to the open file. If pHandle is 0 the file will 1544 be closed on return, in this case ppustrTempFileURL must not be 0. 1545 1546 @param ppustrTempFileURL [out] 1547 On success receives the full qualified URL of the temporary file. 1548 If ppustrTempFileURL is 0 the file will be automatically removed on close, 1549 in this case pHandle must not be 0. 1550 If ppustrTempFileURL is not 0 the caller receives the name of the created 1551 file and is responsible for removing the file, in this case 1552 *ppustrTempFileURL must be 0 or must point to a valid rtl_uString. 1553 1554 @descr 1555 Description of the different pHandle, ppustrTempFileURL parameter combinations. 1556 pHandle is 0 and ppustrTempDirURL is 0 - this combination is invalid 1557 pHandle is not 0 and ppustrTempDirURL is 0 - a handle to the open file 1558 will be returned on success and the file will be automatically removed on close. 1559 pHandle is 0 and ppustrTempDirURL is not 0 - the name of the file will be returned, 1560 the caller is responsible for opening, closing and removing the file. 1561 pHandle is not 0 and ppustrTempDirURL is not 0 - a handle to the open file as well as 1562 the file name will be returned, the caller is responsible for closing and removing 1563 the file. 1564 1565 @return 1566 osl_File_E_None on success 1567 osl_File_E_INVAL the format of the parameter is invalid 1568 osl_File_E_NOMEM not enough memory for allocating structures 1569 osl_File_E_ACCES Permission denied 1570 osl_File_E_NOENT No such file or directory 1571 osl_File_E_NOTDIR Not a directory 1572 osl_File_E_ROFS Read-only file system 1573 osl_File_E_NOSPC No space left on device 1574 osl_File_E_DQUOT Quota exceeded 1575 1576 @see osl_getTempDirURL() 1577 */ 1578 1579 oslFileError SAL_CALL osl_createTempFile( 1580 rtl_uString* pustrDirectoryURL, 1581 oslFileHandle* pHandle, 1582 rtl_uString** ppustrTempFileURL); 1583 1584 #ifdef __cplusplus 1585 } 1586 #endif 1587 1588 #endif /* _OSL_FILE_H_ */ 1589 1590 1591