文件系统FatFsR0.09a翻译（三）：ff.h

//本译文只供学习使用，未经作者许可，不得用于其它任何用途  

//译者：xiaofeng

//修改日期:2013/03/19

//版本：V1.0

//版权所有，盗版必究。

/*---------------------------------------------------------------------------/
/  FatFs - FAT file system module include file  R0.09a    (C)ChaN, 2012
/----------------------------------------------------------------------------/
/ FatFs module is a generic FAT file system module for small embedded systems.
/ This is a free software that opened for education, research and commercial
/ developments under license policy of following terms.
/
/  Copyright (C) 2012, ChaN, all right reserved.
/
/ * The FatFs module is a free software and there is NO WARRANTY.
/ * No restriction on use. You can use, modify and redistribute it for
/   personal, non-profit or commercial product UNDER YOUR RESPONSIBILITY.
/ * Redistributions of source code must retain the above copyright notice.
/
/----------------------------------------------------------------------------*/

#ifndef _FATFS
#define _FATFS  4004    /* 版本ID Revision ID */

#ifdef __cplusplus
extern  "C"  {
#endif

#include "integer.h"    /* 基本整数类型 Basic integer types */
#include "ffconf.h"     /* FatFs配置选项 FatFs configuration options */

#if _FATFS != _FFCONF
#error Wrong configuration file (ffconf.h).
#endif



/* 容量管理的定义 Definitions of volume management */

#if _MULTI_PARTITION        /* 多分区配置 Multiple partition configuration */
typedef  struct  {
    BYTE  pd;     /* 物理驱动号 Physical drive number */
    BYTE  pt;     /* 分区：0：自动检测，1-4：强制分区Partition: 0:Auto detect, 1-4:Forced partition) */
} PARTITION;
extern  PARTITION VolToPart[];    /* 卷分区解析表 Volume - Partition resolution table */
#define LD2PD(vol) (VolToPart[vol].pd)  /* 获取物理驱动号 Get physical drive number */
#define LD2PT(vol) (VolToPart[vol].pt)  /* 获取分区索引 Get partition index */

#else                           /* 单分区配置 Single partition configuration */
#define LD2PD(vol) (BYTE)(vol)  /* 每个逻辑驱动器都和一个物理驱动号对应 Each logical drive is bound to the same physical drive number */
#define LD2PT(vol) 0            /* 始终安装在第一分区或者SFD Always mounts the 1st partition or in SFD */

#endif



/* FatFs API路径名称字符串类型 Type of path name strings on FatFs API */

#if _LFN_UNICODE            /* Unicode string */
#if !_USE_LFN
#error _LFN_UNICODE must be 0 in non-LFN cfg.
#endif
#ifndef _INC_TCHAR
typedef  WCHAR  TCHAR ;
#define _T(x) L ## x
#define _TEXT(x) L ## x
#endif

#else                       /* ANSI / OEM字符串 ANSI/OEM string */
#ifndef _INC_TCHAR
typedef  char  TCHAR ;
#define _T(x) x
#define _TEXT(x) x
#endif

#endif



/* 文件系统对象结构 File system object structure (FATFS) */

typedef  struct  {
    BYTE     fs_type;         /* FAT子类型（0：没安装）FAT sub-type (0:Not mounted) */
    BYTE     drv;               /* 物理驱动器号 Physical drive number */
    BYTE     csize;           /* 每簇的扇区数 Sectors per cluster (1,2,4...128) */
    BYTE     n_fats;          /* 文件配置表（FAT）的副本数 Number of FAT copies (1,2) */
    BYTE     wflag;           /* ？？ win[] dirty flag (1:must be written back) */
    BYTE     fsi_flag;        /* ？？fsinfo dirty flag (1:must be written back) */
    WORD     id;                /* 文件系统安装ID File system mount ID */
    WORD     n_rootdir;   /* 根目录的数量 Number of root directory entries (FAT12/16) */
#if _MAX_SS != 512
    WORD     ssize;           /* 每扇区字节 Bytes per sector (512, 1024, 2048 or 4096) */
#endif
#if _FS_REENTRANT
    _SYNC_t sobj;            /* 同步对象标识符 Identifier of sync object */
#endif
#if !_FS_READONLY
    DWORD    last_clust;  /* 最后分配的簇 Last allocated cluster */
    DWORD    free_clust;  /* 多余的簇数 Number of free clusters */
    DWORD    fsi_sector;  /* fsinfo sector (FAT32) */
#endif
#if _FS_RPATH
    DWORD    cdir;                /* 当前目录的起始簇（0根）Current directory start cluster (0:root) */
#endif
    DWORD    n_fatent;        /* 文件配置表的数 Number of FAT entries (= number of clusters + 2) */
    DWORD    fsize;           /* 扇区的文档配置表 Sectors per FAT */
    DWORD    fatbase;         /* 文档配置表开始的扇区 FAT start sector */
    DWORD    dirbase;         /* 根目录开始的扇区 Root directory start sector (FAT32:Cluster#) */
    DWORD    database;        /* 数据开始的扇区 Data start sector */
    DWORD    winsect;         /* 当前扇区出现在win[] Current sector appearing in the win[] */
    BYTE     win[_MAX_SS];    /* 目录的磁盘访问窗口，文件配置表（和小的CFG数据）Disk access window for Directory, FAT (and Data on tiny cfg) */
} FATFS;



/* 文件对象的结构 File object structure (FIL) */

typedef  struct  {
    FATFS*  fs;              /* 对相关文件系统对象的指针 Pointer to the related file system object */
    WORD     id;                /* 相关的文件系统的文件系统挂载对象ID File system mount ID of the related file system object */
    BYTE     flag;              /* 文件状态标志 File status flags */
    BYTE     pad1;
    DWORD    fptr;              /* 文件的读/写指针 File read/write pointer (0ed on file open) */
    DWORD    fsize;           /* 文件大小 File size */
    DWORD    sclust;          /* 文件数据的起始簇 File data start cluster (0:no data cluster, always 0 when fsize is 0) */
    DWORD    clust;           /* 文件读写指针的当前簇 Current cluster of fpter */
    DWORD    dsect;           /* 文件读写的当前数据扇区 Current data sector of fpter */
#if !_FS_READONLY
    DWORD    dir_sect;        /* 扇区包含的目录条目 Sector containing the directory entry */
    BYTE *   dir_ptr;         /* 在窗口中的目录项的指针 Pointer to the directory entry in the window */
#endif
#if _USE_FASTSEEK
    DWORD *  cltbl;       /* 链簇映射表指针 Pointer to the cluster link map table (null on file open) */
#endif
#if _FS_LOCK
    UINT     lockid;          /* 文件锁定ID File lock ID (index of file semaphore table Files[]) */
#endif
#if !_FS_TINY
    BYTE     buf[_MAX_SS];    /* 文件数据读/写缓冲 File data read/write buffer */
#endif
} FIL;



/* 目录结构对象 Directory object structure (DIR) */

typedef  struct  {
    FATFS*  fs;              /* 主文件系统对象的指针 Pointer to the owner file system object */
    WORD     id;                /* 主文件系统安装ID Owner file system mount ID */
    WORD     index;           /* 当前读写索引数 Current read/write index number */
    DWORD    sclust;          /* 表的起始簇 Table start cluster (0:Root dir) */
    DWORD    clust;           /* 当前簇Current cluster */
    DWORD    sect;              /* 当前扇区 Current sector */
    BYTE *   dir;               /* 当前SFN指针在win[] Pointer to the current SFN entry in the win[] */
    BYTE *   fn;                /* SFN的指针 Pointer to the SFN (in/out) {file[8],ext[3],status[1]} */
#if _USE_LFN
    WCHAR *  lfn;             /* LFN工作缓冲区指针 Pointer to the LFN working buffer */
    WORD     lfn_idx;         /* 最后匹配的LFN索引数 Last matched LFN index number (0xFFFF:No LFN) */
#endif
} DIR;



/* 文件状态结构 File status structure (FILINFO) */

typedef  struct  {
    DWORD    fsize;           /* File size */
    WORD     fdate;           /* Last modified date */
    WORD     ftime;           /* Last modified time */
    BYTE     fattrib;         /* Attribute */
    TCHAR    fname[13];       /* Short file name (8.3 format) */
#if _USE_LFN
    TCHAR *  lfname;          /* Pointer to the LFN buffer */
    UINT     lfsize;          /* Size of LFN buffer in TCHAR */
#endif
} FILINFO;



/* 文件函数的返回代码 File function return code (FRESULT) */

typedef  enum  {
    FR_OK = 0,                   /* (0) 成功 Succeeded */
    FR_DISK_ERR,                 /* (1) 在低电平的磁盘I / O层发生硬件错误 A hard error occurred in the low level disk I/O layer */
    FR_INT_ERR,                  /* (2) 使用错误 Assertion failed */
    FR_NOT_READY,                /* (3) 物理驱动器不工作 The physical drive cannot work */
    FR_NO_FILE,                  /* (4) 找不到文件 Could not find the file */
    FR_NO_PATH,                  /* (5) 找不到路径 Could not find the path */
    FR_INVALID_NAME,         /* (6) 路径名格式无效 The path name format is invalid */
    FR_DENIED,                   /* (7) 访问拒绝由于禁止访问或者目录满 Access denied due to prohibited access or directory full */
    FR_EXIST,                        /* (8) 拒绝访问由于禁止访问 Access denied due to prohibited access */
    FR_INVALID_OBJECT,   /* (9) 文件/目录对象是无效的 The file/directory object is invalid */
    FR_WRITE_PROTECTED,  /* (10) 物理驱动器写保护 The physical drive is write protected */
    FR_INVALID_DRIVE,        /* (11) 逻辑驱动器号无效 The logical drive number is invalid */
    FR_NOT_ENABLED,          /* (12) 卷没有工作空间 The volume has no work area */
    FR_NO_FILESYSTEM,        /* (13) 没有可用的卷 There is no valid FAT volume */
    FR_MKFS_ABORTED,         /* (14) f_mkfs()由于任何参数误差中止 The f_mkfs() aborted due to any parameter error */
    FR_TIMEOUT,                  /* (15) 不能获得授权在规定的时间内访问卷 Could not get a grant to access the volume within defined period */
    FR_LOCKED,                   /* (16) 操作被拒绝根据文件共享政策 The operation is rejected according to the file sharing policy */
    FR_NOT_ENOUGH_CORE,  /* (17) LFN无法分配工作缓冲区 LFN working buffer could not be allocated */
    FR_TOO_MANY_OPEN_FILES,  /* (18) 打开文件数大于FS_SHARE Number of open files > _FS_SHARE */
    FR_INVALID_PARAMETER         /* (19) 给定的参数无效 Given parameter is invalid */
} FRESULT;



/*--------------------------------------------------------------*/
/* FatFs模块应用程序接口 FatFs module application interface                           */

FRESULT f_mount ( BYTE , FATFS*);                                      /* 安装/卸载一个逻辑驱动器 Mount/Unmount a logical drive */
FRESULT f_open (FIL*,  const  TCHAR *,  BYTE );               /* 打开或创建一个文件 Open or create a file */
FRESULT f_read (FIL*,  void *,  UINT ,  UINT *);               /* 从文件中读取数据 Read data from a file */
FRESULT f_lseek (FIL*,  DWORD );                                       /* 改变一个文件对象文件指针 Move file pointer of a file object */
FRESULT f_close (FIL*);                                                      /* 关闭打开的文件对象 Close an open file object */
FRESULT f_opendir (DIR*,  const  TCHAR *);                      /* 打开一个已经存在的目录 Open an existing directory */
FRESULT f_readdir (DIR*, FILINFO*);                              /* 读一个目录项 Read a directory item */
FRESULT f_stat ( const  TCHAR *, FILINFO*);                     /* 获取文件状态 Get file status */
FRESULT f_write (FIL*,  const  void *,  UINT ,  UINT *);    /* 写数据到一个文件 Write data to a file */
FRESULT f_getfree ( const  TCHAR *,  DWORD *, FATFS**); /* 获取驱动器上的空闲簇数 Get number of free clusters on the drive */
FRESULT f_truncate (FIL*);                                               /* 截断文件 Truncate file */
FRESULT f_sync (FIL*);                                                       /* 刷新正写入文件的缓存数据Flush cached data of a writing file */
FRESULT f_unlink ( const  TCHAR *);                                     /* 删除现有文件或目录 Delete an existing file or directory */
FRESULT f_mkdir ( const  TCHAR *);                                      /* 创建新目录 Create a new directory */
FRESULT f_chmod ( const  TCHAR *,  BYTE ,  BYTE );              /* 改变文件/目录属性 Change attribute of the file/dir */
FRESULT f_utime ( const  TCHAR *,  const  FILINFO*);      /* 改变文件/目录的时间戳 Change times-tamp of the file/dir */
FRESULT f_rename ( const  TCHAR *,  const  TCHAR *);       /* 重命名/移动文件或目录 Rename/Move a file or directory */
FRESULT f_chdrive ( BYTE );                                                    /* 改变当前的驱动器 Change current drive */
FRESULT f_chdir ( const  TCHAR *);                                      /* 改变当前目录 Change current directory */
FRESULT f_getcwd ( TCHAR *,  UINT );                                     /* 获取当前目录 Get current directory */
FRESULT f_forward (FIL*,  UINT (*)( const  BYTE *, UINT ),  UINT ,  UINT *);    /* 向流发送数据 Forward data to the stream */
FRESULT f_mkfs ( BYTE ,  BYTE ,  UINT );                               /* 创建一个驱动器上的文件系统 Create a file system on the drive */
FRESULT f_fdisk ( BYTE ,  const  DWORD [],  void *);            /* 将一个物理驱动器为若干分区 Divide a physical drive into some partitions */
int  f_putc ( TCHAR , FIL*);                                                    /* 放一个字符在文件中 Put a character to the file */
int  f_puts ( const  TCHAR *, FIL*);                                     /* 放一组字符串在文件中 Put a string to the file */
int  f_printf (FIL*,  const  TCHAR *, ...);                      /* 将格式化后的字符串的文件 Put a formatted string to the file */
TCHAR * f_gets ( TCHAR *,  int , FIL*);                               /* 从文件中获得字符串 Get a string from the file */

#define f_eof(fp) (((fp)->fptr == (fp)->fsize) ? 1 : 0)
#define f_error(fp) (((fp)->flag & FA__ERROR) ? 1 : 0)
#define f_tell(fp) ((fp)->fptr)
#define f_size(fp) ((fp)->fsize)

#ifndef EOF
#define EOF (-1)
#endif




/*--------------------------------------------------------------*/
/* 额外的用户定义函数 Additional user defined functions        */

/* RTC函数 RTC function */
#if !_FS_READONLY
DWORD  get_fattime ( void );
#endif

/* Union支持函数 Unicode support functions */
#if _USE_LFN                                        /* Unicode - OEM码转换 Unicode - OEM code conversion */
WCHAR  ff_convert ( WCHAR ,  UINT );  /* OEM-Unicode双向转换 OEM-Unicode bidirectional conversion */
WCHAR  ff_wtoupper ( WCHAR );           /* Unicode大写转换 Unicode upper-case conversion */
#if _USE_LFN == 3                               /* 内存函数 Memory functions */
void * ff_memalloc ( UINT );                /* 分配内存块 Allocate memory block */
void  ff_memfree ( void *);                 /* 空闲内存块 Free memory block */
#endif
#endif

/* 同步函数 Sync functions */
#if _FS_REENTRANT
int  ff_cre_syncobj ( BYTE , _SYNC_t*); /* 创建一个同步对象 Create a sync object */
int  ff_req_grant (_SYNC_t);                  /* 锁同步对象 Lock sync object */
void  ff_rel_grant (_SYNC_t);                 /* 解锁同步对象 Unlock sync object */
int  ff_del_syncobj (_SYNC_t);                /* D删除同步对象 elete a sync object */
#endif




/*--------------------------------------------------------------*/
/* 标志和偏移地址 Flags and offset address                     */


/* 文件访问控制和文件状态标志 File access control and file status flags (FIL.flag) */

#define FA_READ             0x01
#define FA_OPEN_EXISTING    0x00
#define FA__ERROR           0x80

#if !_FS_READONLY
#define FA_WRITE            0x02
#define FA_CREATE_NEW       0x04
#define FA_CREATE_ALWAYS    0x08
#define FA_OPEN_ALWAYS      0x10
#define FA__WRITTEN         0x20
#define FA__DIRTY           0x40
#endif


/* FAT副类型 FAT sub type (FATFS.fs_type) */

#define FS_FAT12    1
#define FS_FAT16    2
#define FS_FAT32    3


/* 目录项的文件属性字节 File attribute bits for directory entry */

#define AM_RDO  0x01    /* 只读 Read only */
#define AM_HID  0x02    /* 隐藏 Hidden */
#define AM_SYS  0x04    /* 系统 System */
#define AM_VOL  0x08    /* 卷标 Volume label */
#define AM_LFN  0x0F    /* LFN项 LFN entry */
#define AM_DIR  0x10    /* 目录Directory */
#define AM_ARC  0x20    /* 存档 Archive */
#define AM_MASK 0x3F    /* 掩码位 Mask of defined bits */


/* 快速查找功能 Fast seek feature */
#define CREATE_LINKMAP  0xFFFFFFFF



/*--------------------------------*/
/* 多字节字访问宏 Multi-byte word access macros  */

#if _WORD_ACCESS == 1   /* FAT结构使字访问 Enable word access to the FAT structure */
#define LD_WORD(ptr)        (WORD)(*(WORD*)(BYTE*)(ptr))
#define LD_DWORD(ptr)       (DWORD)(*(DWORD*)(BYTE*)(ptr))
#define ST_WORD(ptr,val)    *(WORD*)(BYTE*)(ptr)=(WORD)(val)
#define ST_DWORD(ptr,val)   *(DWORD*)(BYTE*)(ptr)=(DWORD)(val)
#else                                   /* FAT结构用位访问 Use byte-by-byte access to the FAT structure */
#define LD_WORD(ptr)        (WORD)(((WORD)*((BYTE*)(ptr)+1)<<8)|(WORD)*(BYTE*)(ptr))
#define LD_DWORD(ptr)       (DWORD)(((DWORD)*((BYTE*)(ptr)+3)<<24)|((DWORD)*((BYTE*)(ptr)+2)<<16)|((WORD)*((BYTE*)(ptr)+1)<<8)|*(BYTE*)(ptr))
#define ST_WORD(ptr,val)    *(BYTE*)(ptr)=(BYTE)(val); *((BYTE*)(ptr)+1)=(BYTE)((WORD)(val)>>8)
#define ST_DWORD(ptr,val)   *(BYTE*)(ptr)=(BYTE)(val); *((BYTE*)(ptr)+1)=(BYTE)((WORD)(val)>>8); *((BYTE*)(ptr)+2)=(BYTE)((DWORD)(val)>>16); *((BYTE*)(ptr)+3)=(BYTE)((DWORD)(val)>>24)
#endif

#ifdef __cplusplus
}
#endif

#endif /* _FATFS */