git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-Plus-FAT/include/ff_file.h

   1 /*\r
   2  * FreeRTOS+FAT build 191128 - Note:  FreeRTOS+FAT is still in the lab!\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  * Authors include James Walmsley, Hein Tibosch and Richard Barry\r
   5  *\r
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   7  * this software and associated documentation files (the "Software"), to deal in\r
   8  * the Software without restriction, including without limitation the rights to\r
   9  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
  10  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  11  * subject to the following conditions:\r
  12  *\r
  13  * The above copyright notice and this permission notice shall be included in all\r
  14  * copies or substantial portions of the Software.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * https://www.FreeRTOS.org\r
  24  *\r
  25  */\r
  26 \r
  27 /**\r
  28  *      @file           ff_file.h\r
  29  *      @ingroup        FILEIO\r
  30  **/\r
  31 #ifndef _FF_FILE_H_\r
  32 #define _FF_FILE_H_\r
  33 \r
  34 #ifndef PLUS_FAT_H\r
  35         #error this header will be included from "plusfat.h"\r
  36 #endif\r
  37 \r
  38 #define FF_SEEK_SET     0\r
  39 #define FF_SEEK_CUR     1\r
  40 #define FF_SEEK_END     2\r
  41 \r
  42 #if( ffconfigOPTIMISE_UNALIGNED_ACCESS != 0 )\r
  43         #define FF_BUFSTATE_INVALID                             0x00    /* Data in file handle buffer is invalid. */\r
  44         #define FF_BUFSTATE_VALID                               0x01    /* Valid data in pBuf (Something has been read into it). */\r
  45         #define FF_BUFSTATE_WRITTEN                             0x02    /* Data was written into pBuf, this must be saved when leaving sector. */\r
  46 #endif\r
  47 \r
  48 #if( ffconfigDEV_SUPPORT != 0 )\r
  49 struct xDEV_NODE\r
  50 {\r
  51         uint8_t\r
  52                 ucIsDevice;\r
  53 };\r
  54 #endif\r
  55 \r
  56 typedef struct _FF_FILE\r
  57 {\r
  58         FF_IOManager_t *pxIOManager;                    /* Ioman Pointer! */\r
  59         uint32_t ulFileSize;                    /* File's Size. */\r
  60         uint32_t ulObjectCluster;               /* File's Start Cluster. */\r
  61         uint32_t ulChainLength;                 /* Total Length of the File's cluster chain. */\r
  62         uint32_t ulCurrentCluster;              /* Prevents FAT Thrashing. */\r
  63         uint32_t ulAddrCurrentCluster;  /* Address of the current cluster. */\r
  64         uint32_t ulEndOfChain;                  /* Address of the last cluster in the chain. */\r
  65         uint32_t ulFilePointer;                 /* Current Position Pointer. */\r
  66         uint32_t ulDirCluster;                  /* Cluster Number that the Dirent is in. */\r
  67         uint32_t ulValidFlags;                  /* Handle validation flags. */\r
  68 \r
  69 #if( ffconfigOPTIMISE_UNALIGNED_ACCESS != 0 )\r
  70         uint8_t *pucBuffer;                             /* A buffer for providing fast unaligned access. */\r
  71         uint8_t ucState;                                /* State information about the buffer. */\r
  72 #endif\r
  73         uint8_t ucMode;                                 /* Mode that File Was opened in. */\r
  74         uint16_t usDirEntry;                    /* Dirent Entry Number describing this file. */\r
  75 \r
  76 #if( ffconfigDEV_SUPPORT != 0 )\r
  77         struct SFileCache *pxDevNode;\r
  78 #endif\r
  79         struct _FF_FILE *pxNext;                /* Pointer to the next file object in the linked list. */\r
  80 } FF_FILE;\r
  81 \r
  82 #define FF_VALID_FLAG_INVALID   0x00000001\r
  83 #define FF_VALID_FLAG_DELETED   0x00000002\r
  84 \r
  85 /*---------- PROTOTYPES */\r
  86 /* PUBLIC (Interfaces): */\r
  87 \r
  88 #if( ffconfigUNICODE_UTF16_SUPPORT != 0 )\r
  89         FF_FILE *FF_Open( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *path, uint8_t Mode, FF_Error_t *pError );\r
  90         BaseType_t FF_isDirEmpty( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *Path );\r
  91         FF_Error_t FF_RmFile( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *path );\r
  92         FF_Error_t FF_RmDir( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *path );\r
  93         FF_Error_t FF_Move( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *szSourceFile, const FF_T_WCHAR *szDestinationFile,\r
  94                 BaseType_t bDeleteIfExists );\r
  95 #else   /* ffconfigUNICODE_UTF16_SUPPORT */\r
  96         FF_FILE *FF_Open( FF_IOManager_t *pxIOManager, const char *path, uint8_t Mode, FF_Error_t *pError );\r
  97         BaseType_t FF_isDirEmpty( FF_IOManager_t *pxIOManager, const char *Path );\r
  98         FF_Error_t FF_RmFile( FF_IOManager_t *pxIOManager, const char *path );\r
  99         FF_Error_t FF_RmDir( FF_IOManager_t *pxIOManager, const char *path );\r
 100         FF_Error_t FF_Move( FF_IOManager_t *pxIOManager, const char *szSourceFile, const char *szDestinationFile,\r
 101                 BaseType_t bDeleteIfExists );\r
 102 #endif  /* ffconfigUNICODE_UTF16_SUPPORT */\r
 103 \r
 104 #if( ffconfigTIME_SUPPORT != 0 )\r
 105         enum {\r
 106                 ETimeCreate = 1,\r
 107                 ETimeMod = 2,\r
 108                 ETimeAccess = 4,\r
 109                 ETimeAll = 7\r
 110         };\r
 111         FF_Error_t FF_SetFileTime( FF_FILE *pFile, FF_SystemTime_t *pxTime, UBaseType_t uxWhat );\r
 112         #if( ffconfigUNICODE_UTF16_SUPPORT != 0 )\r
 113                 FF_Error_t FF_SetTime( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *path, FF_SystemTime_t *pxTime, UBaseType_t uxWhat );\r
 114         #else\r
 115                 FF_Error_t FF_SetTime( FF_IOManager_t *pxIOManager, const char *path, FF_SystemTime_t *pxTime, UBaseType_t uxWhat );\r
 116         #endif  /* ffconfigUNICODE_UTF16_SUPPORT */\r
 117 #endif  /* ffconfigTIME_SUPPORT */\r
 118 \r
 119 #if( ffconfigUNICODE_UTF16_SUPPORT != 0 )\r
 120         FF_Error_t FF_SetPerm( FF_IOManager_t *pxIOManager, const FF_T_WCHAR *path, UBaseType_t aPerm );\r
 121 #else\r
 122         FF_Error_t FF_SetPerm( FF_IOManager_t *pxIOManager, const char *path, UBaseType_t aPerm );\r
 123 #endif\r
 124 \r
 125 FF_Error_t FF_SetEof( FF_FILE *pFile );\r
 126 \r
 127 FF_Error_t FF_Close( FF_FILE *pFile );\r
 128 int32_t FF_GetC( FF_FILE *pFile );\r
 129 int32_t FF_GetLine( FF_FILE *pFile, char *szLine, uint32_t ulLimit );\r
 130 int32_t FF_Read( FF_FILE *pFile, uint32_t ElementSize, uint32_t Count, uint8_t *buffer );\r
 131 int32_t FF_Write( FF_FILE *pFile, uint32_t ElementSize, uint32_t Count, uint8_t *buffer );\r
 132 BaseType_t FF_isEOF( FF_FILE *pFile );\r
 133 int32_t FF_BytesLeft( FF_FILE *pFile ); /* Returns # of bytes left to read. */\r
 134 \r
 135 /* FF_FileSize is an earlier version of FF_GetFileSize(). For files\r
 136 equal to or larger than 2GB, the return value is negative.\r
 137 Function is deprecated. Please use FF_GetFileSize(). */\r
 138 int32_t FF_FileSize( FF_FILE *pFile ); /* Returns # of bytes in a file. */\r
 139 \r
 140 /* Use the following function in case files may get larger than 2  GB.\r
 141 Writes the size of a file to the parameter.\r
 142 Returns 0 or error code. */\r
 143 FF_Error_t FF_GetFileSize( FF_FILE *pFile, uint32_t *pulSize );\r
 144 \r
 145 FF_Error_t FF_Seek( FF_FILE *pFile, int32_t Offset, BaseType_t xOrigin  );\r
 146 int32_t FF_PutC( FF_FILE *pFile, uint8_t Value );\r
 147 \r
 148 static portINLINE uint32_t FF_Tell( FF_FILE *pFile )\r
 149 {\r
 150         return pFile ? pFile->ulFilePointer : 0;\r
 151 }\r
 152 \r
 153 uint8_t FF_GetModeBits( const char *Mode );\r
 154 \r
 155 FF_Error_t FF_CheckValid( FF_FILE *pFile );   /* Check if pFile is a valid FF_FILE pointer. */\r
 156 \r
 157 #if( ffconfigREMOVABLE_MEDIA != 0 )\r
 158         int32_t FF_Invalidate( FF_IOManager_t *pxIOManager ); /* Invalidate all handles belonging to pxIOManager. */\r
 159 #endif\r
 160 \r
 161 /* Private : */\r
 162 \r
 163 #endif\r