fsystem.h File Reference

FileSystem main header. More...

Go to the source code of this file.

Data Structures

struct  __frag
struct  __buffer
struct  __file
 Main structure FS_FILE. More...

Defines

#define FSATTR_RDONLY   1
 Read only file attribute.
#define FSATTR_HIDDEN   2
 Hidden file attribute.
#define FSATTR_SYSTEM   4
 System file attribute.
#define FSATTR_VOLUME   8
 Volume file attribute.
#define FSATTR_DIR   16
 Directory file attribute.
#define FSATTR_ARCHIVE   32
 Archive file attribute.
#define FSATTR_LONGNAME   0xf
 Special attribute value for long filename entries.
#define FSATTR_LONGMASK   0x3f
 Long filename attribute mask.
#define FSMODE_READ   0
 Read only mode.
#define FSMODE_WRITE   2
 Write mode.
#define FSMODE_APPEND   4
 Append mode.
#define FSMODE_MODIFY   8
 Modify mode.
#define FSMODE_NOGROW   16
 No-growth mode.
#define FSMODE_NOCREATE   32
 Don't create file.
#define FS_OK   1
 Error code: Returned by all functions when there are no errors.
#define FS_ERROR   0
 Error code: Indicates a hardware error or an unknown error.
#define FS_EOF   -1
 Error code: Indicates end-of-file was reached.
#define FS_BADNAME   -2
 Error code: Indicates an invalid file name was given.
#define FS_BADVOLUME   -3
 Error code: Returned when the volume requested doesn't exist.
#define FS_NOTFOUND   -4
 Error code: File not found.
#define FS_CANTWRITE   -5
 Error code: Write operation failed or not permitted.
#define FS_NOCARD   -6
 Error code: No card is currently inserted.
#define FS_CHANGED   -7
 Error code: User has changed the card without unmounting the volumes.
#define FS_MAXFILES   -8
 Error code: Max. number of open files has been reached.
#define FS_OPENDIR   -9
 Error code: The name given correspond to an open directory.
#define FS_OPENFILE   -9
 Error code: The name given corresponds to an open file.
#define FS_USED   -9
 Error code: File/directory is open/referenced/locked.
#define FS_DISKFULL   -10
 Error code: Disk is full.
#define FS_EXIST   -11
 Error code: File already exists.
#define FSCASE_SENS   0
 Case sensitivity mode: RAW case sensitive.
#define FSCASE_SENSHP   1
 Case sensitivity mode: HP compatible case sensitive.
#define FSCASE_INSENS   2
 Case sensitivity mode: Case insensitive.
#define FSCASE_SENSHPTRUE   3
 Case sensitivity mode: HP compatible case sensitive.
#define FSNAME_HASVOL   1
 Name constant: Name includes volume specification.
#define FSNAME_HASPATH   2
 Name constant: Name includes path information.
#define FSNAME_ABSPATH   4
 Name constant: Name has an absolute path.
#define FSNAME_ENDSLASH   8
 Name constant: Name is a directory ended in slash.
#define FSNAME_VOLHP   16
 Name constant: Drive specification is HP style (:x:).
#define FSNAME_EMPTY   32
 Name constant: Name/path does not have a file name.
#define FSNAME_INVALID   -1
 Name constant: Invalid filename.
#define __ICASE(a)   ( ((a>96)&&(a<123))? (a&0xdf):a)
#define __UPPER(a)   ( ((a>96)&&(a<123))? (a&0xdf):a)
#define __LOWER(a)   ( ((a>64)&&(a<91))? (a|0x20):a)

Typedefs

typedef __frag FS_FRAGMENT
typedef __buffer FS_BUFFER
typedef __file FS_FILE

Functions

int FSShutdown ()
 Shutdown file system, close all open files and unmount all volumes.
int FSRestart ()
 Shutdown and reinitialize the file system.
void FSSleep ()
 Stops the clock to the SD card to preserve power.
void FSWakeUp ()
 Restarts the clock to the SD card.
int FSVolumeMounted (int VolNumber)
 Checks if a specified volume is currently mounted.
int FSVolumeInserted (int VolNumber)
 Checks if a specified volume is mounted and inserted.
