vfs.h.svn-base

vc环境下编译的一个对USB设备进行烧录的驱动程序

/** @file 
 * @brief This file provides all the interface APIs of flash file system
 *
 * Copyright (C) 2005 Anyka (GuangZhou) Software Technology Co., Ltd.
 * @author xuchang
 * @date 2005-05-010
 * @version 1.0
 * @ref Please refer to INTERFACE OF FS LIBRARY.doc                                                                                                                       
 */



#ifndef __FS_API_H__
#define __FS_API_H__

/** @defgroup FFSLIB File system library
 */
/**@{*/
/**@}*/

/// @cond OK

#ifndef FSAPI
#define FSAPI(_funname) FS_##_funname
#endif

#ifndef FSTAPI
#define FSTAPI(_funname) FST_##_funname
#endif

/** define the file handler*/
#ifndef T_hFILE
#define	T_hFILE					T_S32		/* FILE * */
#endif


/** define the file status structure
 */
#ifndef T_hFILESTAT
#define	T_hFILESTAT				T_S32
#endif


/** file mode 
*/
#ifndef T_FILE_MODE
#define T_FILE_MODE				T_U32		
#endif


/** file flag 
*/
#ifndef T_FILE_FLAG
#define T_FILE_FLAG				T_U32	
#endif

/** define the invalid file handle 
*/
#ifndef FS_INVALID_HANDLE
#define FS_INVALID_HANDLE		-1
#endif


/** define the invvalid file stat handle 
*/
#ifndef FS_INVALID_STATHANDLE
#define FS_INVALID_STATHANDLE	0
#endif

/** FS_FileOpen flag reference
 * @NOTE
 * This flag only works while opening a file
 */
#define FS_PO_RDWR			0x0000 /**< Read/write access allowed. */
#define FS_PO_RDONLY		0x0001 /**< Open for read only. */
#define FS_PO_WRONLY		0x0002 /**< Open for write only. */
#define FS_PO_APPEND		0x0004 /**< Filepointer will be set to end of file on opening the file. */
#define FS_PO_CREAT			0x0010 /**< Create the file if it does not exist. */
#define FS_PO_TRUNC			0x0020 /**< Truncate the file if it already exists. */
#define FS_PO_EXCL			0x0040 /**< Attempt to create will fail if  the given file already exists.  Used in conjunction with VPO_CREAT*/


/** FS_FileOpen mode reference
 * @NOTE
 * This is the file mode attribute, it is used when creating a file
 */
#define FS_ANORMAL			0x00000000	//normal file
#define FS_AHIDDEN			0x00010000	//hidden file
#define FS_ASYSTEM			0x00020000	//system file
#define FS_UNDELETE			0x00040000	//undelete file
#define FS_S_IWRITE			0x00100000 /**< Write permitted  */
#define FS_S_IREAD			0x00200000 /**< Read permitted. (Always true anyway)*/
#define FS_S_IFMT			0x17000000 /**< type of file mask */
#define FS_S_IFDIR			0x04000000 /**< directory */
#define FS_S_IFREG			0x10000000 /**< regular */

#define FS_S_ISDIR(m)		((m & FS_S_IFMT) == FS_S_IFDIR) /**< directory */
#define FS_S_ISREG(m)		((m & FS_S_IFMT) == FS_S_IFREG) /**< regular file */

/** following macro for compatible usage
 */
#define FS_PS_IWRITE		FS_S_IWRITE /**< Write permitted  */
#define FS_PS_IREAD			FS_S_IREAD /**< Read permitted. (Always true) */
#define FS_ISDIR			FS_S_IFDIR

/// @endcond 

/** @{@name File open mode for filesystem of FAT and NORFS
*
* You can use these mode to create a file, open a file in read-only mode and so on. \n
* You can pass these macro as the flag and mode to FS_FileOpen.
 */
#ifndef FS_MODE_CREATE
/** 
 *access file in create mode.if not exsit, create it. if exsit, its content will be destoryed 
*/
#define FS_MODE_CREATE		(FS_PO_RDWR|FS_PO_CREAT|FS_S_IWRITE|FS_S_IREAD)
#endif

#ifndef FS_MODE_READ
/**
* access file in read-only mode.if the file isn't exsit yet, an error will be returned. 
*/
#define FS_MODE_READ		(FS_PO_RDONLY|FS_S_IWRITE|FS_S_IREAD)
#endif

