sal/inc/osl/file.h

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