int FSSetCurrentVolume (int VolNumber)
 Set the current working volume.
int FSGetCurrentVolume ()
 Get the current working volume.
int FSGetVolumeSize (int Volnumber)
 Get the total size of a volume.
int FSGetVolumeFree (int Volnumber)
 Get the free space on a volume.
int FSMkdir (char *name)
 Creates a directory.
int FSRmdir (char *name)
 Delete a directory.
int FSChdir (char *name)
 Changes current working directory.
char * FSGetcwd (int Volume)
 Returns the current work directory for the specified volume.
int FSOpenDir (char *name, FS_FILE **fileptr)
 Open a directory for entry scanning.
int FSGetNextEntry (FS_FILE *entry, FS_FILE *dir)
 Get the next entry from a directory.
void FSReleaseEntry (FS_FILE *file)
 Release dynamically allocated memory on a FS_FILE structure.
int FSCreate (char *name, int attr, FS_FILE **fileptr)
 Create a file.
int FSOpen (char *name, int mode, FS_FILE **fileptr)
 Open a file. Create if it doesn't exist.
int FSClose (FS_FILE *file)
 Close an open file.
int FSCloseAndDelete (FS_FILE *file)
 Close an open file and delete it.
int FSSeek (FS_FILE *file, int Offset, int position)
 Move the current position pointer for read/write.
int FSTell (FS_FILE *file)
 Get the current position pointer for read/write.
int FSRead (char *buffer, int nbytes, FS_FILE *file)
 Read data from a file.
int FSWrite (char *buffer, int nbytes, FS_FILE *file)
 Write data to a file.
int FSEof (FS_FILE *file)
 Detect end-of-file condition.
int FSDelete (char *name)
 Delete a file.
int FSRename (char *oldname, char *newname)
 Rename a file.
int FSNameCompare (char *name1, char *name2, int caseflags)
 Compare two file names.
char * FSGetFileName (FS_FILE *file, int pathflags)
 Obtain the file name.
int FSGetNameType (char *name)
 Get information about a file name.
void FSStripSemi (char *name)
 Strip trailing semicolons.
char * FSGetErrorMsg (int errornum)
 Get error message.
int FSChMode (FS_FILE *file, int newmode)
 Change file access mode.
int FSChAttr (FS_FILE *file, int newattr)
 Change file attributes.
int FSAttr (FS_FILE *file)
 Get file attributes.
int FSFileLength (FS_FILE *file)
 Get file size.
void FSSetCaseMode (int casemode)
 Set the case sensitivity mode.
void FSGetCreatTime (FS_FILE *file, struct tm *timedate)
 Get file creation time and date.
void FSGetWriteTime (FS_FILE *file, struct tm *timedate)
 Get file write time and date.
void FSGetAccessDate (FS_FILE *file, struct tm *timedate)
 Get file access date (no time).


Detailed Description

FileSystem main header.

Definition in file fsystem.h.


Define Documentation

#define __ICASE (  )     ( ((a>96)&&(a<123))? (a&0xdf):a)

Definition at line 317 of file fsystem.h.

#define __LOWER (  )     ( ((a>64)&&(a<91))? (a|0x20):a)

Definition at line 319 of file fsystem.h.

#define __UPPER (  )     ( ((a>96)&&(a<123))? (a&0xdf):a)

Definition at line 318 of file fsystem.h.

#define FS_BADNAME   -2

Error code: Indicates an invalid file name was given.

Definition at line 146 of file fsystem.h.

#define FS_BADVOLUME   -3

Error code: Returned when the volume requested doesn't exist.

Definition at line 150 of file fsystem.h.

#define FS_CANTWRITE   -5

Error code: Write operation failed or not permitted.

Definition at line 158 of file fsystem.h.

#define FS_CHANGED   -7

Error code: User has changed the card without unmounting the volumes.

Definition at line 166 of file fsystem.h.

#define FS_DISKFULL   -10

Error code: Disk is full.

Definition at line 186 of file fsystem.h.

#define FS_EOF   -1

Error code: Indicates end-of-file was reached.

