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