Gitiles
Code Review Sign In
192.168.1.100 / T800_MD / 6c1fd8fba87d5723e0e5614ae30b4258b603cb70 / . / mcu / interface / service / fs / fs_general_api.h
blob: a2ea6881b00ef601c094c8f84550840c2660d2a5 [file] [log] [blame]
rjw6c1fd8f2022-11-30 14:33:01 +0800[diff] [blame^]1/*****************************************************************************
2* Copyright Statement:
3* --------------------
4* This software is protected by Copyright and the information contained
5* herein is confidential. The software may not be copied and the information
6* contained herein may not be used or disclosed except with the written
7* permission of MediaTek Inc. (C) 2005
8*
9* BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
10* THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE")
11* RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON
12* AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES,
13* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
14* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
15* NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
16* SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
17* SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH
18* THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO
19* NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S
20* SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM.
21*
22* BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE
23* LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
24* AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE,
25* OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO
26* MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
27*
28* THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
29* WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
30* LAWS PRINCIPLES. ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
31* RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
32* THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
33*
34*****************************************************************************/
35
36/*****************************************************************************
37 *
38 * Filename:
39 * ---------
40 * fs_general_api.h
41 *
42 * Project:
43 * --------
44 * Maui Software
45 *
46 * Description:
47 * ------------
48 * This file provides the header of MTK file system service.
49 *
50 * Author:
51 * -------
52 * -------
53 *
54 *============================================================================
55 * HISTORY
56 * Below this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
57 *------------------------------------------------------------------------------
58 * removed!
59 * removed!
60 * removed!
61 *
62 * removed!
63 * removed!
64 * removed!
65 *
66 * removed!
67 * removed!
68 * removed!
69 * removed!
70 *
71 * removed!
72 * removed!
73 * removed!
74 * removed!
75 *
76 * removed!
77 * removed!
78 * removed!
79 *
80 * removed!
81 * removed!
82 * removed!
83 * removed!
84 *
85 *------------------------------------------------------------------------------
86 * Upper this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
87 *============================================================================
88 ****************************************************************************/
89
90#ifndef _FS_GENERAL_API_H_
91#define _FS_GENERAL_API_H_
92
93#ifdef __cplusplus
94extern "C"
95{
96#endif /* __cplusplus */
97
98/*---------------------------------------------------------------------------
99 * Included Header Files
100 *---------------------------------------------------------------------------*/
101
102//-- KAL headers
103#include "kal_general_types.h"
104
105//-- Extern headers for FS features
106#include "kal_public_defs.h"
107#include "kal_public_api.h"
108#include "fs_general_types.h"
109#include "nvram_config.h"
110/*---------------------------------------------------------------------------
111 * File System APIs
112 *---------------------------------------------------------------------------*/
113
114#if !(defined(__CCCIFS_SUPPORT__) && defined(__MTK_TARGET__))
115
116// Feature Phone Proto types
117
118/*****************************************************************************
119 * <GROUP FileContent>
120 *
121 * FUNCTION
122 * FS_Open
123 * DESCRIPTION
124 * FS_Open opens and possibly creates a file for subsequent read and/or write access.
125 * PARAMETERS
126 * FileName : [IN]<P>Must point to the name of the file to open/create.
127 * File names are not case sensitive; they will be converted to
128 * upper case when file system searches this file, and they should
129 * be two-byte aligned and UCS2 encoded. The file name can have one
130 * of the following formats:
131 * [Drive:][\][Path\]Name[.Ext] A data file or directory file name with optional drive and path information.
132 * [Drive:]\ A root directory.
133 * \\.\Drive: A logical drive.
134 * \\.\PHYSICALDRIVEx A physical hard disk. x must be a digit (starting at '0') specifying the desired hard disk.
135 * \\.\FMapF\[hexstrings] A virtual file, the whole path name should be generated by the dedicated FS_GenVirtualFileName API.
136 * Flag : [IN]<P>Can be a combination of the following flags:
137 * FS_READ_WRITE FS_READ_ONLY FS_OPEN_SHARED FS_OPEN_NO_DIR
138 * FS_OPEN_DIR FS_CREATE FS_CREATE_ALWAYS FS_COMMITTED
139 * FS_CACHE_DATA FS_LAZY_DATA FS_ATTR_HIDDEN FS_ATTR_SYSTEM
140 * FS_ATTR_ARCHIVE FS_NONBLOCK_MODE FS_PROTECTION_MODE
141 * RETURNS
142 * Please refer to fs_error_enum.
143 * NOTE
144 * If the function succeeds, the return value is a file handle for the
145 * opened file and the file pointer of the file is set to 0. If the return
146 * value is less than 0, the function has failed and the return value is the
147 * error code. For data and directory files, the same rules for file name
148 * syntax apply as under MS-DOS. For logical drive and physical disk file
149 * names, the same rules as under Windows NT apply.
150 * SEE ALSO
151 * fs_error_enum
152 *****************************************************************************/
153extern int FS_Open(const WCHAR * FileName, UINT Flag);
154
155/*****************************************************************************
156 * <GROUP Obsolete >
157 *
158 * FUNCTION
159 * FS_OpenHint
160 * DESCRIPTION
161 * Open a file with location hint to reduce the search time.
162 * PARAMETERS
163 * FileName : [IN]<P>refer to FS_Open
164 * Flag : [IN]<P>refer to FS_Open
165 * DSR_Hint : [IN]<P>FS_FileOpenHint.
166 * The first time that invoke open hint function, the Cluster and Index
167 * fields of DSR_Hint must be 0. If the file is opened successfully, it
168 * returns the opened file?s location information by the DSR_Hint. Next
169 * time, if the same file needs to be opened, opening file with this
170 * DSR_Hint can reduce the searching time.
171 * It's not allowed to pass arbitrary Cluster and Index value of DSR_Hint
172 * to FS_OpenHint.
173 * If passing NULL as DSR_Hint, this function performs the same as FS_Open.
174 * RETURNS
175 * Refer to FS_Open
176 * SEE ALSO
177 * FS_Open
178 *****************************************************************************/
179extern int FS_OpenHint(const WCHAR * FileName, UINT Flag, FS_FileOpenHint * DSR_Hint);
180
181/*****************************************************************************
182 * <GROUP FileContent>
183 *
184 * FUNCTION
185 * FS_Close
186 * DESCRIPTION
187 * To close an open file and return a file handle back.
188 * PARAMETERS
189 * FileHandle : [IN]<P>the handle. Must have been assigned in a previous
190 * successful call to FS_Open. FS_Close will write
191 * any un-flushed file data to the disk (except for
192 * FS_DEVICE_LAZY_WRITE devices) and release all
193 * resources associated with the file handle.
194 * RETURNS
195 * Successful: FS_NO_ERROR
196 * Failed: Please refer to fs_error_enum.
197 * SEE ALSO
198 * fs_error_enum
199 *****************************************************************************/
200extern int FS_Close(FS_HANDLE FileHandle);
201
202/*****************************************************************************
203 * <GROUP FileContent>
204 *
205 * FUNCTION
206 * FS_Read
207 * DESCRIPTION
208 * To read data from a opened file.
209 * PARAMETERS
210 * FileHandle : [IN] <P>References the open file from which to read.
211 * DataPtr : [OUT]<P>Specifies the address for the data to be read.
212 * Length : [IN] <P>Specifies the number of bytes to read
213 * Read : [OUT]<P>Pointer to an unsigned integer to receive the number of
214 * bytes actually read. Usually, *Read will contain Length
215 * after the call. However, in case of an error or if the
216 * end of file is encountered during the read, the value may
217 * be less. Read may be set to NULL if this information is
218 * not required by an application.
219 * RETURNS
220 * Successful: FS_NO_ERROR
221 * Failed: Please refer to fs_error_enum.
222 * Details - Reading past the end of file is not regarded as an error.
223 * If FS_Read returns FS_NO_ERROR, but *Read is less than
224 * Length, the end of file has been encountered. Reading on
225 * a virtual file but its mapped file closed somehow,
226 * FS_VF_MAP_ERROR error code is returned. This function
227 * advances the file's file pointer by the amount given in
228 * *Read. In case of an error and if parameter Read is NULL,
229 * the new file pointer is undefined.
230 *****************************************************************************/
231extern int FS_Read(FS_HANDLE FileHandle, void * DataPtr, UINT Length, UINT * Read);
232
233/*****************************************************************************
234 * <GROUP FileContent>
235 *
236 * FUNCTION
237 * FS_Write
238 * DESCRIPTION
239 * To write data to a file.
240 * PARAMETERS
241 * FileHandle : [IN] <P>References the open file to write to.
242 * DataPtr : [IN] <P>Specifies the address of the data to be written.
243 * Length : [IN] <P>Specifies the number of bytes to write.
244 * Written : [OUT]<P>Pointer to an unsigned integer to receive the number of
245 * bytes actually been written. Usually, *Written will contain
246 * Length after the call. However, in case of an error, the
247 * returned value may be less. Written may be set to NULL if
248 * this information is not required by an application.
249 * RETURNS
250 * Successful: FS_NO_ERROR
251 * Failed: Please refer to fs_error_enum.
252 * Details - Writing past the current end of file will automatically
253 * extend the file. When the file size exceeds the current
254 * allocated file size, new clusters are allocated for the
255 * file. FS will allocate new clusters immediately following
256 * the current last cluster, if possible. This function
257 * advances the file's file pointer by the amount given in
258 * *Written. In case of an error and if parameter Written
259 * is NULL, the new file pointer is undefined.
260 *****************************************************************************/
261extern int FS_Write(FS_HANDLE FileHandle, void * DataPtr, UINT Length, UINT * Written);
262
263/*****************************************************************************
264 * <GROUP FileContent>
265 *
266 * FUNCTION
267 * FS_SetSeekHint
268 * DESCRIPTION
269 * This function provides user to specify several check points of file to speedup
270 * the seek function. FS_Seek will start to seek from these places.
271 * PARAMETERS
272 * FileHandle : [IN]<P>The file handle to be seeked
273 * HintNum : [IN]<P>Number of hint
274 * Hint : [IN]<P>Pointer to user defined hint
275 * RETURNS
276 * Success: The number of hint that is successfully set
277 * Error: FS_ACCESS_DENIED
278 * NOTE
279 * 1. User should specify the hint in "bytes".
280 * 2. This function only provides hint. One should not call this to extend file.
281 * i.e. Hint in bytes cannot be larger than the file size.
282 * 3. User should allocate and free the memory by himself
283 * 4. User should sort the hint by himself (small to big), or hint setting will
284 * be stopped by the number not in sequence
285 * 5. After processed, "index" in each hint entry is cluster-aligned and is a "absolute"
286 * file offset in bytes. "Cluster" is the corresponding cluster number of each index.
287 *****************************************************************************/
288extern int FS_SetSeekHint(FS_HANDLE FileHandle, UINT HintNum, FS_FileLocationHint * Hint);
289
290/*****************************************************************************
291 * <GROUP FileContent>
292 *
293 * FUNCTION
294 * FS_SetSeekHintEx
295 * DESCRIPTION
296 * A seek hint is a milestone to remember the physical address of a specified
297 * file offset. With seek hint, FS can seek from an installed milestone to save
298 * the seek time.
299 * This function provides a convenient and efficient way to enable this facility
300 * for a specified file handle. After this API is used for a specified file
301 * handle, FS will install¨seek hints? automatically during any following
302 * FS_Seek, FS_Read and FS_Write operations on the same file handle.
303 * After file is extended or truncated, seek hints will also be adjusted
304 * automatically. Any seek hint operations are transparent to users.
305 * PARAMETERS
306 * FileHandle : [IN]<P>The target file handle
307 * HintCount : [IN]<P>Number of hint
308 * Flag : [IN]<P>Flag for configuring the behavior of FS_SetSeekHintEx
309 * FS_SEEKHINT_FLAG_INITIALIZE_HINT - Setting the flag will let FS_SetSeekHintEx
310 * immediately install all hints.
311 * Otherwise - hints will be installed automatically during following file
312 * operations, like FS_Write, FS_Read and FS_Seek.
313 * Buffer : [IN]<P>User should allocate and free a buffer for FS_SetSeekHintEx.
314 * Buffer address should be 4-byte alignment.
315 * BufferSize : [IN]<P>To have N seek hints, please use
316 * FS_SEEKHINT_BUFFER_SIZE_FOR_HINT_CNT(N) to get the buffer
317 * size for N seek hints.
318 * RETURNS
319 * Success: FS_NO_ERROR
320 * Error: List below
321 * RETURN VALUES
322 * FS_INVALID_FILE_HANDLE: File handle is invalid, or target file is not Normal File.
323 * (Only Normal File supports this facility, other file type like Virtual File,
324 * Volume File and Physical Disk does not support currently).
325 * FS_ACCESS_DENIED: Hint is NULL buffer or file system is not initialized
326 * FS_FAIL_GET_MEM:
327 * 1. Buffer pointer is NULL or BufferSize is not enough for N seek hints.
328 * 2. Buffer has been used by another file handle.
329 * FS_FAT_ALLOC_ERROR: Target file?s cluster chain is broken.
330 * FS_DEVICE_EXPORTED_ERROR: The device on which the target file handle is exported.
331 * FS_MEDIA_CHANGED: The device on which the target file handle is removed or changed.
332 * EXAMPLE
333 * <code>
334 * #define MY_FILE_PATH L"E:\\1.mp3"
335 * #define MY_HINT_NUM 5
336 * #define MY_HINT_BUFFER_SIZE (FS_SEEKHINT_BUFFER_SIZE_FOR_HINT_CNT(MY_HINT_NUM))
337 * #define MY_TARGET_BYTE ?
338 *
339 * FS_HANDLE MyHandle;
340 * __align(4) char MyHint[MY_HINT_BUFFER_SIZE];
341 * int dRetval;
342 *
343 * MyHandle = FS_Open(MY_FILE_PATH, FS_OPEN_NO_DIR);
344 * If (MyHandle > FS_NO_ERROR)
345 * {
346 * dRetval = FS_SetSeekHintEx(MyHandle, MY_HINT_NUM, 0, (void*)MyHint, MY_HINT_BUFFER_SIZE);
347 * if (dRetval > FS_NO_ERROR)
348 * dRetval = FS_Seek(MyHandle, MY_TARGET_BYTE, FS_FILE_BEGIN);
349 * }
350 * </code>
351 * NOTE
352 * 1. Hint buffer memory should be allocated and freed by caller himself.
353 * 2. Hint buffer memory should be unique for different file handle! Any conflict
354 * usage will get FS_FAIL_GET_MEM error code.
355 * 3. Please use FS_SEEKHINT_BUFFER_SIZE_FOR_HINT_CNT(N) to get the buffer size for
356 * N seek hints.
357 * 4. User could let seek hint be installed during following file operations (default),
358 * or be installed once this API is called (by set FS_SEEKHINT_FLAG_INITIALIZE_HINT
359 * flag in Flag parameter).
360 *****************************************************************************/
361extern int FS_SetSeekHintEx(FS_HANDLE FileHandle, UINT HintCount, UINT Flag, void *Buffer, UINT BufferSize);
362
363/*****************************************************************************
364 * <GROUP FileContent>
365 *
366 * FUNCTION
367 * FS_SeekLargeFile
368 * DESCRIPTION
369 * Extended version of FS_Seek.
370 * PARAMETERS
371 * FileHandle : [IN] <P>References the open file for which to reposition the file pointer.
372 * Offset : [IN] <P>Specifies how far the file pointer should be moved. Please note that Offset is a signed long value.
373 * Whence : [IN] <P>Specifies Offset's meaning. Please refer to FS_SEEK_POS_ENUM.
374 * RETURNS
375 * Please refer to FS_Seek.
376 *****************************************************************************/
377extern kal_int64 FS_SeekLargeFile(FS_HANDLE FileHandle, kal_int64 Offset, int Whence);
378
379/*****************************************************************************
380 * <GROUP FileContent>
381 *
382 * FUNCTION
383 * FS_Seek
384 * DESCRIPTION
385 * Repositions a file pointer and possibly extends a file.
386 * PARAMETERS
387 * FileHandle : [IN] <P>References the open file for which to reposition the file pointer.
388 * Offset : [IN] <P>Specifies how far the file pointer should be moved.
389 * Whence : [IN] <P>Specifies Offset's meaning. Please refer to FS_SEEK_POS_ENUM.
390 * RETURNS
391 * If the function succeeds, the return value is the new file pointer value, or,
392 * if the file pointer is larger than 231-1, FS_LONG_FILE_POS is returned.
393 * In this case, the actual file pointer can be queried using function FS_GetFileInfo.
394 * If the function fails, the return value is some other negative error code.
395 * Moving the file pointer before the beginning of the file is an error.
396 * However, moving it beyond the current file size is supported.
397 * In this case, the file is extended. The data between the previous file size
398 * and the new file size is undefined. This method to extend a file is much faster
399 * than actually writing data to it.
400 * Seeking on a virtual file but its mapped file closed somehow, FS_VF_MAP_ERROR error code is returned.
401 *****************************************************************************/
402extern int FS_Seek(FS_HANDLE FileHandle, int Offset, int Whence);
403
404/*****************************************************************************
405 * <GROUP FileContent>
406 *
407 * FUNCTION
408 * FS_Commit
409 * DESCRIPTION
410 * Immediately flushes all buffers associated with a file to disk.
411 * PARAMETERS
412 * FileHandle : [IN]<P>References the open file from which to read.
413 * RETURNS
414 * Successful: FS_NO_ERROR
415 * Failed: Please refer to fs_error_enum.
416 * Details
417 * FS_Commit guarantees that all of the file's data is flushed. If the file
418 * was opened with flag FS_LAZY_DATA, all dirty buffers of the file's drive
419 * are flushed. Otherwise, the file's data buffer, directory entry, and the
420 * complete FAT are flushed.
421 *****************************************************************************/
422extern int FS_Commit(FS_HANDLE FileHandle);
423
424/*****************************************************************************
425 * <GROUP AsyncIF>
426 *
427 * FUNCTION
428 * FS_Abort
429 * DESCRIPTION
430 * This function can abort the action on specified file handle right away.
431 * PARAMETERS
432 * ActionHandle : [IN]
433 * (1) The action on the specified file handle will be aborted.
434 * (2) FS_ABORT_CHECK_DRIVE (0x12345678): Special file handle to abort drive check
435 * (3) FS_ABORT_XDELETE (0x87654321): Special file handle to abort FS_XDelete
436 * RETURNS
437 * Successful: FS_NO_ERROR
438 * Failed: Please refer to fs_error_enum.
439 *****************************************************************************/
440extern int FS_Abort(UINT ActionHandle);
441
442/*****************************************************************************
443 * <GROUP FileOperation>
444 *
445 * FUNCTION
446 * FS_ParseFH
447 * DESCRIPTION
448 * This function parse the file handle to a index between 0 to FS_MAX_FILES
449 * PARAMETERS
450 * FileHandle : [IN] <P>File handle to be parsed
451 * RETURNS
452 * The zero-based index or fs_error_enum.
453 *****************************************************************************/
454extern int FS_ParseFH(FS_HANDLE FileHandle);
455
456/*****************************************************************************
457 * <GROUP VirtualOperation>
458 *
459 * FUNCTION
460 * FS_GenVirtualFileName
461 * DESCRIPTION
462 * Some file formats pack multiple objects inside. This API is designed for programmers
463 * who want to process inside objects without copy overhead. Users call this API to
464 * generate a virtual file name (full-path string in fact) first. Then users can
465 * FS_Open(), FS_Read(), and FS_Seek() against virtual file just like a normal file.
466 * The generated virtual filename is a wide-character type, null-terminated string.
467 * The length (in byte unit) is defined as a MACRO named FS_GenVFN_SIZE. For user's
468 * convenience, it is allowed to replace the null-terminated character with a dot
469 * character and append arbitrary extension name such as jpeg?.
470 * Currently, APIs that support virtual file are FS_Open(), FS_Read(), FS_Seek(),
471 * FS_Close(), FS_GetFileInfo(), FS_GetFileSize(), and FS_GetFilePosition().
472 * PARAMETERS
473 * FileHandle : [IN] <P>The file-handler of the real-file that virtual-file mapped into.
474 * VFileNameBuf: [IN] <P>A pointer of the file name string buffer provided to store generated file name.
475 * BufLength : [IN] <P>The available buffer length (in byte unit) of VFileNameBuf provided to prevent buffer overflow.
476 * VFBeginOffset:[IN] <P>Specify the segment beginning (in byte unit) in the real-file to be treated as virtual-file content.
477 * VFValidLength:[IN] <P>Specify the segment length (in byte unit) in the real-file to be treated as virtual-file content.
478 * RETURNS
479 * Successful : FS_NO_ERROR
480 * Failed : Please refer to fs_error_enum.
481 * EXAMPLE
482 * <code>
483 * </code>
484 * NOTE
485 * There are 2 major constrictions you should keep in mind while using virtual-file.
486 * (1) The mapped file must be opened before FS_GenVirtualFileName() are called, and
487 * should be closed after all generated virtual file are closed. On the other word,
488 * once user close the mapped file, all virtual file name generated by
489 * FS_GenVirtualFileNmae() call are invalid.
490 * (2) Both mapped file and virtual file must FS_Open() with FS_READ_ONLY flag. User
491 * cannot update virtual file or mapped file by FS_Write().
492 *****************************************************************************/
493extern int FS_GenVirtualFileName(FS_HANDLE FileHandle, WCHAR * VFileNameBuf, UINT BufLength, UINT VFBeginOffset, UINT VFValidLength);
494
495/*****************************************************************************
496 * <GROUP DirectoryEntry>
497 *
498 * FUNCTION
499 * FS_GetFileInfo
500 * DESCRIPTION
501 * Return file information about an open file.
502 * PARAMETERS
503 * FileHandle : [IN] <P>References the open file from which to read.
504 * FileInfo : [OUT] <P>Refer to FS_FileInfo, FS_DOSDataTime and FS_DOSDirEntry
505 * RETURNS
506 * Successful : FS_NO_ERROR
507 * Failed : Please refer to fs_error_enum.
508 *****************************************************************************/
509extern int FS_GetFileInfo(FS_HANDLE FileHandle, FS_FileInfo * FileInfo);
510
511/*****************************************************************************
512 * <GROUP DirectoryEntry>
513 *
514 * FUNCTION
515 * FS_GetFileInfoEx
516 * DESCRIPTION
517 * Return file information about an open file.
518 * PARAMETERS
519 * FileHandle : [IN] <P>References the open file from which to read.
520 * FileInfo : [OUT] <P>Refer to FS_FileInfo, FS_DOSDataTime and FS_DOSDirEntry
521 * Flags : [IN] <P>Refer to fs_fi_enum *
522 * RETURNS
523 * Successful : FS_NO_ERROR
524 * Failed : Please refer to fs_error_enum.
525 *****************************************************************************/
526extern int FS_GetFileInfoEx(FS_HANDLE FileHandle, FS_FileInfo *FileInfo, UINT Flags);
527
528/*****************************************************************************
529 * <GROUP DirectoryEntry>
530 *
531 * FUNCTION
532 * FS_GetFileSize
533 * DESCRIPTION
534 * Retrieve the current size of an open file.
535 * PARAMETERS
536 * FileHandle : [IN] <P>References the open file for which to retrieve the file size.
537 * Size : [OUT] <P>Must point to the int to receive the file's size.
538 * RETURNS
539 * Successful : FS_NO_ERROR
540 * Failed : Please refer to fs_error_enum.
541 *****************************************************************************/
542extern int FS_GetFileSize(FS_HANDLE FileHandle, UINT * Size);
543
544/*****************************************************************************
545 * <GROUP DirectoryEntry>
546 *
547 * FUNCTION
548 * FS_GetFilePosition
549 * DESCRIPTION
550 * Retrieve the current file pointer position of an open file.
551 * Note: We provide this function to save a lot of time if application just
552 * wants to know the file pointer information. Because FS_GetFileInfo
553 * will cost a lot of to traverse the file allocated cluster chain.
554 * PARAMETERS
555 * FileHandle : [IN] <P>File handle to reference the open file for which to retrieve the file pointer.
556 * Position : [OUT]<P>The current file pointer of the opened file
557 * RETURNS
558 * This function always returns FS_NO_ERROR.
559 * EXAMPLE
560 * <code>
561 * kal_uint32 file_position;
562 *
563 * FS_GetFilePosition(myHandle, &file_position);
564 * </code>
565 *****************************************************************************/
566extern int FS_GetFilePosition(FS_HANDLE FileHandle, UINT * Position);
567
568/*****************************************************************************
569 * <GROUP DirectoryEntry>
570 *
571 * FUNCTION
572 * FS_SetFileTime
573 * DESCRIPTION
574 * Set the last modify information in a file's directory entry.
575 * PARAMETERS
576 * FileHandle : [IN] <P>References the open file for which to set the time and date.
577 * Time : [OUT] <P>the time when this file is modified. Refer to FS_DOSDateTime
578 * RETURNS
579 * FS will update the file's date and time on every write access. Thus, function
580 * FS_SetFileTime should not be followed by a call to FS_Write, since this would
581 * overwrite the date and time set by FS_SetFileTime.
582 *****************************************************************************/
583extern int FS_SetFileTime(FS_HANDLE FileHandle, const FS_DOSDateTime * Time);
584
585/*****************************************************************************
586 * <GROUP DirectoryEntry>
587 *
588 * FUNCTION
589 * FS_GetAttributes
590 * DESCRIPTION
591 * Returns the attributes set for a specific file.
592 * PARAMETERS
593 * FileName : [IN]<P>It's the file path for which to retrieve the attributes.
594 * RETURNS
595 * The value(s) below
596 * RETURN VALUES
597 * FS_ATTR_READ_ONLY
598 * FS_ATTR_HIDDEN
599 * FS_ATTR_SYSTEM
600 * FS_ATTR_VOLUME
601 * FS_ATTR_DIR
602 * FS_ATTR_ARCHIVE
603 *****************************************************************************/
604extern int FS_GetAttributes(const WCHAR * FileName);
605
606/*****************************************************************************
607 * <GROUP DirectoryEntry>
608 *
609 * FUNCTION
610 * FS_SetAttributes
611 * DESCRIPTION
612 * Returns the attributes set for a specific file.
613 * PARAMETERS
614 * FileName : [IN] <P>It's the file path for which to retrieve the attributes.
615 * Attributes : [IN] <P>
616 * FS_ATTR_READ_ONLY
617 * FS_ATTR_HIDDEN
618 * FS_ATTR_SYSTEM
619 * FS_ATTR_VOLUME
620 * FS_ATTR_DIR
621 * FS_ATTR_ARCHIVE
622 * RETURNS
623 * Please refer to fs_error_enum.
624 *****************************************************************************/
625extern int FS_SetAttributes(const WCHAR * FileName, BYTE Attributes);
626
627/*****************************************************************************
628 * <GROUP FileOperation>
629 *
630 * FUNCTION
631 * FS_Delete
632 * DESCRIPTION
633 * Delete a file.
634 * PARAMETERS
635 * FileName : [IN] <P>Must point to the name of the file to be deleted and may not contain wildcards. This function cannot delete directories.
636 * RETURNS
637 * Please refer to fs_error_enum.
638 *****************************************************************************/
639extern int FS_Delete(const WCHAR * FileName);
640
641/*****************************************************************************
642 * <GROUP VirtualOperation>
643 *
644 * FUNCTION
645 * FS_PseudoMerge
646 * DESCRIPTION
647 * This function provides facility for Multimedia task to merge audio and video
648 * files.
649 * PARAMETERS
650 * FileName1: [IN]<P>File being extended
651 * FileName2: [IN]<P>Append to FileName1, and FileName2 will be deleted
652 * RETURNS
653 * Successful : FS_NO_ERROR
654 * Failed : List below
655 * RETURN VALUES
656 * FS_INVALID_FILENAME(-3): FileName1 or FileName2 are invalid.
657 * FS_ACCESS_DENIED(-16):
658 * 1. FileName1 and FileName2 located on different drive
659 * 2. FileName1 or FileName2 are opened by others
660 * FS_FILE_NOT_FOUND(-9): FileName1 not found
661 * FS_READ_ONLY_ERROR(-45): FileName1 or FileName2 contain read-only
662 * or directory file attributes.
663 * FS_FAT_ALLOC_ERROR (-20): The cluster chains of FileName1 or FileName2
664 * are incorrect.
665 * EXAMPLE
666 * <code>
667 * int reval;
668 * reval = FS_PseudoMerge(L"E:\\2.mp3", L"E:\\3.mp3");
669 * </code>
670 * NOTE
671 * This function will
672 * (1) Check file size and cross link of the input files
673 * (2) Append File2 to File1 without caring the last cluster of
674 * File1 is not cluster alinged. One calling this API should
675 * be aware that FS_COMMITTED is the default setting of this call.
676 *****************************************************************************/
677extern int FS_PseudoMerge(const WCHAR * FileName1, const WCHAR * FileName2);
678
679
680/******************************************************************************
681 * <GROUP FileOperation>
682 *
683 * FUNCTION
684 * FS_CheckFile
685 * DESCRIPTION
686 * This function provides facility for user to check a file. It will check
687 * if this exists or not first and then check the cluster chain. If
688 * invalid cluster is allocated (for an example, 0), error code,
689 * FS_CHECKDISK_RETRY (-41), will be returned. Finally, it will check if
690 * the file size fit the allocation size. If not, the file size will be
691 * adjusted.
692 * PARAMETERS
693 * FileName: [IN]<P>File to be checked
694 * RETURNS
695 * If the function succeeds, the return value is FS_NO_ERROR. If the function fails, the return value is a negative error code. If FS_CHECKDISK_RETRY (-41) is returned, it means the file has allocated an invalid cluster. You should ask for check the whole drive to fix this error.
696 * NOTE
697 * This function will adjust the allocated clusters to fit the file size
698 * automatically if needed.
699 *
700 * <xtable>
701 * Allocated Cluster Original File FS_PseudoMerge FS_CheckFile
702 * Size (Byte)
703 * ------------------ -------------- ------------------------------- -------------------------------
704 * 0 ( 0 bytes) N/A N/A 0
705 * 1 (1024 bytes) 100 100 100
706 * 1 (1024 bytes) 1024 1024 1024
707 * 2 (2048 bytes) 1024 <color Red><b>2048</b></color> <color Red><b>1024</b></color>
708 * 2 (2048 bytes) 1537 1537 1537
709 * 3 (3072 bytes) 3073 3072 3072
710 * 3 (3072 bytes) 2049 2049 2049
711 * </xtable>
712 *****************************************************************************/
713extern int FS_CheckFile(const WCHAR * FileName);
714
715/*****************************************************************************
716 * <GROUP FolderOperation>
717 *
718 * FUNCTION
719 * FS_GetCurrentDir
720 * DESCRIPTION
721 * Return the current drive and directory.
722 * PARAMETERS
723 * DirName : [OUT] <P>Must point to a string buffer to receive the full path
724 * of the current directory.
725 * MaxLength : [IN] <P>Specifies the size of the buffer passed in DirName.
726 * It is recommended to use a buffer with FS_MAX_PATH (520)
727 * characters length. If the buffer is too small to hold
728 * the current path, the function fails.
729 * RETURNS
730 * If the function succeeds, the return value is FS_NO_ERROR and the current
731 * path has been copied to the specified buffer. If the function fails, the
732 * return value is a negative error code.
733 *
734 * NOTE
735 * This funciton returns the directory set by the nearest FS_SetCurrentDir(). To get
736 * current directory of a specified drive, please use FS_GetCurrentDirByDrive().
737 *****************************************************************************/
738extern int FS_GetCurrentDir(WCHAR * DirName, UINT MaxLength);
739
740/*****************************************************************************
741 * <GROUP FolderOperation>
742 *
743 * FUNCTION
744 * FS_GetCurrentDirByDrive
745 * DESCRIPTION
746 * Return the current drive and directory by given path.
747 * PARAMETERS
748 * DirName : [OUT]<P>Must point to a string buffer to receive the full path
749 * of the current directory, including a drive letter.
750 * MaxLength : [IN] <P>Specifies the size of the buffer passed in DirName.
751 * It is recommended to use a buffer with FS_MAX_PATH (520)
752 * characters length. If the buffer is too small to hold
753 * the current path, the function fails.
754 * RETURNS
755 * Please refer to FS_GetCurrentDir.
756 *****************************************************************************/
757extern int FS_GetCurrentDirByDrive(WCHAR * DirName, UINT MaxLength);
758
759/*****************************************************************************
760 * <GROUP FolderOperation>
761 *
762 * FUNCTION
763 * FS_SetCurrentDir
764 * DESCRIPTION
765 * Change the current directory and drive.
766 * PARAMETERS
767 * DirName : [IN] <P>DirName must point to the name of the new current directory.
768 * The new directory can have any legal file name syntax. If
769 * no drive is given, the current drive is not changed. In
770 * other cases, both current drive and current directory are
771 * changed as DirName.
772 * RETURNS
773 * Successful: FS_NO_ERROR
774 * Failed: Please refer to fs_error_enum.
775 * NOTE
776 * FS maintains a default directory for each drive, but only one drive and its
777 * current directory can be active at any one time.
778 *****************************************************************************/
779extern int FS_SetCurrentDir(const WCHAR * DirName);
780
781/*****************************************************************************
782 * <GROUP FolderOperation>
783 *
784 * FUNCTION
785 * FS_CreateDir
786 * DESCRIPTION
787 * Create a new directory(folder).
788 * PARAMETERS
789 * DirName: [IN] <P>It must point to the name of the directory to create. The
790 * directory can have any legal file name syntax.
791 * RETURNS
792 * Successful: FS_NO_ERROR
793 * Failed: Please refer to fs_error_enum.
794 *****************************************************************************/
795extern int FS_CreateDir(const WCHAR * DirName);
796
797/*****************************************************************************
798 * <GROUP FolderOperation>
799 *
800 * FUNCTION
801 * FS_RemoveDir
802 * DESCRIPTION
803 * Removes a directory.
804 * PARAMETERS
805 * DirName: [IN] <P>It must point to the name of the directory to be removed.
806 * The directory can have any legal file name syntax.
807 * RETURNS
808 * Successful: FS_NO_ERROR
809 * Failed: Please refer to fs_error_enum.
810 * NOTE
811 * This function fails on an attempt to remove a current directory, a non-empty
812 * directory, or a root directory.
813 *****************************************************************************/
814extern int FS_RemoveDir(const WCHAR * DirName);
815
816/*****************************************************************************
817 * <GROUP RecursiveOperation>
818 *
819 * FUNCTION
820 * FS_GetFolderSize
821 * DESCRIPTION
822 * This function provides a facility to get folder size
823 * PARAMETERS
824 * DirName : [IN]<P>Full source path to be counted
825 * Flag : [IN]<P>FS_COUNT_IN_BYTE, FS_COUNT_IN_CLUSTER
826 * RecursiveStack : [IN]<P>A memory pointer to store deep folder hierarchy recrusive data
827 * StackSize : [IN]<P>The size of RecursiveStack
828 * RETURNS
829 * >0 : Size in byte or cluster
830 * Error : RTF_PATH_NOT_FOUND, RTF_PARAM_ERROR
831 * NOTE
832 * 1. The size here counts for FAT allocation, not only data setctor allocation
833 * 2. This API leverage the Recursive Class
834 *****************************************************************************/
835extern int FS_GetFolderSize(const WCHAR *DirName, UINT Flag, BYTE *RecursiveStack, const UINT StackSize);
836
837/*****************************************************************************
838 * <GROUP RecursiveOperation>
839 *
840 * FUNCTION
841 * FS_GetFolderSizeEx
842 * DESCRIPTION
843 * This function provides a facility to get folder size with progress callback support
844 * PARAMETERS
845 * DirName : [IN]<P>Full source path to be counted
846 * Flag : [IN]<P>FS_COUNT_IN_BYTE, FS_COUNT_IN_CLUSTER
847 * RecursiveStack : [IN]<P>A memory pointer to store deep folder hierarchy recrusive data
848 * StackSize : [IN]<P>The size of RecursiveStack
849 * Progress : [IN]<P>User callback. User can get progress of this API or abort this operation by returning a negative integer.
850 * RETURNS
851 * >0 : Size in byte or cluster
852 * Error : RTF_PATH_NOT_FOUND, RTF_PARAM_ERROR
853 * NOTE
854 * 1. The size here counts for FAT allocation, not only data setctor allocation
855 * 2. This API leverage the Recursive Class
856 *****************************************************************************/
857extern int FS_GetFolderSizeEx(const WCHAR *DirName, UINT Flag, BYTE *RecursiveStack, const UINT StackSize, FS_ProgressCallback Progress);
858
859/*****************************************************************************
860 * <GROUP FileContent>
861 *
862 * FUNCTION
863 * FS_Extend
864 * DESCRIPTION
865 * To extend the allocated file size, but not the current file size of a file.
866 * PARAMETERS
867 * FileHandle : [IN] <P>References the open file to be extended.
868 * Length : [IN] <P>Specifies by how many bytes the file is to be extended relative to the current file pointer.
869 * RETURNS
870 * Successful: FS_NO_ERROR
871 * Failed: Please refer to fs_error_enum.
872 * RETURN VALUES
873 * FS_DISK_FULL (-22): FS cannot find a continuous chain of free clusters
874 * long enough to satisfy the request. Because disk really
875 * full and no any available free cluster.
876 * FS_DISK_FRAGMENT (-53): FS cannot find a continuous chain of free clusters
877 * long enough to satisfy the request. But some fragment
878 * free clusters found.
879 * EXAMPLE
880 * <code>
881 * #include "kal_general_types.h"
882 * #include "fs_gprot.h"
883 *
884 * #define CHUNK_SIZE (5 * 1024)
885 * kal_uint8 sample_extend_buff[6 * 1024];
886 *
887 * static kal_int32 sample_extend_body(kal_uint8 *dirty_buffer_ptr, kal_uint32 dirty_buffer_size)
888 * {
889 * FS_HANDLE fp = FS_Open(L"e:\\temp.txt", FS_READ_WRITE);
890 *
891 * if (fp > FS_NO_ERROR)
892 * {
893 * kal_int32 ret = FS_NO_ERROR;
894 *
895 * while (dirty_buffer_size > CHUNK_SIZE)
896 * {
897 * ret = FS_Extend(fp, CHUNK_SIZE);
898 * if (ret < FS_NO_ERROR)
899 * break;
900 *
901 * ret = FS_Write(fp, dirty_buffer_ptr, CHUNK_SIZE, &written);
902 * if (ret < FS_NO_ERROR)
903 * break;
904 *
905 * dirty_buffer_size -= CHUNK_SIZE;
906 * }
907 * FS_Close(fp);
908 * }
909 * }
910 *
911 * void sample_extend_main(void)
912 * {
913 * kal_int32 result = FS_NO_ERROR;
914 *
915 * kal_mem_set(sample_extend_buff, 0xFF, sizeof(sample_extend_buff));
916 * result = sample_extend_body(sample_extend_buff, sizeof(sample_extend_buff));
917 * if (result == FS_NO_ERROR)
918 * {
919 * USER_PROMPT("FS_Extend success!");
920 * }
921 * else
922 * {
923 * USER_PROMPT("FS_Extend faile! error code = %d", result);
924 * }
925 * }
926 * </code>
927 *****************************************************************************/
928extern int FS_Extend(FS_HANDLE FileHandle, UINT Length);
929
930/*****************************************************************************
931 * <GROUP FileContent>
932 *
933 * FUNCTION
934 * FS_Truncate
935 * DESCRIPTION
936 * To set the current file size to the current file pointer position.
937 * PARAMETERS
938 * FileHandle : [IN] <P>References the open file to be truncated.
939 * RETURNS
940 * Successful: FS_NO_ERROR
941 * Failed: Please refer to fs_error_enum.
942 * NOTE
943 * Users must seek to the "point to trunck" first.
944 *****************************************************************************/
945extern int FS_Truncate(FS_HANDLE FileHandle);
946
947/*****************************************************************************
948 * <GROUP DirectoryEntry>
949 *
950 * FUNCTION
951 * FS_MakeFileName
952 * DESCRIPTION
953 * This function will provide a facility for user to get a short file name (SFN)
954 * or long file name (LFN) via specified file handle. However, if the length of
955 * file name buffer is not big enough to store the requested LFN, SFN will be
956 * returned.
957 * PARAMETERS
958 * FileHandle : [IN] <P>The file handle from successful FS_Open
959 * Flag : [IN] <P>FS_LONGNAME_ATTR: Get LFN from disk to FileName buffer
960 * <P>0: Get SFN from disk to FileName buffer (default choice)
961 * FileName : [OUT] <P>User provides wide character buffer for file system to store SFN or LFN
962 * MaxLength : [IN] <P>The length of the FileName buffer in ¨byte?
963 * RETURNS
964 * If the function succeeds, the return value is FS_NO_ERROR. If the function fails
965 * (EX: file handle is invalid or input buffer is too small that cannot keep a SFN),
966 * the return value is a negative error code.
967 *****************************************************************************/
968extern int FS_MakeFileName(FS_HANDLE FileHandle, UINT Flag, WCHAR * FileName, UINT MaxLength);
969
970/*****************************************************************************
971 * <GROUP DirectoryEntry>
972 *
973 * FUNCTION
974 * FS_Rename
975 * DESCRIPTION
976 * Rename a file.
977 * PARAMETERS
978 * FileName : [IN] <P>Must point to the name of the file to be renamed.
979 * NewName : [OUT] <P>It points to the new name of the file. Both file names
980 * must not contain wildcards and must reference the same
981 * logical drive. However, they may reference different
982 * directories. Data files and directory files (except
983 * root directories) may be renamed or moved with this
984 * call.
985 * RETURNS
986 * If the function succeeds, the return value is FS_NO_ERROR. If the function
987 * fails, the return value is a negative error code. This function fails if a
988 * file with the name specified by NewName already exists, on an attempt to
989 * rename the current directory or a parent of the current directory, or on
990 * an attempt to rename a volume label.
991 *****************************************************************************/
992extern int FS_Rename(const WCHAR * FileName, const WCHAR * NewName);
993
994/*****************************************************************************
995 * <GROUP RecursiveOperation>
996 *
997 * FUNCTION
998 * FS_Move
999 * DESCRIPTION
1000 * This function provides a facility to move/copy a file or folder
1001 * PARAMETERS
1002 * SrcFullPath : [IN] <P>Source path to be moved/copied
1003 * DstFullPath : [IN] <P>Destination path
1004 * Flag : [IN]
1005 * FS_MOVE_OVERWRITE(4) - Overwrite the destination if it has already existed. This option should combine with FS_MOVE_COPY or FS_MOVE_KILL via ¯|?.
1006 * FS_MOVE_COPY (2) - Copy from source to destination and keep the source file/folder. This option cannot combine with FS_MOVE_KILL.
1007 * FS_MOVE_KILL (1) - Move from source to destination and do not keep the source file/folder. This option cannot combine with FS_MOVE_COPY.
1008 * RecursiveStack : [IN] <P>A memory pointer to store deep folder hierarchy recrusive data
1009 * Before W08.40: If NULL, only 39 levels supported. It?s recommend
1010 * that foreground application should provide 6.6K bytes to support up
1011 * to maximum 128 levels in FAT specification.
1012 * After 08A W08.40 (Included): If NULL, only 39 levels supported.
1013 * To support deeper folders, user should assign the RecursiveStack
1014 * of proper size. The minimum space required for 128 levels is about
1015 * 11K bytes. Here is a helper macro to calculate the required buffer
1016 * for different levels. -FS_MOVE_BUFFER_SIZE_FOR_FOLDER_LEVEL(x).
1017 * StackSize : [IN] <P>The size of RecursiveStack
1018 * RETURNS
1019 * Successful: FS_NO_ERROR
1020 * Failed: As below
1021 * RETURN VALUES
1022 * FS_PARAM_ERROR (-2): Neither FS_MOVE_COPY nor FS_MOVE_KILL is specified in parameter, Flag.
1023 * FS_INVALID_FILENAME (-3): Either SrcFullPath or DstFullPath is wrong
1024 * FS_PATH_NOT_FOUND (-19): Cannot find SrcFullPath specified in the first parameter.
1025 * FS_FILE_EXISTS (-36): DstFullPath exists while FS_MOVE_OVERWRITE is not specified in the third parameter.
1026 * FS_FAIL_GET_MEM (-44): Cannot get memory to do the operation
1027 * FS_READ_ONLY_ERROR (-45): The SrcFullPath contain READ_ONLY file attribute that cannot be move across drive/partition.
1028 * FS_ABORTED_ERROR (-47): This action has been aborted in the user?s callback function.
1029 * NOTE
1030 * 1. Original RTFRename does not allow move to different drive
1031 * 2. Only can file to file or dir to dir
1032 * 3. This API leverage the Recursive Class
1033 * EXAMPLE
1034 * <code>
1035 * (1)FS_Move(L"E:\\AUDIO", L"D:\\AUDIO", FS_MOVE_OVERWRITE | FS_MOVE_COPY, YourCallBack, NULL, 0);
1036 * (2)FS_Move(L"E:\\AUDIO\test.txt", L"D:\\AUDIO\test.txt", FS_MOVE_COPY, YourCallBack, NULL, 0);
1037 * (3)FS_Move(L"E:\\AUDIO\test.txt", L"D:\\AUDIO\test.txt", FS_MOVE_KILL, YourCallBack, NULL, 0);
1038 * (4)FS_Move(L"E:\\AUDIO", L"D:\\AUDIO", FS_MOVE_OVERWRITE | FS_MOVE_KILL, YourCallBack, NULL, 0);
1039 *
1040 *
1041 * int YourCallBack(int Action, UINT Total, UINT Completed, UINT MyHandle)
1042 * {
1043 * if (Action == FS_MOVE_PGS_PREPARE)
1044 * //show preparing image
1045 * else if (Action == FS_MOVE_PGS_START)
1046 * //show empty progressing bar
1047 * else if (Action == FS_MOVE_PGS_FAIL)
1048 * //show error message
1049 * else if (Action == FS_MOVE_PGS_DONE)
1050 * //show full progressing bar and then show ¨Done? image
1051 * else if (Action == FS_MOVE_PGS_ING)
1052 * {
1053 * if (WantStop && (MyHandle > 0))
1054 * {
1055 * FS_Abort(MyHandle);
1056 * }
1057 * else
1058 * {
1059 * //show progressing percentage: (Completed/Total) *100%
1060 * //Be careful of the DIV BY ZERO problem here
1061 * }
1062 * }
1063 * }
1064 * </code>
1065 *****************************************************************************/
1066extern int FS_Move(const WCHAR * SrcFullPath, const WCHAR * DstFullPath, UINT Flag, FS_ProgressCallback Progress, BYTE *RecursiveStack, const UINT StackSize);
1067
1068/*****************************************************************************
1069 * <GROUP RecursiveOperation>
1070 *
1071 * FUNCTION
1072 * FS_Move
1073 * DESCRIPTION
1074 * This function provides a facility to count the number of files
1075 * or folders recursively
1076 * PARAMETERS
1077 * FullPath: : [IN] <P>Source path to be counted
1078 * Flag: : [IN] <P>All the types as following can combine together
1079 * FS_FILE_TYPE - Count files
1080 * FS_DIR_TYPE - Count folders
1081 * FS_RECURSIVE_TYPE - Count recursively including the sub-folder inside
1082 * the source folder. This option works only when
1083 * FS_DIR_TYPE is chosen.
1084 * FS_FILTER_SYSTEM_ATTR - Count file/folder without ¨SYSTEM? attribute.
1085 * FS_FILTER_HIDDEN_ATTR - Count file/folder without ¨HIDDEN? attribute.
1086 * RecursiveStack:: [IN] <P>A memory pointer to store deep folder hierarchy recrusive data
1087 * StackSize: : [IN] <P>The size of RecursiveStack
1088 * RETURNS
1089 * Successful: FS_NO_ERROR
1090 * Failed: As below
1091 * RETURN VALUES
1092 * FS_PARAM_ERROR(-2): Neither FS_FILE_TYPE nor FS_DIR_TYPE nor FS_RECURSIVE_TYPE
1093 * is specified in parameter, Flag.
1094 * FS_INVALID_FILENAME(-3): FullPath is wrong
1095 * FS_PATH_NOT_FOUND(-19): Cannot find FullPath specified in the first parameter.
1096 * FS_FAIL_GET_MEM(-44): Cannot get memory to do the operation
1097 * NOTE
1098 * This API needs to get control buffer for operation.
1099 * If it cannot get memory at that time, error code (-44) will be returned..
1100 * EXAMPLE
1101 * <code>
1102 * (1) FS_Count(L"D:\\AUDIO", FS_FILE_TYPE | FS_DIR_TYPE | FS_RECURSIVE_TYPE, NULL, 0);
1103 * (2) FS_Count(L"D:\\AUDIO", FS_ DIR _TYPE | FS_RECURSIVE_TYPE, NULL, 0);
1104 * (3) FS_Count(L"D:\\AUDIO", FS_FILE_TYPE, NULL, 0);
1105 * (4) FS_Count(L"D:\\AUDIO", FS_FILE_TYPE | FS_DIR_TYPE, NULL, 0);
1106 * </code>
1107 *****************************************************************************/
1108extern int FS_Count(const WCHAR * FullPath, UINT Flag, BYTE *RecursiveStack, const UINT StackSize);
1109
1110
1111/*****************************************************************************
1112 * <GROUP RecursiveOperation>
1113 *
1114 * FUNCTION
1115 * FS_XDeleteEx
1116 * DESCRIPTION
1117 * This function provides a facility to delete a file or folder recursively
1118 * PARAMETERS
1119 * FullPath: : [IN] <P>Source path to be counted
1120 * Flag: : [IN] <P>All the three types as following can combine together
1121 * FS_FILE_TYPE(2) - Delete files
1122 * FS_DIR_TYPE(4) - Delete folders
1123 * FS_RECURSIVE_TYPE(8) - Delete recursively including the sub-folder
1124 * inside the source folder. This option works
1125 * only when FS_DIR_TYPE is chosen.
1126 * RecursiveStack:: [IN] <P>An external buffer for deep directory hierarchy processing.
1127 * Before W08.40, if NULL, only 39 levels supported. It's
1128 * recommend that foreground application should provide 6.6K
1129 * bytes to support up to maximum 128 levels in FAT specification.
1130 * After 08A W08.40 (Included), if NULL, only 39 levels supported.
1131 * To support deeper folders, user should assign the RecursiveStack
1132 * of proper size. The minimum space required for 128 levels is about
1133 * 8.5K bytes. Here is a helper macro to calculate the required buffer
1134 * for different levels. - FS_XDELETE_BUFFER_SIZE_FOR_FOLDER_LEVEL (x).
1135 * StackSize: : [IN] <P>The size of RecursiveStack
1136 * RETURNS
1137 * Successful: FS_NO_ERROR
1138 * Failed: As below
1139 * RETURN VALUES
1140 * FS_PARAM_ERROR(-2): Neither FS_FILE_TYPE nor FS_DIR_TYPE nor FS_RECURSIVE_TYPE
1141 * is specified in parameter, Flag.
1142 * FS_INVALID_FILENAME(-3): FullPath is wrong
1143 * FS_PATH_NOT_FOUND(-19): Cannot find FullPath specified in the first parameter.
1144 * FS_FAIL_GET_MEM(-44): Cannot get memory to do the operation
1145 * NOTE
1146 * (1) This API needs to get control buffer for operation. If it cannot get memory
1147 * at that time, error code (-44) will be returned..
1148 * (2) if the target folder is an empty folder, an error string like ¨[FS ERR]-10#4234@fs> Task(TASK) 65531th FH?
1149 * will show up in FS Trace. This is normal. It does NOT mean that FS_XDelete is failed.
1150 *****************************************************************************/
1151extern int FS_XDelete(const WCHAR * FullPath, UINT Flag, BYTE *RecursiveStack, const UINT StackSize);
1152
1153/*****************************************************************************
1154 * <GROUP RecursiveOperation>
1155 *
1156 * FUNCTION
1157 * FS_XDeleteEx
1158 * DESCRIPTION
1159 * This function provides a facility to delete a file or folder recursively
1160 * PARAMETERS
1161 * FullPath : [IN]<P>Source path to be counted
1162 * Flag : [IN]<P>All the three types as following can combine together
1163 * FS_FILE_TYPE(2) - Delete files
1164 * FS_DIR_TYPE(4) - Delete folders
1165 * FS_RECURSIVE_TYPE(8) - Delete recursively including the sub-folder
1166 * inside the source folder. This option works
1167 * only when FS_DIR_TYPE is chosen.
1168 * Progress : [IN] <P>User callback
1169 * RecursiveStack : [IN] <P>An external buffer for deep directory hierarchy processing.
1170 * Before W08.40, if NULL, only 39 levels supported. It's
1171 * recommend that foreground application should provide 6.6K
1172 * bytes to support up to maximum 128 levels in FAT specification.
1173 * After 08A W08.40 (Included), if NULL, only 39 levels supported.
1174 * To support deeper folders, user should assign the RecursiveStack
1175 * of proper size. The minimum space required for 128 levels is about
1176 * 8.5K bytes. Here is a helper macro to calculate the required buffer
1177 * for different levels. - FS_XDELETE_BUFFER_SIZE_FOR_FOLDER_LEVEL (x).
1178 * StackSize : [IN] <P>The size of RecursiveStack
1179 * RETURNS
1180 * Successful: FS_NO_ERROR
1181 * Failed: As below
1182 * RETURN VALUES
1183 * FS_PARAM_ERROR(-2): Neither FS_FILE_TYPE nor FS_DIR_TYPE nor FS_RECURSIVE_TYPE
1184 * is specified in parameter, Flag.
1185 * FS_INVALID_FILENAME(-3): FullPath is wrong
1186 * FS_PATH_NOT_FOUND(-19): Cannot find FullPath specified in the first parameter.
1187 * FS_FAIL_GET_MEM(-44): Cannot get memory to do the operation
1188 * NOTE
1189 * (1) This API needs to get control buffer for operation. If it cannot get memory
1190 * at that time, error code (-44) will be returned..
1191 * (2) if the target folder is an empty folder, an error string like ¨[FS ERR]-10#4234@fs> Task(TASK) 65531th FH?
1192 * will show up in FS Trace. This is normal. It does NOT mean that FS_XDelete is failed.
1193 *****************************************************************************/
1194extern int FS_XDeleteEx(const WCHAR * FullPath, UINT Flag, FS_ProgressCallback Progress, BYTE *RecursiveStack, const UINT StackSize);
1195
1196/*****************************************************************************
1197 * <GROUP DiskManagement>
1198 *
1199 * FUNCTION
1200 * FS_CompactDir
1201 * DESCRIPTION
1202 * This function provides a facility to release space of a folder which contains "deleted" files/folders.
1203 * PARAMETERS
1204 * DirName : [IN] <P>the folder to compact.
1205 * Flags : [IN] <P> FS_CMPCT_RECURSIVE only
1206 * RETURNS
1207 * Please refer to fs_error_enum.
1208 *****************************************************************************/
1209extern int FS_CompactDir(const WCHAR* DirName, UINT Flags);
1210
1211/*****************************************************************************
1212 * <GROUP DirectoryEntry>
1213 *
1214 * FUNCTION
1215 * FS_CheckVolumeLabel
1216 * DESCRIPTION
1217 * This function provides a facility to check if the volume label is valid.
1218 * PARAMETERS
1219 * Path : [IN] <P>The volume label.
1220 * RETURNS
1221 * If volume label is valid, FS_NO_ERROR is returned.
1222 * For error case, please refer to fs_error_enum.
1223 *****************************************************************************/
1224extern int FS_CheckVolumeLabel(WCHAR *Label);
1225
1226/*****************************************************************************
1227 * <GROUP DirectoryEntry>
1228 *
1229 * FUNCTION
1230 * FS_CheckFileName
1231 * DESCRIPTION
1232 * This function provides a facility to check if the specified file name is valid.
1233 * PARAMETERS
1234 * Path : [IN] <P>The file path. Both full path or file name only are acceptible.
1235 * If it is full path, FS will only check the file name, i.e., the last part after '\\'.
1236 * RETURNS
1237 * If file name is valid, FS_NO_ERROR is returned.
1238 * For error case, please refer to fs_error_enum.
1239 *****************************************************************************/
1240extern int FS_CheckFileName(WCHAR *Path);
1241
1242/*****************************************************************************
1243 * <GROUP Enumerate>
1244 *
1245 * FUNCTION
1246 * FS_FindFirst
1247 *
1248 * DESCRIPTION
1249 * Search a directory for a file satisfying certain criteria.
1250 *
1251 * PARAMETERS
1252 * NamePattern : [IN] <P>Pointer to a file name which may contain wildcard characters '*'
1253 * (match zero or more characters) and/or '?' (match exactly one
1254 * character), and can optionally be preceded by a path. If a path
1255 * is present, it must not contain any wildcard characters.
1256 * For compatibility with MS-DOS, Pattern "*.*" is silently converted
1257 * to "*". To search for file names containing one or more periods,
1258 * use "?*.*" or "*.?*".
1259 * Attr : [IN] <P>Specifies a set of all file attributes a file must have to match
1260 * the request.
1261 * AttrMask : [IN] <P>Specified the set of attributes, which are matched against Attr.
1262 * Attributes set in Attr are automatically added to AttrMask. Any
1263 * combination of the following flags can be specified for Attr and
1264 * AttrMask:
1265 * FS_ATTR_READ_ONLY
1266 * FS_ATTR_HIDDEN
1267 * FS_ATTR_SYSTEM
1268 * FS_ATTR_VOLUME
1269 * FS_ATTR_DIR
1270 * FS_ATTR_ARCHIVE
1271 * FileInfo : [IN/OUT] <P>It?s a pointer to FS_DOSDirEntry structure. If the function succeeds,
1272 * this structure will be filled with the directory entry of the file
1273 * found. This parameter may be NULL. Refer to FS_FIND_ENUM.
1274 * FileName : [IN] <P>Pointer to a string buffer to receive the file name without path if
1275 * a file is found.
1276 * MaxLength : [IN] <P>Size in bytes of the buffer pointed to by FileName. Files with a file
1277 * name length larger than MaxLength-1 will not be found. Be careful that
1278 * it should be the length of wide-characters.
1279 * RETURNS
1280 * If the function succeeds, at least one file satisfies the search criteria. *FileInfo contains the
1281 * directory entry of the first file and the function return value is greater than or equal to 0. The
1282 * return value is a file handle, which may be passed to subsequent calls to FS_FindNext. If the function
1283 * fails, the return value is a negative error code. In this case, no handle is allocated and FS_FindClose
1284 * need not be called.
1285 * It is important to close the handle using FS_FindClose when no longer needed. Failing to do so will
1286 * quickly exhaust the available file handles.
1287 *****************************************************************************/
1288extern int FS_FindFirst(const WCHAR * NamePattern, BYTE Attr, BYTE AttrMask, FS_DOSDirEntry * FileInfo, WCHAR * FileName, UINT MaxLength);
1289
1290/*****************************************************************************
1291 * <GROUP Enumerate>
1292 *
1293 * FUNCTION
1294 * FS_FindNext
1295 *
1296 * DESCRIPTION
1297 * Find more files with the same search criteria as a preceding call to FS_FindFirst.
1298 *
1299 * PARAMETERS
1300 * FileHandle : [IN] <P>Handle returned by a previous successful call to FS_FindFirst.
1301 * FileInfo : [IN/OUT]<P>It?s a pointer to FS_DOSDirEntry structure (may be NULL).
1302 * FileName : [IN] <P>It?s a pointer to a string buffer to receive a file name without path.
1303 * MaxLength : [IN] <P>Size in bytes of the buffer pointed to by FileName. Files with a file
1304 * name length larger than MaxLength-1 will not be found. Be careful that
1305 * it should be the length of wide-characters
1306 * RETURNS
1307 * If the function succeeds, the return value is FS_NO_ERROR. If the function fails or no more files
1308 * are found, the return value is a negative error code.If the function succeeds, *FileInfo and
1309 * *FileName will be filled with the directory entry and name of the file found.
1310 *****************************************************************************/
1311extern int FS_FindNext(FS_HANDLE FileHandle, FS_DOSDirEntry * FileInfo, WCHAR * FileName, UINT MaxLength);
1312
1313/*****************************************************************************
1314 * <GROUP Enumerate>
1315 *
1316 * FUNCTION
1317 * FS_FindFirstN
1318 *
1319 * DESCRIPTION
1320 * This function provides a facility to find Nth matching file
1321 * and multi-patterns are supported
1322 *
1323 * PARAMETERS
1324 * NamePattern : [IN] <P>Find Pattern (Must have drive name)
1325 * PatternArray : [IN] <P>Multi-patterns array (should not have drive name)
1326 * PatternNum : [IN] <P>Indicate how many pattern in PatternArray
1327 * ArrayMask : [IN] <P>The attributes that match default NamePattern only
1328 * Attr : [IN] <P>The attributes must have
1329 * AttrMask : [IN] <P>The attributes must not have
1330 * FileInfo : [IN/OUT]<P>File information
1331 * FileName : [IN] <P>the long file name
1332 * MaxLength : [IN] <P>The length of FileName
1333 * EntryIndex : [IN] <P>Find Nth index
1334 *
1335 * RETURNS
1336 * Success: FS_NO_ERROR
1337 * Error: Please refer to fs_error_enum.
1338 *****************************************************************************/
1339extern int FS_FindFirstN(const WCHAR * NamePattern, FS_Pattern_Struct * PatternArray, UINT PatternNum, BYTE ArrayMask, BYTE Attr, BYTE AttrMask, FS_DOSDirEntry * FileInfo, WCHAR * FileName, UINT MaxLength, UINT EntryIndex, UINT Flag);
1340
1341/*****************************************************************************
1342 * <GROUP Enumerate>
1343 *
1344 * FUNCTION
1345 * FS_FindNextN
1346 * DESCRIPTION
1347 * This function provides a facility to find next matching file
1348 * and multi-patterns are supported
1349 * PARAMETERS
1350 * Handle : [IN] <P>The file handle record the find position
1351 * PatternArray : [IN] <P>Multi-patterns array (should not have drive name)
1352 * PatternNum : [IN] <P>Indicate how many pattern in PatternArray
1353 * ArrayMask : [IN] <P>The attributes that match default NamePattern only
1354 * FileInfo : [IN/OUT]<P>File information
1355 * FileName : [IN] <P>File name
1356 * MaxLength : [IN] <P>The length of the file name buffer
1357 * RETURNS
1358 * Success: FS_NO_ERROR
1359 * Error: Please refer to fs_error_enum.
1360 *****************************************************************************/
1361extern int FS_FindNextN(FS_HANDLE Handle, FS_Pattern_Struct * PatternArray, UINT PatternNum, BYTE ArrayMask, FS_DOSDirEntry * FileInfo, WCHAR * FileName, UINT MaxLength, UINT Flag);
1362
1363/*****************************************************************************
1364 * <GROUP Enumerate>
1365 *
1366 * FUNCTION
1367 * FS_FindClose
1368 * DESCRIPTION
1369 * To close the handle of FS_FindFirst or FS_FindFirstN
1370 * PARAMETERS
1371 * handle : [IN] <P>the handle of FS_FindFirst or FS_FindFirstN
1372 * RETURNS
1373 * Successful: A non-negative value.
1374 * Failed: Please refer to fs_error_enum.
1375 *****************************************************************************/
1376extern int FS_FindClose(FS_HANDLE FileHandle);
1377
1378/*****************************************************************************
1379 * <GROUP Enumerate>
1380 *
1381 * FUNCTION
1382 * FS_ListOpen
1383 * DESCRIPTION
1384 * 1. To open specific folder and loading file elements with given parameters
1385 * into a backgroud list.
1386 * 2. Similar to opendir of Posix.
1387 * PARAMETERS
1388 * param : [IN] <P>parameter set and list buffer; refer to fs_list_param_struct.
1389 * handle : [OUT] <P>special handle of List serial APIs.
1390 * RETURNS
1391 * Successful: FS_NO_ERROR
1392 * Failed: Please refer to fs_error_enum.
1393 * NOTE
1394 * only one of name_pattern and attr_pattern can be used at the same time
1395 * EXAMPLE
1396 * <code>
1397 * //Intention: to list the first 20 file names under e:\\Photos\\
1398 * FS_HANDLE list;
1399 * kal_int32 result, i = 0;
1400 * kal_wchar wfn[10] = {0};
1401 * kal_char fn[10] = {0};
1402 * fs_list_param_struct param = {0};
1403 *
1404 * param.path = (kal_wchar *)get_ctrl_buffer(FS_MAX_PATH);
1405 * kal_wsprintf(param.path, "E:\\Photos\\*.*");
1406 *
1407 * param.index = 0;
1408 * param.buff_size = FS_LIST_SIZE(20);
1409 * param.buff = (fs_list_param_struct *)get_ctrl_buffer(param.buff_size);
1410 *
1411 * result = FS_ListOpen(&param, &list);
1412 *
1413 * while (result >= FS_NO_ERROR)
1414 * {
1415 * result = FS_ListNext(list, NULL, param.path, wfn, 10, i);
1416 * if (result <FS_NO_ERROR)
1417 * break;
1418 *
1419 * kal_dchar2char(wfn, fn);
1420 * kal_prompt_trace(MOD_USER, "%s", fn);
1421 * }
1422 * FS_ListClose(list);
1423 *
1424 * free_ctrl_buffer(param.buff);
1425 * free_ctrl_buffer(param.path);
1426 * </code>
1427 *****************************************************************************/
1428extern kal_int32 FS_ListOpen(fs_list_param_struct *param, FS_HANDLE *handle);
1429
1430/*****************************************************************************
1431 * <GROUP Enumerate>
1432 *
1433 * FUNCTION
1434 * FS_ListReload
1435 * DESCRIPTION
1436 * Continue to batch enumerate next N files after FS_ListOpen().
1437 * PARAMETERS
1438 * param : [IN] <P>parameter set and list buffer; refer to fs_list_param_struct.
1439 * handle : [OUT] <P>special handle of List serial APIs.
1440 * RETURNS
1441 * Successful: FS_NO_ERROR
1442 * Failed: Please refer to fs_error_enum.
1443 * NOTE
1444 * The param and handle must be identical to those were passed to FS_ListOpen().
1445 * EXAMPLE
1446 * <code>
1447 * </code>
1448 *****************************************************************************/
1449extern kal_int32 FS_ListReload(fs_list_param_struct *param, FS_HANDLE *handle);
1450
1451/*****************************************************************************
1452 * <GROUP Enumerate>
1453 *
1454 * FUNCTION
1455 * FS_ListNext
1456 * DESCRIPTION
1457 * 1. To retrive the Nth element of the background list.
1458 * 2. Similar to readdir of Posix
1459 * 3. optional parameters could be NULL or 0
1460 * PARAMETERS
1461 * handle : [IN] <P>special handle of List serial APIs.
1462 * info : [IN/OUT] <P>(optional)the DOS style information of an element if found. Such as short file name.
1463 * path : [IN] <P>working diretory which will be filled into internal hint
1464 * lfilename : [IN/OUT] <P>the buffer to carry long file name if found.
1465 * lfilename_size: [IN] <P>the buffer size of lfilename with includes null terminator
1466 * index : [IN] <P>specific zero-based index in the list
1467 * RETURNS
1468 * Successful: FS_NO_ERROR
1469 * Failed: Please refer to fs_error_enum.
1470 *****************************************************************************/
1471extern kal_int32 FS_ListNext(FS_HANDLE handle,
1472 FS_DOSDirEntry *info, kal_wchar *path, kal_wchar *lfilename, kal_uint32 lfilename_size,
1473 kal_int32 index);
1474
1475/*****************************************************************************
1476 * <GROUP Enumerate>
1477 *
1478 * FUNCTION
1479 * FS_ListClose
1480 * DESCRIPTION
1481 * 1. To close the list.
1482 * 2. Similar to closedir of Posix.
1483 * PARAMETERS
1484 * handle : [IN] <P>special handle of List serial APIs.
1485 * RETURNS
1486 * Successful: FS_NO_ERROR
1487 * Failed: Please refer to fs_error_enum.
1488 *****************************************************************************/
1489extern kal_int32 FS_ListClose(FS_HANDLE handle);
1490
1491extern void FS_Config(fs_config_enum type, void * data);
1492
1493#ifdef __FS_SORT_SUPPORT__
1494/*****************************************************************************
1495 * <GROUP Sort>
1496 *
1497 * FUNCTION
1498 * FS_SortCompareFileName
1499 * DESCRIPTION
1500 * The build-in compare function. Compare by name
1501 * PARAMETERS
1502 * FileName1 : [IN] <P>source of the comparison.
1503 * FileName2 : [IN] <P>target of the comparison.
1504 * RETURN VALUES
1505 * -1 : char in FileName1 is less than that in FileName2
1506 * 1 : char in FileName1 is greater than that in FileName2
1507 * 0 : equal or no difference is found till all char in FileName1 is traversed.
1508 *****************************************************************************/
1509extern int FS_SortCompareFileName(WCHAR *FileName1, WCHAR *FileName2);
1510
1511/*****************************************************************************
1512 * <GROUP Sort>
1513 *
1514 * FUNCTION
1515 * FS_SortCompareFileType
1516 * DESCRIPTION
1517 * The build-in compare function. Compare by type
1518 * PARAMETERS
1519 * FileName1 : [IN] <P>source of the comparison.
1520 * FileName2 : [IN] <P>target of the comparison.
1521 * RETURN VALUES
1522 * -1 : char in FileName1 is less than that in FileName2
1523 * 1 : char in FileName1 is greater than that in FileName2
1524 * 0 : equal or no difference is found till all char in FileName1 is traversed.
1525 *****************************************************************************/
1526extern int FS_SortCompareFileType(WCHAR *FileName1, WCHAR *FileName2);
1527
1528/*****************************************************************************
1529 * <GROUP Sort>
1530 *
1531 * FUNCTION
1532 * FS_XFindReset
1533 * DESCRIPTION
1534 * This function provides a facility to reset a sort list recursively
1535 * PARAMETERS
1536 * Param : [IN] <P>Please refer to FS_SortingParam.
1537 * RETURN VALUES
1538 * >= 0: The number of folders/files that had been sorted.
1539 * FS_PARAM_ERROR (-2): Some of the parameters are invalid.
1540 * FS_NO_MORE_FILES (-6): Cannot find any file that matches the pattern anymore
1541 * FS_ACCESS_DENIED (-16): You didn't get the lock from FS_XFindReset. The passed buffer or data does not belong to this function.
1542 * FS_FAIL_GET_MEM: Invalid buffer space or size.
1543 * FS_ABORTED_ERROR: The sorting is aborted.
1544 * FS_NO_MORE_FILES: No more files to be retrieved.
1545 * FS_TOO_MANY_FILES: The sorting buffer or working buffer is too small.
1546 * NOTE
1547 * (1) Please be care of the <b>MaxLength</b> input. If it?s too small that FS cannot make short name for you, the sorting sequence will be corrupted, i.e. make sure your length must be greater than 22 characters (11 wide characters).
1548 * (2) If you want to get specific sorting result, just put (index -1) into the input parameter.
1549 * (3) If you get the sorted filename by this function with index from 0 to (the sorted file number -1), the result will be in ASC order. If you want to get the filename in DESC order, you can get the sorted filename with index from (the sorted file number -1) to 0.
1550 *****************************************************************************/
1551extern int FS_XFindReset(FS_SortingParam *Param);
1552
1553/*****************************************************************************
1554 * <GROUP Sort>
1555 *
1556 * FUNCTION
1557 * FS_XFindStart
1558 * DESCRIPTION
1559 * This function retrieves entry from the sorting list got from FS_XFindReset one by one.
1560 * PARAMETERS
1561 * Pattern : [IN] <P>Find Pattern
1562 * FileInfo : [OUT] <P>File information
1563 * FileName : [OUT] <P>File name
1564 * MaxLength : [IN] <P>The length of FileName buffer
1565 * Index : [IN] <P>Find index
1566 * Position : [IN] <P>The sorted list
1567 * RETURN VALUES
1568 * Value >= 0: The number of folders/files that had been sorted.
1569 * FS_PARAM_ERROR (-2): Given an negative index number
1570 * FS_NO_MORE_FILES (-6): Cannot find any file that matches the pattern anymore
1571 * FS_ACCESS_DENIED (-16): You didn?t get the lock from FS_XFindReset.
1572 *****************************************************************************/
1573extern int FS_XFindStart(const WCHAR * Pattern, FS_DOSDirEntry * FileInfo, WCHAR * FileName, UINT MaxLength, UINT Index, UINT * Position, UINT Flag);
1574
1575/*****************************************************************************
1576 * <GROUP Sort>
1577 *
1578 * FUNCTION
1579 * FS_XFindClose
1580 * DESCRIPTION
1581 * This function closes the sorting list got from FS_XFindReset.
1582 * PARAMETERS
1583 * Position : [IN] <P>The sorted list
1584 * RETURN VALUES
1585 * FS_NO_ERROR: Successful
1586 * FS_PARAM_ERROR (-2): Given an negative index number
1587 * FS_ACCESS_DENIED (-16): You didn't get the lock from FS_XFindReset.
1588 *****************************************************************************/
1589extern int FS_XFindClose(UINT * Position);
1590#endif
1591
1592/*****************************************************************************
1593 * <GROUP VolumeManagement>
1594 *
1595 * FUNCTION
1596 * FS_GetDrive
1597 * DESCRIPTION
1598 * Our system support 1 NOR flash + 1 NAND flash + maximum 1 memory card concurrently (Maximum 5 drives). If it acts as a USB slave, we may have the ¨partition? issue: Some private data, like NVRAM or files with digital right, should not be exposed to PC side.
1599 * <img name="FlashConfig" />
1600 * For the special need, we must create partition on our disk. And in order to reduce driver effort, we have to mark the first primary partition as visible and secondary primary partition as invisible. When system acts as USB slave, driver will fool PC side that the ?whole disk? is just big as the visible partition size.
1601 * PS. Memory card should not be partitioned.
1602 * <xtable>
1603 * IDX DRIVES NOR NAND CARD NORMAL 1 NORMAL 2 SYS 1 SYS 2 CARD
1604 * Num
1605 * ----- ------ --- ---- ---- -------- -------- ----- ----- ----
1606 * 1 5 2 2 1 C D E F G
1607 * 2 4 2 1 1 C D E F
1608 * 3 4 2 2 0 C D E F
1609 * 4 4 1 2 1 D C E F
1610 * 5 3 2 0 1 C D E
1611 * 6 3 2 1 0 C D E
1612 * 7 3 1 1 1 D C E
1613 * 8 3 1 2 0 D C E
1614 * 9 3 0 2 1 C D E
1615 * 10 2 2 0 0 C D
1616 * 11 2 1 0 1 C D
1617 * 12 2 1 1 0 D C
1618 * 13 2 0 1 1 C D
1619 * 14 2 0 2 0 C D
1620 * 15 1 1 0 0 C
1621 * 16 1 0 1 0 C
1622 * </xtable>
1623 * SYS 1/2: Invisible drive when system acts as USB slave.
1624 * Normal 1/2 and memory card: Visible drive when system acts as USB slave
1625 *
1626 * In additional to those fixed and internal drives listed above, USB OTG Host support enable system to connect to external card reader with multiple card slots. File System reserved 1 drive to each slot and start from next drive letter of last internal drive index. The maximum number of external drives is customized configuration.
1627 * PARAMETERS
1628 * Type : [IN] <P>3 kinds of drive types
1629 * <P>FS_DRIVE_I_SYSTEM 0x00000004
1630 * <P>FS_DRIVE_V_NORMAL 0x00000008
1631 * <P>FS_DRIVE_V_REMOVABLE 0x00000010
1632 * <P>FS_DRIVE_V_EXTERNAL 0x00000020
1633 * Serial : [IN] <P>drive number (SYSTEM: 1or 2, NORMAL: 1 or 2, REMOVABLE: 1, EXTERNAL: 1~N(customized) )
1634 * AltMask: [IN] <P>3 ways to choose alternative drive
1635 * <P>FS_NO_ALT_DRIVE 0x00000001 (Can not combine other type)
1636 * <P>FS_ONLY_ALT_SERIAL 0x00000002 (Can not combine other type)
1637 * <P>Combination of 3 types (FS_DRIVE_I_SYSTEM | FS_DRIVE_V_NORMAL | FS_DRIVE_V_REMOVABLE)
1638 * RETURN VALUES
1639 * Capital drive name:
1640 * C=67, D=68, E=69, F=70
1641 * G=72, H=73, I=74, J=75?
1642 * FS_PARAM_ERROR (-2):
1643 * Use special type not defined here
1644 * Serial number over range
1645 * AltMask use FS_NO_ALT_DRIVE | other type
1646 * AltMask use FS_ONLY_ALT_SERIAL | other type
1647 * AltMask contain FS_DRIVE_V_EXTERNAL
1648 * FS_DRIVE_NOT_FOUND (-4):
1649 * Cannot find user specified drive
1650 * Serial out of pre-configured maximum number of external drives.
1651 * Successful: FS_NO_ERROR
1652 * Failed: Please refer to fs_error_enum.
1653 * NOTE
1654 * (1) We always have a system drive. However, normal drive and removable device are not guaranteed in the customized combination. Task owner should be aware of each case and choose the best suit drive to use.
1655 * (2) that FS_GetDrive() API always return consist drive index by given Serial parameter whether the external device present or not present.
1656 * (3) the matching sequence of AltMask is:
1657 * Normal 2 -> Normal 1 -> Card -> System 2 -> System 1
1658 * (4) the external drive NOT included in matching sequence.
1659 * EXAMPLE
1660 * <code>
1661 * Int drvLetter;
1662 * TCHAR K_filename[50];
1663 * FS_HANDLE K_hFile;
1664 * drvLetter = FS_GetDrive(FS_DRIVE_V_NORMAL, 2, FS_DRIVE_V_REMOVABLE | FS_DRIVE_I_SYSTEM);
1665 * if(drvLetter > 0)
1666 * {
1667 * kal_wsprintf(K_filename, "%c:\\ TestDir", drvLetter);
1668 * K_hFile = FS_Open(K_filename, FS_READ_WRITE|FS_CREATE_ALWAYS|FS_OPEN_NO_DIR);
1669 * }
1670 * </code>
1671 *****************************************************************************/
1672extern int FS_GetDrive(UINT Type, UINT Serial, UINT AltMask);
1673
1674/*****************************************************************************
1675 * <GROUP VolumeManagement>
1676 *
1677 * FUNCTION
1678 * FS_GetDriveByHandle
1679 * DESCRIPTION
1680 * Get capital drive letter by file handle.
1681 * RETURN VALUES
1682 * Capital drive letter: Query is successful.
1683 * C=67, D=68, E=69, F=70
1684 * G=72, H=73, I=74, J=75?
1685 * FS_INVALID_FILE_HANDLE (-10):
1686 * User specify an invalid file handle.
1687 * NOTE
1688 * EXAMPLE
1689 * <code>
1690 * int drvLetter;
1691 * TCHAR K_filename[50];
1692 * FS_HANDLE K_hFile;
1693 *
1694 * K_hFile = FS_Open(K_filename, FS_CREATE_ALWAYS);
1695 *
1696 * drvLetter = FS_GetDriveByHandle(K_hFile);
1697 *
1698 * if(drvLetter > 0)
1699 * {
1700 * // ......
1701 * }
1702 * </code>
1703 *****************************************************************************/
1704extern int FS_GetDriveByHandle(FS_HANDLE handle);
1705
1706/*****************************************************************************
1707 * <GROUP VolumeManagement>
1708 *
1709 * FUNCTION
1710 * FS_GeneralFormat
1711 * DESCRIPTION
1712 * This function provides general format facility for File Manager.
1713 * PARAMETERS
1714 * DriveName : [IN]<P> The drive that should be formatted (format: "\\\\.X:\\")
1715 * Level : [IN]<P> FS_FORMAT_LOW (low-level format) or FS_FORMAT_HIGH (high-level format)
1716 * Progress : [IN]<P> The callback function. Please refer to FS_FormatCallback.
1717 * RETURN VALUES
1718 * 12, 16 or 32: If format is successful, a positive integer will be returned. 12/16/32 means the target drive is formatted as FAT12/FAT16/FAT32.
1719 * FS_PARAM_ERROR (-2): Use special format level not defined here
1720 * FS_UNSUPPORTED_DRIVER_FUNCTION (-12): Call low-level format on removable device
1721 * FS_MEDIA_CHANGED (-26): Try to format the removable device, which is not present
1722 * FS_DEVICE_BUSY (-46): Only removable device, e.g., memory card, may return this error code. When file system is counting free space on devices in FS_LockFAT or FS_TestMSDC, this error code will be returned.
1723 * FS_DEVICE_EXPORTED_ERROR (-52): Try to format an exporting drive. In this case, file handles will not be closed.
1724 * NOTE
1725 * (1) High-level format will just clean up the FAT table of this drive while low-level format will scan the whole disk, re-partition the whole disk and re-build the driver structure. ? Even if you just low level format a drive, the whole disk will be low-level formatted.
1726 * (2) Other restriction is that only NOR and NAND flash provide the low-level format function. In most cases, you should call high-level format for cleaning up drive purpose. But if you have ever received ¨FS_SYSTEM_CRASH? error code when accessing that drive (NAND flash only), you should call low-level format to make NAND flash driver re-construct the whole system again.
1727 * (3) Format may take a long time. Task should provide callback function for File System to report the format status.
1728 * (4) Format function will close all the file handles on this disk automatically.
1729 * (5) Low-level format may cost a lot of memory, please be careful of your task stack size.
1730 * EXAMPLE
1731 * <code>
1732 * int drvLetter, reval=0;
1733 * TCHAR K_filename[50];
1734 * drvLetter = FS_GetDrive(FS_DRIVE_V_NORMAL, 2, FS_NO_ALT_DRIVE);
1735 *
1736 * if(drvLetter > 0)
1737 * {
1738 * kal_wsprintf(K_filename, "\\\\.\\%c:", drvLetter); //please be careful of the format here
1739 * reval = FS_GeneralFormat (K_filename, FS_FORMAT_HIGH, YourCallBack);
1740 * }
1741 * else
1742 * {
1743 * //check your code
1744 * }
1745 *
1746 * void YourCallBack(const char * DriveName, int Action, UINT Total, UINT Completed)
1747 * {
1748 * if (Action == FS_FMT_PGS_DONE)
1749 * //show format done
1750 * else if (Action == FS_FMT_PGS_FAIL)
1751 * //check your error code return from FS_GeneralFormat
1752 * else
1753 * //show processing percentage: (Completed/Total) *100% //Be careful of the DIV BY ZERO problem here
1754 * }
1755 * </code>
1756 *****************************************************************************/
1757extern int FS_GeneralFormat(const WCHAR * DriveName, UINT Level, FS_FormatCallback Progress);
1758
1759/*****************************************************************************
1760 * <GROUP VolumeManagement>
1761 *
1762 * FUNCTION
1763 * FS_GetClusterSize
1764 * DESCRIPTION
1765 * This function returns the cluster size of the specified drive.
1766 * PARAMETERS
1767 * DriveIdx : [IN] <P>The drive index ('Z' or 0x43, 0x44, ...etc.)
1768 * RETURN VALUES
1769 * > 0: Cluster size in byte
1770 * FS_DRIVE_NOT_FOUND (-4): Cannot get the specified drive
1771 *****************************************************************************/
1772extern int FS_GetClusterSize(UINT DriveIdx);
1773
1774#ifdef __FS_QM_SUPPORT__
1775/*****************************************************************************
1776 * <GROUP VolumeManagement>
1777 *
1778 * FUNCTION
1779 * FS_QmGetFree
1780 * DESCRIPTION
1781 * This function can query the free space left in QuotaSet (Quota Management only).
1782 * User must register target path in QuotaSet, otherwise, FS_PATH_NOT_FOUND will be returned.
1783 * If QMax is set as 0 (Infinite), then all free space left in system drive which allows user to use will be returned.
1784 * PARAMETERS
1785 * Path : [IN] <P>The full path defined in QuotaSet
1786 * RETURN VALUES
1787 * >=0: Free space in bytes counted by (Number Application Free Cluster)*(Cluster Size)
1788 * FS_PATH_NOT_FOUND (-19): Cannot find the path in QuotaSet
1789 * FS_ACCESS_DENIED (-16): Quota Management is not enabled on this drive
1790 * FS_DRIVE_NOT_FOUND (-4): Drive not found or not mounted, this is abnormal case
1791 * FS_INVALID_FILE_SYSTEM (-8): Free cluster count of the drive is unknown, it is abnormal case
1792 * NOTE
1793 * (1) Path name should be exactly the same as one in QuotaSet.
1794 * (2) To save more resource, we use ¨BYTE? (unsigned char) instead of FS traditional WCHAR here.
1795 *****************************************************************************/
1796extern int FS_QmGetFree(const BYTE * Path);
1797#endif
1798
1799/*****************************************************************************
1800 * <GROUP VolumeManagement>
1801 *
1802 * FUNCTION
1803 * FS_CommitAll
1804 * DESCRIPTION
1805 * This API will flush all currently dirty buffers to disk according to given drive.
1806 * PARAMETERS
1807 * DriveName : [IN] <P>Must either be a valid file name (e.g., a root directory name) or NULL. If DriveName is not NULL, only the drive information (possibly the current default drive) is determined. All of that drive's hosting device's dirty buffers are flushed. If the parameter is NULL, the buffers of all devices are flushed.
1808 * RETURNS
1809 * Please refer to fs_error_enum.
1810 *****************************************************************************/
1811extern int FS_CommitAll(const WCHAR * DriveName);
1812
1813/*****************************************************************************
1814 * <GROUP VolumeManagement>
1815 *
1816 * FUNCTION
1817 * FS_SetVolumeLabel
1818 * DESCRIPTION
1819 * This function is used to set the drive labe.
1820 * PARAMETERS
1821 * DriveName : [IN] <P>The Drive to be set volume label. It should be UCS2 encoded. For example, L¨X:\?
1822 * Label : [IN] <P>The label to be set to the specific drive. This label should be UCS2 encoded. In order to be compatible with windows, the maximum length should not exceed 11 bytes when it is converted to native encoding. The allowed character should follow the DOS 8.3 format.
1823 * RETURN VALUES
1824 * FS_NO_ERROR : Successful
1825 * FS_INVALID_FILENAME (-3): The file name is invalid.
1826 * FS_INVALID_FILE_SYSTEM (-8): The specific drive doesn?t contain a legal file system.
1827 * FS_ROOT_DIR_FULL (-21): Root directory is full. The original name will be restored. (Since W09.35)
1828 * FS_DISK_FULL (-22): Disk is full. The original name will be restored. (Since W09.35)
1829 * NOTE
1830 * (1)File system can preserve the capital of volume name by creating LFN entry in FS_SetVolumeLabel(). However, Windows can only show ¨upper case? volume name.
1831 * (2)To get volume label, please use FS_GetDiskInfo() with FS_DI_BASIC_INFO and FS_DI_VOLUME_LABEL flags.
1832 *****************************************************************************/
1833extern int FS_SetVolumeLabel(const WCHAR * DriveName, const WCHAR * Label);
1834
1835/*****************************************************************************
1836 * <GROUP VolumeManagement>
1837 *
1838 * FUNCTION
1839 * FS_SwitchDriveMode
1840 * DESCRIPTION
1841 * This function provides formal plug out facility on MSDC (built-in or OTG external) for File Manager
1842 * PARAMETERS
1843 * DriveIdx : [IN] <P>The Drive to switch the mode
1844 * Mode : [IN] <P> FS_DRIVE_SOFT_UNMOUNT
1845 * <P> FS_DRIVE_SOFT_MOUNT
1846 * RETURN VALUES
1847 * FS_NO_ERROR : success
1848 * FS_DRIVE_NOT_FOUND (-4): The specified drive is not found.
1849 * FS_INVALID_FILE_SYSTEM (-8): The specific drive doesn?t contain a legal file system.
1850 * FS_UNSUPPORTED_DEVICE (-11): It is an unsupported device.
1851 * HISTORY
1852 * Since W08.36
1853 * NOTE
1854 * 1. Only File Manager can call this function.
1855 * 2. Double lock in this function!
1856 *****************************************************************************/
1857extern int FS_SwitchDriveMode(UINT DriveIdx, UINT Mode);
1858
1859/*****************************************************************************
1860 * <GROUP DiskManagement>
1861 *
1862 * FUNCTION
1863 * FS_CheckDiskFlag
1864 * DESCRIPTION
1865 * This function provides NVRAM to check if last time power off is normal or abnormal. NVRAM can check the disk flag to decide do some action or not. (like advice end user to do sanity check or not)
1866 * PARAMETERS
1867 * N/A
1868 * RETURNS
1869 * 0: Power off normally last time
1870 * 1: Power off abnormally last time
1871 *****************************************************************************/
1872extern int FS_CheckDiskFlag(void);
1873
1874#ifdef __FS_CHECKDRIVE_SUPPORT__
1875/*****************************************************************************
1876 * <GROUP DiskManagement>
1877 *
1878 * FUNCTION
1879 * FS_CheckDrive
1880 * DESCRIPTION
1881 * This function provides facility for user to check drive
1882 * PARAMETERS
1883 * DriveIdx : [IN] <P>The drive index ('Z' or 0x43, 0x44, ...etc.)
1884 * CheckBuffer : [IN] <P>The buffer get from caller
1885 * CheckBufferLength : [IN] <P>The buffer length, must > 2048
1886 * RETURNS
1887 * Success: FS_NO_ERROR
1888 * Error: list below
1889 * RETURN VALUES
1890 * FS_NO_ERROR (0)
1891 * FS_ACCESS_DENIED (-16): There?s opened file in the drive.
1892 * FS_FAIL_GET_MEM (-44): User provides a null buffer or smaller than 2048Byte
1893 * FS_DRIVE_NOT_FOUND (-4): DriveIdx provide by caller not found
1894 * FS_WRITE_PROTECTION (-30): the drive is on a write-protected media
1895 * FS_INVALID_FILESYSTEM (-8): the drive not mounted
1896 * FS_TOO_MANY_FILES (-5): the folders are too deep.
1897 * NOTE
1898 * (1) This function is wrapped with compile option, __FS_CHECKDRIVE_SUPPORT__
1899 * (2) This function requires a buffer as cluster-bit-map to process FAT file system internal data. The full size of cluster-bit-map can be retrieve by FS_GetCheckDrive(). For FAT16 disk, the maximum 8KB buffer size, and at least 16KB for FAT32. To break the growing RAM consumption by larger and larger disk size, this function still works if the check buffer size not fully provide. But the execution duration will longer. In worst case, execution duration will double if half buffer size provide.
1900 * (3) File system does not allocate the buffer here. Caller could use ASM (Application Shared Memory) to get/free the memory by himself.
1901 * Recommand Check Buffer Size : 128MB Disk Size ===> 8KB
1902 * for 1GB Size Disk ===> 32KB
1903 * (4) This function is non-recursive. However, if there is not enough file handles for file system to record the folders, file system will sweep the folders if they are too deep. Theoretically, file system support 20 levels of folders. In fact, it may be fewer if the some of the file handles are allocated by other application.
1904 * (5) In this check function, invalid file/folder will be removed automatically.
1905 * (6) Before invoking the FS_CheckDrive, please make sure there?s no module that is initializing itself. FS_CheckDrive will block others task that tries to access the same drive.
1906 * EXAMPLE
1907 * <code>
1908 * unsigned char *myPtr;
1909 * kal_uint32 fullsize, maxsize;
1910 * kal_uint32 DriveIdx = FS_GetDrive(FS_DRIVE_V_NORMAL, 1, FS_NO_ALT_DRIVE);
1911 * fullsize = FS_ GetCheckBufferSize (DriveIdx);
1912 * if (fullsize > FS_NO_ERROR)
1913 * {
1914 * maxsize = query_max_available_pool();//Caller should use ASM mechanism here
1915 * maxsize = (maxsize > fullsize) ? fullsize : maxsize;
1916 * myPtr = (unsigned char*)get_appshared_mem(maxsize); //Caller should use ASM mechanism here
1917 * FS_CheckDrive(DriveIdx, myPtr, maxsize);
1918 * if (myPtr) free_appshared_mem(myPtr); //Caller should use ASM mechanism
1919 * }
1920 * </code>
1921 *****************************************************************************/
1922extern int FS_CheckDrive(const UINT DriveIdx, BYTE * CheckBuffer, const UINT CheckBufferSize);
1923#endif
1924
1925/*****************************************************************************
1926 * <GROUP DiskManagement>
1927 *
1928 * FUNCTION
1929 * FS_GetDiskInfo
1930 * DESCRIPTION
1931 * Return information about a logical drive
1932 * PARAMETERS
1933 * DriveName : [IN] <P>Must be a valid file name, e.g., a root directory name. Only the drive information (possibly the current default drive) is determined.
1934 * DiskInfo : [OUT]<P>Refer to FS_DiskInfo.
1935 * Flags : [IN] <P>Refer to fs_di_enum.
1936 * RETURNS
1937 * Please refer to fs_error_enum.
1938 *****************************************************************************/
1939extern int FS_GetDiskInfo(const WCHAR * DriveName, FS_DiskInfo * DiskInfo, int Flags);
1940
1941/*****************************************************************************
1942 * <GROUP DiskManagement>
1943 *
1944 * FUNCTION
1945 * FS_GetDevType
1946 * DESCRIPTION
1947 * This function return the flash type for the corresponding path
1948 * PARAMETERS
1949 * Path : [IN] <P>The full-path which begin with drive letter
1950 * RETURN VALUES
1951 * FS_DRIVE_NOT_FOUND(-4): Cannot find the drive described by user
1952 * FS_DEVICE_TYPE_NOR (1): device type = NOR
1953 * FS_DEVICE_TYPE_NAND (2): device type = NAND
1954 * FS_DEVICE_TYPE_CARD (3): device type = memory card
1955 * FS_DEVICE_TYPE_EXTERNAL (4): device type = OTG
1956 *****************************************************************************/
1957extern int FS_GetDevType(const WCHAR * Path);
1958
1959/*****************************************************************************
1960 * <GROUP DiskManagement>
1961 *
1962 * FUNCTION
1963 * FS_GetDevStatus
1964 * DESCRIPTION
1965 * This function provides a facility to let task looks up the device status.
1966 * PARAMETERS
1967 * QueryTarget: [IN] <P>the index number get from FS_GetDrive, OR the type enum get from FS_GetDevType
1968 * Flag : [IN] <P>plesae refer to FS_GET_DEV_STATUS_ENUM. <color Red><b>Cannot set on simultaneously</b></color>
1969 * RETURN VALUES
1970 * FS_NO_ERROR (0): Success.
1971 * FS_PARAM_ERROR (-2): Over the drive range or flag error
1972 * FS_DEVICE_BUSY (-46): Device is busy
1973 * FS_FLASH_MOUNT_ERROR (-120): Fixed device is in un-mount state
1974 * FS_MSDC_MOUNT_ERROR (-100): Removable device is in un-mount state (maybe not present or cannot be mounted)
1975 * FS_EXTERNAL_DEVICE_NOT_PRESENT (-106): External device is not connected.
1976 * FS_DEVICE_EXPORTED_ERROR (-52): Device is exported and controlled by USB
1977 * NOTE
1978 * (1)This function cannot wait to get any lock!
1979 * (2)The error code gives you a hint that the device is mounted, busy or exported now. If device is busy and you keep trying to access this device, you may hang there and wait for the device lock. If device is exported and you try to access this device, you will get FS_DEVICE_EXPORTED_ERROR (-52) again. For external card reader, if the device not connected yet, you will get FS_MSDC_MOUNT_ERROR (-100) return value when query for drive index and FS_EXTERNAL_DEVICE_NOT_PRESENT (-106) when query for device type.
1980 * (3)If there are multiple devices with the same type, FS_GetDevStatus will return status of the 1st device matched to the input type.
1981 *****************************************************************************/
1982extern int FS_GetDevStatus(UINT DriveIdx, UINT Flag);
1983
1984/*****************************************************************************
1985 * <GROUP DiskManagement>
1986 *
1987 * FUNCTION
1988 * FS_GetDevPartitions
1989 * DESCRIPTION
1990 * This function provides a facility that user can query the number of partitions on the specific disk, and FS will return the number of partitions.
1991 * PARAMETERS
1992 * QueryTarget: [IN] <P>The drive number (0x43~0x45(depended on customized configuration)) or device type enum (0x01~0x05) needs to lookup. The drive number can be retrieved by FS_GetDrive() API. Device type enum can be retrieved by FS_GetDevType() API.
1993 * RETURN VALUES
1994 * Value > 0: number of partitions, at least 1.
1995 * FS_PARAM_ERROR (-2): Over the drive range or device type range
1996 * NOTE
1997 * (1)This function cannot wait to get any lock!
1998 *****************************************************************************/
1999extern int FS_GetDevPartitions(UINT QueryTarget);
2000
2001/*****************************************************************************
2002 * <GROUP FileOperation>
2003 *
2004 * FUNCTION
2005 * FS_CountUsedFH
2006 * DESCRIPTION
2007 * This function provide various kinds of query about number of file handles.
2008 * PARAMETERS
2009 * flag : [IN] <P>indicate the query type for number of file handles
2010 * <P>FS_FH_COUNT_CURRENT_TASK - the number of file handles occupied by current task
2011 * <P>FS_FH_COUNT_AVAILABLE - the number of file handles available now
2012 * <P>FS_FH_COUNT_USED - the number of file handles that already in use.
2013 * <P>FS_FH_COUNT_CONFIGURED - the total number of file handles that static configured.
2014 * RETURNS
2015 * Value >= 0 : the number of file handles queried.
2016 * FS_PARAM_ERROR (-2): the input flag is invalid
2017 *****************************************************************************/
2018extern int FS_CountUsedFH(int flag);
2019
2020/*****************************************************************************
2021 * <GROUP Notification>
2022 *
2023 * FUNCTION
2024 * FS_SetDirCache
2025 * DESCRIPTION
2026 * This function provides facility for browsing type application to associate reusable value
2027 * on the specific directory. Then get back the value or get miss error later.
2028 * PARAMETERS
2029 * FileHandle : [IN] <P>It?s the file handle for specific directory. You can get the directory filehandle by FS_Open() with FS_OPEN_DIR flag or FS_FindFirst() API.
2030 * NewValue : [IN] <P>The reusable value in 32-bit unsigned integer format is to be associated to specific directory. For example, number of files under the specific folder can be cached to speed up browsing application.
2031 * RETURNS
2032 * Success: FS_NO_ERROR
2033 * Error: refer to fs_error_enum.
2034 * HISTORY
2035 * This API available since 06A Branch
2036 * EXAMPLE
2037 * <code>
2038 * #define MY_PATH L?Z:\\Folder1?
2039 *
2040 * FS_HANDLE fh;
2041 * FS_DOSDirEntry FilInfo;
2042 * kal_int32 result;
2043 * kal_uint32 value;
2044 * WCHAR FileNameBuf[260];
2045 *
2046 * fh = FS_FindFirst(MY_PATH, 0, 0, &FileInfo, FileNameBuf, 520);
2047 * // traverse process? come out a reusable value
2048 * // for example, value = count_number_of_files_under_directories(fh);
2049 * FS_SetDirCache(fh, value);
2050 * FS_FindClose(fh);
2051 *
2052 * ?..
2053 *
2054 * // now we try to reuse the cached value
2055 * kal_uint32 last_cached_value;
2056 * FS_HANDLE fh;
2057 * kal_int32 result;
2058 *
2059 * fh = FS_Open(MY_PATH, FS_OPEN_DIR | FS_READ_ONLY);
2060 * result = FS_GetDirCache(fh, &last_cached_value);
2061 * FS_Close(fh);
2062 *
2063 * if (result == FS_NO_ERROR)
2064 * { // cache hit
2065 * // process with last_cached_value is okay
2066 * }
2067 * else
2068 * { // cache miss handling
2069 * // sorry, we may have to redo it again.
2070 * }
2071 * </code>
2072 *****************************************************************************/
2073extern int FS_SetDirCache(FS_HANDLE FileHandle, UINT NewValue);
2074
2075/*****************************************************************************
2076 * <GROUP Notification>
2077 *
2078 * FUNCTION
2079 * FS_GetDirCache
2080 * DESCRIPTION
2081 * This function provides facility for browsing type application to associate reusable value on the specific directory. File System will search on RAM to get the cache value set by latest FS_SetDirCache() with specific directory.
2082 * PARAMETERS
2083 * FileHandle : [IN] <P>It?s the file handle for specific directory. You can get the directory filehandle by FS_Open() with FS_OPEN_DIR flag or FS_FindFirst() API.
2084 * CurrValue : [OUT] <P>The reusable value in 32-bit unsigned integer format is to be associated to specific directory.
2085 * RETURNS
2086 * RETURN VALUES
2087 * FS_NO_ERROR: Success
2088 * FS_DIRCACHE_EXPIRED: the cached value not found
2089 * Otherwise: refer to fs_error_enum
2090 * HISTORY
2091 * This API available since 06A Branch
2092 *****************************************************************************/
2093extern int FS_GetDirCache(FS_HANDLE FileHandle, UINT *CurrValue);
2094
2095/*****************************************************************************
2096 * <GROUP Notification>
2097 *
2098 * FUNCTION
2099 * FS_ExpireDirCache
2100 * DESCRIPTION
2101 * This function provides facility for browsing type application to associate reusable value on the specific directory. File System will expire the cache value set by latest FS_SetDirCache() with specific directory.
2102 * PARAMETERS
2103 * FileHandle : [IN] <P>It?s the file handle for specific directory. You can get the directory filehandle by FS_Open() with FS_OPEN_DIR flag or FS_FindFirst() API.
2104 * RETURNS
2105 * RETURN VALUES
2106 * FS_NO_ERROR: Success
2107 * FS_INVALID_FILE_HANDLE(-10): File handle invalid
2108 * FS_ACCESS_DENIED(-16): File handle not associated to a directory
2109 * Otherwise: refer to fs_error_enum
2110 * HISTORY
2111 * This API available since 06A Branch
2112 *****************************************************************************/
2113extern int FS_ExpireDirCache(FS_HANDLE FileHandle);
2114
2115/*************************************************************************
2116 * <GROUP DirectIOCtrl>
2117 *
2118 * FUNCTION
2119 * FS_IOCtrl
2120 * DESCRIPTION
2121 * Control or configure device, or read physical information of device by drive name
2122 * PARAMETERS
2123 * DriveName : [IN] <P>DriveName could be any one drive name of the target memory device. It should be UCS2 encoded, e.g., L¨X:\\?.
2124 * CtrlAction : [IN] <P>Please refer to fs_ioctrl_action_enum.
2125 * CtrlData : [IN/OUT] <P>Control data. The usage is depended on the Control Action.
2126 * RETURN VALUES
2127 * FS_NO_ERROR: Success
2128 * FS_UNSUPPORTED_DRIVER_FUNCTION: The specified device does not support IOCtrl device driver.
2129 * FS_PARAM_ERROR: Incorrect drive name
2130 * FS_DRIVE_NOT_READY: Device is not in ready status or not mounted.
2131 * FS_UNSUPPORTED_DEVICE: Device does not support the specified IO control action.
2132 * HISTORY
2133 * Since W09.12
2134 *************************************************************************/
2135extern int FS_IOCtrl(const WCHAR* DriveName, UINT CtrlAction, void* CtrlData);
2136
2137/*****************************************************************************
2138 * <GROUP DiskManagement>
2139 *
2140 * FUNCTION
2141 * FS_RecoverDevice
2142 * DESCRIPTION
2143 * This function provides facility for user to recover flash disk,
2144 * PARAMETERS
2145 * devtype : [IN] <P>FS_DEVICE_TYPE_NOR or FS_DEVICE_TYPE_NAND can be assigned.
2146 * RETURN VALUES
2147 * FS_NO_ERROR : success and finished
2148 * FS_PARAM_ERROR (-2): No such device configured
2149 *****************************************************************************/
2150extern int FS_RecoverDevice(const int devtype);
2151
2152#if defined(__MTP_ENABLE__)
2153/*****************************************************************************
2154 * <GROUP MTP>
2155 *
2156 * FUNCTION
2157 * FS_MakeFilePathByHint
2158 * DESCRIPTION
2159 * Every file has its own directory entry for the file system to maintain the
2160 * folder hierarchy. Every directory entry of a file can be located by the
2161 * Cluster number of the file system and the offset in the cluster?(Cluster, Index).
2162 * The coordinate (Cluster, Index) is called the Hint of the file. If the hint of a
2163 * file is available, it can be used to perform some file operations without searching
2164 * the file in the disk.
2165 * If there is a hint belongs to a folder, this function can be used to get the full
2166 * path of the folder. A file hint is not supported by this function. If a file hint
2167 * is passed to this function, it returns FS_PATH_NOT_FOUND.
2168 * PARAMETERS
2169 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2170 * DirCluster : [IN] <P>The cluster number of the folder hint.
2171 * DirIndex : [IN] <P>The Index of the folder hint.
2172 * FileName : [OUT]<P>The buffer to retrieve the file path
2173 * MaxLength : [IN] <P>The buffer size
2174 * RETURN VALUES
2175 * FS_NO_ERROR : success and finished
2176 * FS_PATH_NOT_FOUND (-19): The path doesn?t exist
2177 *****************************************************************************/
2178extern int FS_MakeFilePathByHint(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex, WCHAR * FileName, UINT MaxLength);
2179
2180/*****************************************************************************
2181 * <GROUP MTP>
2182 *
2183 * FUNCTION
2184 * FS_OpenFileByHint
2185 * DESCRIPTION
2186 * If a hint of a file or a folder is available, it can be used to open the file or the folder by the hint.
2187 * PARAMETERS
2188 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2189 * DirCluster : [IN] <P>The cluster number of the folder hint.
2190 * DirIndex : [IN] <P>The Index of the folder hint.
2191 * Flags : [IN] <P>Can be a combination of the following flags:
2192 * FS_READ_WRITE FS_READ_ONLY FS_OPEN_SHARED FS_OPEN_NO_DIR
2193 * FS_OPEN_DIR FS_COMMITTED FS_CACHE_DATA FS_LAZY_DATA
2194 * FS_NONBLOCK_MODE FS_PROTECTION_MODE
2195 * RETURNS
2196 * If the function succeeds, the return value is a file handle for the opened
2197 * file and the file pointer of the file is set to 0. If the return value is less
2198 * than 0, the function has failed and the return value is the error code.
2199 *****************************************************************************/
2200extern int FS_OpenFileByHint(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex, UINT Flags);
2201
2202/*****************************************************************************
2203 * <GROUP MTP>
2204 *
2205 * FUNCTION
2206 * FS_DeleteByHint
2207 * DESCRIPTION
2208 * This function can be used to delete a file by the file hint. A folder hint
2209 * is not supported by this function. If a hint of a folder is passed to this
2210 * function, it returns FS_READ_ONLY_ERROR.
2211 * PARAMETERS
2212 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2213 * DirCluster : [IN] <P>The cluster number of the folder hint.
2214 * DirIndex : [IN] <P>The Index of the folder hint.
2215 * RETURN VALUES
2216 * FS_NO_ERROR : success
2217 * FS_PATH_NOT_FOUND (-19): The path doesn?t exist
2218 * FS_READ_ONLY_ERROR (-45): A read-only file can?t be deleted.
2219 *****************************************************************************/
2220extern int FS_DeleteByHint(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex);
2221
2222/*****************************************************************************
2223 * <GROUP MTP>
2224 *
2225 * FUNCTION
2226 * FS_GetAttributesByHint
2227 * DESCRIPTION
2228 * This function can be used to retrieve the attribute of the file via a hint.
2229 * PARAMETERS
2230 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2231 * DirCluster : [IN] <P>The cluster number of the folder hint.
2232 * DirIndex : [IN] <P>The Index of the folder hint.
2233 * RETURN VALUES
2234 * FS_ATTR_READ_ONLY
2235 * FS_ATTR_HIDDEN
2236 * FS_ATTR_SYSTEM
2237 * FS_ATTR_VOLUME
2238 * FS_ATTR_DIR
2239 * FS_ATTR_ARCHIVE
2240 *****************************************************************************/
2241extern int FS_GetAttributesByHint(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex);
2242
2243/*****************************************************************************
2244 * <GROUP MTP>
2245 *
2246 * FUNCTION
2247 * FS_SetAttributesByHint
2248 * DESCRIPTION
2249 * This function can be used to set the attribute of the file via a hint.
2250 * PARAMETERS
2251 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2252 * DirCluster : [IN] <P>The cluster number of the folder hint.
2253 * DirIndex : [IN] <P>The Index of the folder hint.
2254 * Attributes : [IN] <P>
2255 * FS_ATTR_READ_ONLY
2256 * FS_ATTR_HIDDEN
2257 * FS_ATTR_SYSTEM
2258 * FS_ATTR_VOLUME
2259 * FS_ATTR_DIR
2260 * FS_ATTR_ARCHIVE
2261 * RETURNS
2262 * Please refer to fs_error_enum.
2263 * NOTE
2264 * If you want to add/remove some attributes of a folder or volume, you should OR the
2265 * FS_ATTR_DIR / FS_ATTR_VOLUME, too. Or you will get FS_ACCESS_DENIED failure.
2266 *****************************************************************************/
2267extern int FS_SetAttributesByHint(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex, BYTE Attributes);
2268
2269/*****************************************************************************
2270 * <GROUP MTP>
2271 *
2272 * FUNCTION
2273 * FS_HintGetParent
2274 * DESCRIPTION
2275 * This function can be used to retrieve the parent?s hint of a folder hint.
2276 * PARAMETERS
2277 * DriveLetter : [IN] <P>Identify which drive the hint belongs to. E.g. ¯D?, ¯E?
2278 * DirCluster : [IN] <P>The cluster number of the folder hint.
2279 * DirIndex : [IN] <P>The Index of the folder hint.
2280 * ParentCluster : [OUT] <P>The parent hint cluster of the folder hint
2281 * ParentIndex : [OUT] <P>The parent hint index of the folder hint
2282 * RETURNS
2283 * Please refer to fs_error_enum.
2284 *****************************************************************************/
2285extern int FS_HintGetParent(WCHAR DriveLetter, UINT DirCluster, UINT DirIndex, UINT *ParentCluster, UINT *ParentIndex);
2286#endif /* __MTP_ENABLE__ */
2287
2288/*****************************************************************************
2289 * <GROUP InternalUse>
2290 *
2291 * FUNCTION
2292 * FS_GetSysInfo
2293 *
2294 * DESCRIPTION
2295 * This function provides facility for user to query file system status.
2296 *
2297 * PARAMETERS
2298 * options :[IN] Query options, it should be FS_SI_BASIC_INFO.
2299 * info :[IN] Pointer to structure fs_sysinfo_struct.
2300 *
2301 * RETURNS
2302 * RETURN VALUES
2303 * FS_NO_ERROR : Success
2304 * FS_PARAM_ERROR : Parameter error
2305 *
2306 * HISTORY
2307 * This API available since 10A.W10.52
2308 *****************************************************************************/
2309extern int FS_GetSysInfo(kal_uint32 options, fs_sysinfo_struct *info);
2310
2311/*****************************************************************************
2312 * <GROUP Notification>
2313 *
2314 * FUNCTION
2315 * FS_DirCtrl
2316 * DESCRIPTION
2317 * This function provides facility for browsing type application to associate reusable value
2318 * on the specific directory. Then get back the value or get miss error later. Lock-down and un-lock features are also provided.
2319 * PARAMETERS
2320 * handle : [IN] <P>It?s the file handle for specific directory. You can get the directory filehandle by FS_Open() with FS_OPEN_DIR flag or FS_FindFirst() API.
2321 * action : [IN] <P>It can be any of the following flags:
2322 * FS_DIRCTRL_DATA_SET
2323 * FS_DIRCTRL_DATA_GET
2324 * FS_DIRCTRL_DATA_EXPIRE
2325 * FS_DIRCTRL_DATA_LOCK
2326 * FS_DIRCTRL_DATA_UNLOCK
2327 * FS_DIRCTRL_DATA_SET_LOCK (Set and Lock)
2328 * FS_DIRCTRL_DATA_GET_LOCK (Get and Lock)
2329 * FS_DIRCTRL_DATA_GET_UNLOCK (Get and unlock)
2330 * FS_DIRCTRL_DATA_EXPIRE_UNLOCK (Expire and unlock)
2331 * value : [IN] <P>The reusable value in 32-bit unsigned integer format is to be associated to specific directory. For example, number of files under the specific folder can be cached to speed up browsing application.
2332 * RETURNS
2333 * Success: FS_NO_ERROR
2334 * Error: refer to fs_error_enum.
2335 * HISTORY
2336 * This API available since 11A Branch
2337 * EXAMPLE
2338 * <code>
2339 * #define MY_PATH L?Z:\\Folder1?
2340 *
2341 * FS_HANDLE fh;
2342 * FS_DOSDirEntry FilInfo;
2343 * kal_int32 result;
2344 * kal_uint32 value;
2345 * WCHAR FileNameBuf[260];
2346 *
2347 * fh = FS_FindFirst(MY_PATH, 0, 0, &FileInfo, FileNameBuf, 520);
2348 * // traverse process? come out a reusable value
2349 * // for example, value = count_number_of_files_under_directories(fh);
2350 * FS_DirCtrl(fh, FS_DIRCTRL_DATA_SET, value);
2351 * FS_FindClose(fh);
2352 *
2353 * ?..
2354 *
2355 * // now we try to reuse the cached value
2356 * kal_uint32 last_cached_value;
2357 * FS_HANDLE fh;
2358 * kal_int32 result;
2359 *
2360 * fh = FS_Open(MY_PATH, FS_OPEN_DIR | FS_READ_ONLY);
2361 * result = FS_DirCtrl(fh, FS_DIRCTRL_DATA_GET, value);
2362 * FS_Close(fh);
2363 *
2364 * if (result == FS_NO_ERROR)
2365 * { // cache hit
2366 * // process with last_cached_value is okay
2367 * }
2368 * else
2369 * { // cache miss handling
2370 * // sorry, we may have to redo it again.
2371 * }
2372 * </code>
2373 *****************************************************************************/
2374extern int FS_DirCtrl(FS_HANDLE handle, kal_uint32 action, void *data);
2375
2376extern void FS_SetFileTable(void *table);
2377
2378/*****************************************************************************
2379 * <GROUP Asynchronous I/F>
2380 *
2381 * FUNCTION
2382 * fs_aysnc_open
2383 *
2384 * DESCRIPTION
2385 * Open a file
2386 *
2387 * PARAMETERS
2388 * filename :[IN] Must point to the name of the file to open/create.
2389 * File names are not case sensitive; they will be converted to
2390 * upper case when file system searches this file, and they should
2391 * be two-byte aligned and UCS2 encoded. The file name can have one
2392 * of the following formats:
2393 * [Drive:][\][Path\]Name[.Ext] A data file or directory file name with optional drive and path information.
2394 * [Drive:]\ A root directory.
2395 * \\.\Drive: A logical drive.
2396 * \\.\PHYSICALDRIVEx A physical hard disk. x must be a digit (starting at '0') specifying the desired hard disk.
2397 * \\.\FMapF\[hexstrings] A virtual file, the whole path name should be generated by the dedicated FS_GenVirtualFileName API.
2398 * <Remarks> Absolute path is recommended because current dir may be changed by others before asynchronous API is executed!)
2399 * flag :[IN] Can be a combination of the following flags:
2400 * FS_READ_WRITE FS_READ_ONLY FS_OPEN_SHARED FS_OPEN_NO_DIR
2401 * FS_OPEN_DIR FS_CREATE FS_CREATE_ALWAYS FS_COMMITTED
2402 * FS_CACHE_DATA FS_LAZY_DATA FS_ATTR_HIDDEN FS_ATTR_SYSTEM
2403 * FS_ATTR_ARCHIVE FS_NONBLOCK_MODE FS_PROTECTION_MODE
2404 * overlapped :[IN] Overlapped structure has 3 members,
2405 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2406 * 2. param :[IN] (Optional) Parameters for call back function
2407 * 3. priority :[IN] (Deprecated) This function is replaced by KAL priority transfer, and the value will be ignored.
2408 * The users have to transfer the priority to the FS task on their own, if they have concerns about priority inversion.
2409 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2410 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2411 * User could free it in callback function.
2412 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2413 * 6. response_flag [IN] (*Required) The response method when job done.
2414 *
2415 * 1. FS_RESPONSE_MESSAGE: Sending ILM when job done, the user must use fs_async_msg_handler() to execute the callback function.
2416 *
2417 * For MMI task, File Manager Service will help register it. For other tasks, user must register message handler by themselves.
2418 * 2. FS_RESPONSE_CALLBACK: Invoke callback function directly in the FS task when job done, and NO ILM sending back.
2419 * RETURNS
2420 * Successful : A positive integer. It is Job ID.
2421 * Failed : A negative integer. Please refer to fs_error_enum for details.
2422 *
2423 * NOTE
2424 * 1. User must assign the response flag in the overlapped structure,
2425 * 2. Pointer types in the overlapped structure, must be allocated from the memory poll, and freed in the callback function to avoid memory leak.
2426 * 3. DO NOT use pointer to local variables in overlapped structure, it will lead to memory corruption.
2427 *
2428 * EXAMPLE
2429 * <code>
2430 * kal_int32 job_id;
2431 * fs_overlapped_struct overlapped; // !overlapped could be local variable
2432 * void *buf;
2433 * kal_wchar *file_name = L"Z:\\folder\\file"
2434 *
2435 * buf = xxx_malloc(FS_ASYNC_WORKING_BUFFER_SIZE); // !working buffer should be prepared by users
2436 *
2437 * kal_mem_set(&overlapped, 0, sizeof(fs_overlapped_struct)); // always clear the overlapped structure to zero
2438 *
2439 * overlapped.callback = callback;
2440 * overlapped.param = param;
2441 * overlapped.priority = FS_PRIORITY_DEFAULT; // *Required: priority options
2442 * overlapped.buf = buf; // *Required: working buffer address
2443 * overlapped.bufsize = FS_ASYNC_WORKING_BUFFER_SIZE; // *Required: working buffer size
2444 * overlapped.response_flag = FS_RESPONSE_MESSAGE; // *Required: response flag
2445 *
2446 * job_id = fs_async_open(file_name, FS_CREATE, &overlapped);
2447 *
2448 * if (job_id > FS_NO_ERROR)
2449 * {
2450 * // job is accepted by FS task.
2451 * //
2452 * // user could do other things.
2453 * // Callback will be called in fs_async_msg_handler() after RSP message is received.
2454 * }
2455 * else
2456 * {
2457 * // job is rejected due to errors, and the FS API is not executed.
2458 * //
2459 * // Callback function will NOT be executed.
2460 * // No response message in the future.
2461 * }
2462 * </code>
2463 *
2464 * NOTE
2465 *
2466 *****************************************************************************/
2467extern kal_int32 fs_async_open(const kal_wchar *file_name, kal_int32 flag, fs_overlapped_struct *overlapped);
2468
2469/*****************************************************************************
2470 * <GROUP Asynchronous I/F>
2471 *
2472 * FUNCTION
2473 * fs_aysnc_write
2474 *
2475 * DESCRIPTION
2476 * Write data to a file
2477 *
2478 * PARAMETERS
2479 * handle :[IN] References the open file to write to.
2480 * data :[IN] Specifies the address of the data to be written.
2481 * length :[IN] Specifies the number of bytes to write.
2482 * written :[OUT] Pointer to an unsigned integer to receive the number of
2483 * bytes actually been written. Usually, *Written will contain
2484 * Length after the call. However, in case of an error, the
2485 * returned value may be less. Written may be set to NULL if
2486 * this information is not required by an application.
2487 * overlapped :[IN] Overlapped structure has 3 members,
2488 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2489 * 2. param :[IN] (Optional) Parameters for call back function
2490 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2491 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2492 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2493 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2494 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2495 * User could free it in callback function.
2496 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2497 *
2498 * RETURNS
2499 * Successful : A positive integer. It is Job ID.
2500 * Failed : A negative integer. Please refer to fs_error_enum for details.
2501 *
2502 * EXAMPLE
2503 * <code>
2504 * </code>
2505 *
2506 * NOTE
2507 *
2508 *****************************************************************************/
2509extern kal_int32 fs_async_write(FS_HANDLE handle, void *data, kal_uint32 length, kal_uint32 *written, fs_overlapped_struct *overlapped);
2510
2511/*****************************************************************************
2512 * <GROUP Asynchronous I/F>
2513 *
2514 * FUNCTION
2515 * fs_async_read
2516 *
2517 * DESCRIPTION
2518 * Read data from a file
2519 *
2520 * PARAMETERS
2521 * handle :[IN] References the open file to write to.
2522 * data :[IN] Specifies the address of the data to be written.
2523 * length :[IN] Specifies the number of bytes to write.
2524 * read :[OUT] Pointer to an unsigned integer to receive the number of
2525 * bytes actually read. Usually, *Read will contain Length
2526 * after the call. However, in case of an error or if the
2527 * end of file is encountered during the read, the value may
2528 * be less. Read may be set to NULL if this information is
2529 * not required by an application.
2530 * overlapped :[IN] Overlapped structure has 3 members,
2531 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2532 * 2. param :[IN] (Optional) Parameters for call back function
2533 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2534 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2535 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2536 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2537 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2538 * User could free it in callback function.
2539 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2540 *
2541 * RETURNS
2542 * Successful : A positive integer. It is Job ID.
2543 * Failed : A negative integer. Please refer to fs_error_enum for details.
2544 *
2545 * NOTE
2546 * DO NOT assign pointer to local vaiable as 'written' in fs_job_write_struct, it will lead to memory corruption.
2547 * The 'written' must be allocated from memory poll, or simply assign as NULL.
2548 *
2549 * EXAMPLE
2550 * <code>
2551 * </code>
2552 *
2553 * NOTE
2554 *
2555 *****************************************************************************/
2556extern kal_int32 fs_async_read(FS_HANDLE handle, void *data, kal_uint32 length, kal_uint32 *read, fs_overlapped_struct *overlapped);
2557
2558/*****************************************************************************
2559 * <GROUP Asynchronous I/F>
2560 *
2561 * FUNCTION
2562 * fs_async_read_interleave
2563 *
2564 * DESCRIPTION
2565 * Read data from a file.
2566 * Interleavely read the buffer to shorten the latency time when aborting.
2567 *
2568 * PARAMETERS
2569 * handle :[IN] References the open file to write to.
2570 * data :[IN] Specifies the address of the data to be written.
2571 * length :[IN] Specifies the number of bytes to write.
2572 * read :[OUT] Pointer to an unsigned integer to receive the number of
2573 * bytes actually read. Usually, *Read will contain Length
2574 * after the call. However, in case of an error or if the
2575 * end of file is encountered during the read, the value may
2576 * be less. Read may be set to NULL if this information is
2577 * not required by an application.
2578 * chunksize :[IN] The buffer chunk size that read at a time, it must less than 'length'.
2579 * If chunksize is less than 32KB, the act of the function is idendical to fs_async_read().
2580 * overlapped :[IN] Overlapped structure has 3 members,
2581 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2582 * 2. param :[IN] (Optional) Parameters for call back function
2583 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2584 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2585 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2586 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2587 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2588 * User could free it in callback function.
2589 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2590 *
2591 * RETURNS
2592 * Successful : A positive integer. It is Job ID.
2593 * Failed : A negative integer. Please refer to fs_error_enum for details.
2594 *
2595 * NOTE
2596 * DO NOT assign pointer to local vaiable as 'read' in fs_job_read_struct, it will lead to memory corruption.
2597 * The 'read' must be allocated from memory poll, or simply assign as NULL.
2598 *
2599 * EXAMPLE
2600 * <code>
2601 * </code>
2602 *
2603 * NOTE
2604 *
2605 *****************************************************************************/
2606extern kal_int32 fs_async_read_interleave(FS_HANDLE handle, void *data, kal_uint32 length, kal_uint32 *read, kal_uint32 chunksize, fs_overlapped_struct *overlapped);
2607
2608/*****************************************************************************
2609 * <GROUP Asynchronous I/F>
2610 *
2611 * FUNCTION
2612 * fs_async_seek
2613 *
2614 * DESCRIPTION
2615 * Seek to a specific position of a file
2616 *
2617 * PARAMETERS
2618 * handle :[IN] References the open file to seek to.
2619 * offset :[IN] Specifies the offset (bytes) of the file to be seeked.
2620 * whence :[IN] Specifies the method (start address) of the seek.
2621 * overlapped :[IN] Overlapped structure has 3 members,
2622 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2623 * 2. param :[IN] (Optional) Parameters for call back function
2624 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2625 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2626 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2627 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2628 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2629 * User could free it in callback function.
2630 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2631 *
2632 * RETURNS
2633 * Successful : A positive integer. It is Job ID.
2634 * Failed : A negative integer. Please refer to fs_error_enum for details.
2635 *
2636 * EXAMPLE
2637 * <code>
2638 * </code>
2639 *
2640 * NOTE
2641 *
2642 *****************************************************************************/
2643extern kal_int32 fs_async_seek(FS_HANDLE handle, kal_int64 offset, kal_int32 whence, fs_overlapped_struct *overlapped);
2644
2645/*****************************************************************************
2646 * <GROUP Asynchronous I/F>
2647 *
2648 * FUNCTION
2649 * fs_async_delete
2650 *
2651 * DESCRIPTION
2652 * Delete a file
2653 *
2654 * PARAMETERS
2655 * filename :[IN] References the open file to seek to.
2656 * overlapped :[IN] Overlapped structure has 3 members,
2657 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2658 * 2. param :[IN] (Optional) Parameters for call back function
2659 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2660 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2661 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2662 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2663 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2664 * User could free it in callback function.
2665 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2666 *
2667 * RETURNS
2668 * Successful : A positive integer. It is Job ID.
2669 * Failed : A negative integer. Please refer to fs_error_enum for details.
2670 *
2671 * EXAMPLE
2672 * <code>
2673 * </code>
2674 *
2675 * NOTE
2676 *
2677 *****************************************************************************/
2678kal_int32 fs_async_delete(const kal_wchar* filename, fs_overlapped_struct *overlapped);
2679
2680/*****************************************************************************
2681 * <GROUP Asynchronous I/F>
2682 *
2683 * FUNCTION
2684 * fs_async_get_folder_size
2685 *
2686 * DESCRIPTION
2687 * This function provides a facility to get folder size
2688 *
2689 * PARAMETERS
2690 * path :[IN] Full source path to be counted
2691 * flag :[IN] FS_COUNT_IN_BYTE, FS_COUNT_IN_CLUSTER
2692 * recursive_stack :[IN] A memory pointer to store deep folder hierarchy recrusive data
2693 * stack_size :[IN] The size of RecursiveStack
2694 * overlapped :[IN] Overlapped structure has 3 members,
2695 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2696 * 2. param :[IN] (Optional) Parameters for call back function
2697 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2698 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2699 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2700 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2701 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2702 * User could free it in callback function.
2703 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2704 *
2705 * RETURNS
2706 * Successful : A positive integer. It is Job ID.
2707 * Failed : A negative integer. Please refer to fs_error_enum for details.
2708 *
2709 * EXAMPLE
2710 * <code>
2711 * </code>
2712 *
2713 * NOTE
2714 *
2715 *****************************************************************************/
2716extern kal_int32 fs_async_get_folder_size(const kal_wchar* path, kal_int32 flag, void* recursive_stack, kal_uint32 stack_size, FS_ProgressCallback callback, fs_overlapped_struct *overlapped);
2717
2718/*****************************************************************************
2719 * <GROUP Asynchronous I/F>
2720 *
2721 * FUNCTION
2722 * fs_async_find_first
2723 *
2724 * DESCRIPTION
2725 * This function provides a facility to find Nth matching file
2726 * and multi-patterns are supported
2727 *
2728 * PARAMETERS
2729 * name_pattern :[IN] Find Pattern (Must have drive name. Must NOT use local variable!)
2730 * attr :[IN] The attributes must have
2731 * attr_mask :[IN] The attributes must not have
2732 * file_info :[IN/OUT] File information (Must NOT use local variable!)
2733 * file_name :[IN/OUT] the long file name (Must NOT use local variable!)
2734 * max_length :[IN] The length of FileName
2735 * overlapped :[IN] Overlapped structure has 3 members,
2736 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2737 * 2. param :[IN] (Optional) Parameters for call back function
2738 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2739 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2740 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2741 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2742 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2743 * User could free it in callback function.
2744 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2745*
2746 * RETURNS
2747 * Successful : A positive integer. It is Job ID.
2748 * Failed : A negative integer. Please refer to fs_error_enum for details.
2749 *
2750 * EXAMPLE
2751 * <code>
2752 * </code>
2753 *
2754 * NOTE
2755 *
2756 *****************************************************************************/
2757extern kal_int32 fs_async_find_first(const kal_wchar *name_pattern,
2758 kal_uint8 attr, kal_uint8 attr_mask,
2759 FS_DOSDirEntry *file_info, kal_wchar *file_name, kal_uint32 max_length,
2760 fs_overlapped_struct *overlapped);
2761
2762/*****************************************************************************
2763 * <GROUP Asynchronous I/F>
2764 *
2765 * FUNCTION
2766 * fs_async_find_first_n
2767 *
2768 * DESCRIPTION
2769 * This function provides a facility to find Nth matching file
2770 * and multi-patterns are supported
2771 *
2772 * PARAMETERS
2773 * name_pattern :[IN] Find Pattern (Must have drive name)
2774 * pattern_array :[IN] Multi-patterns array (should not have drive name)
2775 * pattern_num :[IN] Indicate how many pattern in PatternArray
2776 * array_mask :[IN] The attributes that match default NamePattern only
2777 * attr :[IN] The attributes must have
2778 * attr_mask :[IN] The attributes must not have
2779 * file_info :[IN/OUT] File information
2780 * file_name :[IN/OUT] the long file name
2781 * max_length :[IN] The length of FileName
2782 * entry_index :[IN] Find Nth index
2783 * overlapped :[IN] Overlapped structure has 3 members,
2784 * 1. callback :[IN] (Optional) Call back function. This function will be executed just after response message is received by user.
2785 * 2. param :[IN] (Optional) Parameters for call back function
2786 * 3. priority :[IN] (*Required) Priority of this job, it can be any one of following options,
2787 * 1. FS_PRIORITY_DEFAULT : User has no priority concern for this job)
2788 * 2. FS_PRIORITY_INHERITED: FS task will be raised to a higher priorty to execute this job)
2789 * 4. buf :[IN] (*Required) Working buffer for FS asynchronous I/F. The buffer size should be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2790 * Note that the working buffer should NOT be freed before response message of this FS asynchronous operation!
2791 * User could free it in callback function.
2792 * 5. buf_size :[IN] (*Required) Working buffer size. It shoud be at least FS_ASYNC_WORKING_BUFFER_SIZE.
2793 *
2794 * RETURNS
2795 * Successful : A positive integer. It is Job ID.
2796 * Failed : A negative integer. Please refer to fs_error_enum for details.
2797 *
2798 * EXAMPLE
2799 * <code>
2800 * </code>
2801 *
2802 * NOTE
2803 *
2804 *****************************************************************************/
2805extern kal_int32 fs_async_find_first_n(const kal_wchar *name_pattern,
2806 FS_Pattern_Struct * pattern_array, kal_uint32 pattern_num,
2807 kal_uint8 array_mask, kal_uint8 attr, kal_uint8 attr_mask,
2808 FS_DOSDirEntry *file_info, kal_wchar *file_name, kal_uint32 max_length,
2809 kal_uint32 entry_index, kal_uint32 flag,
2810 fs_overlapped_struct *overlapped);
2811
2812/*****************************************************************************
2813 * <GROUP Asynchronous I/F>
2814 *
2815 * FUNCTION
2816 * fs_async_msg_handler
2817 *
2818 * DESCRIPTION
2819 * This function provides following facilities,
2820 * 1. Execute user's callback function
2821 * 2. Clean FS internal resource for this job.
2822 *
2823 * PARAMETERS
2824 * local_para :[IN] Local parameter of ILM message
2825 *
2826 * EXAMPLE
2827 * <code>
2828 * ilm_struct current_ilm;
2829 *
2830 * while (1)
2831 * {
2832 * receive_msg_ext_q(task_info_g[task_entry_ptr->task_indx].task_ext_qid, &current_ilm);
2833 *
2834 * if (current_ilm.sap_id == FS_SAP) // User could use SAP ID to identify if this message comes from FS task
2835 * {
2836 * fs_async_msg_handler(current_ilm.local_para_ptr); // process FS response message
2837 * }
2838 * else
2839 * {
2840 * // not FS response message, do something else ...
2841 * }
2842 * }
2843 * </code>
2844 *
2845 * NOTE
2846 *
2847 *****************************************************************************/
2848extern void fs_async_msg_handler(local_para_struct *local_para);
2849
2850/*****************************************************************************
2851 * <GROUP Asynchronous I/F>
2852 *
2853 * FUNCTION
2854 * fs_async_abort
2855 *
2856 * DESCRIPTION
2857 * This function provides the facility to abort a specific job by Job ID
2858 *
2859 * PARAMETERS
2860 * job_id :[IN] Job ID
2861 *
2862 * EXAMPLE
2863 * <code>
2864 * fs_async_abort(job_id);
2865 * </code>
2866 *
2867 * NOTE
2868 * 1. This function only abort the asynchronous job in the job list, not the file handle.
2869 * Use FS_Abort(), if you want to abort the handle.
2870 * 2. This function can not abort the job that is not yet recieved by the FS task.
2871 * You can use fs_async_abort_ex(), and explicitly assign the buf address to abort non-recived jobs.
2872 *
2873 *****************************************************************************/
2874extern kal_int32 fs_async_abort(fs_job_id job_id);
2875
2876/*****************************************************************************
2877 * <GROUP Asynchronous I/F>
2878 *
2879 * FUNCTION
2880 * fs_async_abort_ex
2881 *
2882 * DESCRIPTION
2883 * This function provides the facility to abort a specific job, even if it is not recieved by the FS task.
2884 *
2885 *
2886 * PARAMETERS
2887 * job_id :[IN] Job ID
2888 * buf :[IN] Pointer to the buffer, it can not be NULL.
2889 *
2890 * EXAMPLE
2891 * <code>
2892 * fs_async_abort_ex(job_id, overlapped.buf);
2893 * </code>
2894 *
2895 * NOTE
2896 * 1. This function only abort the asynchronous job in the job list, not the file handle.
2897 *
2898 *****************************************************************************/
2899extern kal_int32 fs_async_abort_ex(fs_job_id job_id, void *buf);
2900
2901/* DOM-NOT_FOR_SDK-BEGIN */
2902/*
2903 NOTE!!!
2904 Following prototypes are not belong to MAUI SDK, and shall not be used.
2905*/
2906/*****************************************************************************
2907 * <GROUP Statistics>
2908 *
2909 * FUNCTION
2910 * FS_StartIOLog
2911 * DESCRIPTION
2912 * Gathering the IO statistics of each task during a time period.
2913 * Save current IO status of every task and start logging.
2914 * PARAMETERS
2915 * Statistics : [IN]<P>The pointer to the user allocated statistic buffer,
2916 * the size of the buffer must queried from FS_GetIOStatisticsSize().
2917 * RETURNS
2918 * Successful: FS_NO_ERROR (0)
2919 * Failed: FS_PARAM_ERROR (-2)
2920 *
2921 * EXAMPLE
2922 * <code>
2923 * FS_TaskIOStatistics *iostat=NULL;
2924 * iostat=(FS_TaskIOStatistics*)get_ctrl_buffer(FS_GetIOStatisticsSize());
2925 * FS_StartIOLog(fst_iostat); // Start logging
2926 *
2927 * // ... Some File System Opeartion
2928 *
2929 * FS_EndIOLog(fst_iostat); // End logging and print result to MOD_FS TRACE_ERROR
2930 * free_ctrl_buffer(fst_iostat);
2931 * </code>
2932 *
2933 * SEE ALSO
2934 * FS_EndIOLog
2935 * FS_GetIOStatisticsSize
2936 *****************************************************************************/
2937extern int FS_StartIOLog(FS_TaskIOStatistics *Statistics);
2938
2939/*****************************************************************************
2940 * <GROUP Statistics>
2941 *
2942 * FUNCTION
2943 * FS_EndIOLog
2944 * DESCRIPTION
2945 * Gathering the IO statistics of each task during a time period.
2946 * End logging, caculate IO statistics and print result to MOD_FS TRACE_ERROR.
2947 * PARAMETERS
2948 * Statistics : [IN/OUT]<P>The pointer to the IO statistics saved by FS_StartIOLog()
2949 *
2950 * RETURNS
2951 * Successful: FS_NO_ERROR (0)
2952 * Failed: FS_PARAM_ERROR (-2)
2953 *
2954 * EXAMPLE
2955 * <code>
2956 * FS_TaskIOStatistics *iostat=NULL;
2957 * iostat=(FS_TaskIOStatistics*)get_ctrl_buffer(FS_GetIOStatisticsSize());
2958 * FS_StartIOLog(fst_iostat);
2959 *
2960 * // ... Some File System Opeartion
2961 *
2962 * FS_EndIOLog(fst_iostat);
2963 * free_ctrl_buffer(fst_iostat);
2964 * </code>
2965 *
2966 * SEE ALSO
2967 * FS_StartIOLog
2968 * FS_GetIOStatisticsSize
2969 *
2970 * NOTE
2971 * FS_StartIOLog and FS_EndIOLog must come in pairs, using the same statistic buffer.
2972 *****************************************************************************/
2973extern int FS_EndIOLog(FS_TaskIOStatistics *Statistics);
2974
2975/*****************************************************************************
2976 * <GROUP CardManagement>
2977 *
2978 * FUNCTION
2979 * FS_TestMSDC
2980 * DESCRIPTION
2981 * This function provides mount/un-mount FS facility on MSDC Card Slots for File Manager
2982 * PARAMETERS
2983 * slot_id : [IN] <P>DriverData Pointer which points to a device.
2984 * drive_list : [IN] <P>A list of DriveData. Applications could specify not only one drive.
2985 * drive_num : [IN] <P>Number of drive_list
2986 * RETURNS
2987 * RETURN VALUES
2988 * FS_NO_ERROR (0): Card is present, and mount FS successfully.
2989 * FS_MSDC_NOT_PRESENT (-105): Card is not present, and un-mount FS successfully.
2990 * FS_EXTERNAL_NOT_PRESENT (-106): External card reader not present.
2991 * FS_MSDC_MOUNT_ERROR (-100): Disk is formatting or mount driver fail.
2992 * FS_UNSUPPORTED_DEVICE (-11): It should be task owner error at development stage.
2993 * FS_UNSUPPORTED_DRIVER_FUNCTION (-12): It should be FS error at development stage.
2994 * NOTE
2995 * (1) Only file management task can use this function.
2996 * (2) If file system is not in mount state, other task cannot access removable device until file management task mount the device successfully. Actually, this is not the convention in file system. For other fixed devices, the first one accesses file system will trigger file system to mount the device if the status is not ready.
2997 *****************************************************************************/
2998int FS_TestMSDC(void * slot_id, BYTE * drive_list, UINT * drive_num);
2999
3000/*****************************************************************************
3001 * <GROUP Obsolete >
3002 *
3003 * FUNCTION
3004 * FS_CloseMSDC
3005 * DESCRIPTION
3006 * This function provides formal plug out facility on MSDC (built-in or OTG external) for File Manager
3007 * PARAMETERS
3008 * MSDCIndex : [IN] <P>The drive index (0x43, 0x44, ...etc.)
3009 * Mode : [IN] <P>block or not
3010 * 0: block mode (get lock will wait forever)
3011 * FS_NONBLOCK_MODE: non-block mode (if someone is taking the lock of FS or device, returns right away)
3012 * RETURNS
3013 * RETURN VALUES
3014 * FS_PARAM_ERROR (-2): mode parameter error
3015 * FS_DRIVE_NOT_FOUND (-4): cannot find the specific Drive Index.
3016 * FS_UN SUPPORTED_DEVICE (-11): trying to close non-removable device.
3017 * FS_INVALID_FILESYSTEM (-8): Call this function when FS is not initialized, but can remove device safely now
3018 * FS_TIMEOUT (-23): Cannot get FS or device lock
3019 *****************************************************************************/
3020extern int FS_CloseMSDC(UINT MSDCIndex, UINT Mode);
3021
3022/*****************************************************************************
3023 * <GROUP OTG>
3024 *
3025 * FUNCTION
3026 * FS_ConfigExtDevice
3027 * DESCRIPTION
3028 * This function is designed to support external device that can contain variance number slots and drives such as card reader. FS_ConfigExtDevice() should be called after the external device cable connected on or plugged out.
3029 * PARAMETERS
3030 * Action : [IN] <P>accept FS_SETUP_EXT_DEVICE or FS_ RELEASE_EXT_DEVICE only
3031 * DrvFuncs : [IN] <P>The pointer of device driver callback function array, {MountDevice, Shutdown, ... }. Provided by device driver.
3032 * Slots : [IN] <P>Number of independent slots. Number of elements in SlotIdArray
3033 * SlotIdArray : [IN] <P>The DriverData (treat as slot identify) array to be filled on device list.
3034 * SlotsConfiged : [IN] <P>Pointer to an integer to receive the number of bytes actually configured. Usually, *SlotsConfiged will contain Slots after the call. However, in case of an error.
3035 * RETURNS
3036 * RETURN VALUES
3037 * FS_PARAM_ERROR (-2): NULL DrvFuncs, SlotIdArray or 0 Slots.
3038 * FS_UNSUPPORTED_DEVICE (-11): The device try to configure not found in the list.
3039 * FS_ UNSUPPORTED_DRIVER_FUNCTION (-12): The device doesn?t support hot plug IO mechanism.
3040 * NOTE
3041 * Currently, No *allocate* operation commited, this API is design to keep FMT/FS/DRV iterface
3042 * complete. But not real dynamic yet!
3043 *****************************************************************************/
3044extern int FS_ConfigExtDevice(int Action, FS_Driver *DrvFuncs, int Slots, void **SlotIdArray, int *SlotsConfiged);
3045
3046extern int FS_MountRemovableDevice(void);
3047
3048/*****************************************************************************
3049 * <GROUP DiskManagement>
3050 *
3051 * FUNCTION
3052 * FS_SanityCheck
3053 * DESCRIPTION
3054 * This function provides a facility to handle the following critical jobs
3055 * (1) RUN ONCE
3056 * a. file system initialization, fixed device mount, system drive mount
3057 * b. make 'Z' drive letter as system drive alias
3058 * c. system drive power lose recovery
3059 * d. file system trace/debug level default setting
3060 * e. system drive quota sweep
3061 * f. mount removable card device
3062 * (2) RUN AFTER FILE SYSTEM INITIALIZED
3063 * g. quota configure check
3064 * RETURNS
3065 * Refer to fs_error_enum.
3066 * Note
3067 * This function cannot wait to get any lock!
3068 *****************************************************************************/
3069extern int FS_SanityCheck(void);
3070
3071/*****************************************************************************
3072 *
3073 * FUNCTION
3074 * FS_GetFileDetail
3075 * DESCRIPTION
3076 * This function just for get file modify, change status and access time
3077 * PARAMETERS
3078 * FileName : [IN] <P>refer to FS_Open.
3079 * FileDetail : [OUT] <P>Refer to LastModifiedTime, LastAccessTime and LastStatusChangeTime
3080 * RETURNS
3081 * Successful : FS_NO_ERROR
3082 * Failed : Please refer to fs_error_enum.
3083 *NOTES: Currently this API just for MCF useable, and just only useable to full load.
3084 *****************************************************************************/
3085#define FS_GetFileDetail(...) -255//MD_FS_API(FS_GetFileDetail, __VA_ARGS__)
3086
3087/* DOM-NOT_FOR_SDK-END */
3088
3089#else
3090
3091// Smart Phone Modem Wrapper
3092//------------------------------------------------------------
3093
3094/* DOM-NOT_FOR_SDK-BEGIN */
3095
3096#include "ccci_fs_if.h"
3097#include "nvram_defs.h"
3098
3099
3100extern kal_int32 FS_Write_Wrap(FS_HANDLE FileHandle, void * DataPtr, kal_uint32 Length, kal_uint32 * Written);
3101extern kal_int32 FS_Read_Wrap(FS_HANDLE FileHandle, void * DataPtr, kal_uint32 Length, kal_uint32 * Read);
3102extern kal_int32 FS_CMPT_Read_Wrap(const WCHAR * FileName, NVRAM_FS_PARAM_CMPT_T* nvram_param);
3103
3104#define MD_FS_API(n, ...) MD##_##n(__VA_ARGS__)
3105
3106#define FS_CMPT_Read(...) FS_CMPT_Read_Wrap(__VA_ARGS__)//MD_FS_API(FS_CMPT_Read, __VA_ARGS__)
3107
3108// General I/O
3109#define FS_Open(...) MD_FS_API(FS_Open, __VA_ARGS__)
3110#define FS_OpenHint(...) MD_FS_API(FS_OpenHint, __VA_ARGS__)
3111#define FS_Close(...) MD_FS_API(FS_Close, __VA_ARGS__)
3112#define FS_CloseAll(...) MD_FS_API(FS_CloseAll, __VA_ARGS__)
3113#define FS_Read(...) FS_Read_Wrap(__VA_ARGS__)//MD_FS_API(FS_Read, __VA_ARGS__)
3114#define FS_Write(...) FS_Write_Wrap(__VA_ARGS__)//MD_FS_API(FS_Write, __VA_ARGS__)
3115#define FS_EnableSmartSeek(...) -255
3116#define FS_SetSeekHint(...) -255//MD_FS_API(FS_SetSeekHint, __VA_ARGS__)
3117#define FS_SetSeekHintEx(...) -255//MD_FS_API(FS_SetSeekHint, __VA_ARGS__)
3118#define FS_SeekLargeFile(...) MD_FS_API(FS_Seek, __VA_ARGS__)
3119#define FS_Seek(...) MD_FS_API(FS_Seek, __VA_ARGS__)
3120#define FS_Commit(...) -255//MD_FS_API(FS_Commit, __VA_ARGS__)
3121#define FS_ReleaseFH(...) -255//MD_FS_API(FS_ReleaseFH, __VA_ARGS__)
3122#define FS_Abort(...) -255//MD_FS_API(FS_Abort, __VA_ARGS__)
3123#define FS_ParseFH(...) -255//MD_FS_API(FS_ParseFH, __VA_ARGS__)
3124#define FS_GenVirtualFileName(...) -255//MD_FS_API(FS_GenVirtualFileName, __VA_ARGS__)
3125
3126//Information
3127#define FS_GetFileDetail(...) MD_FS_API(FS_GetFileDetail, __VA_ARGS__)
3128#define FS_GetFileInfo(...) -255//MD_FS_API(FS_GetFileInfo, __VA_ARGS__)
3129#define FS_GetFileInfoEx(...) -255//MD_FS_API(FS_GetFileInfoEx, __VA_ARGS__)
3130#define FS_GetFileSize(...) MD_FS_API(FS_GetFileSize, __VA_ARGS__)
3131#define FS_GetFilePosition(...) -255//MD_FS_API(FS_GetFilePosition, __VA_ARGS__)
3132#define FS_SetFileTime(...) -255//MD_FS_API(FS_SetFileTime, __VA_ARGS__)
3133#define FS_GetAttributes(...) MD_FS_API(FS_GetAttributes, __VA_ARGS__) // Meta tool need this
3134#define FS_GetFirstCluster(...) -255//MD_FS_API(FS_GetFirstCluster, __VA_ARGS__)
3135#define FS_GetSysInfo(...) -255//MD_FS_API(FS_GetSysInfo, __VA_ARGS__)
3136#define FS_SetFileTable(...) -255//MD_FS_API(FS_SetFileTable, __VA_ARGS__)
3137#define FS_Config(...) -255//MD_FS_API(FS_Config, __VA_ARGS__)
3138
3139//File Only Operation
3140#define FS_SetAttributes(...) -255//MD_FS_API(FS_SetAttributes, __VA_ARGS__)
3141#define FS_Delete(...) MD_FS_API(FS_Delete, __VA_ARGS__)
3142#define FS_DeleteEx(...) -255//MD_FS_API(FS_DeleteEx, __VA_ARGS__)
3143#define FS_PseudoMerge(...) -255//MD_FS_API(FS_PseudoMerge, __VA_ARGS__)
3144#define FS_CheckFile(...) -255//MD_FS_API(FS_CheckFile, __VA_ARGS__)
3145
3146//Folder Only Operation
3147#define FS_GetCurrentDir(...) -255//MD_FS_API(FS_GetCurrentDir, __VA_ARGS__)
3148#define FS_GetCurrentDirByDrive(...) -255//MD_FS_API(FS_GetCurrentDirByDrive, __VA_ARGS__)
3149#define FS_SetCurrentDir(...) -255//MD_FS_API(FS_SetCurrentDir, __VA_ARGS__)
3150#define FS_CreateDir(...) MD_FS_API(FS_CreateDir, __VA_ARGS__)
3151#define FS_RemoveDir(...) MD_FS_API(FS_RemoveDir, __VA_ARGS__)
3152#define FS_GetFolderSize(...) MD_FS_API(FS_GetFolderSize, __VA_ARGS__)
3153#define FS_GetFolderSizeEx(...) MD_FS_API(FS_GetFolderSizeEx, __VA_ARGS__)
3154
3155//File and Folder Operations
3156#define FS_Extend(...) -255//MD_FS_API(FS_Extend, __VA_ARGS__)
3157#define FS_Truncate(...) -255//MD_FS_API(FS_Truncate, __VA_ARGS__)
3158#define FS_MakeFileName(...) -255//MD_FS_API(FS_MakeFileName, __VA_ARGS__)
3159#define FS_Rename(...) MD_FS_API(FS_Rename, __VA_ARGS__)
3160
3161#define FS_Move(...) MD_FS_API(FS_Move, __VA_ARGS__)
3162
3163#define FS_Count(...) MD_FS_API(FS_Count, __VA_ARGS__)
3164#define FS_XDelete(...) MD_FS_API(FS_XDelete, __VA_ARGS__)
3165#define FS_XDeleteEx(...) -255//MD_FS_API(FS_XDeleteEx, __VA_ARGS__)
3166
3167#define FS_CompactDir(...) -255//MD_FS_API(FS_XDeleteEx, __VA_ARGS__)
3168
3169#define FS_CheckFileName(...) -255//MD_FS_API(FS_CheckFileName, __VA_ARGS__)
3170#define FS_CheckVolumeLabel(...) -255//MD_FS_API(FS_CheckVolumeLabel, __VA_ARGS__)
3171
3172//Find File
3173#define FS_FindFirst(...) MD_FS_API(FS_FindFirst, __VA_ARGS__)
3174#define FS_FindNext(...) MD_FS_API(FS_FindNext, __VA_ARGS__)
3175#define FS_FindFirstN(...) -255//MD_FS_API(FS_FindFirstN, __VA_ARGS__)
3176#define FS_FindNextN(...) -255//MD_FS_API(FS_FindNextN, __VA_ARGS__)
3177#define FS_FindClose(...) MD_FS_API(FS_FindClose, __VA_ARGS__)
3178#define FS_ListOpen(...) -255
3179#define FS_ListReload(...) -255
3180#define FS_ListNext(...) -255
3181#define FS_ListClose(...) -255
3182
3183#ifdef __FS_SORT_SUPPORT__
3184#define FS_SortCompareFileName(...) -255
3185#define FS_SortCompareFileType(...) -255
3186#define FS_XFindReset(...) -255//MD_FS_API(FS_XFindReset, __VA_ARGS__)
3187#define FS_XFindStart(...) -255//MD_FS_API(FS_XFindStart, __VA_ARGS__)
3188#define FS_XFindClose(...) -255//MD_FS_API(FS_XFindClose, __VA_ARGS__)
3189#endif
3190
3191//Drive Management
3192#define FS_GetDrive(...) MD_FS_API(FS_GetDrive, __VA_ARGS__)
3193#define FS_GetDriveByHandle(...) -255//MD_FS_API(FS_GetDriveByHandle, __VA_ARGS__)
3194#define FS_GeneralFormat(...) -255//MD_FS_API(FS_GeneralFormat, __VA_ARGS__)
3195#define FS_GetClusterSize(...) MD_FS_API(FS_GetClusterSize, __VA_ARGS__)
3196#ifdef __FS_QM_SUPPORT__
3197#define FS_QmGetFree(...) -255//MD_FS_API(FS_QmGetFree, __VA_ARGS__)
3198#endif
3199#define FS_CreateBootSector(...) 0//MD_FS_API(FS_CreateBootSector, __VA_ARGS__)
3200#define FS_GetPartitionInfo(...) -255//MD_FS_API(FS_GetPartitionInfo, __VA_ARGS__)
3201#define FS_CommitAll(...) -255//MD_FS_API(FS_CommitAll, __VA_ARGS__)
3202#define FS_MappingDrive(...) -255//MD_FS_API(FS_MappingDrive, __VA_ARGS__)
3203
3204//Power Lost Detection and Recovery
3205#define FS_SetDiskFlag(...) MD_FS_API(FS_SetDiskFlag, __VA_ARGS__)
3206#define FS_CheckDiskFlag(...) -255//MD_FS_API(FS_CheckDiskFlag, __VA_ARGS__)
3207#define FS_ClearDiskFlag(...) MD_FS_API(FS_ClearDiskFlag, __VA_ARGS__)
3208#ifdef __FS_CHECKDRIVE_SUPPORT__
3209#define FS_CheckDrive(...) -255//MD_FS_API(FS_CheckDrive, __VA_ARGS__)
3210#endif
3211
3212//Disk Management
3213#define FS_CreateMasterBootRecord(...) 0//MD_FS_API(FS_CreateMasterBootRecord, __VA_ARGS__)
3214#define FS_SplitPartition(...) 0//MD_FS_API(FS_SplitPartition, __VA_ARGS__)
3215#define FS_GetDiskInfo(...) MD_FS_API(FS_GetDiskInfo, __VA_ARGS__)
3216#define FS_GetDevType(...) -255//MD_FS_API(FS_GetDevType, __VA_ARGS__)
3217#define FS_GetDevStatus(...) -255//MD_FS_API(FS_GetDevStatus, __VA_ARGS__)
3218#define FS_GetDevPartitions(...) -255//MD_FS_API(FS_GetDevPartitions, __VA_ARGS__)
3219
3220//Card management
3221#define FS_TestMSDC(...) -255//MD_FS_API(FS_TestMSDC, __VA_ARGS__)
3222#define FS_CloseMSDC(...) -255//MD_FS_API(FS_CloseMSDC, __VA_ARGS__)
3223#define FS_MountRemovableDevice(...) -255//MD_FS_API(FS_MountRemovableDevice, __VA_ARGS__)
3224
3225//OTG Card Reader Management
3226#define FS_ConfigExtDevice(...) -255//MD_FS_API(FS_ConfigExtDevice, __VA_ARGS__)
3227
3228//File System Run-Time LifeCycle
3229#define FS_ShutDown(...) MD_FS_API(FS_ShutDown, __VA_ARGS__)
3230#define FS_UnlockAll(...) MD_FS_API(FS_UnlockAll, __VA_ARGS__)
3231#define FS_SanityCheck(...) //MD_FS_API(FS_SanityCheck, __VA_ARGS__)
3232#define FS_LockFAT(...) MD_FS_API(FS_LockFAT, __VA_ARGS__)
3233
3234//File System Run-Time Debug
3235#define FS_CountUsedFH(...) -255//MD_FS_API(FS_CountUsedFH, __VA_ARGS__)
3236#ifdef __FS_TRACE_SUPPORT__
3237#define FS_SetTrace(...) -255//MD_FS_API(FS_SetTrace, __VA_ARGS__)
3238#define FS_DumpFHTable(...) -255//MD_FS_API(FS_DumpFHTable, __VA_ARGS__)
3239#endif
3240
3241//DirCache
3242#define FS_SetDirCache(...) -255//MD_FS_API(FS_SetDirCache, __VA_ARGS__)
3243#define FS_GetDirCache(...) -255//MD_FS_API(FS_GetDirCache, __VA_ARGS__)
3244#define FS_ExpireDirCache(...) -255//MD_FS_API(FS_ExpireDirCache, __VA_ARGS__)
3245#define FS_DirCtrl(...) -255//MD_FS_API(FS_DirCtrl, __VA_ARGS__)
3246
3247//Flash Device Direct IO
3248#define FS_OTPWrite(...) MD_FS_API(FS_OTPWrite, __VA_ARGS__)
3249#define FS_OTPRead(...) MD_FS_API(FS_OTPRead, __VA_ARGS__)
3250#define FS_OTPQueryLength(...) MD_FS_API(FS_OTPQueryLength, __VA_ARGS__)
3251#define FS_OTPLock(...) MD_FS_API(FS_OTPLock, __VA_ARGS__)
3252#define FS_IOCtrl(...) -255//MD_FS_API(FS_IOCtrl, __VA_ARGS__)
3253
3254//Flash Sweep
3255#define FS_SweepDevice(...) -255//MD_FS_API(FS_SweepDevice, __VA_ARGS__)
3256
3257#define FS_StartIOLog(...) -255
3258#define FS_EndIOLog(...) -255
3259
3260#if defined(__MTP_ENABLE__)
3261#define FS_MakeFilePathByHint(...) -255//MD_FS_API(FS_MakeFilePathByHint, __VA_ARGS__)
3262#define FS_OpenFileByHint(...) -255//MD_FS_API(FS_OpenFileByHint, __VA_ARGS__)
3263#define FS_DeleteByHint(...) -255//MD_FS_API(FS_DeleteByHint, __VA_ARGS__)
3264#define FS_GetAttributesByHint(...) -255//MD_FS_API(FS_GetAttributesByHint, __VA_ARGS__)
3265#define FS_SetAttributesByHint(...) -255//MD_FS_API(FS_SetAttributesByHint, __VA_ARGS__)
3266#define FS_HintGetParent(...) -255//MD_FS_API(FS_HintGetParent, __VA_ARGS__)
3267#endif // __MTP_ENABLE__
3268
3269#define fs_async_abort(...) -255
3270#define fs_async_find_first(...) -255
3271#define fs_async_find_first_n(...) -255
3272#define fs_async_get_folder_size(...) -255
3273#define fs_async_open(...) -255
3274#define fs_async_read(...) -255
3275#define fs_async_read_interleave(...) -255
3276#define fs_async_seek(...) -255
3277#define fs_async_write(...) -255
3278
3279/* DOM-NOT_FOR_SDK-END */
3280
3281#endif
3282
3283
3284#ifdef __cplusplus
3285}
3286#endif
3287
3288#endif // _FS_GENERAL_API_H_
3289
3290