Definition at line 142 of file fsystem.h.

#define FS_ERROR   0

Error code: Indicates a hardware error or an unknown error.

Definition at line 138 of file fsystem.h.

#define FS_EXIST   -11

Error code: File already exists.

Definition at line 190 of file fsystem.h.

#define FS_MAXFILES   -8

Error code: Max. number of open files has been reached.

Definition at line 170 of file fsystem.h.

#define FS_NOCARD   -6

Error code: No card is currently inserted.

Definition at line 162 of file fsystem.h.

#define FS_NOTFOUND   -4

Error code: File not found.

Definition at line 154 of file fsystem.h.

#define FS_OK   1

Error code: Returned by all functions when there are no errors.

Definition at line 134 of file fsystem.h.

#define FS_OPENDIR   -9

Error code: The name given correspond to an open directory.

Definition at line 174 of file fsystem.h.

#define FS_OPENFILE   -9

Error code: The name given corresponds to an open file.

Definition at line 178 of file fsystem.h.

#define FS_USED   -9

Error code: File/directory is open/referenced/locked.

Definition at line 182 of file fsystem.h.

#define FSATTR_ARCHIVE   32

Archive file attribute.

Definition at line 76 of file fsystem.h.

#define FSATTR_DIR   16

Directory file attribute.

Definition at line 72 of file fsystem.h.

#define FSATTR_HIDDEN   2

Hidden file attribute.

Definition at line 60 of file fsystem.h.

#define FSATTR_LONGMASK   0x3f

Long filename attribute mask.

Definition at line 84 of file fsystem.h.

#define FSATTR_LONGNAME   0xf

Special attribute value for long filename entries.

Definition at line 80 of file fsystem.h.

#define FSATTR_RDONLY   1

Read only file attribute.

Definition at line 56 of file fsystem.h.

#define FSATTR_SYSTEM   4

System file attribute.

Definition at line 64 of file fsystem.h.

#define FSATTR_VOLUME   8

Volume file attribute.

Definition at line 68 of file fsystem.h.

#define FSCASE_INSENS   2

Case sensitivity mode: Case insensitive.

In this mode, names are case-insensitive but case-preserving. This mode follows the original FAT specification. The behavior is therefore the usual.

Definition at line 248 of file fsystem.h.

#define FSCASE_SENS   0

Case sensitivity mode: RAW case sensitive.

In this mode, names are case-sensitive: "testfile.dat" and "TestFile.dat" are considered different files. However, the FAT specification indicates that two names that differ only in case cannot coexist in the disk. For example, given a disk with only one file called "TestFile.dat": Trying to open "testfile.dat" will fail (file not found). Trying to create "testfile.dat" will fail (conflicting file name).

Definition at line 207 of file fsystem.h.

#define FSCASE_SENSHP   1

Case sensitivity mode: HP compatible case sensitive.

In this mode, names are case-sensitive: "testfile.dat" and "TestFile.dat" are considered different files. However, the FAT specification indicates that two names that differ only in case cannot coexist in the disk. The file system will add trailing semicolons to the names of conflicting files. Trailing semicolons are ignored in name comparisons and handled transparently. The only consideration that the user must keep in mind is that names having trailing semicolons will be visible on the disk when the disk is either read by another OS, or read in a different case-sensitivity mode. For example, given a disk with only one file called "TestFile.dat": Trying to open "TestFile.dat;" wil open the file "TestFile.dat" Trying to open "TestFile.dat;;;;" will open the file "TestFile.dat" Trying to create "TestFile.dat;" will fail (file already exists) Trying to create "testfile.dat" will create "testfile.dat;" Assuming that "testfile.dat;" exists, trying to open "testfile.dat" will open "testfile.dat;" All directory access functions in this mode will report that the files are "TestFile.dat" and "testfile.dat". All trailing semicolons will be stripped. In case of multiple conflicting files, the system will add multiple trailing semicolons. For example: Create "hello world", OK Create "HELLO world" creates "HELLO world;" Create "HELLO WORLD" creates "HELLO WORLD;;"

Definition at line 239 of file fsystem.h.

#define FSCASE_SENSHPTRUE   3

