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