#ifndef FS_MODE_WRITE
/**
* access file in read-write mode.you are permitted to read from and write to file in this mode.
*/
#define FS_MODE_WRITE		(FS_PO_RDWR|FS_S_IWRITE|FS_S_IREAD)
#endif
/** @} */

/** @{@name FS_FileSeek reference
 */
#ifndef FS_SEEK_SET
#define FS_SEEK_SET			0
#endif

#ifndef FS_SEEK_CUR	
#define FS_SEEK_CUR			1	
#endif

#ifndef FS_SEEK_END
#define FS_SEEK_END			2
#endif
/** @} */


/** @defgroup FSAPI File system interface
    @ingroup FFSLIB
 */
/**@{*/
/**
 * @brief Initialize the file system
 * @param[in] T_VOID
 * @return 0: success; -1: failed
 */
T_S16	FSAPI(Init)(T_VOID);
/**
 * @brief format the destination device
 * @param[in] driver   driver name
 * @return success or not
 */
T_BOOL	FSAPI(Format)(T_pCSTR driver);
/**
 * @brief mount a device not to be used
 * @param[in] driver   driver name
 * @return success or not
 */
T_BOOL	FSAPI(Mount)(T_pCSTR driver);
/**
 * @brief unmount a device not to be used
 * @param[in] driver   driver name
 * @return success or not
 */
T_BOOL	FSAPI(UnMount)(T_pCSTR driver);
/**
 * @brief get the size of used space for a device, in bytes
 * @param[in] driver   driver name
 * @return size of used space
 */
T_S32	FSAPI(GetUsedSize)(T_pCSTR driver);
/**
 * @brief get the size of free space for a device, in bytes
 * @param[in] driver   driver name
 * @return size of free space
 */
T_S32	FSAPI(GetFreeSize)(T_pCSTR driver);
/**
 * @brief debug function for printing some system info
 * @param[in] driver   driver name
 * @return void
 */
T_VOID	FSAPI(SysInfo)(T_pCSTR driver);
/**
 * @brief rubbish recycle for file system
 * @param[in] driver   driver name
 * @return void
 */
T_VOID	FSAPI(CheckGC)(T_pCSTR driver);
/** @} */

/** @defgroup FSOAPI File operation interface
    @ingroup FFSLIB
 */
/**@{*/
/**
 * @brief open or create a file
 * @param[in] path   file path
 * @param[in] flag   flag of file accessing
 * @param[in] mode   mode of file attribute
 * @return success: >=0 file handle; failed: -1
 */
T_hFILE FSAPI(FileOpen)(T_pCSTR path, T_FILE_FLAG flag, T_FILE_MODE mode);
/**
 * @brief read data from a file
 * @param[in] hFile   file handle
 * @param[out] buffer  Pointer to the buffer that receives the data read from the file
 * @param[in] count   Number of bytes to be read from the file
 * @return the number of bytes read
 */
T_S32	FSAPI(FileRead)(T_hFILE hFile, T_pVOID buffer, T_U32 count);
/**
 * @brief write data to a file
 * @param[in] hFile   file handle
 * @param[in] buffer  Pointer to the buffer containing the data to be written to the file
 * @param[in] count   Number of bytes to be written to the file
 * @return the number of bytes written
 */
T_S32	FSAPI(FileWrite)(T_hFILE hFile, T_pCVOID buffer, T_U32 count);

/**
 * @brief Close the file
 * @param[in] hFile   file handle
 * @return success or not
 */
T_BOOL	FSAPI(FileClose)(T_hFILE hFile);

/**
 * @brief Moves the file pointer to a specified location
 * @param[in] hFile   file handle
 * @param[in] offset Number of bytes from origin 
 * @param[in] origin Initial position 
 * @return success: current file pointer position; failed: -1
 */
T_S32	FSAPI(FileSeek)(T_hFILE hFile, T_S32 offset, T_U16 origin);

/**
 * @brief Get the length of file
 * @param[in] hFile   file handle
 * @return length of file
 */
T_S32	FSAPI(GetFileLen)(T_hFILE hFile);

/**
 * @brief Delete the file
 * @param[in] path   path of the appointed file to be deleted
 * @return success or not
 */
T_BOOL	FSAPI(FileDelete)(T_pCSTR path);
/** @} */

/** @defgroup FSSAPI File status interface
    @ingroup FFSLIB
 */