Case sensitivity mode: HP compatible case sensitive.

This mode provides case-sensitivity with trailing semicolon handling similar to the mode described in FSCASE_SENSHP. The only difference is that file names returned by directory functions will be "true" names. Trailing semicolons will not be stripped, and the name returned matches exactly the name stored in the disk.

Definition at line 260 of file fsystem.h.

#define FSMODE_APPEND   4

Append mode.

Write operations occur only at the end of the file.

Definition at line 105 of file fsystem.h.

#define FSMODE_MODIFY   8

Modify mode.

Write operations occur anywhere in the file. File preserves its original size.

Definition at line 112 of file fsystem.h.

#define FSMODE_NOCREATE   32

Don't create file.

This flag is for the FSOpen function only. If write permission was requested and the file doesn't exist, don't create a new one.

Definition at line 126 of file fsystem.h.

#define FSMODE_NOGROW   16

No-growth mode.

Write operations that require to increase the file size won't be allowed.

Definition at line 119 of file fsystem.h.

#define FSMODE_READ   0

Read only mode.

Write operations won't be allowed on this file.

Definition at line 93 of file fsystem.h.

#define FSMODE_WRITE   2

Write mode.

Write operations truncate the file after the last written byte.

Definition at line 99 of file fsystem.h.

#define FSNAME_ABSPATH   4

Name constant: Name has an absolute path.

Examples: "\mydir"

Definition at line 282 of file fsystem.h.

#define FSNAME_EMPTY   32

Name constant: Name/path does not have a file name.

Examples: "C:", "C:\mydir\", "\"

Definition at line 303 of file fsystem.h.

#define FSNAME_ENDSLASH   8

Name constant: Name is a directory ended in slash.

Examples: "\mydir\subdir\", "mydir/subdir/"

Definition at line 289 of file fsystem.h.

#define FSNAME_HASPATH   2

Name constant: Name includes path information.

Examples: "mydir/name", "../mydir/subdir/name"

Definition at line 275 of file fsystem.h.

#define FSNAME_HASVOL   1

Name constant: Name includes volume specification.

Examples: "C:", ":3:name", "3:\"

Definition at line 268 of file fsystem.h.

#define FSNAME_INVALID   -1

Name constant: Invalid filename.

Examples: "C:\mydir\\file", "\dir\c:",

Definition at line 310 of file fsystem.h.

#define FSNAME_VOLHP   16

Name constant: Drive specification is HP style (:x:).

Examples: ":C:name"

Definition at line 296 of file fsystem.h.


Typedef Documentation

typedef struct __buffer FS_BUFFER

Definition at line 327 of file fsystem.h.

typedef struct __file FS_FILE

Definition at line 329 of file fsystem.h.

typedef struct __frag FS_FRAGMENT

Definition at line 325 of file fsystem.h.


Function Documentation

int FSAttr ( FS_FILE file  ) 

Get file attributes.

Return attribute of a file.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
Returns:
File attributes.
See also:
FSChAttr FSOpen FSGetNextEntry

int FSChAttr ( FS_FILE file,
int  newattr 
)

Change file attributes.

Change the attributes of a file. It does not check for validity of the attribute, so any combination can be used. If the attribute FSATTR_RDONLY is set, the file access mode will be forced to FSMODE_READ.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
newmode One or more FSATTR_XXX constants
Returns:
An FS_XXX error code (see error code constants)
See also:
FSAttr FSChMode FSOpen FSGetNextEntry

int FSChdir ( char *  name  ) 

Changes current working directory.

Changes the current directory. If the name includes a volume, it changes the current directory for that volume but it does not affect the current volume. See FSGetNameType for details about naming conventions.

Parameters:
name Name of the directory to change to
Returns:
An FS_XXX error code (see error code constants)
See also:
FSMkdir FSRmdir FSGetNameType

int FSChMode ( FS_FILE file,
int  newmode 
)

Change file access mode.

Change the access mode of a file.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
newmode One or more FSMODE_XXX constants
Returns:
An FS_XXX error code (see error code constants)
See also:
FSOpen FSWrite

int FSClose ( FS_FILE file  ) 

