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