/**@{*/
/**
 * @brief Get the status of file from the file handle
 * @param[in] hFile   file handle
 * @return success: handle of file status; failed: FS_INVALID_STATHANDLE
 */
T_hFILESTAT FSAPI(HFileStat)(T_hFILE hFile);

/**
 * @brief Get the status of file from the file name
 * @param[in] path   path of the appointed file
 * @return success: handle of file status; failed: FS_INVALID_STATHANDLE
 */
T_hFILESTAT FSAPI(FileStat)(T_pCSTR path);

/**
 * @brief Set the status of file from the file name
 * @param[in] path   path of the appointed file
 * @param[in] stat   handle of file status
 * @return success or not
 */
T_BOOL	FSAPI(SetStat)(T_pCSTR path, T_hFILESTAT stat);

/**
 * @brief clear the status of file from the file name
 * 
 *@param _stat handle of file status
 */
#define FST_CLEAR(_stat) do{ FSTAPI(Close)(_stat);_stat=FSAPI(INVALID_STATHANDLE);}while(0)

/**
 * @brief Get the status of first file in the appointed directory
 * @param[in] pattern   traversal format
 * @return success: handle of file status; failed: FS_INVALID_STATHANDLE
 */
T_hFILESTAT FSAPI(FindFirst)(T_pCSTR pattern);

/**
 * @brief Get the status of next file in the appointed directory
 * @param[in] stat   handle of file status
 * @return success or not
 */
T_BOOL	FSAPI(FindNext)(T_hFILESTAT stat);

/**
 * @brief Release the handle of file status
 * @param[in] stat   handle of file status
 * @return void
 */
T_VOID	FSAPI(FindClose)(T_hFILESTAT stat);

/**
 * @brief release and reset the handle of file status
 * 
 *@param _stat handle of file status
 */
#define FS_FINDCLEAR(_stat) do{ FSAPI(FindClose)(_stat);_stat=FSAPI(INVALID_STATHANDLE);}while(0)

/**
 * @brief Release the handle of file status
 * @param[in] stat   handle of file status
 * @return void
 */
T_VOID	FSTAPI(Close)(T_hFILESTAT stat);

/**
 * @brief Get the attribute info of file
 * @param[in] stat   handle of file status
 * @return the attribute info of file
 */
T_U32	FSTAPI(GetAttribute)(T_hFILESTAT stat);

/**
 * @brief Get the size info of file
 * @param[in] stat   handle of file status
 * @return the size info of file
 */
T_U32	FSTAPI(GetSize)(T_hFILESTAT stat);

/**
 * @brief Get the path info of file
 * @param[in] stat   handle of file status
 * @return the path info of file
 */
T_pCSTR FSTAPI(GetPath)(T_hFILESTAT stat);

/**
 * @brief Get the name info of file
 * @param[in] stat   handle of file status
 * @return the name info of file
 */
T_pCSTR FSTAPI(GetFileName)(T_hFILESTAT stat);
T_U32	FSTAPI(GetCTime)(T_hFILESTAT stat);
/** @} */

/** @defgroup FSDSAPI Directory operation interface
    @ingroup FFSLIB
 */
/**@{*/
/**
 * @brief create directory operation
 * @param[in] path   name of directory including complete path
 * @param[in] mode   attribute of directory 
 * @return success or not
 */
T_BOOL	FSAPI(MkDir)(T_pCSTR path, T_FILE_MODE mode);

/**
 * @brief remove directory operation
 * @param[in] path   name of directory including complete path
 * @return success or not
 */
T_BOOL	FSAPI(RmDir)(T_pCSTR path);

/**
 * @brief judge if directory or not
 * @param[in] path   name of directory including complete path
 * @return success or not
 */
T_BOOL	FSAPI(IsDir)(T_pCSTR path);

/**
 * @brief Move the file
 * @param[in] oriPath   current position of the file
 * @param[in] newPath   new position of the file
 * @return success or not
 */
T_BOOL	FSAPI(MoveFile)(T_pCSTR oriPath, T_pCSTR newPath);
/** @} */


/** @defgroup FSRAPI  File system related interface
    @ingroup FFSLIB
 */
/**@{*/
/**
 * @brief Check the file name valid or not
 * @param[in] fname   file name, not include path
 * @return valid or not
 */
T_BOOL	FSAPI(FNameValid)(T_pCSTR fname);	//not include path
/** @} */

#endif