Close an open file.

Use this function to close a file or directory opened with FSCreate, FSOpen or FSOpenDir. All buffers will be flushed when the file is closed. Important : If FSClose fails to close a file, data may be lost. The user should check for errors and only consider the file closed if FS_OK is returned. On error condition, the user should fix the error and retry.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
Returns:
An FS_XXX error code (see error code constants)
See also:
FSCreate FSOpen FSOpenDir FSCloseAndDelete

int FSCloseAndDelete ( FS_FILE file  ) 

Close an open file and delete it.

Same as FSClose but for temporary files.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
Returns:
An FS_XXX error code (see error code constants)
See also:
FSCreate FSOpen FSOpenDir FSClose

int FSCreate ( char *  name,
int  attr,
FS_FILE **  fileptr 
)

Create a file.

This function creates a file with the given attribute. It allocates a FS_FILE structure and passes a pointer using the fileptr parameter. ONLY when the function returns FS_OK, *fileptr contains a valid FS_FILE pointer. If the file already exists, returns an error and the file won't be overwritten. File is created in write mode. See FSGetNameType for details about naming conventions.

Parameters:
name Name of the file to create. Paths allowed.
attr File attribute
fileptr Address of a (FS_FILE *) pointer to be filled.
Returns:
An FS_XXX error code (see error code constants)
See also:
FSOpen FSClose FS_FILE FSGetNameType

int FSDelete ( char *  name  ) 

Delete a file.

This function deletes a file. See FSGetNameType for details about naming conventions.

Parameters:
name Name of the file to delete.
Returns:
An FS_XXX error code (see error code constants)
See also:
FSRename FSGetNameType

int FSEof ( FS_FILE file  ) 

Detect end-of-file condition.

Returns TRUE if end-of-file was reached after last operation, it returns FALSE otherwise.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
Returns:
TRUE if end-of-file, FALSE otherwise
See also:
FSSeek FSWrite

int FSFileLength ( FS_FILE file  ) 

Get file size.

Return file length in bytes.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
Returns:
File length in bytes.
See also:
FSOpen FSGetNextEntry

void FSGetAccessDate ( FS_FILE file,
struct tm *  timedate 
)

Get file access date (no time).

Return time and date in a tm struct allocated by the user. Time fields of the structure will be zero-filled, since only date is returned. The value corresponds to the last time the user opened the file for either read or write.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
timedate Pointer to tm structure to fill in
Returns:
Function is void, returns time and date filled in tm structure.
See also:
FSGetCreatTime FSGetWriteTime

void FSGetCreatTime ( FS_FILE file,
struct tm *  timedate 
)

Get file creation time and date.

Return time and date in a tm struct allocated by the user.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
timedate Pointer to tm structure to fill in
Returns:
Function is void, returns time and date filled in tm structure.
See also:
FSGetAccessDate FSGetWriteTime

int FSGetCurrentVolume (  ) 

Get the current working volume.

When using multiple volumes on a card, it returns the volume used by default on all operations.

Returns:
Volume number (from 0 to 3), being volume zero the first existing volume in the card
See also:
FSSetCurrentVolume

char* FSGetcwd ( int  Volume  ) 

Returns the current work directory for the specified volume.

Allocates a string and returns the current work directory for the specified volume as a text string. The string won't have an ending slash. Use FSGetCurrentVolume() to get the current directory of the current volume.

Parameters:
Volume Number of the volume to use (0-3)
Returns:
A string containing the directory, NULL if error.
See also:
FSGetCurrentVolume FSChdir

char* FSGetErrorMsg ( int  errornum  ) 

Get error message.

This function returns a pointer to a static string containing an error message.

Parameters:
errornum Error number.
Returns:
Pointer to a static string.
See also:
Error codes (constants)

char* FSGetFileName ( FS_FILE file,
int  pathflags 
)

Obtain the file name.

This function allocates a string, store a copy of the file name and returns a pointer. The user is responsible for freeing the string. May return NULL if insufficient memory to allocate the string. The user can specify the type of output using FSNAME_XXX constants. If FSNAME_ABSPATH is not specified, the path will be relative to the current directory. If the file is not under the current directory, the path will be absolute.

