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 _OSL_FILE_H_
  21 #define _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 neccessary.<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 occured<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 availiable 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
1134 /** Remove an empty directory.
1135
1136     @param pustrDirectoryURL [in]
1137     Full qualified URL of the directory.
1138
1139     @return
1140     osl_File_E_None on success<br>
1141     osl_File_E_INVAL the format of the parameters was not valid<br>
1142     osl_File_E_NOMEM not enough memory for allocating structures <br>
1143     osl_File_E_PERM operation not permitted<br>
1144     osl_File_E_ACCES permission denied<br>
1145     osl_File_E_NOENT no such file or directory<br>
1146     osl_File_E_NOTDIR not a directory<br>
1147     osl_File_E_NOTEMPTY directory not empty<br>
1148     osl_File_E_FAULT bad address<br>
1149     osl_File_E_NAMETOOLONG file name too long<br>
1150     osl_File_E_BUSY device or resource busy<br>
1151     osl_File_E_ROFS read-only file system<br>
1152     osl_File_E_LOOP too many symbolic links encountered<br>
1153     osl_File_E_BUSY device or resource busy<br>
1154     osl_File_E_EXIST file exists<br>
1155     osl_File_E_IO on I/O errors<br>
1156     osl_File_E_MULTIHOP multihop attempted<br>
1157     osl_File_E_NOLINK link has been severed<br>
1158
1159     @see osl_createDirectory()
1160 */
1161
1162 SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeDirectory( rtl_uString* pustrDirectoryURL );
1163
1164 /** Function pointer representing a function that will be called by osl_createDirectoryPath
1165     if a directory has been created.
1166
1167     To avoid unpredictable results the callee must not access the directory whose
1168     creation is just notified.
1169
1170     @param pData
1171     [in] User specified data given in osl_createDirectoryPath.
1172
1173     @param aDirectoryUrl
1174     [in] The absolute file URL of the directory that was just created by
1175     osl_createDirectoryPath.
1176
1177     @see osl_createDirectoryPath
1178 */
1179 typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uString* aDirectoryUrl);
1180
1181 /** Create a directory path.
1182
1183     The osl_createDirectoryPath function creates a specified directory path.
1184     All nonexisting sub directories will be created.
1185     <p><strong>PLEASE NOTE:</strong> You cannot rely on getting the error code
1186     osl_File_E_EXIST for existing directories. Programming against this error
1187     code is in general a strong indication of a wrong usage of osl_createDirectoryPath.</p>
1188
1189     @param aDirectoryUrl
1190     [in] The absolute file URL of the directory path to create.
1191     A relative file URL will not be accepted.
1192
1193     @param aDirectoryCreationCallbackFunc
1194     [in] Pointer to a function that will be called synchronously
1195     for each sub directory that was created. The value of this
1196     parameter may be NULL, in this case notifications will not be
1197     sent.
1198
1199     @param pData
1200     [in] User specified data to be passed to the directory creation
1201     callback function. The value of this parameter may be arbitrary
1202     and will not be interpreted by osl_createDirectoryPath.
1203
1204     @return
1205     <dl>
1206     <dt>osl_File_E_None</dt>
1207     <dd>On success</dd>
1208     <dt>osl_File_E_INVAL</dt>
1209     <dd>The format of the parameters was not valid</dd>
1210     <dt>osl_File_E_ACCES</dt>
1211     <dd>Permission denied</dd>
1212     <dt>osl_File_E_EXIST</dt>
1213     <dd>The final node of the specified directory path already exist</dd>
1214     <dt>osl_File_E_NAMETOOLONG</dt>
1215     <dd>The name of the specified directory path exceeds the maximum allowed length</dd>
1216     <dt>osl_File_E_NOTDIR</dt>
1217     <dd>A component of the specified directory path already exist as file in any part of the directory path</dd>
1218     <dt>osl_File_E_ROFS</dt>
1219     <dd>Read-only file system</dd>
1220     <dt>osl_File_E_NOSPC</dt>
1221     <dd>No space left on device</dd>
1222     <dt>osl_File_E_DQUOT</dt>
1223     <dd>Quota exceeded</dd>
1224     <dt>osl_File_E_FAULT</dt>
1225     <dd>Bad address</dd>
1226     <dt>osl_File_E_IO</dt>
1227     <dd>I/O error</dd>
1228     <dt>osl_File_E_LOOP</dt>
1229     <dd>Too many symbolic links encountered</dd>
1230     <dt>osl_File_E_NOLINK</dt>
1231     <dd>Link has been severed</dd>
1232     <dt>osl_File_E_invalidError</dt>
1233     <dd>An unknown error occurred</dd>
1234     </dl>
1235
1236     @see oslDirectoryCreationFunc
1237     @see oslFileError
1238     @see osl_createDirectory
1239 */
1240 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryPath(
1241     rtl_uString* aDirectoryUrl,
1242     oslDirectoryCreationCallbackFunc aDirectoryCreationCallbackFunc,
1243     void* pData);
1244
1245 /** Remove a regular file.
1246
1247     @param pustrFileURL [in]
1248     Full qualified URL of the file to remove.
1249
1250     @return
1251     osl_File_E_None on success<br>
1252     osl_File_E_INVAL the format of the parameters was not valid<br>
1253     osl_File_E_NOMEM not enough memory for allocating structures <br>
1254     osl_File_E_ACCES permission denied<br>
1255     osl_File_E_PERM operation not permitted<br>
1256     osl_File_E_NAMETOOLONG file name too long<br>
1257     osl_File_E_NOENT no such file or directory<br>
1258     osl_File_E_ISDIR is a directory<br>
1259     osl_File_E_ROFS read-only file system<br>
1260     osl_File_E_FAULT bad address<br>
1261     osl_File_E_LOOP too many symbolic links encountered<br>
1262     osl_File_E_IO on I/O errors<br>
1263     osl_File_E_BUSY device or resource busy<br>
1264     osl_File_E_INTR function call was interrupted<br>
1265     osl_File_E_LOOP too many symbolic links encountered<br>
1266     osl_File_E_MULTIHOP multihop attempted<br>
1267     osl_File_E_NOLINK link has been severed<br>
1268     osl_File_E_TXTBSY text file busy<br>
1269
1270     @see osl_openFile()
1271 */
1272
1273 SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeFile(
1274         rtl_uString* pustrFileURL );
1275
1276
1277 /** Copy a file to a new destination.
1278
1279     Copies a file to a new destination. Copies only files not directories.
1280     No assumptions should be made about preserving attributes or file time.
1281
1282     @param pustrSourceFileURL [in]
1283     Full qualified URL of the source file.
1284
1285     @param pustrDestFileURL [in]
1286     Full qualified URL of the destination file. A directory is NOT a valid destination file!
1287
1288     @return
1289     osl_File_E_None on success<br>
1290     osl_File_E_INVAL the format of the parameters was not valid<br>
1291     osl_File_E_NOMEM not enough memory for allocating structures <br>
1292     osl_File_E_ACCES permission denied<br>
1293     osl_File_E_PERM operation not permitted<br>
1294     osl_File_E_NAMETOOLONG file name too long<br>
1295     osl_File_E_NOENT no such file or directory<br>
1296     osl_File_E_ISDIR is a directory<br>
1297     osl_File_E_ROFS read-only file system<p>
1298
1299     @see    osl_moveFile()
1300     @see    osl_removeFile()
1301 */
1302
1303 SAL_DLLPUBLIC oslFileError SAL_CALL osl_copyFile(
1304         rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );
1305
1306
1307 /** Move a file or directory to a new destination or renames it.
1308
1309     Moves a file or directory to a new destination or renames it.
1310     File time and attributes are preserved.
1311
1312     @param pustrSourceFileURL [in]
1313     Full qualified URL of the source file.
1314
1315     @param pustrDestFileURL [in]
1316     Full qualified URL of the destination file. An existing directory is NOT a valid destination !
1317
1318     @return
1319     osl_File_E_None on success<br>
1320     osl_File_E_INVAL the format of the parameters was not valid<br>
1321     osl_File_E_NOMEM not enough memory for allocating structures <br>
1322     osl_File_E_ACCES permission denied<br>
1323     osl_File_E_PERM operation not permitted<br>
1324     osl_File_E_NAMETOOLONG file name too long<br>
1325     osl_File_E_NOENT no such file or directory<br>
1326     osl_File_E_ROFS read-only file system<br>
1327
1328     @see osl_copyFile()
1329 */
1330
1331 SAL_DLLPUBLIC oslFileError SAL_CALL osl_moveFile(
1332         rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );
1333
1334
1335 /** Determine a valid unused canonical name for a requested name.
1336
1337     Determines a valid unused canonical name for a requested name.
1338     Depending on the Operating System and the File System the illegal characters are replaced by valid ones.
1339     If a file or directory with the requested name already exists a new name is generated following
1340     the common rules on the actual Operating System and File System.
1341
1342     @param pustrRequestedURL [in]
1343     Requested name of a file or directory.
1344
1345     @param ppustrValidURL [out]
1346     On success receives a name which is unused and valid on the actual Operating System and
1347     File System.
1348
1349     @return
1350     osl_File_E_None on success<br>
1351     osl_File_E_INVAL the format of the parameters was not valid<br>
1352
1353     @see osl_getFileStatus()
1354 */
1355
1356 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getCanonicalName(
1357         rtl_uString *pustrRequestedURL, rtl_uString **ppustrValidURL);
1358
1359
1360 /** Convert a path relative to a given directory into an full qualified file URL.
1361
1362     Convert a path relative to a given directory into an full qualified file URL.
1363     The function resolves symbolic links if possible and path ellipses, so on success
1364     the resulting absolute path is fully resolved.
1365
1366     @param pustrBaseDirectoryURL [in]
1367     Base directory URL to which the relative path is related to.
1368
1369     @param pustrRelativeFileURL [in]
1370     An URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL
1371     or an absolute path.
1372     If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored.
1373
1374     @param ppustrAbsoluteFileURL [out]
1375     On success it receives the full qualified absoulte file URL.
1376
1377     @return
1378     osl_File_E_None on success<br>
1379     osl_File_E_INVAL the format of the parameters was not valid<br>
1380     osl_File_E_NOMEM not enough memory for allocating structures <br>
1381     osl_File_E_NOTDIR not a directory<br>
1382     osl_File_E_ACCES permission denied<br>
1383     osl_File_E_NOENT no such file or directory<br>
1384     osl_File_E_NAMETOOLONG file name too long<br>
1385     osl_File_E_OVERFLOW value too large for defined data type<br>
1386     osl_File_E_FAULT bad address<br>
1387     osl_File_E_INTR function call was interrupted<br>
1388     osl_File_E_LOOP too many symbolic links encountered<br>
1389     osl_File_E_MULTIHOP multihop attempted<br>
1390     osl_File_E_NOLINK link has been severed<br>
1391
1392     @see    osl_getFileStatus()
1393 */
1394
1395 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getAbsoluteFileURL(
1396     rtl_uString* pustrBaseDirectoryURL,
1397     rtl_uString *pustrRelativeFileURL,
1398     rtl_uString **ppustrAbsoluteFileURL );
1399
1400
1401 /** Convert a system dependend path into a file URL.
1402
1403     @param pustrSystemPath [in]
1404     A System dependent path of a file or directory.
1405
1406     @param ppustrFileURL [out]
1407     On success it receives the file URL.
1408
1409     @return
1410     osl_File_E_None on success<br>
1411     osl_File_E_INVAL the format of the parameters was not valid<br>
1412
1413     @see osl_getSystemPathFromFileURL()
1414 */
1415
1416 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath(
1417         rtl_uString *pustrSystemPath, rtl_uString **ppustrFileURL);
1418
1419
1420 /** Searche a full qualified system path or a file URL.
1421
1422     @param pustrFileName [in]
1423     A system dependent path, a file URL, a file or relative directory.
1424
1425     @param pustrSearchPath [in]
1426     A list of system paths, in which a given file has to be searched. The Notation of a path list is
1427     system dependend, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH".
1428     These paths are only for the search of a file or a relative path, otherwise it will be ignored.
1429     If pustrSearchPath is NULL or while using the search path the search failed, the function searches for
1430     a matching file in all system directories and in the directories listed in the PATH environment
1431     variable.
1432     The value of an environment variable should be used (e.g. LD_LIBRARY_PATH) if the caller is not
1433     aware of the Operating System and so doesn't know which path list delimiter to use.
1434
1435     @param ppustrFileURL [out]
1436     On success it receives the full qualified file URL.
1437
1438     @return
1439     osl_File_E_None on success<br>
1440     osl_File_E_INVAL the format of the parameters was not valid<br>
1441     osl_File_E_NOTDIR not a directory<br>
1442     osl_File_E_NOENT no such file or directory not found<br>
1443
1444     @see osl_getFileURLFromSystemPath()
1445     @see osl_getSystemPathFromFileURL()
1446 */
1447
1448 SAL_DLLPUBLIC oslFileError SAL_CALL osl_searchFileURL(
1449         rtl_uString *pustrFileName, rtl_uString *pustrSearchPath, rtl_uString **ppustrFileURL );
1450
1451
1452 /** Convert a file URL into a system dependend path.
1453
1454     @param pustrFileURL [in]
1455     A File URL.
1456
1457     @param ppustrSystemPath [out]
1458     On success it receives the system path.
1459
1460     @return
1461     osl_File_E_None on success
1462     osl_File_E_INVAL the format of the parameters was not valid
1463
1464     @see osl_getFileURLFromSystemPath()
1465 */
1466
1467 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getSystemPathFromFileURL(
1468         rtl_uString *pustrFileURL, rtl_uString **ppustrSystemPath);
1469
1470
1471 /** Function pointer representing the function called back from osl_abbreviateSystemPath
1472
1473     @param ustrText [in]
1474     Text to calculate the width for
1475
1476     @return
1477     The width of the text specified by ustrText, e.g. it can return the width in pixel
1478     or the width in character count.
1479
1480     @see osl_abbreviateSystemPath()
1481 */
1482
1483 typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText );
1484
1485
1486 /** Abbreviate a system notation path.
1487
1488     @param ustrSystemPath [in]
1489     The full system path to abbreviate
1490
1491     @param pustrCompacted [out]
1492     Receives the compacted system path on output
1493
1494     @param pCalcWidth [in]
1495     Function ptr that calculates the width of a string. Can be zero.
1496
1497     @param uMaxWidth [in]
1498     Maximum width allowed that is retunrned from pCalcWidth.
1499     If pCalcWidth is zero the character count is assumed as width.
1500
1501     @return
1502     osl_File_E_None on success<br>
1503
1504     @see    oslCalcTextWidthFunc
1505 */
1506
1507 SAL_DLLPUBLIC oslFileError SAL_CALL osl_abbreviateSystemPath(
1508     rtl_uString *ustrSystemPath,
1509     rtl_uString **pustrCompacted,
1510     sal_uInt32 uMaxWidth,
1511     oslCalcTextWidthFunc pCalcWidth );
1512
1513
1514 /** Set file attributes.
1515
1516     @param pustrFileURL [in]
1517     The full qualified file URL.
1518
1519     @param uAttributes [in]
1520     Attributes of the file to be set.
1521
1522     @return
1523     osl_File_E_None on success<br>
1524     osl_File_E_INVAL the format of the parameters was not valid<br>
1525
1526     @see osl_getFileStatus()
1527 */
1528
1529 SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileAttributes(
1530         rtl_uString *pustrFileURL, sal_uInt64 uAttributes );
1531
1532
1533 /** Set the file time.
1534
1535     @param pustrFileURL [in]
1536     The full qualified URL of the file.
1537
1538     @param aCreationTime [in]
1539     Creation time of the given file.
1540
1541     @param aLastAccessTime [in]
1542     Time of the last access of the given file.
1543
1544     @param aLastWriteTime [in]
1545     Time of the last modifying of the given file.
1546
1547     @return
1548     osl_File_E_None on success<br>
1549     osl_File_E_INVAL the format of the parameters was not valid<br>
1550     osl_File_E_NOENT no such file or directory not found<br>
1551
1552     @see osl_getFileStatus()
1553 */
1554
1555 SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileTime(
1556     rtl_uString *pustrFileURL,
1557     const TimeValue *aCreationTime,
1558     const TimeValue *aLastAccessTime,
1559     const TimeValue *aLastWriteTime);
1560
1561
1562 /** Retrieves the file URL of the system's temporary directory path
1563
1564     @param[out] pustrTempDirURL
1565     On success receives the URL of system's temporary directory path.
1566
1567     @return
1568     osl_File_E_None on success
1569     osl_File_E_NOENT no such file or directory not found
1570 */
1571
1572 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL(
1573         rtl_uString **pustrTempDirURL );
1574
1575
1576 /** Creates a temporary file in the directory provided by the caller or the
1577     directory returned by osl_getTempDirURL.
1578
1579     Creates a temporary file in the directory provided by the caller or the
1580     directory returned by osl_getTempDirURL.
1581     Under UNIX Operating Systems the file will be created with read and write
1582     access for the user exclusively.
1583     If the caller requests only a handle to the open file but not the name of
1584     it, the file will be automatically removed on close else the caller is
1585     responsible for removing the file on success.
1586
1587     Description of the different pHandle, ppustrTempFileURL parameter combinations.
1588     pHandle is 0 and ppustrTempDirURL is 0 - this combination is invalid
1589     pHandle is not 0 and ppustrTempDirURL is 0 - a handle to the open file
1590     will be returned on success and the file will be automatically removed on close.
1591     pHandle is 0 and ppustrTempDirURL is not 0 - the name of the file will be returned,
1592     the caller is responsible for opening, closing and removing the file.
1593     pHandle is not 0 and ppustrTempDirURL is not 0 - a handle to the open file as well as
1594     the file name will be returned, the caller is responsible for closing and removing
1595     the file.
1596
1597     @param  pustrDirectoryURL [in]
1598     Specifies the full qualified URL where the temporary file should be created.
1599     If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used.
1600
1601     @param  pHandle [out]
1602     On success receives a handle to the open file. If pHandle is 0 the file will
1603     be closed on return, in this case ppustrTempFileURL must not be 0.
1604
1605     @param  ppustrTempFileURL [out]
1606     On success receives the full qualified URL of the temporary file.
1607     If ppustrTempFileURL is 0 the file will be automatically removed on close,
1608     in this case pHandle must not be 0.
1609     If ppustrTempFileURL is not 0 the caller receives the name of the created
1610     file and is responsible for removing the file, in this case
1611     *ppustrTempFileURL must be 0 or must point to a valid rtl_uString.
1612
1613     @return
1614     osl_File_E_None   on success
1615     osl_File_E_INVAL  the format of the parameter is invalid
1616     osl_File_E_NOMEM  not enough memory for allocating structures
1617     osl_File_E_ACCES  Permission denied
1618     osl_File_E_NOENT  No such file or directory
1619     osl_File_E_NOTDIR Not a directory
1620     osl_File_E_ROFS   Read-only file system
1621     osl_File_E_NOSPC  No space left on device
1622     osl_File_E_DQUOT  Quota exceeded
1623
1624     @see    osl_getTempDirURL()
1625 */
1626
1627 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createTempFile(
1628     rtl_uString*   pustrDirectoryURL,
1629     oslFileHandle* pHandle,
1630     rtl_uString**  ppustrTempFileURL);
1631
1632 #ifdef __cplusplus
1633 }
1634 #endif
1635
1636 #endif  /* _OSL_FILE_H_ */
1637
1638
1639 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */