// sdfsio370f.h // PIC32MX370F512HでSPI2接続されたSDカードにアクセスする // sdfsio370fLib.aを利用するためのヘッダーファイル // FSIO.h,FSconfig.h,FSDefs.hから抜粋 by K.Tanaka // // サポート // FAT32,書き込み,ファイルサーチ,Dir // 未サポート // LongFileName,FSfprintf,format,FSGetDiskProperties // 同時オープン数 3 /****************************************************************************** * * Microchip Memory Disk Drive File System * ****************************************************************************** * FileName: FSIO.h * Dependencies: GenericTypeDefs.h * FSconfig.h * FSDefs.h * stddef.h * Processor: PIC18/PIC24/dsPIC30/dsPIC33/PIC32 * Compiler: C18/C30/C32 * Company: Microchip Technology, Inc. * Version: 1.3.0 * * Software License Agreement * * The software supplied herewith by Microchip Technology Incorporated * (the 鼎ompany・ for its PICmicroｮ Microcontroller is intended and * supplied to you, the Company痴 customer, for use solely and * exclusively on Microchip PICmicro Microcontroller products. The * software is owned by the Company and/or its supplier, and is * protected under applicable copyright laws. All rights are reserved. * Any use in violation of the foregoing restrictions may subject the * user to criminal sanctions under applicable laws, as well as to * civil liability for the breach of the terms and conditions of this * license. * * THIS SOFTWARE IS PROVIDED IN AN 鄭S IS・CONDITION. NO WARRANTIES, * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT, * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. * *****************************************************************************/ #ifndef FS_DOT_H #define FS_DOT_H #define MDD_MediaInitialize MDD_SDSPI_MediaInitialize #define MDD_MediaDetect MDD_SDSPI_MediaDetect #define MDD_SectorRead MDD_SDSPI_SectorRead #define MDD_SectorWrite MDD_SDSPI_SectorWrite #define MDD_InitIO MDD_SDSPI_InitIO #define MDD_ShutdownMedia MDD_SDSPI_ShutdownMedia #define MDD_WriteProtectState MDD_SDSPI_WriteProtectState #define ALLOW_FILESEARCH #define ALLOW_WRITES #define ALLOW_DIRS #define SUPPORT_FAT32 // Summary: An enumeration used for various error codes. // Description: The CETYPE enumeration is used to indicate different error conditions during device operation. typedef enum _CETYPE { CE_GOOD = 0, // No error CE_ERASE_FAIL, // An erase failed CE_NOT_PRESENT, // No device was present CE_NOT_FORMATTED, // The disk is of an unsupported format CE_BAD_PARTITION, // The boot record is bad CE_UNSUPPORTED_FS, // The file system type is unsupported CE_INIT_ERROR, // An initialization error has occured CE_NOT_INIT, // An operation was performed on an uninitialized device CE_BAD_SECTOR_READ, // A bad read of a sector occured CE_WRITE_ERROR, // Could not write to a sector CE_INVALID_CLUSTER, // Invalid cluster value > maxcls CE_FILE_NOT_FOUND, // Could not find the file on the device CE_DIR_NOT_FOUND, // Could not find the directory CE_BAD_FILE, // File is corrupted CE_DONE, // No more files in this directory CE_COULD_NOT_GET_CLUSTER, // Could not load/allocate next cluster in file CE_FILENAME_2_LONG, // A specified file name is too long to use CE_FILENAME_EXISTS, // A specified filename already exists on the device CE_INVALID_FILENAME, // Invalid file name CE_DELETE_DIR, // The user tried to delete a directory with FSremove CE_DIR_FULL, // All root dir entry are taken CE_DISK_FULL, // All clusters in partition are taken CE_DIR_NOT_EMPTY, // This directory is not empty yet, remove files before deleting CE_NONSUPPORTED_SIZE, // The disk is too big to format as FAT16 CE_WRITE_PROTECTED, // Card is write protected CE_FILENOTOPENED, // File not opened for the write CE_SEEK_ERROR, // File location could not be changed successfully CE_BADCACHEREAD, // Bad cache read CE_CARDFAT32, // FAT 32 - card not supported CE_READONLY, // The file is read-only CE_WRITEONLY, // The file is write-only CE_INVALID_ARGUMENT, // Invalid argument CE_TOO_MANY_FILES_OPEN, // Too many files are already open CE_UNSUPPORTED_SECTOR_SIZE // Unsupported sector size } CETYPE; // Summary: A macro indicating a dir entry was found // Description: The FOUND macro indicates that a directory entry was found in the specified position #define FOUND 0 // Summary: A macro indicating no dir entry was found // Description: The NOT_FOUND macro indicates that the specified directory entry to load was deleted #define NOT_FOUND 1 // Summary: A macro indicating that no more files were found // Description: The NO_MORE macro indicates that there are no more directory entries to search for #define NO_MORE 2 // Summary: A macro indicating the device is formatted with FAT12 // Description: The FAT12 macro is used to indicate that the file system on the device being accessed is a FAT12 file system. #define FAT12 1 // Summary: A macro indicating the device is formatted with FAT16 // Description: The FAT16 macro is used to indicate that the file system on the device being accessed is a FAT16 file system. #define FAT16 2 // Summary: A macro indicating the device is formatted with FAT32 // Description: The FAT32 macro is used to indicate that the file system on the device being accessed is a FAT32 file system. #define FAT32 3 // Summary: A read-only attribute macro // Description: A macro for the read-only attribute. A file with this attribute should not be written to. Note that this // attribute will not actually prevent a write to the file; that functionality is operating-system dependant. The // user should take care not to write to a read-only file. #define ATTR_READ_ONLY 0x01 // Summary: A hidden attribute macro // Description: A macro for the hidden attribute. A file with this attribute may be hidden from the user, depending on the // implementation of the operating system. #define ATTR_HIDDEN 0x02 // Summary: A system attribute macro // Description: A macro for the system attribute. A file with this attribute is used by the operating system, and should not be // modified. Note that this attribute will not actually prevent a write to the file. #define ATTR_SYSTEM 0x04 // Summary: A volume attribute macro // Description: A macro for the volume attribute. If the first directory entry in the root directory has the volume attribute set, // the device will use the name in that directory entry as the volume name. #define ATTR_VOLUME 0x08 // Summary: A macro for the attributes for a long-file name entry // Description: A macro for the long-name attributes. If a directory entry is used in a long-file name implementation, it will have // all four lower bits set. This indicates that any software that does not support long file names should ignore that // entry. #define ATTR_LONG_NAME 0x0f // Summary: A directory attribute macro // Description: A macro for the directory attribute. If a directory entry has this attribute set, the file it points to is a directory- // type file, and will contain directory entries that point to additional directories or files. #define ATTR_DIRECTORY 0x10 // Summary: An archive attribute macro // Description: A macro for the archive attribute. This attribute will indicate to some archiving programs that the file with this // attribute needs to be backed up. Most operating systems create files with the archive attribute set. #define ATTR_ARCHIVE 0x20 // Summary: A macro for all attributes // Description: A macro for all attributes. The search functions in this library require an argument that determines which attributes // a file is allowed to have in order to be found. If ATTR_MASK is specified as this argument, any file may be found, regardless // of its attributes. #define ATTR_MASK 0x3f // Summary: A macro to indicate an empty FAT entry // Description: The CLUSTER_EMPTY value is used to indicate that a FAT entry and it's corresponding cluster are available. #define CLUSTER_EMPTY 0x0000 // Summary: A macro to indicate the last cluster value for FAT12 // Description: The LAST_CLUSTER_FAT12 macro is used when reading the FAT to indicate that the next FAT12 entry for a file contains // the end-of-file value. #define LAST_CLUSTER_FAT12 0xff8 // Summary: A macro to indicate the last cluster value for FAT16 // Description: The LAST_CLUSTER_FAT16 macro is used when reading the FAT to indicate that the next FAT16 entry for a file contains // the end-of-file value. #define LAST_CLUSTER_FAT16 0xfff8 // Summary: A macro to indicate the last allocatable cluster for FAT12 // Description: The END_CLUSTER_FAT12 value is used as a comparison in FAT12 to determine that the firmware has reached the end of // the range of allowed allocatable clusters. #define END_CLUSTER_FAT12 0xFF7 // Summary: A macro to indicate the last allocatable cluster for FAT16 // Description: The END_CLUSTER_FAT16 value is used as a comparison in FAT16 to determine that the firmware has reached the end of // the range of allowed allocatable clusters. #define END_CLUSTER_FAT16 0xFFF7 // Summary: A macro to indicate the failure of the ReadFAT function // Description: The CLUSTER_FAIL_FAT16 macro is used by the ReadFAT function to indicate that an error occured reading a FAT12 or FAT16 // file allocation table. Note that since '0xFFF8' is used for the last cluster return value in the FAT16 implementation // the end-of-file value '0xFFFF' can be used to indicate an error condition. #define CLUSTER_FAIL_FAT16 0xFFFF #ifdef SUPPORT_FAT32 // Summary: A macro to indicate the last cluster value for FAT32 // Description: The LAST_CLUSTER_FAT32 macro is used when reading the FAT to indicate that the next FAT32 entry for a file contains // the end-of-file value. #define LAST_CLUSTER_FAT32 0x0FFFFFF8 // Summary: A macro to indicate the last allocatable cluster for FAT32 // Description: The END_CLUSTER_FAT32 value is used as a comparison in FAT32 to determine that the firmware has reached the end of // the range of allowed allocatable clusters. #define END_CLUSTER_FAT32 0x0FFFFFF7 // Summary: A macro to indicate the failure of the ReadFAT function // Description: The CLUSTER_FAIL_FAT32 macro is used by the ReadFAT function to indicate that an error occured reading a FAT32 // file allocation able. #define CLUSTER_FAIL_FAT32 0x0FFFFFFF #endif // Summary: A macro indicating the number of bytes in a directory entry. // Description: The NUMBER_OF_BYTES_IN_DIR_ENTRY macro represents the number of bytes in one directory entry. It is used to calculate // the number of sectors in the root directory based on information in the boot sector. #define NUMBER_OF_BYTES_IN_DIR_ENTRY 32 // Summary: A macro for a deleted dir entry marker. // Description: The DIR_DEL macro is used to mark a directory entry as deleted. When a file is deleted, this value will replace the // first character in the file name, and will indicate that the file the entry points to was deleted. #define DIR_DEL 0xE5 // Summary: A macro for the last dir entry marker. // Description: The DIR_EMPTY macro is used to indicate the last entry in a directory. Since entries in use cannot start with a 0 and // deleted entries start with the DIR_DEL character, a 0 will mark the end of the in-use or previously used group of // entries in a directory #define DIR_EMPTY 0 // Summary: A macro used to indicate the length of an 8.3 file name // Description: The DIR_NAMESIZE macro is used when validing the name portion of 8.3 filenames #define DIR_NAMESIZE 8 // Summary: A macro used to indicate the length of an 8.3 file extension // Description: The DIR_EXTENSION macro is used when validating the extension portion of 8.3 filenames #define DIR_EXTENSION 3 // Summary: A macro used to indicate the length of an 8.3 file name and extension // Description: The DIR_NAMECOMP macro is used when validating 8.3 filenames #define DIR_NAMECOMP (DIR_NAMESIZE+DIR_EXTENSION) // Summary: A macro to write a byte to RAM // Description: The RAMwrite macro is used to write a byte of data to a RAM array #define RAMwrite( a, f, d) *(a+f) = d // Summary: A macro to read a byte from RAM // Description: The RAMread macro is used to read a byte of data from a RAM array #define RAMread( a, f) *(a+f) // Summary: A macro to read a 16-bit word from RAM // Description: The RAMreadW macro is used to read two bytes of data from a RAM array #define RAMreadW( a, f) *(WORD *)(a+f) // Summary: A macro to read a 32-bit word from RAM // Description: The RAMreadD macro is used to read four bytes of data from a RAM array #define RAMreadD( a, f) *(DWORD *)(a+f) #ifndef EOF // Summary: Indicates error conditions or end-of-file conditions // Description: The EOF macro is used to indicate error conditions in some function calls. It is also used to indicate // that the end-of-file has been reached. #define EOF ((int)-1) #endif // Summary: A structure containing information about the device. // Description: The DISK structure contains information about the device being accessed. typedef struct { BYTE * buffer; // Address of the global data buffer used to read and write file information DWORD firsts; // Logical block address of the first sector of the FAT partition on the device DWORD fat; // Logical block address of the FAT DWORD root; // Logical block address of the root directory DWORD data; // Logical block address of the data section of the device. WORD maxroot; // The maximum number of entries in the root directory. DWORD maxcls; // The maximum number of clusters in the partition. DWORD sectorSize; // The size of a sector in bytes DWORD fatsize; // The number of sectors in the FAT BYTE fatcopy; // The number of copies of the FAT in the partition BYTE SecPerClus; // The number of sectors per cluster in the data region BYTE type; // The file system type of the partition (FAT12, FAT16 or FAT32) BYTE mount; // Device mount flag (TRUE if disk was mounted successfully, FALSE otherwise) #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) DISK; #else } DISK; #endif #ifdef __18CXX // Summary: A 24-bit data type // Description: The SWORD macro is used to defined a 24-bit data type. For 16+ bit architectures, this must be represented as // an array of three bytes. typedef unsigned short long SWORD; #else // Summary: A 24-bit data type // Description: The SWORD macro is used to defined a 24-bit data type. For 16+ bit architectures, this must be represented as // an array of three bytes. typedef struct { unsigned char array[3]; #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) SWORD; #else } SWORD; #endif #endif // Summary: A structure containing the bios parameter block for a FAT12 file system (in the boot sector) // Description: The _BPB_FAT12 structure provides a layout of the "bios parameter block" in the boot sector of a FAT12 partition. typedef struct { SWORD BootSec_JumpCmd; // Jump Command BYTE BootSec_OEMName[8]; // OEM name WORD BootSec_BPS; // Number of bytes per sector BYTE BootSec_SPC; // Number of sectors per cluster WORD BootSec_ResrvSec; // Number of reserved sectors at the beginning of the partition BYTE BootSec_FATCount; // Number of FATs on the partition WORD BootSec_RootDirEnts; // Number of root directory entries WORD BootSec_TotSec16; // Total number of sectors BYTE BootSec_MDesc; // Media descriptor WORD BootSec_SPF; // Number of sectors per FAT WORD BootSec_SPT; // Number of sectors per track WORD BootSec_HeadCnt; // Number of heads DWORD BootSec_HiddenSecCnt; // Number of hidden sectors DWORD BootSec_Reserved; // Reserved space BYTE BootSec_DriveNum; // Drive number BYTE BootSec_Reserved2; // Reserved space BYTE BootSec_BootSig; // Boot signature - equal to 0x29 BYTE BootSec_VolID[4]; // Volume ID BYTE BootSec_VolLabel[11]; // Volume Label BYTE BootSec_FSType[8]; // File system type in ASCII. Not used for determination #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) _BPB_FAT12; #else } _BPB_FAT12; #endif // Summary: A structure containing the bios parameter block for a FAT16 file system (in the boot sector) // Description: The _BPB_FAT16 structure provides a layout of the "bios parameter block" in the boot sector of a FAT16 partition. typedef struct { SWORD BootSec_JumpCmd; // Jump Command BYTE BootSec_OEMName[8]; // OEM name WORD BootSec_BPS; // Number of bytes per sector BYTE BootSec_SPC; // Number of sectors per cluster WORD BootSec_ResrvSec; // Number of reserved sectors at the beginning of the partition BYTE BootSec_FATCount; // Number of FATs on the partition WORD BootSec_RootDirEnts; // Number of root directory entries WORD BootSec_TotSec16; // Total number of sectors BYTE BootSec_MDesc; // Media descriptor WORD BootSec_SPF; // Number of sectors per FAT WORD BootSec_SPT; // Number of sectors per track WORD BootSec_HeadCnt; // Number of heads DWORD BootSec_HiddenSecCnt; // Number of hidden sectors DWORD BootSec_TotSec32; // Total sector count (32 bits) BYTE BootSec_DriveNum; // Drive number BYTE BootSec_Reserved; // Reserved space BYTE BootSec_BootSig; // Boot signature - equal to 0x29 BYTE BootSec_VolID[4]; // Volume ID BYTE BootSec_VolLabel[11]; // Volume Label BYTE BootSec_FSType[8]; // File system type in ASCII. Not used for determination #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) _BPB_FAT16; #else } _BPB_FAT16; #endif // Summary: A structure containing the bios parameter block for a FAT32 file system (in the boot sector) // Description: The _BPB_FAT32 structure provides a layout of the "bios parameter block" in the boot sector of a FAT32 partition. typedef struct { SWORD BootSec_jmpBoot; // Jump Command BYTE BootSec_OEMName[8]; // OEM name WORD BootSec_BytsPerSec; // Number of bytes per sector BYTE BootSec_SecPerClus; // Number of sectors per cluster WORD BootSec_RsvdSecCnt; // Number of reserved sectors at the beginning of the partition BYTE BootSec_NumFATs; // Number of FATs on the partition WORD BootSec_RootEntCnt; // Number of root directory entries WORD BootSec_TotSec16; // Total number of sectors BYTE BootSec_Media; // Media descriptor WORD BootSec_FATSz16; // Number of sectors per FAT WORD BootSec_SecPerTrk; // Number of sectors per track WORD BootSec_NumHeads; // Number of heads DWORD BootSec_HiddSec; // Number of hidden sectors DWORD BootSec_TotSec32; // Total sector count (32 bits) DWORD BootSec_FATSz32; // Sectors per FAT (32 bits) WORD BootSec_ExtFlags; // Presently active FAT. Defined by bits 0-3 if bit 7 is 1. WORD BootSec_FSVers; // FAT32 filesystem version. Should be 0:0 DWORD BootSec_RootClus; // Start cluster of the root directory (should be 2) WORD BootSec_FSInfo; // File system information WORD BootSec_BkBootSec; // Backup boot sector address. BYTE BootSec_Reserved[12]; // Reserved space BYTE BootSec_DrvNum; // Drive number BYTE BootSec_Reserved1; // Reserved space BYTE BootSec_BootSig; // Boot signature - 0x29 BYTE BootSec_VolID[4]; // Volume ID BYTE BootSec_VolLab[11]; // Volume Label BYTE BootSec_FilSysType[8]; // File system type in ASCII. Not used for determination #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) _BPB_FAT32; #else } _BPB_FAT32; #endif // Description: A macro for the boot sector bytes per sector value offset #define BSI_BPS 11 // Description: A macro for the boot sector sector per cluster value offset #define BSI_SPC 13 // Description: A macro for the boot sector reserved sector count value offset #define BSI_RESRVSEC 14 // Description: A macro for the boot sector FAT count value offset #define BSI_FATCOUNT 16 // Description: A macro for the boot sector root directory entry count value offset #define BSI_ROOTDIRENTS 17 // Description: A macro for the boot sector 16-bit total sector count value offset #define BSI_TOTSEC16 19 // Description: A macro for the boot sector sectors per FAT value offset #define BSI_SPF 22 // Description: A macro for the boot sector 32-bit total sector count value offset #define BSI_TOTSEC32 32 // Description: A macro for the boot sector boot signature offset #define BSI_BOOTSIG 38 // Description: A macro for the boot sector file system type string offset #define BSI_FSTYPE 54 // Description: A macro for the boot sector 32-bit sector per FAT value offset #define BSI_FATSZ32 36 // Description: A macro for the boot sector start cluster of root directory value offset #define BSI_ROOTCLUS 44 // Description: A macro for the FAT32 boot sector boot signature offset #define BSI_FAT32_BOOTSIG 66 // Description: A macro for the FAT32 boot sector file system type string offset #define BSI_FAT32_FSTYPE 82 // Summary: A partition table entry structure. // Description: The PTE_MBR structure contains values found in a partition table entry in the MBR of a device. typedef struct { BYTE PTE_BootDes; // The boot descriptor (should be 0x00 in a non-bootable device) SWORD PTE_FrstPartSect; // The cylinder-head-sector address of the first sector of the partition BYTE PTE_FSDesc; // The file system descriptor SWORD PTE_LstPartSect; // The cylinder-head-sector address of the last sector of the partition DWORD PTE_FrstSect; // The logical block address of the first sector of the partition DWORD PTE_NumSect; // The number of sectors in a partition #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) PTE_MBR; #else } PTE_MBR; #endif // Summary: A structure of the organization of a master boot record. // Description: The _PT_MBR structure has the same form as a master boot record. When the MBR is loaded from the device, it will // be cast as a _PT_MBR structure so the MBR elements can be accessed. typedef struct { BYTE ConsChkRtn[446]; // Boot code PTE_MBR Partition0; // The first partition table entry PTE_MBR Partition1; // The second partition table entry PTE_MBR Partition2; // The third partition table entry PTE_MBR Partition3; // The fourth partition table entry BYTE Signature0; // MBR signature code - equal to 0x55 BYTE Signature1; // MBR signature code - equal to 0xAA #if defined __PIC32MX__ || defined __C30__ }__attribute__((packed)) _PT_MBR; #else }_PT_MBR; #endif // Summary: A pointer to a _PT_MBR structure // Description: The PT_MBR pointer points to a _PT_MBR structure. typedef _PT_MBR * PT_MBR; // Summary: A structure of the organization of a boot sector. // Description: The _BootSec structure has the same form as a boot sector. When the boot sector is loaded from the device, it will // be cast as a _BootSec structure so the boot sector elements can be accessed. typedef struct { // A union of different bios parameter blocks union { _BPB_FAT32 FAT_32; _BPB_FAT16 FAT_16; _BPB_FAT12 FAT_12; }FAT; BYTE Reserved[512-sizeof(_BPB_FAT32)-2]; // Reserved space BYTE Signature0; // Boot sector signature code - equal to 0x55 BYTE Signature1; // Boot sector signature code - equal to 0xAA #if defined __PIC32MX__ || defined __C30__ } __attribute__ ((packed)) _BootSec; #else } _BootSec; #endif // Summary: A pointer to a _BootSec structure // Description: The BootSec pointer points to a _BootSec structure. typedef _BootSec * BootSec; // Summary: A macro indicating the offset for the master boot record // Description: FO_MBR is a macro that indicates the addresss of the master boot record on the device. When the device is initialized // this sector will be read #define FO_MBR 0L // Summary: A macro for the first boot sector/MBR signature byte // Description: The FAT_GOOD_SIGN_0 macro is used to determine that the first byte of the MBR or boot sector signature code is correct #define FAT_GOOD_SIGN_0 0x55 // Summary: A macro for the second boot sector/MBR signature byte // Description: The FAT_GOOD_SIGN_1 macro is used to determine that the second byte of the MBR or boot sector signature code is correct #define FAT_GOOD_SIGN_1 0xAA typedef struct { BYTE errorCode; union { BYTE value; struct { BYTE sectorSize : 1; BYTE maxLUN : 1; } bits; } validityFlags; WORD sectorSize; BYTE maxLUN; } MEDIA_INFORMATION; typedef enum { MEDIA_NO_ERROR, // No errors MEDIA_DEVICE_NOT_PRESENT, // The requested device is not present MEDIA_CANNOT_INITIALIZE // Cannot initialize media } MEDIA_ERRORS; /*******************************************************************/ /* Strunctures and defines */ /*******************************************************************/ #ifndef FALSE // Summary: False value // Description: This macro will indicate that a condition is false. #define FALSE 0 #endif #ifndef TRUE // Summary: True value // Description: This macro will indicate that a condition is true. #define TRUE !FALSE // True value #endif #ifndef SEEK_SET // Summary: Macro for the FSfseek SEEK_SET base location. // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed // relative to the beginning of the file. #define SEEK_SET 0 #endif #ifndef SEEK_CUR // Summary: Macro for the FSfseek SEEK_CUR base location. // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed // relative to the current location of the file #define SEEK_CUR 1 #endif #ifndef SEEK_END // Summary: Macro for the FSfseek SEEK_END base location // Description: Functions as an input for FSfseek that specifies that the position in the file will be changed // relative to the end of the file. For this macro, the offset value will be subtracted from // the end location of the file by default. #define SEEK_END 2 #endif // Summary: Macro for the FSfopen FS_APPEND mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will // be created if it doesn't exist. If it does exist, it's file information will be loaded and the // current location in the file will be set to the end. The user will then be able to write to the file. #define FS_APPEND "a" #define APPEND "a" //deprecated // Summary: Macro for the FSfopen FS_WRITE mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will // be created if it doesn't exist. If it does exist, it will be erased and replaced by an empty file // of the same name. The user will then be able to write to the file. #define FS_WRITE "w" #define WRITE "w" //deprecated // Summary: Macro for the FSfopen FS_READ mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file information for the // specified file will be loaded. If the file does not exist, the FSfopen function will fail. The user // will then be able to read from the file. #define FS_READ "r" #if defined(__32MX795F512L__) #warning FSfopen must use "r" and not READ as input on this device #else #define READ "r" //deprecated #endif // Summary: Macro for the FSfopen FS_APPEND+ mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will // be created if it doesn't exist. If it does exist, it's file information will be loaded and the // current location in the file will be set to the end. The user will then be able to write to the file // or read from the file. #define FS_APPENDPLUS "a+" #define APPENDPLUS "a+" //deprecated // Summary: Macro for the FSfopen FS_WRITE+ mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file being opened will // be created if it doesn't exist. If it does exist, it will be erased and replaced by an empty file // of the same name. The user will then be able to write to the file or read from the file. #define FS_WRITEPLUS "w+" #define WRITEPLUS "w+" //deprecated // Summary: Macro for the FSfopen FS_READ+ mode // Description: If this macro is specified as the mode argument in a call of FSfopen, the file information for the // specified file will be loaded. If the file does not exist, the FSfopen function will fail. The user // will then be able to read from the file or write to the file. #define FS_READPLUS "r+" #define READPLUS "r+" //deprecated #ifndef intmax_t #ifdef __PIC24F__ // Summary: A data type indicating the maximum integer size in an architecture // Description: The intmax_t data type refers to the maximum-sized data type on any given architecture. This // data type can be specified as a format specifier size specification for the FSfprintf function. #define intmax_t long long #elif defined __PIC24H__ #define intmax_t long long #elif defined __dsPIC30F__ #define intmax_t long long #elif defined __dsPIC33F__ #define intmax_t long long #endif #endif // Summary: Indicates flag conditions for a file object // Description: The FILEFLAGS structure is used to indicate conditions in a file. It contains three flags: 'write' indicates // that the file was opened in a mode that allows writes, 'read' indicates that the file was opened in a mode // that allows reads, and 'FileWriteEOF' indicates that additional data that is written to the file will increase // the file size. typedef struct { unsigned write :1; // Indicates a file was opened in a mode that allows writes unsigned read :1; // Indicates a file was opened in a mode that allows reads unsigned FileWriteEOF :1; // Indicates the current position in a file is at the end of the file }FILEFLAGS; // Summary: Indicates how to search for file entries in the FILEfind function // Description: The values in the SEARCH_TYPE enumeration are used internally by the library to indicate how the FILEfind function // how to perform a search. The 'LOOK_FOR_EMPTY_ENTRY' value indicates that FILEfind should search for an empty file entry. // The 'LOOK_FOR_MATCHING_ENTRY' value indicates that FILEfind should search for an entry that matches the FSFILE object // that was passed into the FILEfind function. typedef enum{ LOOK_FOR_EMPTY_ENTRY = 0, LOOK_FOR_MATCHING_ENTRY } SEARCH_TYPE; // Summary: Macro indicating the length of a 8.3 file name // Description: The TOTAL_FILE_SIZE_8P3 macro indicates the maximum number of characters in an 8.3 file name. This value includes // 8 characters for the name, three for the extentsion, and 1 for the radix ('.') #define TOTAL_FILE_SIZE_8P3 (8+3+1) #define TOTAL_FILE_SIZE TOTAL_FILE_SIZE_8P3 // Summary: Macro indicating the max length of a LFN file name // Description: The MAX_FILE_NAME_LENGTH_LFN macro indicates the maximum number of characters in an LFN file name. #define MAX_FILE_NAME_LENGTH_LFN 256 // Summary: A mask that indicates the limit of directory entries in a sector // Description: The MASK_MAX_FILE_ENTRY_LIMIT_BITS is used to indicate to the Cache_File_Entry function that a new sector needs to // be loaded. #define MASK_MAX_FILE_ENTRY_LIMIT_BITS 0x0f // Summary: Value used for shift operations to calculate the sector offset in a directory // Description: The VALUE_BASED_ON_ENTRIES_PER_CLUSTER macro is used to calculate sector offsets for directories. The position of the // entry is shifted by 4 bits (divided by 16, since there are 16 entries in a sector) to calculate how many sectors a // specified entry is offset from the beginning of the directory. #define VALUE_BASED_ON_ENTRIES_PER_CLUSTER 4 // Summary: A value that will indicate that a dotdot directory entry points to the root. // Description: The VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT macro is used as an absolute address when writing information to a dotdot entry // in a newly created directory. If a dotdot entry points to the root directory, it's cluster value must be set to 0, // regardless of the actual cluster number of the root directory. #define VALUE_DOTDOT_CLUSTER_VALUE_FOR_ROOT 0 // Summary: MAcro indicating the length of an 8.3 file name in a directory entry // Description: The FILE_NAME_SIZE_8P3 macro indicates the number of characters that an 8.3 file name will take up when packed in // a directory entry. This value includes 8 characters for the name and 3 for the extension. Note that the radix is not // stored in the directory entry. #define FILE_NAME_SIZE_8P3 11 #define FILE_NAME_SIZE FILE_NAME_SIZE_8P3 // Summary: Contains file information and is used to indicate which file to access. // Description: The FSFILE structure is used to hold file information for an open file as it's being modified or accessed. A pointer to // an open file's FSFILE structure will be passeed to any library function that will modify that file. typedef struct { DISK * dsk; // Pointer to a DISK structure DWORD cluster; // The first cluster of the file DWORD ccls; // The current cluster of the file WORD sec; // The current sector in the current cluster of the file WORD pos; // The position in the current sector DWORD seek; // The absolute position in the file DWORD size; // The size of the file FILEFLAGS flags; // A structure containing file flags WORD time; // The file's last update time WORD date; // The file's last update date char name[FILE_NAME_SIZE_8P3]; // The short name of the file #ifdef SUPPORT_LFN BOOL AsciiEncodingType; // Ascii file name or Non-Ascii file name indicator unsigned short int *utf16LFNptr; // Pointer to long file name in UTF16 format unsigned short int utf16LFNlength; // LFN length in terms of words including the NULL word at the last. #endif WORD entry; // The position of the file's directory entry in it's directory WORD chk; // File structure checksum WORD attributes; // The file attributes DWORD dirclus; // The base cluster of the file's directory DWORD dirccls; // The current cluster of the file's directory } FSFILE; /* Summary: Possible results of the FSGetDiskProperties() function. ** Description: See the FSGetDiskProperties() function for more information. */ typedef enum { FS_GET_PROPERTIES_NO_ERRORS = 0, FS_GET_PROPERTIES_DISK_NOT_MOUNTED, FS_GET_PROPERTIES_CLUSTER_FAILURE, FS_GET_PROPERTIES_STILL_WORKING = 0xFF } FS_DISK_ERRORS; /* Summary: Contains the disk search information, intermediate values, and results ** Description: This structure is used in conjunction with the FSGetDiskProperties() ** function. See that function for more information about the usage. */ typedef struct { DISK * disk; /* pointer to the disk we are searching */ BOOL new_request; /* is this a new request or a continued request */ FS_DISK_ERRORS properties_status; /* status of the last call of the function */ struct { BYTE disk_format; /* disk format: FAT12, FAT16, FAT32 */ WORD sector_size; /* sector size of the drive */ BYTE sectors_per_cluster; /* number of sectors per cluster */ DWORD total_clusters; /* the number of total clusters on the drive */ DWORD free_clusters; /* the number of free (unused) clusters on drive */ } results; /* the results of the current search */ struct { DWORD c; DWORD curcls; DWORD EndClusterLimit; DWORD ClusterFailValue; } private; /* intermediate values used to continue searches. This member should be used only by the FSGetDiskProperties() function */ } FS_DISK_PROPERTIES; // Summary: A structure used for searching for files on a device. // Description: The SearchRec structure is used when searching for file on a device. It contains parameters that will be loaded with // file information when a file is found. It also contains the parameters that the user searched for, allowing further // searches to be perfomed in the same directory for additional files that meet the specified criteria. typedef struct { char filename[FILE_NAME_SIZE_8P3 + 2]; // The name of the file that has been found unsigned char attributes; // The attributes of the file that has been found unsigned long filesize; // The size of the file that has been found unsigned long timestamp; // The last modified time of the file that has been found (create time for directories) #ifdef SUPPORT_LFN BOOL AsciiEncodingType; // Ascii file name or Non-Ascii file name indicator unsigned short int *utf16LFNfound; // Pointer to long file name found in UTF16 format unsigned short int utf16LFNfoundLength; // LFN Found length in terms of words including the NULL word at the last. #endif unsigned int entry; // The directory entry of the last file found that matches the specified attributes. (Internal use only) char searchname[FILE_NAME_SIZE_8P3 + 2]; // The 8.3 format name specified when the user began the search. (Internal use only) unsigned char searchattr; // The attributes specified when the user began the search. (Internal use only) unsigned long cwdclus; // The directory that this search was performed in. (Internal use only) unsigned char initialized; // Check to determine if the structure was initialized by FindFirst (Internal use only) } SearchRec; /*************************************************************************** * Prototypes * ***************************************************************************/ /************************************************************************* Function: int FSInit(void) Summary: Function to initialize the device. Conditions: The physical device should be connected to the microcontroller. Input: None Return Values: TRUE - Initialization successful FALSE - Initialization unsuccessful Side Effects: The FSerrno variable will be changed. Description: Initializes the static or dynamic memory slots for holding file structures. Initializes the device with the DISKmount function. Loads MBR and boot sector information. Initializes the current working directory to the root directory for the device if directory support is enabled. Remarks: None *************************************************************************/ int FSInit(void); /********************************************************************* Function: FSFILE * FSfopen (const char * fileName, const char *mode) Summary: Open a Ascii file Conditions: For read modes, file exists; FSInit performed Input: fileName - The name of the file to open mode - - WRITE - Create a new file or replace an existing file - READ - Read data from an existing file - APPEND - Append data to an existing file - WRITEPLUS - Create a new file or replace an existing file (reads also enabled) - READPLUS - Read data from an existing file (writes also enabled) - APPENDPLUS - Append data to an existing file (reads also enabled) Return Values: FSFILE * - The pointer to the file object NULL - The file could not be opened Side Effects: The FSerrno variable will be changed. Description: This function will open a file or directory. First, RAM in the dynamic heap or static array will be allocated to a new FSFILE object. Then, the specified file name will be formatted to ensure that it's in 8.3 format or LFN format. Next, the FILEfind function will be used to search for the specified file name. If the name is found, one of three things will happen: if the file was opened in read mode, its file info will be loaded using the FILEopen function; if it was opened in write mode, it will be erased, and a new file will be constructed in its place; if it was opened in append mode, its file info will be loaded with FILEopen and the current location will be moved to the end of the file using the FSfseek function. If the file was not found by FILEfind, a new file will be created if the mode was specified as a write or append mode. In these cases, a pointer to the heap or static FSFILE object array will be returned. If the file was not found and the mode was specified as a read mode, the memory allocated to the file will be freed and the NULL pointer value will be returned. Remarks: None. *********************************************************************/ FSFILE * FSfopen(const char * fileName, const char *mode); #ifdef SUPPORT_LFN /********************************************************************* Function: FSFILE * wFSfopen (const unsigned short int * fileName, const char *mode) Summary: Open a UTF16 file. Conditions: For read modes, file exists; FSInit performed Input: fileName - The name of the file to open mode - - WRITE - Create a new file or replace an existing file - READ - Read data from an existing file - APPEND - Append data to an existing file - WRITEPLUS - Create a new file or replace an existing file (reads also enabled) - READPLUS - Read data from an existing file (writes also enabled) - APPENDPLUS - Append data to an existing file (reads also enabled) Return Values: FSFILE * - The pointer to the file object NULL - The file could not be opened Side Effects: The FSerrno variable will be changed. Description: This function will open a file or directory. First, RAM in the dynamic heap or static array will be allocated to a new FSFILE object. Then, the specified file name will be formatted to ensure that it's in 8.3 format or LFN format. Next, the FILEfind function will be used to search for the specified file name. If the name is found, one of three things will happen: if the file was opened in read mode, its file info will be loaded using the FILEopen function; if it was opened in write mode, it will be erased, and a new file will be constructed in its place; if it was opened in append mode, its file info will be loaded with FILEopen and the current location will be moved to the end of the file using the FSfseek function. If the file was not found by FILEfind, a new file will be created if the mode was specified as a write or append mode. In these cases, a pointer to the heap or static FSFILE object array will be returned. If the file was not found and the mode was specified as a read mode, the memory allocated to the file will be freed and the NULL pointer value will be returned. Remarks: None. *********************************************************************/ FSFILE * wFSfopen(const unsigned short int * fileName, const char *mode); #endif #ifdef ALLOW_PGMFUNCTIONS /****************************************************************************** Function: FSFILE * FSfopenpgm(const rom char * fileName, const rom char *mode) Summary: Open a Ascii file named with a ROM string on PIC18 Conditions: For read modes, file exists; FSInit performed Input: fileName - The name of the file to be opened (ROM) mode - The mode the file will be opened in (ROM) Return Values: FSFILE * - A pointer to the file object NULL - File could not be opened Side Effects: The FSerrno variable will be changed. Description: The FSfopenpgm function will copy a PIC18 ROM fileName and mode argument into RAM arrays, and then pass those arrays to the FSfopen function. Remarks: This function is for use with PIC18 when passing arguments in ROM. ******************************************************************************/ FSFILE * FSfopenpgm(const rom char * fileName, const rom char *mode); /************************************************************************************** Function: int FindFirstpgm (const char * fileName, unsigned int attr, SearchRec * rec) Summary: Find a file named with a ROM string on PIC18 Conditions: None Input: fileName - The name of the file to be found (ROM) attr - The attributes of the file to be found rec - Pointer to a search record to store the file info in Return Values: 0 - File was found -1 - No file matching the given parameters was found Side Effects: Search criteria from previous FindFirstpgm call on passed SearchRec object will be lost.The FSerrno variable will be changed. Description: The FindFirstpgm function will copy a PIC18 ROM fileName argument into a RAM array, and then pass that array to the FindFirst function. Remarks: Call FindFirstpgm or FindFirst before calling FindNext. This function is for use with PIC18 when passing arguments in ROM. **************************************************************************************/ int FindFirstpgm (const rom char * fileName, unsigned int attr, SearchRec * rec); /************************************************************************** Function: int FSchdirpgm (const rom char * path) Summary: Changed the CWD with a path in ROM on PIC18 Conditions: None Input: path - The path of the directory to change to (ROM) Return Values: 0 - The current working directory was changed successfully EOF - The current working directory could not be changed Side Effects: The current working directory may be changed. The FSerrno variable will be changed. Description: The FSchdirpgm function passes a PIC18 ROM path pointer to the chdirhelper function. Remarks: This function is for use with PIC18 when passing arguments in ROM **************************************************************************/ int FSchdirpgm (const rom char * path); #ifdef ALLOW_WRITES /************************************************************* Function: int FSremovepgm (const rom char * fileName) Summary: Delete a file named with a ROM string on PIC18 Conditions: File not opened; file exists Input: fileName - The name of the file to be deleted (ROM) Return Values: 0 - File was removed successfully -1 - File could not be removed Side Effects: The FSerrno variable will be changed. Description: The FSremovepgm function will copy a PIC18 ROM fileName argument into a RAM array, and then pass that array to the FSremove function. Remarks: This function is for use with PIC18 when passing arguments in ROM. *************************************************************/ int FSremovepgm (const rom char * fileName); /************************************************************************** Function: int FSmkdirpgm (const rom char * path) Summary: Create a directory with a path in ROM on PIC18 Conditions: None Input: path - The path of directories to create (ROM) Return Values: 0 - The specified directory was created successfully EOF - The specified directory could not be created Side Effects: Will create all non-existent directories in the path. The FSerrno variable will be changed. Description: The FSmkdirpgm function passes a PIC18 ROM path pointer to the mkdirhelper function. Remarks: This function is for use with PIC18 when passing arugments in ROM **************************************************************************/ int FSmkdirpgm (const rom char * path); /************************************************************************** Function: int FSrmdirpgm (const rom char * path) Summary: Delete a directory with a path in ROM on PIC18 Conditions: None. Input: path - The path of the directory to remove (ROM) rmsubdirs - - TRUE - All sub-dirs and files in the target dir will be removed - FALSE - FSrmdir will not remove non-empty directories Return Values: 0 - The specified directory was deleted successfully EOF - The specified directory could not be deleted Side Effects: The FSerrno variable will be changed. Description: The FSrmdirpgm function passes a PIC18 ROM path pointer to the rmdirhelper function. Remarks: This function is for use with PIC18 when passing arguments in ROM. **************************************************************************/ int FSrmdirpgm (const rom char * path, unsigned char rmsubdirs); /***************************************************************** Function: int FSrenamepgm(const rom char * fileName, FSFILE * fo) Summary: Rename a file named with a ROM string on PIC18 Conditions: File opened. Input: fileName - The new name of the file (in ROM) fo - The file to rename Return Values: 0 - File renamed successfully -1 - File could not be renamed Side Effects: The FSerrno variable will be changed. Description: The Fsrenamepgm function will copy the rom fileName specified by the user into a RAM array and pass that array into the FSrename function. Remarks: This function is for use with PIC18 when passing arguments in ROM. *****************************************************************/ int FSrenamepgm (const rom char * fileName, FSFILE * fo); #endif #endif /************************************************************ Function: int FSfclose(FSFILE *fo) Summary: Update file information and free FSFILE objects Conditions: File opened Input: fo - Pointer to the file to close Return Values: 0 - File closed successfully EOF - Error closing the file Side Effects: The FSerrno variable will be changed. Description: This function will update the directory entry for the file pointed to by 'fo' with the information contained in 'fo,' including the new file size and attributes. Timestamp information will also be loaded based on the method selected by the user and written to the entry as the last modified time and date. The file entry will then be written to the device. Finally, the memory used for the specified file object will be freed from the dynamic heap or the array of FSFILE objects. Remarks: A function to flush data to the device without closing the file can be created by removing the portion of this function that frees the memory and the line that clears the write flag. ************************************************************/ int FSfclose(FSFILE *fo); /********************************************************* Function: void FSrewind (FSFILE * fo) Summary: Set the current position in a file to the beginning Conditions: File opened. Input: fo - Pointer to file structure Return Values: None Side Effects: None. Description: The FSrewind funciton will reset the position of the specified file to the beginning of the file. This functionality is faster than using FSfseek to reset the position in the file. Remarks: None. *********************************************************/ void FSrewind (FSFILE *fo); /************************************************************************** Function: size_t FSfread(void *ptr, size_t size, size_t n, FSFILE *stream) Summary: Read data from a file Conditions: File is opened in a read mode Input: ptr - Destination buffer for read bytes size - Size of units in bytes n - Number of units to be read stream - File to be read from Return: size_t - number of units read Side Effects: The FSerrno variable will be changed. Description: The FSfread function will read data from the specified file. First, the appropriate sector of the file is loaded. Then, data is read into the specified buffer until the specified number of bytes have been read. When a cluster boundary is reached, a new cluster will be loaded. The parameters 'size' and 'n' indicate how much data to read. 'Size' refers to the size of one object to read (in bytes), and 'n' will refer to the number of these objects to read. The value returned will be equal to 'n' unless an error occured or the user tried to read beyond the end of the file. Remarks: None. **************************************************************************/ size_t FSfread(void *ptr, size_t size, size_t n, FSFILE *stream); /********************************************************************** Function: int FSfseek(FSFILE *stream, long offset, int whence) Summary: Change the current position in a file Conditions: File opened Input: stream - Pointer to file structure offset - Offset from base location whence - - SEEK_SET - Seek from start of file - SEEK_CUR - Seek from current location - SEEK_END - Seek from end of file (subtract offset) Return Values: 0 - Operation successful -1 - Operation unsuccesful Side Effects: The FSerrno variable will be changed. Description: The FSfseek function will change the current position in the file to one specified by the user. First, an absolute offset is calculated using the offset and base location passed in by the user. Then, the position variables are updated, and the sector number that corresponds to the new location. That sector is then loaded. If the offset falls exactly on a cluster boundary, a new cluster will be allocated to the file and the position will be set to the first byte of that cluster. Remarks: None **********************************************************************/ int FSfseek(FSFILE *stream, long offset, int whence); /******************************************************************* Function: long FSftell (FSFILE * fo) Summary: Determine the current location in a file Conditions: File opened Input: fo - Pointer to file structure Return: Current location in the file Side Effects: The FSerrno variable will be changed Description: The FSftell function will return the current position in the file pointed to by 'fo' by returning the 'seek' variable in the FSFILE object, which is used to keep track of the absolute location of the current position in the file. Remarks: None *******************************************************************/ long FSftell(FSFILE *fo); /**************************************************** Function: int FSfeof( FSFILE * stream ) Summary: Indicate whether the current file position is at the end Conditions: File is open in a read mode Input: stream - Pointer to the target file Return Values: Non-Zero - EOF reached 0 - Not at end of File Side Effects: The FSerrno variable will be changed. Description: The FSfeof function will indicate that the end-of- file has been reached for the specified file by comparing the absolute location in the file to the size of the file. Remarks: None. ****************************************************/ int FSfeof( FSFILE * stream ); #ifdef ALLOW_FORMATS /******************************************************************* Function: int FSformat (char mode, long int serialNumber, char * volumeID) Summary: Formats a device Conditions: The device must possess a valid master boot record. Input: mode - - 0 - Just erase the FAT and root - 1 - Create a new boot sector serialNumber - Serial number to write to the card volumeID - Name of the card Return Values: 0 - Format was successful EOF - Format was unsuccessful Side Effects: The FSerrno variable will be changed. Description: The FSformat function can be used to create a new boot sector on a device, based on the information in the master boot record. This function will first initialize the I/O pins and the device, and then attempts to read the master boot record. If the MBR cannot be loaded successfully, the function will fail. Next, if the 'mode' argument is specified as '0' the existing boot sector information will be loaded. If the 'mode' argument is '1' an entirely new boot sector will be constructed using the disk values from the master boot record. Once the boot sector has been successfully loaded/created, the locations of the FAT and root will be loaded from it, and they will be completely erased. If the user has specified a volumeID parameter, a VOLUME attribute entry will be created in the root directory to name the device. FAT12, FAT16 and FAT32 formatting are supported. Based on the number of sectors, the format function automatically compute the smallest possible value for the cluster size in order to accommodate the physical size of the media. In this case, if a media with a big capacity is formatted, the format function may take a very long time to write all the FAT tables. Therefore, the FORMAT_SECTORS_PER_CLUSTER macro may be used to specify the exact cluster size (in multiples of sector size). This macro can be defined in FSconfig.h Remarks: Only devices with a sector size of 512 bytes are supported by the format function *******************************************************************/ int FSformat (char mode, long int serialNumber, char * volumeID); #endif #ifdef ALLOW_WRITES /*************************************************************************** Function: int FSattrib (FSFILE * file, unsigned char attributes) Summary: Change the attributes of a file Conditions: File opened Input: file - Pointer to file structure attributes - The attributes to set for the file - Attribute - Value - Indications - ATTR_READ_ONLY - 0x01 - The read-only attribute - ATTR_HIDDEN - 0x02 - The hidden attribute - ATTR_SYSTEM - 0x04 - The system attribute - ATTR_ARCHIVE - 0x20 - The archive attribute Return Values: 0 - Attribute change was successful -1 - Attribute change was unsuccessful Side Effects: The FSerrno variable will be changed. Description: The FSattrib funciton will set the attributes of the specified file to the attributes passed in by the user. This function will load the file entry, replace the attributes with the ones specified, and write the attributes back. If the specified file is a directory, the directory attribute will be preserved. Remarks: None ***************************************************************************/ int FSattrib (FSFILE * file, unsigned char attributes); /*************************************************************** Function: int FSrename (const rom char * fileName, FSFILE * fo) Summary: Change the Ascii name of a file or directory Conditions: File opened. Input: fileName - The new name of the file fo - The file to rename Return Values: 0 - File was renamed successfully EOF - File was not renamed Side Effects: The FSerrno variable will be changed. Description: The FSrename function will rename a file. First, it will search through the current working directory to ensure the specified new filename is not already in use. If it isn't, the new filename will be written to the file entry of the file pointed to by 'fo.' Remarks: None ***************************************************************/ int FSrename (const char * fileName, FSFILE * fo); #ifdef SUPPORT_LFN /*************************************************************** Function: int wFSrename (const rom unsigned short int * fileName, FSFILE * fo) Summary: Change the name of a file or directory to the UTF16 input fileName Conditions: File opened. Input: fileName - The new name of the file fo - The file to rename Return Values: 0 - File was renamed successfully EOF - File was not renamed Side Effects: The FSerrno variable will be changed. Description: The wFSrename function will rename a file. First, it will search through the current working directory to ensure the specified new UTF16 filename is not already in use. If it isn't, the new filename will be written to the file entry of the file pointed to by 'fo.' Remarks: None ***************************************************************/ int wFSrename (const unsigned short int * fileName, FSFILE * fo); #endif /********************************************************************* Function: int FSremove (const char * fileName) Summary: Delete a Ascii file Conditions: File not opened, file exists Input: fileName - Name of the file to erase Return Values: 0 - File removed EOF - File was not removed Side Effects: The FSerrno variable will be changed. Description: The FSremove function will attempt to find the specified file with the FILEfind function. If the file is found, it will be erased using the FILEerase function.The user can also provide ascii alias name of the ascii long file name as the input to this function to get it erased from the memory. Remarks: None **********************************************************************/ int FSremove (const char * fileName); #ifdef SUPPORT_LFN /********************************************************************* Function: int wFSremove (const unsigned short int * fileName) Summary: Delete a UTF16 file Conditions: File not opened, file exists Input: fileName - Name of the file to erase Return Values: 0 - File removed EOF - File was not removed Side Effects: The FSerrno variable will be changed. Description: The wFSremove function will attempt to find the specified UTF16 file name with the FILEfind function. If the file is found, it will be erased using the FILEerase function. Remarks: None **********************************************************************/ int wFSremove (const unsigned short int * fileName); #endif /********************************************************************************* Function: size_t FSfwrite(const void *data_to_write, size_t size, size_t n, FSFILE *stream) Summary: Write data to a file Conditions: File opened in WRITE, APPEND, WRITE+, APPEND+, READ+ mode Input: data_to_write - Pointer to source buffer size - Size of units in bytes n - Number of units to transfer stream - Pointer to file structure Return: size_t - number of units written Side Effects: The FSerrno variable will be changed. Description: The FSfwrite function will write data to a file. First, the sector that corresponds to the current position in the file will be loaded (if it hasn't already been cached in the global data buffer). Data will then be written to the device from the specified buffer until the specified amount has been written. If the end of a cluster is reached, the next cluster will be loaded, unless the end-of-file flag for the specified file has been set. If it has, a new cluster will be allocated to the file. Finally, the new position and filesize will be stored in the FSFILE object. The parameters 'size' and 'n' indicate how much data to write. 'Size' refers to the size of one object to write (in bytes), and 'n' will refer to the number of these objects to write. The value returned will be equal to 'n' unless an error occured. Remarks: None. *********************************************************************************/ size_t FSfwrite(const void *data_to_write, size_t size, size_t n, FSFILE *stream); #endif #ifdef ALLOW_DIRS /************************************************************************** Function: int FSchdir (char * path) Summary: Change the current working directory as per the path specified in Ascii format Conditions: None Input: path - The path of the directory to change to. Return Values: 0 - The current working directory was changed successfully EOF - The current working directory could not be changed Side Effects: The current working directory may be changed. The FSerrno variable will be changed. Description: The FSchdir function passes a RAM pointer to the path to the chdirhelper function. Remarks: None **************************************************************************/ int FSchdir (char * path); #ifdef SUPPORT_LFN /************************************************************************** Function: int wFSchdir (unsigned short int * path) Summary: Change the current working directory as per the path specified in UTF16 format Conditions: None Input: path - The path of the directory to change to. Return Values: 0 - The current working directory was changed successfully EOF - The current working directory could not be changed Side Effects: The current working directory may be changed. The FSerrno variable will be changed. Description: The FSchdir function passes a RAM pointer to the path to the chdirhelper function. Remarks: None **************************************************************************/ int wFSchdir (unsigned short int * path); #endif /************************************************************** Function: char * FSgetcwd (char * path, int numchars) Summary: Get the current working directory path in Ascii format Conditions: None Input: path - Pointer to the array to return the cwd name in numchars - Number of chars in the path Return Values: char * - The cwd name string pointer (path or defaultArray) NULL - The current working directory name could not be loaded. Side Effects: The FSerrno variable will be changed Description: The FSgetcwd function will get the name of the current working directory and return it to the user. The name will be copied into the buffer pointed to by 'path,' starting at the root directory and copying as many chars as possible before the end of the buffer. The buffer size is indicated by the 'numchars' argument. The first thing this function will do is load the name of the current working directory, if it isn't already present. This could occur if the user switched to the dotdot entry of a subdirectory immediately before calling this function. The function will then copy the current working directory name into the buffer backwards, and insert a backslash character. Next, the function will continuously switch to the previous directories and copy their names backwards into the buffer until it reaches the root. If the buffer overflows, it will be treated as a circular buffer, and data will be copied over existing characters, starting at the beginning. Once the root directory is reached, the text in the buffer will be swapped, so that the buffer contains as much of the current working directory name as possible, starting at the root. Remarks: None **************************************************************/ char * FSgetcwd (char * path, int numbchars); #ifdef SUPPORT_LFN /************************************************************** Function: char * wFSgetcwd (unsigned short int * path, int numchars) Summary: Get the current working directory path in UTF16 format Conditions: None Input: path - Pointer to the array to return the cwd name in numchars - Number of chars in the path Return Values: char * - The cwd name string pointer (path or defaultArray) NULL - The current working directory name could not be loaded. Side Effects: The FSerrno variable will be changed Description: The FSgetcwd function will get the name of the current working directory and return it to the user. The name will be copied into the buffer pointed to by 'path,' starting at the root directory and copying as many chars as possible before the end of the buffer. The buffer size is indicated by the 'numchars' argument. The first thing this function will do is load the name of the current working directory, if it isn't already present. This could occur if the user switched to the dotdot entry of a subdirectory immediately before calling this function. The function will then copy the current working directory name into the buffer backwards, and insert a backslash character. Next, the function will continuously switch to the previous directories and copy their names backwards into the buffer until it reaches the root. If the buffer overflows, it will be treated as a circular buffer, and data will be copied over existing characters, starting at the beginning. Once the root directory is reached, the text in the buffer will be swapped, so that the buffer contains as much of the current working directory name as possible, starting at the root. Remarks: None **************************************************************/ char * wFSgetcwd (unsigned short int * path, int numbchars); #endif #ifdef ALLOW_WRITES /************************************************************************** Function: int FSmkdir (char * path) Summary: Create a directory as per the Ascii input path Conditions: None Input: path - The path of directories to create. Return Values: 0 - The specified directory was created successfully EOF - The specified directory could not be created Side Effects: Will create all non-existent directories in the path. The FSerrno variable will be changed. Description: The FSmkdir function passes a RAM pointer to the path to the mkdirhelper function. Remarks: None **************************************************************************/ int FSmkdir (char * path); #ifdef SUPPORT_LFN /************************************************************************** Function: int wFSmkdir (unsigned short int * path) Summary: Create a directory as per the UTF16 input path Conditions: None Input: path - The path of directories to create. Return Values: 0 - The specified directory was created successfully EOF - The specified directory could not be created Side Effects: Will create all non-existent directories in the path. The FSerrno variable will be changed. Description: The wFSmkdir function passes a RAM pointer to the path to the mkdirhelper function. Remarks: None **************************************************************************/ int wFSmkdir (unsigned short int * path); #endif /************************************************************************** Function: int FSrmdir (char * path) Summary: Delete a directory as per the Ascii input path Conditions: None Input: path - The path of the directory to remove rmsubdirs - - TRUE - All sub-dirs and files in the target dir will be removed - FALSE - FSrmdir will not remove non-empty directories Return Values: 0 - The specified directory was deleted successfully EOF - The specified directory could not be deleted Side Effects: The FSerrno variable will be changed. Description: The FSrmdir function passes a RAM pointer to the path to the rmdirhelper function. Remarks: None. **************************************************************************/ int FSrmdir (char * path, unsigned char rmsubdirs); #ifdef SUPPORT_LFN /************************************************************************** Function: int wFSrmdir (unsigned short int * path, unsigned char rmsubdirs) Summary: Delete a directory as per the UTF16 input path Conditions: None Input: path - The path of the directory to remove rmsubdirs - - TRUE - All sub-dirs and files in the target dir will be removed - FALSE - FSrmdir will not remove non-empty directories Return Values: 0 - The specified directory was deleted successfully EOF - The specified directory could not be deleted Side Effects: The FSerrno variable will be changed. Description: The wFSrmdir function passes a RAM pointer to the path to the rmdirhelper function. Remarks: None. **************************************************************************/ int wFSrmdir (unsigned short int * path, unsigned char rmsubdirs); #endif #endif #endif #ifdef USERDEFINEDCLOCK /*********************************************************************************************************** Function: int SetClockVars (unsigned int year, unsigned char month, unsigned char day, unsigned char hour, unsigned char minute, unsigned char second) Summary: Manually set timestamp variables Conditions: USERDEFINEDCLOCK macro defined in FSconfig.h. Input: year - The year (1980\-2107) month - The month (1\-12) day - The day of the month (1\-31) hour - The hour (0\-23) minute - The minute (0\-59) second - The second (0\-59) Return Values: None Side Effects: Modifies global timing variables Description: Lets the user manually set the timing variables. The values passed in will be converted to the format used by the FAT timestamps. Remarks: Call this before creating a file or directory (set create time) and before closing a file (set last access time, last modified time) ***********************************************************************************************************/ int SetClockVars (unsigned int year, unsigned char month, unsigned char day, unsigned char hour, unsigned char minute, unsigned char second); #endif #ifdef ALLOW_FILESEARCH /*********************************************************************************** Function: int FindFirst (const char * fileName, unsigned int attr, SearchRec * rec) Summary: Initial search function for the input Ascii fileName Conditions: None Input: fileName - The name to search for - Parital string search characters - * - Indicates the rest of the filename or extension can vary (e.g. FILE.*) - ? - Indicates that one character in a filename can vary (e.g. F?LE.T?T) attr - The attributes that a found file may have - ATTR_READ_ONLY - File may be read only - ATTR_HIDDEN - File may be a hidden file - ATTR_SYSTEM - File may be a system file - ATTR_VOLUME - Entry may be a volume label - ATTR_DIRECTORY - File may be a directory - ATTR_ARCHIVE - File may have archive attribute - ATTR_MASK - All attributes rec - pointer to a structure to put the file information in Return Values: 0 - File was found -1 - No file matching the specified criteria was found Side Effects: Search criteria from previous FindFirst call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent FindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed. Description: The FindFirst function will search for a file based on parameters passed in by the user. This function will use the FILEfind function to parse through the current working directory searching for entries that match the specified parameters. If a file is found, its parameters are copied into the SearchRec structure, as are the initial parameters passed in by the user and the position of the file entry in the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation. Remarks: Call FindFirst or FindFirstpgm before calling FindNext ***********************************************************************************/ int FindFirst (const char * fileName, unsigned int attr, SearchRec * rec); #ifdef SUPPORT_LFN /*********************************************************************************** Function: int wFindFirst (const unsigned short int * fileName, unsigned int attr, SearchRec * rec) Summary: Initial search function for the input UTF16 fileName Conditions: None Input: fileName - The name to search for - Parital string search characters - * - Indicates the rest of the filename or extension can vary (e.g. FILE.*) - ? - Indicates that one character in a filename can vary (e.g. F?LE.T?T) attr - The attributes that a found file may have - ATTR_READ_ONLY - File may be read only - ATTR_HIDDEN - File may be a hidden file - ATTR_SYSTEM - File may be a system file - ATTR_VOLUME - Entry may be a volume label - ATTR_DIRECTORY - File may be a directory - ATTR_ARCHIVE - File may have archive attribute - ATTR_MASK - All attributes rec - pointer to a structure to put the file information in Return Values: 0 - File was found -1 - No file matching the specified criteria was found Side Effects: Search criteria from previous wFindFirst call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent wFindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed. Description: The wFindFirst function will search for a file based on parameters passed in by the user. This function will use the FILEfind function to parse through the current working directory searching for entries that match the specified parameters. If a file is found, its parameters are copied into the SearchRec structure, as are the initial parameters passed in by the user and the position of the file entry in the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation. Remarks: Call FindFirst or FindFirstpgm before calling FindNext ***********************************************************************************/ int wFindFirst (const unsigned short int * fileName, unsigned int attr, SearchRec * rec); #endif /********************************************************************** Function: int FindNext (SearchRec * rec) Summary: Sequential search function Conditions: None Input: rec - The structure to store the file information in Return Values: 0 - File was found -1 - No additional files matching the specified criteria were found Side Effects: Search criteria from previous FindNext call on passed SearchRec object will be lost. "utf16LFNfound" is overwritten after subsequent FindFirst/FindNext operations.It is the responsibility of the application to read the "utf16LFNfound" before it is lost.The FSerrno variable will be changed. Description: The FindNext function performs the same function as the FindFirst funciton, except it does not copy any search parameters into the SearchRec structure (only info about found files) and it begins searching at the last directory entry offset at which a file was found, rather than at the beginning of the current working directory.If the return value of the function is 0 then "utf16LFNfoundLength" indicates whether the file found was long file name or short file name(8P3 format). The "utf16LFNfoundLength" is non-zero for long file name and is zero for 8P3 format."utf16LFNfound" points to the address of long file name if found during the operation. Remarks: Call FindFirst or FindFirstpgm before calling this function **********************************************************************/ int FindNext (SearchRec * rec); #endif /********************************************************************** Function: // PIC24/30/33/32 int FSfprintf (FSFILE * fptr, const char * fmt, ...) // PIC18 int FSfpritnf (FSFILE * fptr, const rom char * fmt, ...) Summary: Function to write formatted strings to a file Conditions: For PIC18, integer promotion must be enabled in the project build options menu. File opened in a write mode. Input: fptr - A pointer to the file to write to. fmt - A string of characters and format specifiers to write to the file ... - Additional arguments inserted in the string by format specifiers Returns: The number of characters written to the file Side Effects: The FSerrno variable will be changed. Description: Writes a specially formatted string to a file. Remarks: Consult AN1045 for a full description of how to use format specifiers. **********************************************************************/ #ifdef ALLOW_FSFPRINTF #ifdef __18CXX int FSfprintf (FSFILE *fptr, const rom char *fmt, ...); #else int FSfprintf (FSFILE *fptr, const char * fmt, ...); #endif #endif /************************************************************************** Function: int FSerror (void) Summary: Return an error code for the last function call Conditions: The return value depends on the last function called. Input: None Side Effects: None. Return Values: FSInit - - CE_GOOD ・ No Error - CE_INIT_ERROR ・ The physical media could not be initialized - CE_BAD_SECTOR_READ ・ The MBR or the boot sector could not be read correctly - CE_BAD_PARITION ・ The MBR signature code was incorrect. - CE_NOT_FORMATTED ・ The boot sector signature code was incorrect or indicates an invalid number of bytes per sector. - CE_CARDFAT32 ・ The physical media is FAT32 type (only an error when FAT32 support is disabled). - CE_UNSUPPORTED_FS ・ The device is formatted with an unsupported file system (not FAT12 or 16). FSfopen - - CE_GOOD ・ No Error - CE_NOT_INIT ・ The device has not been initialized. - CE_TOO_MANY_FILES_OPEN ・ The function could not allocate any additional file information to the array of FSFILE structures or the heap. - CE_INVALID_FILENAME ・ The file name argument was invalid. - CE_INVALID_ARGUMENT ・ The user attempted to open a directory in a write mode or specified an invalid mode argument. - CE_FILE_NOT_FOUND ・ The specified file (which was to be opened in read mode) does not exist on the device. - CE_BADCACHEREAD ・ A read from the device failed. - CE_ERASE_FAIL ・ The existing file could not be erased (when opening a file in WRITE mode). - CE_DIR_FULL ・ The directory is full. - CE_DISK_FULL・ The data memory section is full. - CE_WRITE_ERROR ・ A write to the device failed. - CE_SEEK_ERROR ・ The current position in the file could not be set to the end (when the file was opened in APPEND mode). FSfclose - - CE_GOOD ・ No Error - CE_WRITE_ERROR ・ The existing data in the data buffer or the new file entry information could not be written to the device. - CE_BADCACHEREAD ・ The file entry information could not be cached FSfread - - CE_GOOD ・ No Error - CE_WRITEONLY ・ The file was opened in a write-only mode. - CE_WRITE_ERROR ・ The existing data in the data buffer could not be written to the device. - CE_BAD_SECTOR_READ ・ The data sector could not be read. - CE_EOF ・ The end of the file was reached. - CE_COULD_NOT_GET_CLUSTER ・Additional clusters in the file could not be loaded. FSfwrite - - CE_GOOD ・ No Error - CE_READONLY ・ The file was opened in a read-only mode. - CE_WRITE_PROTECTED ・ The device write-protect check function indicated that the device has been write-protected. - CE_WRITE_ERROR ・ There was an error writing data to the device. - CE_BADCACHEREAD ・ The data sector to be modified could not be read from the device. - CE_DISK_FULL ・ All data clusters on the device are in use. FSfseek - - CE_GOOD ・ No Error - CE_WRITE_ERROR ・ The existing data in the data buffer could not be written to the device. - CE_INVALID_ARGUMENT ・ The specified offset exceeds the size of the file. - CE_BADCACHEREAD ・ The sector that contains the new current position could not be loaded. - CE_COULD_NOT_GET_CLUSTER ・Additional clusters in the file could not be loaded/allocated. FSftell - - CE_GOOD ・ No Error FSattrib - - CE_GOOD ・ No Error - CE_INVALID_ARGUMENT ・ The attribute argument was invalid. - CE_BADCACHEREAD ・ The existing file entry information could not be loaded. - CE_WRITE_ERROR ・ The file entry information could not be written to the device. FSrename - - CE_GOOD ・ No Error - CE_FILENOTOPENED ・ A null file pointer was passed into the function. - CE_INVALID_FILENAME ・ The file name passed into the function was invalid. - CE_BADCACHEREAD ・ A read from the device failed. - CE_FILENAME_EXISTS ・ A file with the specified name already exists. - CE_WRITE_ERROR ・ The new file entry data could not be written to the device. FSfeof - - CE_GOOD ・ No Error FSformat - - CE_GOOD ・ No Error - CE_INIT_ERROR ・ The device could not be initialized. - CE_BADCACHEREAD ・ The master boot record or boot sector could not be loaded successfully. - CE_INVALID_ARGUMENT ・ The user selected to create their own boot sector on a device that has no master boot record, or the mode argument was invalid. - CE_WRITE_ERROR ・ The updated MBR/Boot sector could not be written to the device. - CE_BAD_PARTITION ・ The calculated number of sectors per clusters was invalid. - CE_NONSUPPORTED_SIZE ・ The card has too many sectors to be formatted as FAT12 or FAT16. FSremove - - CE_GOOD ・ No Error - CE_WRITE_PROTECTED ・ The device write-protect check function indicated that the device has been write-protected. - CE_INVALID_FILENAME ・ The specified filename was invalid. - CE_FILE_NOT_FOUND ・ The specified file could not be found. - CE_ERASE_FAIL ・ The file could not be erased. FSchdir - - CE_GOOD ・ No Error - CE_INVALID_ARGUMENT ・ The path string was mis-formed or the user tried to change to a non-directory file. - CE_BADCACHEREAD ・ A directory entry could not be cached. - CE_DIR_NOT_FOUND ・ Could not find a directory in the path. FSgetcwd - - CE_GOOD ・ No Error - CE_INVALID_ARGUMENT ・ The user passed a 0-length buffer into the function. - CE_BADCACHEREAD ・ A directory entry could not be cached. - CE_BAD_SECTOR_READ ・ The function could not determine a previous directory of the current working directory. FSmkdir - - CE_GOOD ・ No Error - CE_WRITE_PROTECTED ・ The device write-protect check function indicated that the device has been write-protected. - CE_INVALID_ARGUMENT ・ The path string was mis-formed. - CE_BADCACHEREAD ・ Could not successfully change to a recently created directory to store its dir entry information, or could not cache directory entry information. - CE_INVALID_FILENAME ・ One or more of the directory names has an invalid format. - CE_WRITE_ERROR ・ The existing data in the data buffer could not be written to the device or the dot/dotdot entries could not be written to a newly created directory. - CE_DIR_FULL ・ There are no available dir entries in the CWD. - CE_DISK_FULL ・ There are no available clusters in the data region of the device. FSrmdir - - CE_GOOD ・ No Error - CE_DIR_NOT_FOUND ・ The directory specified could not be found or the function could not change to a subdirectory within the directory to be deleted (when recursive delete is enabled). - CE_INVALID_ARGUMENT ・ The user tried to remove the CWD or root directory. - CE_BADCACHEREAD ・ A directory entry could not be cached. - CE_DIR_NOT_EMPTY ・ The directory to be deleted was not empty and recursive subdirectory removal was disabled. - CE_ERASE_FAIL ・ The directory or one of the directories or files within it could not be deleted. - CE_BAD_SECTOR_READ ・ The function could not determine a previous directory of the CWD. SetClockVars - - CE_GOOD ・ No Error - CE_INVALID_ARGUMENT ・ The time values passed into the function were invalid. FindFirst - - CE_GOOD ・ No Error - CE_INVALID_FILENAME ・ The specified filename was invalid. - CE_FILE_NOT_FOUND ・ No file matching the specified criteria was found. - CE_BADCACHEREAD ・ The file information for the file that was found could not be cached. FindNext - - CE_GOOD ・ No Error - CE_NOT_INIT ・ The SearchRec object was not initialized by a call to FindFirst. - CE_INVALID_ARGUMENT ・ The SearchRec object was initialized in a different directory from the CWD. - CE_INVALID_FILENAME ・ The filename is invalid. - CE_FILE_NOT_FOUND ・ No file matching the specified criteria was found. FSfprintf - - CE_GOOD ・ No Error - CE_WRITE_ERROR ・ Characters could not be written to the file. Description: The FSerror function will return the FSerrno variable. This global variable will have been set to an error value during the last call of a library function. Remarks: None **************************************************************************/ int FSerror (void); /********************************************************************************* Function: int FSCreateMBR (unsigned long firstSector, unsigned long numSectors) Summary: Creates a master boot record Conditions: The I/O pins for the device have been initialized by the InitIO function. Input: firstSector - The first sector of the partition on the device (cannot be 0; that's the MBR) numSectors - The number of sectors available in memory (including the MBR) Return Values: 0 - MBR was created successfully EOF - MBR could not be created Side Effects: None Description: This function can be used to create a master boot record for a device. Note that this function should not be used on a device that is already formatted with a master boot record (i.e. most SD cards, CF cards, USB keys). This function will fill the global data buffer with appropriate partition information for a FAT partition with a type determined by the number of sectors available to the partition. It will then write the MBR information to the first sector on the device. This function should be followed by a call to FSformat, which will create a boot sector, root dir, and FAT appropriate the the information contained in the new master boot record. Note that FSformat only supports FAT12 and FAT16 formatting at this time, and so cannot be used to format a device with more than 0x3FFD5F sectors. Remarks: This function can damage the device being used, and should not be called unless the user is sure about the size of the device and the first sector value. *********************************************************************************/ int FSCreateMBR (unsigned long firstSector, unsigned long numSectors); #ifdef ALLOW_GET_DISK_PROPERTIES /********************************************************************************* Function: void FSGetDiskProperties(FS_DISK_PROPERTIES* properties) Summary: Allows user to get the disk properties (size of disk, free space, etc) Conditions: 1) ALLOW_GET_DISK_PROPERTIES must be defined in FSconfig.h 2) a FS_DISK_PROPERTIES object must be created before the function is called 3) the new_request member of the FS_DISK_PROPERTIES object must be set before calling the function for the first time. This will start a new search. 4) this function should not be called while there is a file open. Close all files before calling this function. Input: properties - a pointer to a FS_DISK_PROPERTIES object where the results should be stored. Return Values: This function returns void. The properties_status of the previous call of this function is located in the properties.status field. This field has the following possible values: FS_GET_PROPERTIES_NO_ERRORS - operation completed without error. Results are in the properties object passed into the function. FS_GET_PROPERTIES_DISK_NOT_MOUNTED - there is no mounted disk. Results in properties object is not valid FS_GET_PROPERTIES_CLUSTER_FAILURE - there was a failure trying to read a cluster from the drive. The results in the properties object is a partial result up until the point of the failure. FS_GET_PROPERTIES_STILL_WORKING - the search for free sectors is still in process. Continue calling this function with the same properties pointer until either the function completes or until the partial results meets the application needs. The properties object contains the partial results of the search and can be used by the application. Side Effects: Can cause errors if called when files are open. Close all files before calling this function. Calling this function without setting the new_request member on the first call can result in undefined behavior and results. Calling this function after a result is returned other than FS_GET_PROPERTIES_STILL_WORKING can result in undefined behavior and results. Description: This function returns the information about the mounted drive. The results member of the properties object passed into the function is populated with the information about the drive. Before starting a new request, the new_request member of the properties input parameter should be set to TRUE. This will initiate a new search request. This function will return before the search is complete with partial results. All of the results except the free_clusters will be correct after the first call. The free_clusters will contain the number of free clusters found up until that point, thus the free_clusters result will continue to grow until the entire drive is searched. If an application only needs to know that a certain number of bytes is available and doesn't need to know the total free size, then this function can be called until the required free size is verified. To continue a search, pass a pointer to the same FS_DISK_PROPERTIES object that was passed in to create the search. A new search request sould be made once this function has returned a value other than FS_GET_PROPERTIES_STILL_WORKING. Continuing a completed search can result in undefined behavior or results. Typical Usage: FS_DISK_PROPERTIES disk_properties; disk_properties.new_request = TRUE; do { FSGetDiskProperties(&disk_properties); } while (disk_properties.properties_status == FS_GET_PROPERTIES_STILL_WORKING); results.disk_format - contains the format of the drive. Valid results are FAT12(1), FAT16(2), or FAT32(3). results.sector_size - the sector size of the mounted drive. Valid values are 512, 1024, 2048, and 4096. results.sectors_per_cluster - the number sectors per cluster. results.total_clusters - the number of total clusters on the drive. This can be used to calculate the total disk size (total_clusters * sectors_per_cluster * sector_size = total size of drive in bytes) results.free_clusters - the number of free (unallocated) clusters on the drive. This can be used to calculate the total free disk size (free_clusters * sectors_per_cluster * sector_size = total size of drive in bytes) Remarks: PIC24F size estimates: Flash - 400 bytes (-Os setting) PIC24F speed estimates: Search takes approximately 7 seconds per Gigabyte of drive space. Speed will vary based on the number of sectors per cluster and the sector size. *********************************************************************************/ void FSGetDiskProperties(FS_DISK_PROPERTIES* properties); #endif #endif