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