Parameters:
file Pointer to the file's FS_FILE structure
pathflags Any combination of FSNAME_XXX constants
Returns:
A pointer to the allocated string, NULL if error
See also:
FSStripSemi FSGetNameType FSNAME_XXX constants

int FSGetNameType ( char *  name  ) 

Get information about a file name.

This function analyzes a file name, and return a collection of flags. The file system naming convention is as follows: Volumes (drives): Are specified using either a letter or a port number. The four volumes in a card will be mounted to letters C: D: E: F:, and port numbers 3: 4: 5: 6:. Both DOS syntax (C:) and HP calculator syntax (:3:) are accepted and considered equivalent (3: is the same as :3:) Drive letters are case insensitive (c: and C: are the same). Directories: Both forward slash and back slash are accepted and considered equivalent. Names: File and directory names can have up to 255 characters (including a period and the file extension if any). There's no distinction between long and short names. Valid characters are the same as any FAT file system, with the exception of the semicolon, which receives special treatment when working in HP compatible case-sensitive mode. In such mode, trailing semicolons are ignored. See the FSCASE_XXX constants for more details. Examples of valid filenames: 3:\mydir\Hello world.dat :3:/mydir/Hello world.dat :C:mydir\Hello world.dat C:/mydir\Hello world.dat ..\Hello world.dat :c:Hello world.dat

Parameters:
name Name to analyze.
Returns:
Bits 0-15 contain flags, any combination of FSNAME_XXX constants. Bits 16-30 contain the number of subdirectories in the path if any. If the name is invalid, the function returns a negative number.
See also:
FSStripSemi FSGetNameType FSCASE_XXX constants FSNAME_XXX constants

int FSGetNextEntry ( FS_FILE entry,
FS_FILE dir 
)

Get the next entry from a directory.

This function returns the next valid directory entry at the current offset within the directory. It fills a FS_FILE structure allocated by the user and passed as a parameter. All members in the FS_FILE structure will be filled, including date/time, attributes, file length, etc. The FS_FILE structure contains dynamically allocated members that need to be freed using FSReleaseEntry. For every call to this function there should be a corresponding call to FSReleaseEntry. Failure to do so will result in memory leaks. This function returns FS_EOF when there are no more entries in the directory. The FS_FILE structure will contain valid data ONLY when the function returns FS_OK.

Parameters:
entry Pointer to a FS_FILE structure to fill. The caller is responsible for allocating the FS_FILE structure.
dir Pointer to a FS_FILE structure obtained from FSOpenDir
Returns:
An FS_XXX error code (see error code constants)
See also:
FSOpenDir FSReleaseEntry FS_FILE

int FSGetVolumeFree ( int  Volnumber  ) 

Get the free space on a volume.

Get volume total free space, in bytes.

Parameters:
Volnumber Number of the volume (0-3)
Returns:
Free space of the volume in bytes, If error, one of the FS_XXX constants (<=0).
See also:
FSGetVolumeSize

int FSGetVolumeSize ( int  Volnumber  ) 

Get the total size of a volume.

Get volume total size, in bytes.

Parameters:
Volnumber Number of the volume (0-3)
Returns:
Total size of the volume in bytes. If error, one of the FS_XXX constants (<=0).
See also:
FSGetVolumeFree

void FSGetWriteTime ( FS_FILE file,
struct tm *  timedate 
)

Get file write time and date.

Return time and date in a tm struct allocated by the user. This corresponds to the last time the user opened the file for writing.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen or entry obtained from FSGetNextEntry
timedate Pointer to tm structure to fill in
Returns:
Function is void, returns time and date filled in tm structure.
See also:
FSGetAccessDate FSGetCreatTime

int FSMkdir ( char *  name  ) 

Creates a directory.

Creates a directory. See the documentation on FSGetNameType for details about naming conventions.

Parameters:
name Name for the new directory
Returns:
An FS_XXX error code (see error code constants)
See also:
FSChdir FSRmdir FSGetNameType

int FSNameCompare ( char *  name1,
char *  name2,
int  caseflags 
)

Compare two file names.

