include/osl/file.h

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