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