This function compares two names, according to the case sensitivity mode. In FSCASE_SENS mode, it performs a standard case-sensitive comparison. In FSCASE_SENSHP oR FSCASE_SENSHPTRUE mode, it performs a fully case-sensitive comparison, but trailing semicolons are neglected. In FSCASE_INSENS mode, it performs a case-insensitive comparison.

Parameters:
name1 Name of a file to compare
name2 Name of a file to compare
caseflags One of the FSCASE_XXX constants
Returns:
TRUE if names are equal, FALSE otherwise
See also:
FSStripSemi FSGetNameType FSCASE_XXX constants

int FSOpen ( char *  name,
int  mode,
FS_FILE **  fileptr 
)

Open a file. Create if it doesn't exist.

This function opens a file in the given mode (see FSMODE_XXX constants) It allocates a FS_FILE structure and passes a pointer using the fileptr parameter. ONLY when the function returns FS_OK, *fileptr contains a valid FS_FILE pointer. If the file is open for writing and it doesn't exist then it creates the file. If the file is open in FSMODE_WRITE mode, the file is truncated to length zero if it exists. In FSMODE_APPEND, all write operations will be forced at the end of the file. In FSMODE_MODIFY, write operations can happen anywhere on the file. The initial position will be set at the beginning of the file, same as in write mode but the file won't be truncated. See FSGetNameType for details about naming conventions.

Parameters:
name Name of the file to create. Paths allowed.
mode Read/Write mode (one or more FSMODE_XXX constants)
fileptr Address of a (FS_FILE *) pointer to be filled.
Returns:
An FS_XXX error code (see error code constants)
See also:
FSCreate FSClose FSGetNameType FS_FILE FSMODE_XXX constants

int FSOpenDir ( char *  name,
FS_FILE **  fileptr 
)

Open a directory for entry scanning.

Opens a directory for read, to be scanned using FSGetNextEntry. Use FSClose to close an open directory. See FSGetNameType for details about naming conventions.

Parameters:
name Name of the directory
fileptr Address of a (FS_FILE *) pointer to be filled with the address of a newly created FS_FILE structure
Returns:
An FS_XXX error code (see error code constants)
See also:
FSOpen FSClose FSGetNameType FS_FILE

int FSRead ( char *  buffer,
int  nbytes,
FS_FILE file 
)

Read data from a file.

Read the requested number of bytes into the given buffer, starting at the current position. Position is updated. Trying to read beyond end-of-file will result on a number of bytes read that is lower than the requested number or a zero.

Parameters:
buffer Byte-aligned buffer to store requested data
nbytes Number of bytes requested
file (FS_FILE *) pointer obtained from FSOpen
Returns:
Number of bytes read, 0 if error or end-of-file.
See also:
FSSeek FSWrite

void FSReleaseEntry ( FS_FILE file  ) 

Release dynamically allocated memory on a FS_FILE structure.

This function releases any memory allocated within the FS_FILE structure. The FS_FILE structure itself is NOT freed. Data in the structure should be considered invalid after calling this function.

Parameters:
file Pointer to a FS_FILE structure to release.
See also:
FSGetNextEntry FS_FILE

int FSRename ( char *  oldname,
char *  newname 
)

Rename a file.

This function moves/renames a file. See FSGetNameType for details about naming conventions. If the target name already exists, returns an error. Files must be in the same volume to be moved.

Parameters:
name Name of the file to delete.
Returns:
An FS_XXX error code (see error code constants)
See also:
FSDelete FSGetNameType

int FSRestart (  ) 

Shutdown and reinitialize the file system.

This function forces to close all files, unmount all volumes and remount if a card is inserted. It is usually called whenever a card change is detected. However, if any files are open and the card was changed, data will be lost, so use it with caution.

Returns:
The FS_XXX error code (see error code constants)
See also:
FSShutdown

int FSRmdir ( char *  name  ) 

Delete a directory.

Delete an empty directory, it will fail if the directory contains any files, or if the directory is the current directory. See the documentation on FSGetNameType for details about naming conventions.

Parameters:
name Name for the new directory
Returns:
An FS_XXX error code (see error code constants)
See also:
FSChdir FSMkdir FSGetNameType

