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