| Line No. | Rev | Author | Line |
|---|---|---|---|
| 1 | 32 | kaklik | /****************************************************************************** |
| 2 | * |
||
| 3 | * Microchip Memory Disk Drive File System |
||
| 4 | * |
||
| 5 | ****************************************************************************** |
||
| 6 | * FileName: FSIO.h |
||
| 7 | * Dependencies: GenericTypeDefs.h |
||
| 8 | * FSconfig.h |
||
| 9 | * FSDefs.h |
||
| 10 | * stddef.h |
||
| 11 | * Processor: PIC18/PIC24/dsPIC30/dsPIC33/PIC32 |
||
| 12 | * Compiler: C18/C30/C32 |
||
| 13 | * Company: Microchip Technology, Inc. |
||
| 14 | * |
||
| 15 | * Software License Agreement |
||
| 16 | * |
||
| 17 | * The software supplied herewith by Microchip Technology Incorporated |
||
| 18 | * (the Company) for its PICmicro® Microcontroller is intended and |
||
| 19 | * supplied to you, the Companys customer, for use solely and |
||
| 20 | * exclusively on Microchip PICmicro Microcontroller products. The |
||
| 21 | * software is owned by the Company and/or its supplier, and is |
||
| 22 | * protected under applicable copyright laws. All rights are reserved. |
||
| 23 | * Any use in violation of the foregoing restrictions may subject the |
||
| 24 | * user to criminal sanctions under applicable laws, as well as to |
||
| 25 | * civil liability for the breach of the terms and conditions of this |
||
| 26 | * license. |
||
| 27 | * |
||
| 28 | * THIS SOFTWARE IS PROVIDED IN AN AS IS CONDITION. NO WARRANTIES, |
||
| 29 | * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED |
||
| 30 | * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A |
||
| 31 | * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, |
||
| 32 | * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR |
||
| 33 | * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. |
||
| 34 | * |
||
| 35 | *****************************************************************************/ |
||
| 36 | //DOM-IGNORE-BEGIN |
||
| 37 | /******************************************************************** |
||
| 38 | Change History: |
||
| 39 | Rev Description |
||
| 40 | ---- ----------------------- |
||
| 41 | 1.2.4 - 1.2.6 No major changes |
||
| 42 | ********************************************************************/ |
||
| 43 | //DOM-IGNORE-END |
||
| 44 | |||
| 45 | #ifndef FS_DOT_H |
||
| 46 | #define FS_DOT_H |
||
| 47 | |||
| 48 | #include "GenericTypeDefs.h" |
||
| 49 | #include "FSconfig.h" |
||
| 50 | #include "MDD File System\FSDefs.h" |
||
| 51 | #include "stddef.h" |
||
| 52 | |||
| 53 | #ifdef USE_SD_INTERFACE_WITH_SPI |
||
| 54 | #include "MDD File System\SD-SPI.h" |
||
| 55 | #endif |
||
| 56 | #ifdef USE_CF_INTERFACE_WITH_PMP |
||
| 57 | #include "MDD File System\CF-PMP.h" |
||
| 58 | #endif |
||
| 59 | #ifdef USE_MANUAL_CF_INTERFACE |
||
| 60 | #include "MDD File System\CF- Bit transaction.h" |
||
| 61 | #endif |
||
| 62 | #ifdef USE_USB_INTERFACE |
||
| 63 | #include "USB\usb_host_msd_scsi.h" |
||
| 64 | #endif |
||
| 65 | #ifdef USE_INTERNAL_FLASH |
||
| 66 | #include "MDD File System\Internal Flash.h" |
||
| 67 | #endif |
||
| 68 | |||
| 69 | |||
| 70 | /*******************************************************************/ |
||
| 71 | /* Strunctures and defines */ |
||
| 72 | /*******************************************************************/ |
||
| 73 | |||
| 74 | #ifndef FALSE |
||
| 75 | // Summary: False value |
||
| 76 | // Description: This macro will indicate that a condition is false. |
||
| 77 | #define FALSE 0 |
||
| 78 | #endif |
||
| 79 | #ifndef TRUE |
||
| 80 | // Summary: True value |
||
| 81 | // Description: This macro will indicate that a condition is true. |
||
| 82 | #define TRUE !FALSE // True value |
||
| 83 | #endif |
||
| 84 | |||
| 85 | |||
| 86 | |||
| 87 | |||
| 88 | #ifndef SEEK_SET |
||
| 89 | // Summary: Macro for the FSfseek SEEK_SET base location. |
||
| 90 | // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed |
||
| 91 | // relative to the beginning of the file. |
||
| 92 | #define SEEK_SET 0 |
||
| 93 | |||
| 94 | #endif |
||
| 95 | #ifndef SEEK_CUR |
||
| 96 | |||
| 97 | // Summary: Macro for the FSfseek SEEK_CUR base location. |
||
| 98 | // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed |
||
| 99 | // relative to the current location of the file |
||
| 100 | #define SEEK_CUR 1 |
||
| 101 | |||
| 102 | #endif |
||
| 103 | #ifndef SEEK_END |
||
| 104 | |||
| 105 | // Summary: Macro for the FSfseek SEEK_END base location |
||
| 106 | // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed |
||
| 107 | // relative to the end of the file. For this macro, the offset value will be subtracted from |
||
| 108 | // the end location of the file by default. |
||
| 109 | #define SEEK_END 2 |
||
| 110 | |||
| 111 | #endif |
||
| 112 | |||
| 113 | |||
| 114 | |||
| 115 | |||
| 116 | // Summary: Macro for the FSfopen FS_APPEND mode |
||
| 117 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will |
||
| 118 | // be created if it doesn't exist. If it does exist, it's file information will be loaded and the |
||
| 119 | // current location in the file will be set to the end. The user will then be able to write to the file. |
||
| 120 | #define FS_APPEND "a" |
||
| 121 | #define APPEND "a" //deprecated |
||
| 122 | |||
| 123 | // Summary: Macro for the FSfopen FS_WRITE mode |
||
| 124 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will |
||
| 125 | // be created if it doesn't exist. If it does exist, it will be erased and replaced by an empty file |
||
| 126 | // of the same name. The user will then be able to write to the file. |
||
| 127 | #define FS_WRITE "w" |
||
| 128 | #define WRITE "w" //deprecated |
||
| 129 | |||
| 130 | // Summary: Macro for the FSfopen FS_READ mode |
||
| 131 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file information for the |
||
| 132 | // specified file will be loaded. If the file does not exist, the FSfopen function will fail. The user |
||
| 133 | // will then be able to read from the file. |
||
| 134 | #define FS_READ "r" |
||
| 135 | #if defined(__32MX795F512L__) |
||
| 136 | #warning FSfopen must use "r" and not READ as input on this device |
||
| 137 | #else |
||
| 138 | #define READ "r" //deprecated |
||
| 139 | #endif |
||
| 140 | |||
| 141 | // Summary: Macro for the FSfopen FS_APPEND+ mode |
||
| 142 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will |
||
| 143 | // be created if it doesn't exist. If it does exist, it's file information will be loaded and the |
||
| 144 | // current location in the file will be set to the end. The user will then be able to write to the file |
||
| 145 | // or read from the file. |
||
| 146 | #define FS_APPENDPLUS "a+" |
||
| 147 | #define APPENDPLUS "a+" //deprecated |
||
| 148 | |||
| 149 | // Summary: Macro for the FSfopen FS_WRITE+ mode |
||
| 150 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will |
||
| 151 | // be created if it doesn't exist. If it does exist, it will be erased and replaced by an empty file |
||
| 152 | // of the same name. The user will then be able to write to the file or read from the file. |
||
| 153 | #define FS_WRITEPLUS "w+" |
||
| 154 | #define WRITEPLUS "w+" //deprecated |
||
| 155 | |||
| 156 | // Summary: Macro for the FSfopen FS_READ+ mode |
||
| 157 | // Description: If this macro is specified as the mode argument in a call of FSfopen, the file information for the |
||
| 158 | // specified file will be loaded. If the file does not exist, the FSfopen function will fail. The user |
||
| 159 | // will then be able to read from the file or write to the file. |
||
| 160 | #define FS_READPLUS "r+" |
||
| 161 | #define READPLUS "r+" //deprecated |
||
| 162 | |||
| 163 | |||
| 164 | |||
| 165 | #ifndef intmax_t |
||
| 166 | #ifdef __PIC24F__ |
||
| 167 | // Summary: A data type indicating the maximum integer size in an architecture |
||
| 168 | // Description: The intmax_t data type refers to the maximum-sized data type on any given architecture. This |
||
| 169 | // data type can be specified as a format specifier size specification for the FSfprintf function. |
||
| 170 | #define intmax_t long long |
||
| 171 | #elif defined __PIC24H__ |
||
| 172 | #define intmax_t long long |
||
| 173 | #elif defined __dsPIC30F__ |
||
| 174 | #define intmax_t long long |
||
| 175 | #elif defined __dsPIC33F__ |
||
| 176 | #define intmax_t long long |
||
| 177 | #endif |
||
| 178 | #endif |
||
| 179 | |||
| 180 | |||
| 181 | |||
| 182 | // Summary: Indicates flag conditions for a file object |
||
| 183 | // Description: The FILEFLAGS structure is used to indicate conditions in a file. It contains three flags: 'write' indicates |
||
| 184 | // that the file was opened in a mode that allows writes, 'read' indicates that the file was opened in a mode |
||
| 185 | // that allows reads, and 'FileWriteEOF' indicates that additional data that is written to the file will increase |
||
| 186 | // the file size. |
||
| 187 | typedef struct |
||
| 188 | { |
||
| 189 | unsigned write :1; // Indicates a file was opened in a mode that allows writes |
||
| 190 | unsigned read :1; // Indicates a file was opened in a mode that allows reads |
||
| 191 | unsigned FileWriteEOF :1; // Indicates the current position in a file is at the end of the file |
||
| 192 | }FILEFLAGS; |
||
| 193 | |||
| 194 | |||
| 195 | |||
| 196 | // Summary: Indicates how to search for file entries in the FILEfind function |
||
| 197 | // Description: The values in the SEARCH_TYPE enumeration are used internally by the library to indicate how the FILEfind function |
||
| 198 | // how to perform a search. The 'LOOK_FOR_EMPTY_ENTRY' value indicates that FILEfind should search for an empty file entry. |
||
| 199 | // The 'LOOK_FOR_MATCHING_ENTRY' value indicates that FILEfind should search for an entry that matches the FSFILE object |
||
| 200 | // that was passed into the FILEfind function. |
||
| 201 | typedef enum{ |
||
| 202 | LOOK_FOR_EMPTY_ENTRY = 0, |
||
| 203 | LOOK_FOR_MATCHING_ENTRY |
||
| 204 | } SEARCH_TYPE; |
||
| 205 | |||
| 206 | |||
| 207 | |||
| 208 | // Summary: Macro indicating the length of a 8.3 file name |
||
| 209 | // Description: The TOTAL_FILE_SIZE macro indicates the maximum number of characters in an 8.3 file name. This value includes |
||
| 210 | // 8 characters for the name, three for the extentsion, and 1 for the radix ('.') |
||
| 211 | #define TOTAL_FILE_SIZE 8+3+1 |
||
| 212 | |||
| 213 | // Summary: A mask that indicates the limit of directory entries in a sector |
||
| 214 | // Description: The MASK_MAX_FILE_ENTRY_LIMIT_BITS is used to indicate to the Cache_File_Entry function that a new sector needs to |
||
| 215 | // be loaded. |
||
| 216 | #define MASK_MAX_FILE_ENTRY_LIMIT_BITS 0x0f |
||
| 217 | |||
| 218 | // Summary: Value used for shift operations to calculate the sector offset in a directory |
||
| 219 | // Description: The VALUE_BASED_ON_ENTRIES_PER_CLUSTER macro is used to calculate sector offsets for directories. The position of the |
||
| 220 | // entry is shifted by 4 bits (divided by 16, since there are 16 entries in a sector) to calculate how many sectors a |
||
| 221 | // specified entry is offset from the beginning of the directory. |
||
| 222 | #define VALUE_BASED_ON_ENTRIES_PER_CLUSTER 4 |
||
| 223 | |||
| 224 | // Summary: A value that will indicate that a dotdot directory entry points to the root. |
||
| 225 | // Description: The VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT macro is used as an absolute address when writing information to a dotdot entry |
||
| 226 | // in a newly created directory. If a dotdot entry points to the root directory, it's cluster value must be set to 0, |
||
| 227 | // regardless of the actual cluster number of the root directory. |
||
| 228 | #define VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT 0 |
||
| 229 | |||
| 230 | // Summary: MAcro indicating the length of an 8.3 file name in a directory entry |
||
| 231 | // Description: The FILE_NAME_SIZE macro indicates the number of characters that an 8.3 file name will take up when packed in |
||
| 232 | // a directory entry. This value includes 8 characters for the name and 3 for the extension. Note that the radix is not |
||
| 233 | // stored in the directory entry. |
||
| 234 | #define FILE_NAME_SIZE 11 |
||
| 235 | |||
| 236 | |||
| 237 | |||
| 238 | // Summary: Contains file information and is used to indicate which file to access. |
||
| 239 | // Description: The FSFILE structure is used to hold file information for an open file as it's being modified or accessed. A pointer to |
||
| 240 | // an open file's FSFILE structure will be passeed to any library function that will modify that file. |
||
| 241 | typedef struct |
||
| 242 | { |
||
| 243 | DISK * dsk; // Pointer to a DISK structure |
||
| 244 | DWORD cluster; // The first cluster of the file |
||
| 245 | DWORD ccls; // The current cluster of the file |
||
| 246 | WORD sec; // The current sector in the current cluster of the file |
||
| 247 | WORD pos; // The position in the current sector |
||
| 248 | DWORD seek; // The absolute position in the file |
||
| 249 | DWORD size; // The size of the file |
||
| 250 | FILEFLAGS flags; // A structure containing file flags |
||
| 251 | WORD time; // The file's last update time |
||
| 252 | WORD date; // The file's last update date |
||
| 253 | char name[FILE_NAME_SIZE]; // The name of the file |
||
| 254 | WORD entry; // The position of the file's directory entry in it's directory |
||
| 255 | WORD chk; // File structure checksum |
||
| 256 | WORD attributes; // The file attributes |
||
| 257 | DWORD dirclus; // The base cluster of the file's directory |
||
| 258 | DWORD dirccls; // The current cluster of the file's directory |
||
| 259 | } FSFILE; |
||
| 260 | |||
| 261 | /* Summary: Possible results of the FSGetDiskProperties() function. |
||
| 262 | ** Description: See the FSGetDiskProperties() function for more information. |
||
| 263 | */ |
||
| 264 | typedef enum |
||
| 265 | { |
||
| 266 | FS_GET_PROPERTIES_NO_ERRORS = 0, |
||
| 267 | FS_GET_PROPERTIES_DISK_NOT_MOUNTED, |
||
| 268 | FS_GET_PROPERTIES_CLUSTER_FAILURE, |
||
| 269 | FS_GET_PROPERTIES_STILL_WORKING = 0xFF |
||
| 270 | } FS_DISK_ERRORS; |
||
| 271 | |||
| 272 | /* Summary: Contains the disk search information, intermediate values, and results |
||
| 273 | ** Description: This structure is used in conjunction with the FSGetDiskProperties() |
||
| 274 | ** function. See that function for more information about the usage. |
||
| 275 | */ |
||
| 276 | typedef struct |
||
| 277 | { |
||
| 278 | DISK * disk; /* pointer to the disk we are searching */ |
||
| 279 | BOOL new_request; /* is this a new request or a continued request */ |
||
| 280 | FS_DISK_ERRORS properties_status; /* status of the last call of the function */ |
||
| 281 | |||
| 282 | struct |
||
| 283 | { |
||
| 284 | BYTE disk_format; /* disk format: FAT12, FAT16, FAT32 */ |
||
| 285 | WORD sector_size; /* sector size of the drive */ |
||
| 286 | BYTE sectors_per_cluster; /* number of sectors per cluster */ |
||
| 287 | DWORD total_clusters; /* the number of total clusters on the drive */ |
||
| 288 | DWORD free_clusters; /* the number of free (unused) clusters on drive */ |
||
| 289 | } results; /* the results of the current search */ |
||
| 290 | |||
| 291 | struct |
||
| 292 | { |
||
| 293 | DWORD c; |
||
| 294 | DWORD curcls; |
||
| 295 | DWORD EndClusterLimit; |
||
| 296 | DWORD ClusterFailValue; |
||
| 297 | } private; /* intermediate values used to continue searches. This |
||
| 298 | member should be used only by the FSGetDiskProperties() |
||
| 299 | function */ |
||
| 300 | |||
| 301 | } FS_DISK_PROPERTIES; |
||
| 302 | |||
| 303 | // Summary: A structure used for searching for files on a device. |
||
| 304 | // Description: The SearchRec structure is used when searching for file on a device. It contains parameters that will be loaded with |
||
| 305 | // file information when a file is found. It also contains the parameters that the user searched for, allowing further |
||
| 306 | // searches to be perfomed in the same directory for additional files that meet the specified criteria. |
||
| 307 | typedef struct |
||
| 308 | { |
||
| 309 | char filename[FILE_NAME_SIZE + 2]; // The name of the file that has been found |
||
| 310 | unsigned char attributes; // The attributes of the file that has been found |
||
| 311 | unsigned long filesize; // The size of the file that has been found |
||
| 312 | unsigned long timestamp; // The last modified time of the file that has been found (create time for directories) |
||
| 313 | |||
| 314 | unsigned int entry; // The directory entry of the last file found that matches the specified attributes. (Internal use only) |
||
| 315 | char searchname[FILE_NAME_SIZE + 2]; // The name specified when the user began the search. (Internal use only) |
||
| 316 | unsigned char searchattr; // The attributes specified when the user began the search. (Internal use only) |
||
| 317 | unsigned long cwdclus; // The directory that this search was performed in. (Internal use only) |
||
| 318 | unsigned char initialized; // Check to determine if the structure was initialized by FindFirst (Internal use only) |
||
| 319 | } SearchRec; |
||
| 320 | |||
| 321 | |||
| 322 | /*************************************************************************** |
||
| 323 | * Prototypes * |
||
| 324 | ***************************************************************************/ |
||
| 325 | |||
| 326 | |||
| 327 | |||
| 328 | |||
| 329 | /************************************************************************* |
||
| 330 | Function: |
||
| 331 | int FSInit(void) |
||
| 332 | Summary: |
||
| 333 | Function to initialize the device. |
||
| 334 | Conditions: |
||
| 335 | The physical device should be connected to the microcontroller. |
||
| 336 | Input: |
||
| 337 | None |
||
| 338 | Return Values: |
||
| 339 | TRUE - Initialization successful |
||
| 340 | FALSE - Initialization unsuccessful |
||
| 341 | Side Effects: |
||
| 342 | The FSerrno variable will be changed. |
||
| 343 | Description: |
||
| 344 | Initializes the static or dynamic memory slots for holding file |
||
| 345 | structures. Initializes the device with the DISKmount function. Loads |
||
| 346 | MBR and boot sector information. Initializes the current working |
||
| 347 | directory to the root directory for the device if directory support |
||
| 348 | is enabled. |
||
| 349 | Remarks: |
||
| 350 | None |
||
| 351 | *************************************************************************/ |
||
| 352 | |||
| 353 | int FSInit(void); |
||
| 354 | |||
| 355 | |||
| 356 | /********************************************************************* |
||
| 357 | Function: |
||
| 358 | FSFILE * FSfopen (const char * fileName, const char *mode) |
||
| 359 | Summary: |
||
| 360 | Open a file |
||
| 361 | Conditions: |
||
| 362 | For read modes, file exists; FSInit performed |
||
| 363 | Input: |
||
| 364 | fileName - The name of the file to open |
||
| 365 | mode - |
||
| 366 | - WRITE - Create a new file or replace an existing file |
||
| 367 | - READ - Read data from an existing file |
||
| 368 | - APPEND - Append data to an existing file |
||
| 369 | - WRITEPLUS - Create a new file or replace an existing file (reads also enabled) |
||
| 370 | - READPLUS - Read data from an existing file (writes also enabled) |
||
| 371 | - APPENDPLUS - Append data to an existing file (reads also enabled) |
||
| 372 | Return Values: |
||
| 373 | FSFILE * - The pointer to the file object |
||
| 374 | NULL - The file could not be opened |
||
| 375 | Side Effects: |
||
| 376 | The FSerrno variable will be changed. |
||
| 377 | Description: |
||
| 378 | This function will open a file or directory. First, RAM in the |
||
| 379 | dynamic heap or static array will be allocated to a new FSFILE object. |
||
| 380 | Then, the specified file name will be formatted to ensure that it's |
||
| 381 | in 8.3 format. Next, the FILEfind function will be used to search |
||
| 382 | for the specified file name. If the name is found, one of three |
||
| 383 | things will happen: if the file was opened in read mode, its file |
||
| 384 | info will be loaded using the FILEopen function; if it was opened in |
||
| 385 | write mode, it will be erased, and a new file will be constructed in |
||
| 386 | its place; if it was opened in append mode, its file info will be |
||
| 387 | loaded with FILEopen and the current location will be moved to the |
||
| 388 | end of the file using the FSfseek function. If the file was not |
||
| 389 | found by FILEfind, it will be created if the mode was specified as |
||
| 390 | a write or append mode. In these cases, a pointer to the heap or |
||
| 391 | static FSFILE object array will be returned. If the file was not |
||
| 392 | found and the mode was specified as a read mode, the memory |
||
| 393 | allocated to the file will be freed and the NULL pointer value |
||
| 394 | will be returned. |
||
| 395 | Remarks: |
||
| 396 | None. |
||
| 397 | *********************************************************************/ |
||
| 398 | |||
| 399 | FSFILE * FSfopen(const char * fileName, const char *mode); |
||
| 400 | |||
| 401 | |||
| 402 | |||
| 403 | #ifdef ALLOW_PGMFUNCTIONS |
||
| 404 | |||
| 405 | /****************************************************************************** |
||
| 406 | Function: |
||
| 407 | FSFILE * FSfopenpgm(const rom char * fileName, const rom char *mode) |
||
| 408 | Summary: |
||
| 409 | Open a file named with a ROM string on PIC18 |
||
| 410 | Conditions: |
||
| 411 | For read modes, file exists; FSInit performed |
||
| 412 | Input: |
||
| 413 | fileName - The name of the file to be opened (ROM) |
||
| 414 | mode - The mode the file will be opened in (ROM) |
||
| 415 | Return Values: |
||
| 416 | FSFILE * - A pointer to the file object |
||
| 417 | NULL - File could not be opened |
||
| 418 | Side Effects: |
||
| 419 | The FSerrno variable will be changed. |
||
| 420 | Description: |
||
| 421 | The FSfopenpgm function will copy a PIC18 ROM fileName and mode argument |
||
| 422 | into RAM arrays, and then pass those arrays to the FSfopen function. |
||
| 423 | Remarks: |
||
| 424 | This function is for use with PIC18 when passing arguments in ROM. |
||
| 425 | ******************************************************************************/ |
||
| 426 | |||
| 427 | FSFILE * FSfopenpgm(const rom char * fileName, const rom char *mode); |
||
| 428 | |||
| 429 | |||
| 430 | /************************************************************************************** |
||
| 431 | Function: |
||
| 432 | int FindFirstpgm (const char * fileName, unsigned int attr, SearchRec * rec) |
||
| 433 | Summary: |
||
| 434 | Find a file named with a ROM string on PIC18 |
||
| 435 | Conditions: |
||
| 436 | None |
||
| 437 | Input: |
||
| 438 | fileName - The name of the file to be found (ROM) |
||
| 439 | attr - The attributes of the file to be found |
||
| 440 | rec - Pointer to a search record to store the file info in |
||
| 441 | Return Values: |
||
| 442 | |||
| 443 | -1 - No file matching the given parameters was found |
||
| 444 | Side Effects: |
||
| 445 | Search criteria from previous FindFirst call on passed SearchRec object will be lost. |
||
| 446 | The FSerrno variable will be changed. |
||
| 447 | Description: |
||
| 448 | The FindFirstpgm function will copy a PIC18 ROM fileName argument |
||
| 449 | into a RAM array, and then pass that array to the FindFirst function. |
||
| 450 | Remarks: |
||
| 451 | Call FindFirstpgm or FindFirst before calling FindNext. |
||
| 452 | This function is for use with PIC18 when passing arguments in ROM. |
||
| 453 | **************************************************************************************/ |
||
| 454 | |||
| 455 | int FindFirstpgm (const rom char * fileName, unsigned int attr, SearchRec * rec); |
||
| 456 | |||
| 457 | |||
| 458 | /************************************************************************** |
||
| 459 | Function: |
||
| 460 | int FSchdirpgm (const rom char * path) |
||
| 461 | Summary: |
||
| 462 | Changed the CWD with a path in ROM on PIC18 |
||
| 463 | Conditions: |
||
| 464 | None |
||
| 465 | Input: |
||
| 466 | path - The path of the directory to change to (ROM) |
||
| 467 | Return Values: |
||
| 468 | |||
| 469 | EOF - The current working directory could not be changed |
||
| 470 | Side Effects: |
||
| 471 | The current working directory may be changed. The FSerrno variable will |
||
| 472 | be changed. |
||
| 473 | Description: |
||
| 474 | The FSchdirpgm function passes a PIC18 ROM path pointer to the |
||
| 475 | chdirhelper function. |
||
| 476 | Remarks: |
||
| 477 | This function is for use with PIC18 when passing arguments in ROM |
||
| 478 | **************************************************************************/ |
||
| 479 | |||
| 480 | int FSchdirpgm (const rom char * path); |
||
| 481 | |||
| 482 | #ifdef ALLOW_WRITES |
||
| 483 | |||
| 484 | |||
| 485 | /************************************************************* |
||
| 486 | Function: |
||
| 487 | int FSremovepgm (const rom char * fileName) |
||
| 488 | Summary: |
||
| 489 | Delete a file named with a ROM string on PIC18 |
||
| 490 | Conditions: |
||
| 491 | File not opened; file exists |
||
| 492 | Input: |
||
| 493 | fileName - The name of the file to be deleted (ROM) |
||
| 494 | Return Values: |
||
| 495 | |||
| 496 | -1 - File could not be removed |
||
| 497 | Side Effects: |
||
| 498 | The FSerrno variable will be changed. |
||
| 499 | Description: |
||
| 500 | The FSremovepgm function will copy a PIC18 ROM fileName argument |
||
| 501 | into a RAM array, and then pass that array to the FSremove function. |
||
| 502 | Remarks: |
||
| 503 | This function is for use with PIC18 when passing arguments in ROM. |
||
| 504 | *************************************************************/ |
||
| 505 | |||
| 506 | int FSremovepgm (const rom char * fileName); |
||
| 507 | |||
| 508 | |||
| 509 | /************************************************************************** |
||
| 510 | Function: |
||
| 511 | int FSmkdirpgm (const rom char * path) |
||
| 512 | Summary: |
||
| 513 | Create a directory with a path in ROM on PIC18 |
||
| 514 | Conditions: |
||
| 515 | None |
||
| 516 | Input: |
||
| 517 | path - The path of directories to create (ROM) |
||
| 518 | Return Values: |
||
| 519 | |||
| 520 | EOF - The specified directory could not be created |
||
| 521 | Side Effects: |
||
| 522 | Will create all non-existent directories in the path. The FSerrno |
||
| 523 | variable will be changed. |
||
| 524 | Description: |
||
| 525 | The FSmkdirpgm function passes a PIC18 ROM path pointer to the |
||
| 526 | mkdirhelper function. |
||
| 527 | Remarks: |
||
| 528 | This function is for use with PIC18 when passing arugments in ROM |
||
| 529 | **************************************************************************/ |
||
| 530 | |||
| 531 | int FSmkdirpgm (const rom char * path); |
||
| 532 | |||
| 533 | |||
| 534 | /************************************************************************** |
||
| 535 | Function: |
||
| 536 | int FSrmdirpgm (const rom char * path) |
||
| 537 | Summary: |
||
| 538 | Delete a directory with a path in ROM on PIC18 |
||
| 539 | Conditions: |
||
| 540 | None. |
||
| 541 | Input: |
||
| 542 | path - The path of the directory to remove (ROM) |
||
| 543 | rmsubdirs - |
||
| 544 | - TRUE - All sub-dirs and files in the target dir will be removed |
||
| 545 | - FALSE - FSrmdir will not remove non-empty directories |
||
| 546 | Return Values: |
||
| 547 | |||
| 548 | EOF - The specified directory could not be deleted |
||
| 549 | Side Effects: |
||
| 550 | The FSerrno variable will be changed. |
||
| 551 | Description: |
||
| 552 | The FSrmdirpgm function passes a PIC18 ROM path pointer to the |
||
| 553 | rmdirhelper function. |
||
| 554 | Remarks: |
||
| 555 | This function is for use with PIC18 when passing arguments in ROM. |
||
| 556 | **************************************************************************/ |
||
| 557 | |||
| 558 | int FSrmdirpgm (const rom char * path, unsigned char rmsubdirs); |
||
| 559 | |||
| 560 | |||
| 561 | /***************************************************************** |
||
| 562 | Function: |
||
| 563 | int FSrenamepgm(const rom char * fileName, FSFILE * fo) |
||
| 564 | Summary: |
||
| 565 | Rename a file named with a ROM string on PIC18 |
||
| 566 | Conditions: |
||
| 567 | File opened. |
||
| 568 | Input: |
||
| 569 | fileName - The new name of the file (in ROM) |
||
| 570 | fo - The file to rename |
||
| 571 | Return Values: |
||
| 572 | |||
| 573 | -1 - File could not be renamed |
||
| 574 | Side Effects: |
||
| 575 | The FSerrno variable will be changed. |
||
| 576 | Description: |
||
| 577 | The Fsrenamepgm function will copy the rom fileName specified |
||
| 578 | by the user into a RAM array and pass that array into the |
||
| 579 | FSrename function. |
||
| 580 | Remarks: |
||
| 581 | This function is for use with PIC18 when passing arguments in ROM. |
||
| 582 | *****************************************************************/ |
||
| 583 | |||
| 584 | int FSrenamepgm (const rom char * fileName, FSFILE * fo); |
||
| 585 | #endif |
||
| 586 | #endif |
||
| 587 | |||
| 588 | |||
| 589 | /************************************************************ |
||
| 590 | Function: |
||
| 591 | int FSfclose(FSFILE *fo) |
||
| 592 | Summary: |
||
| 593 | Update file information and free FSFILE objects |
||
| 594 | Conditions: |
||
| 595 | File opened |
||
| 596 | Input: |
||
| 597 | fo - Pointer to the file to close |
||
| 598 | Return Values: |
||
| 599 | |||
| 600 | EOF - Error closing the file |
||
| 601 | Side Effects: |
||
| 602 | The FSerrno variable will be changed. |
||
| 603 | Description: |
||
| 604 | This function will update the directory entry for the |
||
| 605 | file pointed to by 'fo' with the information contained |
||
| 606 | in 'fo,' including the new file size and attributes. |
||
| 607 | Timestamp information will also be loaded based on the |
||
| 608 | method selected by the user and written to the entry |
||
| 609 | as the last modified time and date. The file entry will |
||
| 610 | then be written to the device. Finally, the memory |
||
| 611 | used for the specified file object will be freed from |
||
| 612 | the dynamic heap or the array of FSFILE objects. |
||
| 613 | Remarks: |
||
| 614 | A function to flush data to the device without closing the |
||
| 615 | file can be created by removing the portion of this |
||
| 616 | function that frees the memory and the line that clears |
||
| 617 | the write flag. |
||
| 618 | ************************************************************/ |
||
| 619 | |||
| 620 | int FSfclose(FSFILE *fo); |
||
| 621 | |||
| 622 | |||
| 623 | /********************************************************* |
||
| 624 | Function: |
||
| 625 | void FSrewind (FSFILE * fo) |
||
| 626 | Summary: |
||
| 627 | Set the current position in a file to the beginning |
||
| 628 | Conditions: |
||
| 629 | File opened. |
||
| 630 | Input: |
||
| 631 | fo - Pointer to file structure |
||
| 632 | Return Values: |
||
| 633 | None |
||
| 634 | Side Effects: |
||
| 635 | None. |
||
| 636 | Description: |
||
| 637 | The FSrewind funciton will reset the position of the |
||
| 638 | specified file to the beginning of the file. This |
||
| 639 | functionality is faster than using FSfseek to reset |
||
| 640 | the position in the file. |
||
| 641 | Remarks: |
||
| 642 | None. |
||
| 643 | *********************************************************/ |
||
| 644 | |||
| 645 | void FSrewind (FSFILE *fo); |
||
| 646 | |||
| 647 | |||
| 648 | /************************************************************************** |
||
| 649 | Function: |
||
| 650 | size_t FSfread(void *ptr, size_t size, size_t n, FSFILE *stream) |
||
| 651 | Summary: |
||
| 652 | Read data from a file |
||
| 653 | Conditions: |
||
| 654 | File is opened in a read mode |
||
| 655 | Input: |
||
| 656 | ptr - Destination buffer for read bytes |
||
| 657 | size - Size of units in bytes |
||
| 658 | n - Number of units to be read |
||
| 659 | stream - File to be read from |
||
| 660 | Return: |
||
| 661 | size_t - number of units read |
||
| 662 | Side Effects: |
||
| 663 | The FSerrno variable will be changed. |
||
| 664 | Description: |
||
| 665 | The FSfread function will read data from the specified file. First, |
||
| 666 | the appropriate sector of the file is loaded. Then, data is read into |
||
| 667 | the specified buffer until the specified number of bytes have been read. |
||
| 668 | When a cluster boundary is reached, a new cluster will be loaded. The |
||
| 669 | parameters 'size' and 'n' indicate how much data to read. 'Size' |
||
| 670 | refers to the size of one object to read (in bytes), and 'n' will refer |
||
| 671 | to the number of these objects to read. The value returned will be equal |
||
| 672 | to 'n' unless an error occured or the user tried to read beyond the end |
||
| 673 | of the file. |
||
| 674 | Remarks: |
||
| 675 | None. |
||
| 676 | **************************************************************************/ |
||
| 677 | |||
| 678 | size_t FSfread(void *ptr, size_t size, size_t n, FSFILE *stream); |
||
| 679 | |||
| 680 | |||
| 681 | /********************************************************************** |
||
| 682 | Function: |
||
| 683 | int FSfseek(FSFILE *stream, long offset, int whence) |
||
| 684 | Summary: |
||
| 685 | Change the current position in a file |
||
| 686 | Conditions: |
||
| 687 | File opened |
||
| 688 | Input: |
||
| 689 | stream - Pointer to file structure |
||
| 690 | offset - Offset from base location |
||
| 691 | whence - |
||
| 692 | - SEEK_SET - Seek from start of file |
||
| 693 | - SEEK_CUR - Seek from current location |
||
| 694 | - SEEK_END - Seek from end of file (subtract offset) |
||
| 695 | Return Values: |
||
| 696 | |||
| 697 | -1 - Operation unsuccesful |
||
| 698 | Side Effects: |
||
| 699 | The FSerrno variable will be changed. |
||
| 700 | Description: |
||
| 701 | The FSfseek function will change the current position in the file to |
||
| 702 | one specified by the user. First, an absolute offset is calculated |
||
| 703 | using the offset and base location passed in by the user. Then, the |
||
| 704 | position variables are updated, and the sector number that corresponds |
||
| 705 | to the new location. That sector is then loaded. If the offset |
||
| 706 | falls exactly on a cluster boundary, a new cluster will be allocated |
||
| 707 | to the file and the position will be set to the first byte of that |
||
| 708 | cluster. |
||
| 709 | Remarks: |
||
| 710 | None |
||
| 711 | **********************************************************************/ |
||
| 712 | |||
| 713 | int FSfseek(FSFILE *stream, long offset, int whence); |
||
| 714 | |||
| 715 | |||
| 716 | /******************************************************************* |
||
| 717 | Function: |
||
| 718 | long FSftell (FSFILE * fo) |
||
| 719 | Summary: |
||
| 720 | Determine the current location in a file |
||
| 721 | Conditions: |
||
| 722 | File opened |
||
| 723 | Input: |
||
| 724 | fo - Pointer to file structure |
||
| 725 | Return: Current location in the file |
||
| 726 | Side Effects: |
||
| 727 | The FSerrno variable will be changed |
||
| 728 | Description: |
||
| 729 | The FSftell function will return the current position in the |
||
| 730 | file pointed to by 'fo' by returning the 'seek' variable in the |
||
| 731 | FSFILE object, which is used to keep track of the absolute |
||
| 732 | location of the current position in the file. |
||
| 733 | Remarks: |
||
| 734 | None |
||
| 735 | *******************************************************************/ |
||
| 736 | |||
| 737 | long FSftell(FSFILE *fo); |
||
| 738 | |||
| 739 | |||
| 740 | /**************************************************** |
||
| 741 | Function: |
||
| 742 | int FSfeof( FSFILE * stream ) |
||
| 743 | Summary: |
||
| 744 | Indicate whether the current file position is at the end |
||
| 745 | Conditions: |
||
| 746 | File is open in a read mode |
||
| 747 | Input: |
||
| 748 | stream - Pointer to the target file |
||
| 749 | Return Values: |
||
| 750 | Non-Zero - EOF reached |
||
| 751 | |||
| 752 | Side Effects: |
||
| 753 | The FSerrno variable will be changed. |
||
| 754 | Description: |
||
| 755 | The FSfeof function will indicate that the end-of- |
||
| 756 | file has been reached for the specified file by |
||
| 757 | comparing the absolute location in the file to the |
||
| 758 | size of the file. |
||
| 759 | Remarks: |
||
| 760 | None. |
||
| 761 | ****************************************************/ |
||
| 762 | |||
| 763 | int FSfeof( FSFILE * stream ); |
||
| 764 | |||
| 765 | |||
| 766 | #ifdef ALLOW_FORMATS |
||
| 767 | /******************************************************************* |
||
| 768 | Function: |
||
| 769 | int FSformat (char mode, long int serialNumber, char * volumeID) |
||
| 770 | Summary: |
||
| 771 | Formats a device |
||
| 772 | Conditions: |
||
| 773 | The device must possess a valid master boot record. |
||
| 774 | Input: |
||
| 775 | mode - - 0 - Just erase the FAT and root |
||
| 776 | - 1 - Create a new boot sector |
||
| 777 | serialNumber - Serial number to write to the card |
||
| 778 | volumeID - Name of the card |
||
| 779 | Return Values: |
||
| 780 | |||
| 781 | EOF - Format was unsuccessful |
||
| 782 | Side Effects: |
||
| 783 | The FSerrno variable will be changed. |
||
| 784 | Description: |
||
| 785 | The FSformat function can be used to create a new boot sector |
||
| 786 | on a device, based on the information in the master boot record. |
||
| 787 | This function will first initialize the I/O pins and the device, |
||
| 788 | and then attempts to read the master boot record. If the MBR |
||
| 789 | cannot be loaded successfully, the function will fail. Next, if |
||
| 790 | the 'mode' argument is specified as '0' the existing boot sector |
||
| 791 | information will be loaded. If the 'mode' argument is '1' an |
||
| 792 | entirely new boot sector will be constructed using the disk |
||
| 793 | values from the master boot record. Once the boot sector has |
||
| 794 | been successfully loaded/created, the locations of the FAT and |
||
| 795 | root will be loaded from it, and they will be completely |
||
| 796 | erased. If the user has specified a volumeID parameter, a |
||
| 797 | VOLUME attribute entry will be created in the root directory |
||
| 798 | to name the device. |
||
| 799 | |||
| 800 | FAT12, FAT16 and FAT32 formatting are supported. |
||
| 801 | |||
| 802 | Based on the number of sectors, the format function automatically |
||
| 803 | compute the smallest possible value for the cluster size in order to |
||
| 804 | accommodate the physical size of the media. In this case, if a media |
||
| 805 | with a big capacity is formatted, the format function may take a very |
||
| 806 | long time to write all the FAT tables. |
||
| 807 | |||
| 808 | Therefore, the FORMAT_SECTORS_PER_CLUSTER macro may be used to |
||
| 809 | specify the exact cluster size (in multiples of sector size). This |
||
| 810 | macro can be defined in FSconfig.h |
||
| 811 | |||
| 812 | Remarks: |
||
| 813 | Only devices with a sector size of 512 bytes are supported by the |
||
| 814 | format function |
||
| 815 | *******************************************************************/ |
||
| 816 | |||
| 817 | int FSformat (char mode, long int serialNumber, char * volumeID); |
||
| 818 | #endif |
||
| 819 | |||
| 820 | |||
| 821 | #ifdef ALLOW_WRITES |
||
| 822 | /*************************************************************************** |
||
| 823 | Function: |
||
| 824 | int FSattrib (FSFILE * file, unsigned char attributes) |
||
| 825 | Summary: |
||
| 826 | Change the attributes of a file |
||
| 827 | Conditions: |
||
| 828 | File opened |
||
| 829 | Input: |
||
| 830 | file - Pointer to file structure |
||
| 831 | attributes - The attributes to set for the file |
||
| 832 | - Attribute - Value - Indications |
||
| 833 | - ATTR_READ_ONLY - 0x01 - The read-only attribute |
||
| 834 | - ATTR_HIDDEN - 0x02 - The hidden attribute |
||
| 835 | - ATTR_SYSTEM - 0x04 - The system attribute |
||
| 836 | - ATTR_ARCHIVE - 0x20 - The archive attribute |
||
| 837 | Return Values: |
||
| 838 | |||
| 839 | -1 - Attribute change was unsuccessful |
||
| 840 | Side Effects: |
||
| 841 | The FSerrno variable will be changed. |
||
| 842 | Description: |
||
| 843 | The FSattrib funciton will set the attributes of the specified file |
||
| 844 | to the attributes passed in by the user. This function will load the |
||
| 845 | file entry, replace the attributes with the ones specified, and write |
||
| 846 | the attributes back. If the specified file is a directory, the |
||
| 847 | directory attribute will be preserved. |
||
| 848 | Remarks: |
||
| 849 | None |
||
| 850 | ***************************************************************************/ |
||
| 851 | |||
| 852 | int FSattrib (FSFILE * file, unsigned char attributes); |
||
| 853 | |||
| 854 | |||
| 855 | /*************************************************************** |
||
| 856 | Function: |
||
| 857 | int FSrename (const rom char * fileName, FSFILE * fo) |
||
| 858 | Summary: |
||
| 859 | Change the name of a file or directory |
||
| 860 | Conditions: |
||
| 861 | File opened. |
||
| 862 | Input: |
||
| 863 | fileName - The new name of the file |
||
| 864 | fo - The file to rename |
||
| 865 | Return Values: |
||
| 866 | |||
| 867 | EOF - File was not renamed |
||
| 868 | Side Effects: |
||
| 869 | The FSerrno variable will be changed. |
||
| 870 | Description: |
||
| 871 | The FSrename function will rename a file. First, it will |
||
| 872 | search through the current working directory to ensure the |
||
| 873 | specified new filename is not already in use. If it isn't, |
||
| 874 | the new filename will be written to the file entry of the |
||
| 875 | file pointed to by 'fo.' |
||
| 876 | Remarks: |
||
| 877 | None |
||
| 878 | ***************************************************************/ |
||
| 879 | |||
| 880 | int FSrename (const char * fileName, FSFILE * fo); |
||
| 881 | |||
| 882 | |||
| 883 | /********************************************************************* |
||
| 884 | Function: |
||
| 885 | int FSremove (const char * fileName) |
||
| 886 | Summary: |
||
| 887 | Delete a file |
||
| 888 | Conditions: |
||
| 889 | File not opened, file exists |
||
| 890 | Input: |
||
| 891 | fileName - Name of the file to erase |
||
| 892 | Return Values: |
||
| 893 | |||
| 894 | EOF - File was not removed |
||
| 895 | Side Effects: |
||
| 896 | The FSerrno variable will be changed. |
||
| 897 | Description: |
||
| 898 | The FSremove function will attempt to find the specified file with |
||
| 899 | the FILEfind function. If the file is found, it will be erased |
||
| 900 | using the FILEerase function. |
||
| 901 | Remarks: |
||
| 902 | None |
||
| 903 | **********************************************************************/ |
||
| 904 | |||
| 905 | int FSremove (const char * fileName); |
||
| 906 | |||
| 907 | |||
| 908 | /********************************************************************************* |
||
| 909 | Function: |
||
| 910 | size_t FSfwrite(const void *ptr, size_t size, size_t n, FSFILE *stream) |
||
| 911 | Summary: |
||
| 912 | Write data to a file |
||
| 913 | Conditions: |
||
| 914 | File opened in WRITE, APPEND, WRITE+, APPEND+, READ+ mode |
||
| 915 | Input: |
||
| 916 | ptr - Pointer to source buffer |
||
| 917 | size - Size of units in bytes |
||
| 918 | n - Number of units to transfer |
||
| 919 | stream - Pointer to file structure |
||
| 920 | Return: |
||
| 921 | size_t - number of units written |
||
| 922 | Side Effects: |
||
| 923 | The FSerrno variable will be changed. |
||
| 924 | Description: |
||
| 925 | The FSfwrite function will write data to a file. First, the sector that |
||
| 926 | corresponds to the current position in the file will be loaded (if it hasn't |
||
| 927 | already been cached in the global data buffer). Data will then be written to |
||
| 928 | the device from the specified buffer until the specified amount has been written. |
||
| 929 | If the end of a cluster is reached, the next cluster will be loaded, unless |
||
| 930 | the end-of-file flag for the specified file has been set. If it has, a new |
||
| 931 | cluster will be allocated to the file. Finally, the new position and filezize |
||
| 932 | will be stored in the FSFILE object. The parameters 'size' and 'n' indicate how |
||
| 933 | much data to write. 'Size' refers to the size of one object to write (in bytes), |
||
| 934 | and 'n' will refer to the number of these objects to write. The value returned |
||
| 935 | will be equal to 'n' unless an error occured. |
||
| 936 | Remarks: |
||
| 937 | None. |
||
| 938 | *********************************************************************************/ |
||
| 939 | |||
| 940 | size_t FSfwrite(const void *ptr, size_t size, size_t n, FSFILE *stream); |
||
| 941 | |||
| 942 | #endif |
||
| 943 | |||
| 944 | #ifdef ALLOW_DIRS |
||
| 945 | |||
| 946 | |||
| 947 | /************************************************************************** |
||
| 948 | Function: |
||
| 949 | int FSchdir (char * path) |
||
| 950 | Summary: |
||
| 951 | Change the current working directory |
||
| 952 | Conditions: |
||
| 953 | None |
||
| 954 | Input: |
||
| 955 | path - The path of the directory to change to. |
||
| 956 | Return Values: |
||
| 957 | |||
| 958 | EOF - The current working directory could not be changed |
||
| 959 | Side Effects: |
||
| 960 | The current working directory may be changed. The FSerrno variable will |
||
| 961 | be changed. |
||
| 962 | Description: |
||
| 963 | The FSchdir function passes a RAM pointer to the path to the |
||
| 964 | chdirhelper function. |
||
| 965 | Remarks: |
||
| 966 | None |
||
| 967 | **************************************************************************/ |
||
| 968 | |||
| 969 | int FSchdir (char * path); |
||
| 970 | |||
| 971 | |||
| 972 | /************************************************************** |
||
| 973 | Function: |
||
| 974 | char * FSgetcwd (char * path, int numchars) |
||
| 975 | Summary: |
||
| 976 | Get the current working directory name |
||
| 977 | Conditions: |
||
| 978 | None |
||
| 979 | Input: |
||
| 980 | path - Pointer to the array to return the cwd name in |
||
| 981 | numchars - Number of chars in the path |
||
| 982 | Return Values: |
||
| 983 | char * - The cwd name string pointer (path or defaultArray) |
||
| 984 | NULL - The current working directory name could not be loaded. |
||
| 985 | Side Effects: |
||
| 986 | The FSerrno variable will be changed |
||
| 987 | Description: |
||
| 988 | The FSgetcwd function will get the name of the current |
||
| 989 | working directory and return it to the user. The name |
||
| 990 | will be copied into the buffer pointed to by 'path,' |
||
| 991 | starting at the root directory and copying as many chars |
||
| 992 | as possible before the end of the buffer. The buffer |
||
| 993 | size is indicated by the 'numchars' argument. The first |
||
| 994 | thing this function will do is load the name of the current |
||
| 995 | working directory, if it isn't already present. This could |
||
| 996 | occur if the user switched to the dotdot entry of a |
||
| 997 | subdirectory immediately before calling this function. The |
||
| 998 | function will then copy the current working directory name |
||
| 999 | into the buffer backwards, and insert a backslash character. |
||
| 1000 | Next, the function will continuously switch to the previous |
||
| 1001 | directories and copy their names backwards into the buffer |
||
| 1002 | until it reaches the root. If the buffer overflows, it |
||
| 1003 | will be treated as a circular buffer, and data will be |
||
| 1004 | copied over existing characters, starting at the beginning. |
||
| 1005 | Once the root directory is reached, the text in the buffer |
||
| 1006 | will be swapped, so that the buffer contains as much of the |
||
| 1007 | current working directory name as possible, starting at the |
||
| 1008 | root. |
||
| 1009 | Remarks: |
||
| 1010 | None |
||
| 1011 | **************************************************************/ |
||
| 1012 | |||
| 1013 | char * FSgetcwd (char * path, int numbchars); |
||
| 1014 | |||
| 1015 | |||
| 1016 | #ifdef ALLOW_WRITES |
||
| 1017 | |||
| 1018 | /************************************************************************** |
||
| 1019 | Function: |
||
| 1020 | int FSmkdir (char * path) |
||
| 1021 | Summary: |
||
| 1022 | Create a directory |
||
| 1023 | Conditions: |
||
| 1024 | None |
||
| 1025 | Input: |
||
| 1026 | path - The path of directories to create. |
||
| 1027 | Return Values: |
||
| 1028 | |||
| 1029 | EOF - The specified directory could not be created |
||
| 1030 | Side Effects: |
||
| 1031 | Will create all non-existent directories in the path. The FSerrno |
||
| 1032 | variable will be changed. |
||
| 1033 | Description: |
||
| 1034 | The FSmkdir function passes a RAM pointer to the path to the |
||
| 1035 | mkdirhelper function. |
||
| 1036 | Remarks: |
||
| 1037 | None |
||
| 1038 | **************************************************************************/ |
||
| 1039 | |||
| 1040 | int FSmkdir (char * path); |
||
| 1041 | |||
| 1042 | |||
| 1043 | /************************************************************************** |
||
| 1044 | Function: |
||
| 1045 | int FSrmdir (char * path) |
||
| 1046 | Summary: |
||
| 1047 | Delete a directory |
||
| 1048 | Conditions: |
||
| 1049 | None |
||
| 1050 | Input: |
||
| 1051 | path - The path of the directory to remove |
||
| 1052 | rmsubdirs - |
||
| 1053 | - TRUE - All sub-dirs and files in the target dir will be removed |
||
| 1054 | - FALSE - FSrmdir will not remove non-empty directories |
||
| 1055 | Return Values: |
||
| 1056 | |||
| 1057 | EOF - The specified directory could not be deleted |
||
| 1058 | Side Effects: |
||
| 1059 | The FSerrno variable will be changed. |
||
| 1060 | Description: |
||
| 1061 | The FSrmdir function passes a RAM pointer to the path to the |
||
| 1062 | rmdirhelper function. |
||
| 1063 | Remarks: |
||
| 1064 | None. |
||
| 1065 | **************************************************************************/ |
||
| 1066 | |||
| 1067 | int FSrmdir (char * path, unsigned char rmsubdirs); |
||
| 1068 | #endif |
||
| 1069 | |||
| 1070 | #endif |
||
| 1071 | |||
| 1072 | #ifdef USERDEFINEDCLOCK |
||
| 1073 | |||
| 1074 | |||
| 1075 | /*********************************************************************************************************** |
||
| 1076 | Function: |
||
| 1077 | int SetClockVars (unsigned int year, unsigned char month, unsigned char day, unsigned char hour, unsigned char minute, unsigned char second) |
||
| 1078 | Summary: |
||
| 1079 | Manually set timestamp variables |
||
| 1080 | Conditions: |
||
| 1081 | USERDEFINEDCLOCK macro defined in FSconfig.h. |
||
| 1082 | Input: |
||
| 1083 | year - The year (1980\-2107) |
||
| 1084 | month - The month (1\-12) |
||
| 1085 | day - The day of the month (1\-31) |
||
| 1086 | hour - The hour (0\-23) |
||
| 1087 | minute - The minute (0\-59) |
||
| 1088 | second - The second (0\-59) |
||
| 1089 | Return Values: |
||
| 1090 | None |
||
| 1091 | Side Effects: |
||
| 1092 | Modifies global timing variables |
||
| 1093 | Description: |
||
| 1094 | Lets the user manually set the timing variables. The values passed in will be converted to the format |
||
| 1095 | used by the FAT timestamps. |
||
| 1096 | Remarks: |
||
| 1097 | Call this before creating a file or directory (set create time) and |
||
| 1098 | before closing a file (set last access time, last modified time) |
||
| 1099 | ***********************************************************************************************************/ |
||
| 1100 | |||
| 1101 | int SetClockVars (unsigned int year, unsigned char month, unsigned char day, unsigned char hour, unsigned char minute, unsigned char second); |
||
| 1102 | #endif |
||
| 1103 | |||
| 1104 | |||
| 1105 | #ifdef ALLOW_FILESEARCH |
||
| 1106 | |||
| 1107 | /*********************************************************************************** |
||
| 1108 | Function: |
||
| 1109 | int FindFirst (const char * fileName, unsigned int attr, SearchRec * rec) |
||
| 1110 | Summary: |
||
| 1111 | Initial search function |
||
| 1112 | Conditions: |
||
| 1113 | None |
||
| 1114 | Input: |
||
| 1115 | fileName - The name to search for |
||
| 1116 | - Parital string search characters |
||
| 1117 | - * - Indicates the rest of the filename or extension can vary (e.g. FILE.*) |
||
| 1118 | - ? - Indicates that one character in a filename can vary (e.g. F?LE.T?T) |
||
| 1119 | attr - The attributes that a found file may have |
||
| 1120 | - ATTR_READ_ONLY - File may be read only |
||
| 1121 | - ATTR_HIDDEN - File may be a hidden file |
||
| 1122 | - ATTR_SYSTEM - File may be a system file |
||
| 1123 | - ATTR_VOLUME - Entry may be a volume label |
||
| 1124 | - ATTR_DIRECTORY - File may be a directory |
||
| 1125 | - ATTR_ARCHIVE - File may have archive attribute |
||
| 1126 | - ATTR_MASK - All attributes |
||
| 1127 | rec - pointer to a structure to put the file information in |
||
| 1128 | Return Values: |
||
| 1129 | |||
| 1130 | -1 - No file matching the specified criteria was found |
||
| 1131 | Side Effects: |
||
| 1132 | Search criteria from previous FindFirst call on passed SearchRec object |
||
| 1133 | will be lost. The FSerrno variable will be changed. |
||
| 1134 | Description: |
||
| 1135 | The FindFirst function will search for a file based on parameters passed in |
||
| 1136 | by the user. This function will use the FILEfind function to parse through |
||
| 1137 | the current working directory searching for entries that match the specified |
||
| 1138 | parameters. If a file is found, its parameters are copied into the SearchRec |
||
| 1139 | structure, as are the initial parameters passed in by the user and the position |
||
| 1140 | of the file entry in the current working directory. |
||
| 1141 | Remarks: |
||
| 1142 | Call FindFirst or FindFirstpgm before calling FindNext |
||
| 1143 | ***********************************************************************************/ |
||
| 1144 | |||
| 1145 | int FindFirst (const char * fileName, unsigned int attr, SearchRec * rec); |
||
| 1146 | |||
| 1147 | |||
| 1148 | /********************************************************************** |
||
| 1149 | Function: |
||
| 1150 | int FindNext (SearchRec * rec) |
||
| 1151 | Summary: |
||
| 1152 | Sequential search function |
||
| 1153 | Conditions: |
||
| 1154 | None |
||
| 1155 | Input: |
||
| 1156 | rec - The structure to store the file information in |
||
| 1157 | Return Values: |
||
| 1158 | |||
| 1159 | -1 - No additional files matching the specified criteria were found |
||
| 1160 | Side Effects: |
||
| 1161 | The FSerrno variable will be changed. |
||
| 1162 | Description: |
||
| 1163 | The FindNext function performs the same function as the FindFirst |
||
| 1164 | funciton, except it does not copy any search parameters into the |
||
| 1165 | SearchRec structure (only info about found files) and it begins |
||
| 1166 | searching at the last directory entry offset at which a file was |
||
| 1167 | found, rather than at the beginning of the current working |
||
| 1168 | directory. |
||
| 1169 | Remarks: |
||
| 1170 | Call FindFirst or FindFirstpgm before calling this function |
||
| 1171 | **********************************************************************/ |
||
| 1172 | |||
| 1173 | int FindNext (SearchRec * rec); |
||
| 1174 | #endif |
||
| 1175 | |||
| 1176 | |||
| 1177 | /********************************************************************** |
||
| 1178 | Function: |
||
| 1179 | // PIC24/30/33/32 |
||
| 1180 | int FSfprintf (FSFILE * fptr, const char * fmt, ...) |
||
| 1181 | // PIC18 |
||
| 1182 | int FSfpritnf (FSFILE * fptr, const rom char * fmt, ...) |
||
| 1183 | Summary: |
||
| 1184 | Function to write formatted strings to a file |
||
| 1185 | Conditions: |
||
| 1186 | For PIC18, integer promotion must be enabled in the project build |
||
| 1187 | options menu. File opened in a write mode. |
||
| 1188 | Input: |
||
| 1189 | fptr - A pointer to the file to write to. |
||
| 1190 | fmt - A string of characters and format specifiers to write to |
||
| 1191 | the file |
||
| 1192 | ... - Additional arguments inserted in the string by format |
||
| 1193 | specifiers |
||
| 1194 | Returns: |
||
| 1195 | The number of characters written to the file |
||
| 1196 | Side Effects: |
||
| 1197 | The FSerrno variable will be changed. |
||
| 1198 | Description: |
||
| 1199 | Writes a specially formatted string to a file. |
||
| 1200 | Remarks: |
||
| 1201 | Consult AN1045 for a full description of how to use format |
||
| 1202 | specifiers. |
||
| 1203 | **********************************************************************/ |
||
| 1204 | |||
| 1205 | #ifdef ALLOW_FSFPRINTF |
||
| 1206 | #ifdef __18CXX |
||
| 1207 | int FSfprintf (FSFILE *fptr, const rom char *fmt, ...); |
||
| 1208 | #else |
||
| 1209 | int FSfprintf (FSFILE *fptr, const char * fmt, ...); |
||
| 1210 | #endif |
||
| 1211 | #endif |
||
| 1212 | |||
| 1213 | |||
| 1214 | /************************************************************************** |
||
| 1215 | Function: |
||
| 1216 | int FSerror (void) |
||
| 1217 | Summary: |
||
| 1218 | Return an error code for the last function call |
||
| 1219 | Conditions: |
||
| 1220 | The return value depends on the last function called. |
||
| 1221 | Input: |
||
| 1222 | None |
||
| 1223 | Side Effects: |
||
| 1224 | None. |
||
| 1225 | Return Values: |
||
| 1226 | FSInit - |
||
| 1227 | - CE_GOOD No Error |
||
| 1228 | - CE_INIT_ERROR The physical media could not be initialized |
||
| 1229 | - CE_BAD_SECTOR_READ The MBR or the boot sector could not be |
||
| 1230 | read correctly |
||
| 1231 | - CE_BAD_PARITION The MBR signature code was incorrect. |
||
| 1232 | - CE_NOT_FORMATTED The boot sector signature code was incorrect or |
||
| 1233 | indicates an invalid number of bytes per sector. |
||
| 1234 | - CE_CARDFAT32 The physical media is FAT32 type (only an error |
||
| 1235 | when FAT32 support is disabled). |
||
| 1236 | - CE_UNSUPPORTED_FS The device is formatted with an unsupported file |
||
| 1237 | system (not FAT12 or 16). |
||
| 1238 | FSfopen - |
||
| 1239 | - CE_GOOD No Error |
||
| 1240 | - CE_NOT_INIT The device has not been initialized. |
||
| 1241 | - CE_TOO_MANY_FILES_OPEN The function could not allocate any |
||
| 1242 | additional file information to the array |
||
| 1243 | of FSFILE structures or the heap. |
||
| 1244 | - CE_INVALID_FILENAME The file name argument was invalid. |
||
| 1245 | - CE_INVALID_ARGUMENT The user attempted to open a directory in a |
||
| 1246 | write mode or specified an invalid mode argument. |
||
| 1247 | - CE_FILE_NOT_FOUND The specified file (which was to be opened in read |
||
| 1248 | mode) does not exist on the device. |
||
| 1249 | - CE_BADCACHEREAD A read from the device failed. |
||
| 1250 | - CE_ERASE_FAIL The existing file could not be erased (when opening |
||
| 1251 | a file in WRITE mode). |
||
| 1252 | - CE_DIR_FULL The directory is full. |
||
| 1253 | - CE_DISK_FULL The data memory section is full. |
||
| 1254 | - CE_WRITE_ERROR A write to the device failed. |
||
| 1255 | - CE_SEEK_ERROR The current position in the file could not be set to |
||
| 1256 | the end (when the file was opened in APPEND mode). |
||
| 1257 | FSfclose - |
||
| 1258 | - CE_GOOD No Error |
||
| 1259 | - CE_WRITE_ERROR The existing data in the data buffer or the new file |
||
| 1260 | entry information could not be written to the device. |
||
| 1261 | - CE_BADCACHEREAD The file entry information could not be cached |
||
| 1262 | FSfread - |
||
| 1263 | - CE_GOOD No Error |
||
| 1264 | - CE_WRITEONLY The file was opened in a write-only mode. |
||
| 1265 | - CE_WRITE_ERROR The existing data in the data buffer could not be |
||
| 1266 | written to the device. |
||
| 1267 | - CE_BAD_SECTOR_READ The data sector could not be read. |
||
| 1268 | - CE_EOF The end of the file was reached. |
||
| 1269 | - CE_COULD_NOT_GET_CLUSTER Additional clusters in the file could not be loaded. |
||
| 1270 | FSfwrite - |
||
| 1271 | - CE_GOOD No Error |
||
| 1272 | - CE_READONLY The file was opened in a read-only mode. |
||
| 1273 | - CE_WRITE_PROTECTED The device write-protect check function indicated |
||
| 1274 | that the device has been write-protected. |
||
| 1275 | - CE_WRITE_ERROR There was an error writing data to the device. |
||
| 1276 | - CE_BADCACHEREAD The data sector to be modified could not be read from |
||
| 1277 | the device. |
||
| 1278 | - CE_DISK_FULL All data clusters on the device are in use. |
||
| 1279 | FSfseek - |
||
| 1280 | - CE_GOOD No Error |
||
| 1281 | - CE_WRITE_ERROR The existing data in the data buffer could not be |
||
| 1282 | written to the device. |
||
| 1283 | - CE_INVALID_ARGUMENT The specified offset exceeds the size of the file. |
||
| 1284 | - CE_BADCACHEREAD The sector that contains the new current position |
||
| 1285 | could not be loaded. |
||
| 1286 | - CE_COULD_NOT_GET_CLUSTER Additional clusters in the file could not be |
||
| 1287 | loaded/allocated. |
||
| 1288 | FSftell - |
||
| 1289 | - CE_GOOD No Error |
||
| 1290 | FSattrib - |
||
| 1291 | - CE_GOOD No Error |
||
| 1292 | - CE_INVALID_ARGUMENT The attribute argument was invalid. |
||
| 1293 | - CE_BADCACHEREAD The existing file entry information could not be |
||
| 1294 | loaded. |
||
| 1295 | - CE_WRITE_ERROR The file entry information could not be written to |
||
| 1296 | the device. |
||
| 1297 | FSrename - |
||
| 1298 | - CE_GOOD No Error |
||
| 1299 | - CE_FILENOTOPENED A null file pointer was passed into the function. |
||
| 1300 | - CE_INVALID_FILENAME The file name passed into the function was invalid. |
||
| 1301 | - CE_BADCACHEREAD A read from the device failed. |
||
| 1302 | - CE_FILENAME_EXISTS A file with the specified name already exists. |
||
| 1303 | - CE_WRITE_ERROR The new file entry data could not be written to the |
||
| 1304 | device. |
||
| 1305 | FSfeof - |
||
| 1306 | - CE_GOOD No Error |
||
| 1307 | FSformat - |
||
| 1308 | - CE_GOOD No Error |
||
| 1309 | - CE_INIT_ERROR The device could not be initialized. |
||
| 1310 | - CE_BADCACHEREAD The master boot record or boot sector could not be |
||
| 1311 | loaded successfully. |
||
| 1312 | - CE_INVALID_ARGUMENT The user selected to create their own boot sector on |
||
| 1313 | a device that has no master boot record, or the mode |
||
| 1314 | argument was invalid. |
||
| 1315 | - CE_WRITE_ERROR The updated MBR/Boot sector could not be written to |
||
| 1316 | the device. |
||
| 1317 | - CE_BAD_PARTITION The calculated number of sectors per clusters was |
||
| 1318 | invalid. |
||
| 1319 | - CE_NONSUPPORTED_SIZE The card has too many sectors to be formatted as |
||
| 1320 | FAT12 or FAT16. |
||
| 1321 | FSremove - |
||
| 1322 | - CE_GOOD No Error |
||
| 1323 | - CE_WRITE_PROTECTED The device write-protect check function indicated |
||
| 1324 | that the device has been write-protected. |
||
| 1325 | - CE_INVALID_FILENAME The specified filename was invalid. |
||
| 1326 | - CE_FILE_NOT_FOUND The specified file could not be found. |
||
| 1327 | - CE_ERASE_FAIL The file could not be erased. |
||
| 1328 | FSchdir - |
||
| 1329 | - CE_GOOD No Error |
||
| 1330 | - CE_INVALID_ARGUMENT The path string was mis-formed or the user tried to |
||
| 1331 | change to a non-directory file. |
||
| 1332 | - CE_BADCACHEREAD A directory entry could not be cached. |
||
| 1333 | - CE_DIR_NOT_FOUND Could not find a directory in the path. |
||
| 1334 | FSgetcwd - |
||
| 1335 | - CE_GOOD No Error |
||
| 1336 | - CE_INVALID_ARGUMENT The user passed a 0-length buffer into the function. |
||
| 1337 | - CE_BADCACHEREAD A directory entry could not be cached. |
||
| 1338 | - CE_BAD_SECTOR_READ The function could not determine a previous directory |
||
| 1339 | of the current working directory. |
||
| 1340 | FSmkdir - |
||
| 1341 | - CE_GOOD No Error |
||
| 1342 | - CE_WRITE_PROTECTED The device write-protect check function indicated |
||
| 1343 | that the device has been write-protected. |
||
| 1344 | - CE_INVALID_ARGUMENT The path string was mis-formed. |
||
| 1345 | - CE_BADCACHEREAD Could not successfully change to a recently created |
||
| 1346 | directory to store its dir entry information, or |
||
| 1347 | could not cache directory entry information. |
||
| 1348 | - CE_INVALID_FILENAME One or more of the directory names has an invalid |
||
| 1349 | format. |
||
| 1350 | - CE_WRITE_ERROR The existing data in the data buffer could not be |
||
| 1351 | written to the device or the dot/dotdot entries could |
||
| 1352 | not be written to a newly created directory. |
||
| 1353 | - CE_DIR_FULL There are no available dir entries in the CWD. |
||
| 1354 | - CE_DISK_FULL There are no available clusters in the data region of |
||
| 1355 | the device. |
||
| 1356 | FSrmdir - |
||
| 1357 | - CE_GOOD No Error |
||
| 1358 | - CE_DIR_NOT_FOUND The directory specified could not be found or the |
||
| 1359 | function could not change to a subdirectory within |
||
| 1360 | the directory to be deleted (when recursive delete is |
||
| 1361 | enabled). |
||
| 1362 | - CE_INVALID_ARGUMENT The user tried to remove the CWD or root directory. |
||
| 1363 | - CE_BADCACHEREAD A directory entry could not be cached. |
||
| 1364 | - CE_DIR_NOT_EMPTY The directory to be deleted was not empty and |
||
| 1365 | recursive subdirectory removal was disabled. |
||
| 1366 | - CE_ERASE_FAIL The directory or one of the directories or files |
||
| 1367 | within it could not be deleted. |
||
| 1368 | - CE_BAD_SECTOR_READ The function could not determine a previous directory |
||
| 1369 | of the CWD. |
||
| 1370 | SetClockVars - |
||
| 1371 | - CE_GOOD No Error |
||
| 1372 | - CE_INVALID_ARGUMENT The time values passed into the function were |
||
| 1373 | invalid. |
||
| 1374 | FindFirst - |
||
| 1375 | - CE_GOOD No Error |
||
| 1376 | - CE_INVALID_FILENAME The specified filename was invalid. |
||
| 1377 | - CE_FILE_NOT_FOUND No file matching the specified criteria was found. |
||
| 1378 | - CE_BADCACHEREAD The file information for the file that was found |
||
| 1379 | could not be cached. |
||
| 1380 | FindNext - |
||
| 1381 | - CE_GOOD No Error |
||
| 1382 | - CE_NOT_INIT The SearchRec object was not initialized by a call to |
||
| 1383 | FindFirst. |
||
| 1384 | - CE_INVALID_ARGUMENT The SearchRec object was initialized in a different |
||
| 1385 | directory from the CWD. |
||
| 1386 | - CE_INVALID_FILENAME The filename is invalid. |
||
| 1387 | - CE_FILE_NOT_FOUND No file matching the specified criteria was found. |
||
| 1388 | FSfprintf - |
||
| 1389 | - CE_GOOD No Error |
||
| 1390 | - CE_WRITE_ERROR Characters could not be written to the file. |
||
| 1391 | Description: |
||
| 1392 | The FSerror function will return the FSerrno variable. This global |
||
| 1393 | variable will have been set to an error value during the last call of a |
||
| 1394 | library function. |
||
| 1395 | Remarks: |
||
| 1396 | None |
||
| 1397 | **************************************************************************/ |
||
| 1398 | |||
| 1399 | int FSerror (void); |
||
| 1400 | |||
| 1401 | |||
| 1402 | /********************************************************************************* |
||
| 1403 | Function: |
||
| 1404 | int FSCreateMBR (unsigned long firstSector, unsigned long numSectors) |
||
| 1405 | Summary: |
||
| 1406 | Creates a master boot record |
||
| 1407 | Conditions: |
||
| 1408 | The I/O pins for the device have been initialized by the InitIO function. |
||
| 1409 | Input: |
||
| 1410 | firstSector - The first sector of the partition on the device (cannot |
||
| 1411 | be 0; that's the MBR) |
||
| 1412 | numSectors - The number of sectors available in memory (including the |
||
| 1413 | MBR) |
||
| 1414 | Return Values: |
||
| 1415 | |||
| 1416 | EOF - MBR could not be created |
||
| 1417 | Side Effects: |
||
| 1418 | None |
||
| 1419 | Description: |
||
| 1420 | This function can be used to create a master boot record for a device. Note |
||
| 1421 | that this function should not be used on a device that is already formatted |
||
| 1422 | with a master boot record (i.e. most SD cards, CF cards, USB keys). This |
||
| 1423 | function will fill the global data buffer with appropriate partition information |
||
| 1424 | for a FAT partition with a type determined by the number of sectors available |
||
| 1425 | to the partition. It will then write the MBR information to the first sector |
||
| 1426 | on the device. This function should be followed by a call to FSformat, which |
||
| 1427 | will create a boot sector, root dir, and FAT appropriate the the information |
||
| 1428 | contained in the new master boot record. Note that FSformat only supports |
||
| 1429 | FAT12 and FAT16 formatting at this time, and so cannot be used to format a |
||
| 1430 | device with more than 0x3FFD5F sectors. |
||
| 1431 | Remarks: |
||
| 1432 | This function can damage the device being used, and should not be called |
||
| 1433 | unless the user is sure about the size of the device and the first sector value. |
||
| 1434 | *********************************************************************************/ |
||
| 1435 | |||
| 1436 | int FSCreateMBR (unsigned long firstSector, unsigned long numSectors); |
||
| 1437 | |||
| 1438 | |||
| 1439 | #ifdef ALLOW_GET_DISK_PROPERTIES |
||
| 1440 | /********************************************************************************* |
||
| 1441 | Function: |
||
| 1442 | void FSGetDiskProperties(FS_DISK_PROPERTIES* properties) |
||
| 1443 | Summary: |
||
| 1444 | Allows user to get the disk properties (size of disk, free space, etc) |
||
| 1445 | Conditions: |
||
| 1446 | 1) ALLOW_GET_DISK_PROPERTIES must be defined in FSconfig.h |
||
| 1447 | 2) a FS_DISK_PROPERTIES object must be created before the function is called |
||
| 1448 | 3) the new_request member of the FS_DISK_PROPERTIES object must be set before |
||
| 1449 | calling the function for the first time. This will start a new search. |
||
| 1450 | 4) this function should not be called while there is a file open. Close all |
||
| 1451 | files before calling this function. |
||
| 1452 | Input: |
||
| 1453 | properties - a pointer to a FS_DISK_PROPERTIES object where the results should |
||
| 1454 | be stored. |
||
| 1455 | Return Values: |
||
| 1456 | This function returns void. The properties_status of the previous call of |
||
| 1457 | this function is located in the properties.status field. This field has |
||
| 1458 | the following possible values: |
||
| 1459 | |||
| 1460 | FS_GET_PROPERTIES_NO_ERRORS - operation completed without error. Results |
||
| 1461 | are in the properties object passed into the function. |
||
| 1462 | FS_GET_PROPERTIES_DISK_NOT_MOUNTED - there is no mounted disk. Results in |
||
| 1463 | properties object is not valid |
||
| 1464 | FS_GET_PROPERTIES_CLUSTER_FAILURE - there was a failure trying to read a |
||
| 1465 | cluster from the drive. The results in the properties object is a partial |
||
| 1466 | result up until the point of the failure. |
||
| 1467 | FS_GET_PROPERTIES_STILL_WORKING - the search for free sectors is still in |
||
| 1468 | process. Continue calling this function with the same properties pointer |
||
| 1469 | until either the function completes or until the partial results meets the |
||
| 1470 | application needs. The properties object contains the partial results of |
||
| 1471 | the search and can be used by the application. |
||
| 1472 | Side Effects: |
||
| 1473 | Can cause errors if called when files are open. Close all files before |
||
| 1474 | calling this function. |
||
| 1475 | |||
| 1476 | Calling this function without setting the new_request member on the first |
||
| 1477 | call can result in undefined behavior and results. |
||
| 1478 | |||
| 1479 | Calling this function after a result is returned other than |
||
| 1480 | FS_GET_PROPERTIES_STILL_WORKING can result in undefined behavior and results. |
||
| 1481 | Description: |
||
| 1482 | This function returns the information about the mounted drive. The results |
||
| 1483 | member of the properties object passed into the function is populated with |
||
| 1484 | the information about the drive. |
||
| 1485 | |||
| 1486 | Before starting a new request, the new_request member of the properties |
||
| 1487 | input parameter should be set to TRUE. This will initiate a new search |
||
| 1488 | request. |
||
| 1489 | |||
| 1490 | This function will return before the search is complete with partial results. |
||
| 1491 | All of the results except the free_clusters will be correct after the first |
||
| 1492 | call. The free_clusters will contain the number of free clusters found up |
||
| 1493 | until that point, thus the free_clusters result will continue to grow until |
||
| 1494 | the entire drive is searched. If an application only needs to know that a |
||
| 1495 | certain number of bytes is available and doesn't need to know the total free |
||
| 1496 | size, then this function can be called until the required free size is |
||
| 1497 | verified. To continue a search, pass a pointer to the same FS_DISK_PROPERTIES |
||
| 1498 | object that was passed in to create the search. |
||
| 1499 | |||
| 1500 | A new search request sould be made once this function has returned a value |
||
| 1501 | other than FS_GET_PROPERTIES_STILL_WORKING. Continuing a completed search |
||
| 1502 | can result in undefined behavior or results. |
||
| 1503 | |||
| 1504 | Typical Usage: |
||
| 1505 | <code> |
||
| 1506 | FS_DISK_PROPERTIES disk_properties; |
||
| 1507 | |||
| 1508 | disk_properties.new_request = TRUE; |
||
| 1509 | |||
| 1510 | do |
||
| 1511 | { |
||
| 1512 | FSGetDiskProperties(&disk_properties); |
||
| 1513 | } while (disk_properties.properties_status == FS_GET_PROPERTIES_STILL_WORKING); |
||
| 1514 | </code> |
||
| 1515 | |||
| 1516 | results.disk_format - contains the format of the drive. Valid results are |
||
| 1517 | FAT12(1), FAT16(2), or FAT32(3). |
||
| 1518 | |||
| 1519 | results.sector_size - the sector size of the mounted drive. Valid values are |
||
| 1520 | 512, 1024, 2048, and 4096. |
||
| 1521 | |||
| 1522 | results.sectors_per_cluster - the number sectors per cluster. |
||
| 1523 | |||
| 1524 | results.total_clusters - the number of total clusters on the drive. This |
||
| 1525 | can be used to calculate the total disk size (total_clusters * |
||
| 1526 | sectors_per_cluster * sector_size = total size of drive in bytes) |
||
| 1527 | |||
| 1528 | results.free_clusters - the number of free (unallocated) clusters on the drive. |
||
| 1529 | This can be used to calculate the total free disk size (free_clusters * |
||
| 1530 | sectors_per_cluster * sector_size = total size of drive in bytes) |
||
| 1531 | |||
| 1532 | Remarks: |
||
| 1533 | PIC24F size estimates: |
||
| 1534 | Flash - 400 bytes (-Os setting) |
||
| 1535 | |||
| 1536 | PIC24F speed estimates: |
||
| 1537 | Search takes approximately 7 seconds per Gigabyte of drive space. Speed |
||
| 1538 | will vary based on the number of sectors per cluster and the sector size. |
||
| 1539 | *********************************************************************************/ |
||
| 1540 | void FSGetDiskProperties(FS_DISK_PROPERTIES* properties); |
||
| 1541 | #endif |
||
| 1542 | |||
| 1543 | |||
| 1544 | #endif |
Powered by WebSVN v2.8.3