int FSSeek ( FS_FILE file,
int  Offset,
int  position 
)

Move the current position pointer for read/write.

Change the current position within the file, to a given offset counting from the specified position (one of the SEEK_XXX constants). Setting a position beyond end-of-file is OK. Negative positions will be set to the beginning of the file.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
Offset Number of bytes to move
position Starting position (one of the SEEK_XXX constants)
Returns:
An FS_XXX error code (see error code constants)
See also:
FSRead FSWrite FSTell

void FSSetCaseMode ( int  casemode  ) 

Set the case sensitivity mode.

Change the case sensitivity mode for all volumes. See the FSCASE_XXX constants for a detailed explanation of the modes.

Parameters:
casemode New case mode. One of the FSCASE_XXX constants
See also:
FSCASE_XXX constants

int FSSetCurrentVolume ( int  VolNumber  ) 

Set the current working volume.

When using multiple volumes on a card, set the volume used by default on all operations.

Parameters:
VolNumber Volume number (from 0 to 3), being volume zero the first existing volume in the card
Returns:
One of the following error codes: FS_OK (current volume was changed), FS_ERROR (volume doesn't exist or other errors)
See also:
FSGetCurrentVolume

int FSShutdown (  ) 

Shutdown file system, close all open files and unmount all volumes.

This function may be called when the program exits or when the file system will no longer be used (recomended to preserve batteries). If the program exits normally by exit() or by returning from main(), this function will be called automatically.

Returns:
An FS_XXX error code (see error code constants)
See also:
FSRestart

void FSSleep (  ) 

Stops the clock to the SD card to preserve power.

If the file system will not be used for a while, use this function to preserve batteries. The clock needs to be restarted using FSWakeUp.

See also:
FSWakeUp

void FSStripSemi ( char *  name  ) 

Strip trailing semicolons.

This function removes all trailing semicolons in the given string. It modifies the original buffer.

Parameters:
name Name of a file to strip
See also:
FSGetNameType FSCASE_XXX constants

int FSTell ( FS_FILE file  ) 

Get the current position pointer for read/write.

Obtain the current position within the file. First byte of the file is offset zero.

Parameters:
file (FS_FILE *) pointer obtained from FSOpen
Returns:
Current position.
See also:
FSRead FSWrite FSSeek

int FSVolumeInserted ( int  VolNumber  ) 

Checks if a specified volume is mounted and inserted.

This function verifies that the volume number given as a parameter is a valid mounted volume and the SD card that contains the volume is currently inserted.

Parameters:
VolNumber Volume number (from 0 to 3), being volume zero the first existing volume in the card
Returns:
One of the following error codes: FS_OK (volume is inserted), FS_NOCARD (no card inserted), FS_CHANGED (user inserted a different card), FS_ERROR (unknown error - hardware/memory)
See also:
FSVolumeMounted

int FSVolumeMounted ( int  VolNumber  ) 

Checks if a specified volume is currently mounted.

This function verifies that the volume number given as a parameter is a valid mounted volume.

Parameters:
VolNumber Volume number (from 0 to 3), being volume zero the first existing volume in the card
Returns:
TRUE if the volume exists and is mounted, FALSE otherwise
See also:
FSVolumeInserted

void FSWakeUp (  ) 

Restarts the clock to the SD card.

Use this function to recover when FSSleep was used

See also:
FSSleep

int FSWrite ( char *  buffer,
int  nbytes,
FS_FILE file 
)

Write data to a file.

Write the requested number of bytes into the given file, starting at the current position. Position is updated. In FSMODE_WRITE mode, file length will be truncated after the written block of data. In FSMODE_APPEND the current position will be moved to the end of the file before writing. If the file was open for read-only, it returns zero.

Parameters:
buffer Byte-aligned buffer with data to write
nbytes Number of bytes requested
file (FS_FILE *) pointer obtained from FSOpen
Returns:
Number of bytes written, 0 if error
See also:
FSSeek FSRead


Generated on Sat Feb 17 00:05:27 2007 for FILESYSTEM by  doxygen 1.5.0