net/fsee.h File Reference


Detailed Description

FSEE Module for Modtronix TCP/IP Stack.

Author:
Modtronix Engineering
Dependencies:
stacktsk.h
Compiler:
MPLAB C18 v2.10 or higher
HITECH PICC-18 V8.35PL3 or higher

Description

This module contains the Modtronix File System code.
For a detailed description, see the File System FSEE section of this document - in [Modules] [System Modules].

Configuration

The following defines are used to configure this module, and should be placed in the projdefs.h (or similar) file. For details, see Project Configuration. To configure the module, the required defines should be uncommended, and the rest commented out.
//*********************************************************************
//--------------------  File System Configuration --------------------
//*********************************************************************
//Defines the maximum size of a file used in the file system.
//When FSEE_FILE_SIZE_16MB is defined, the file system can handle files with a size of up to 16 Mbytes.
//When not defined, the maximum size of a file is 64 Kbyte.
//When defined, the FSEE16M File System will be created.
//when NOT defined, the FSEE File System will be created.
#define FSEE_FILE_SIZE_16MB

//Specifies the maximum number of files that can be open at any one time. When defined as 1, the code
//will be much faster and smaller. This value should not be much less then the the number of HTTP
//Connections, seeing that each HTTP connection can have a open file. If most web page files are
//small (below 2 kbytes) then this is not so important.
#define FSEE_MAX_FILES 1

//When this define is present, the FSEE File System is used as the primary file system. All functions
//Will be remapped to general names, for example fseeOpen() will be mapped to fileOpen. This makes switching
//between different File System much simpler.
#define FSEE_IS_PRIMARY_FS


Data Structures

struct  _FSEE_FILE_INFO

Defines

#define FSEE_FILE   BYTE
#define FSEE_FILE_INVALID   0xff
#define FSEE_FILE_POS   WORD
#define FSEE_MAX_FILES   1
#define FSEE_NOT_AVAILABLE   0xfe
#define FSEE_POS   SWORD
#define FSEE_WRITE_PAGE_SIZE   (64)
#define FSEEFILE_EOF   0x40
#define FSEEFILE_ERROR   0x20
#define FSEEFILE_READING   0x02
#define FSEEFILE_RES   0x80
#define FSEEFILE_USED   0x01
#define FSEEFILE_WRITING   0x04
#define FSEEFLAG_AVAILABLE   0x01
#define FSEEFLAG_READING_WRITING   0x02
#define fseeHasError(fhandle)   (FCB[0].flags & FSEEFILE_ERROR)
#define fseeIsEOF(fhandle)   (FCB[0].flags & FSEEFILE_EOF)
#define fseeIsInUse()   ((fseeFlags & FSEEFLAG_AVAILABLE) == 0)
#define fseeIsOK(fhandle)   (FCB[0].flags & (FSEEFILE_ERROR | FSEEFILE_EOF))
#define fseeIsValidHandle(fhandle)   (fhandle < FSEE_MAX_FILES)

Typedefs

typedef _FSEE_FILE_INFO FSEE_FILE_INFO

Functions

void fseeClose (FSEE_FILE fhandle)
BOOL fseeCloseImage (void)
void fseeFlush (FSEE_FILE fhandle)
BOOL fseeFormat (void)
BYTE fseeGetByte (FSEE_FILE fhandle)
FSEE_POS fseeGetFAT (BYTE *name)
FSEE_FILE_POS fseeGetPos (FSEE_FILE fhandle)
BOOL fseeInit (void)
FSEE_FILE fseeOpen (BYTE *name, BYTE mode)
FSEE_FILE fseeOpenFAT (FSEE_POS fatPos)
BOOL fseeOpenImage (void)
BOOL fseePutByte (FSEE_FILE fhandle, BYTE b)
BOOL fseePutByteImage (BYTE b)
void fseeRelease (FSEE_FILE fhandle)
void fseeSetPos (FSEE_FILE fhandle, FSEE_FILE_POS put)

Variables

FSEE_FILE_INFO FCB [FSEE_MAX_FILES]
BYTE fseeFlags
BYTE fseeOpenCount


Define Documentation

#define FSEE_FILE   BYTE

FILE handle. Each open files is assigned a file handle.

#define FSEE_FILE_INVALID   0xff

When FILE Handle has this value, it indicates an invalid file

#define FSEE_FILE_POS   WORD

FILE position pointer. A variable that can be used to give the offset anywhere in a file. File length

#define FSEE_MAX_FILES   1

#define FSEE_NOT_AVAILABLE   0xfe

When FILE Handle has this value, it indicates that the File System is not available

#define FSEE_POS   SWORD

File System position pointer. A variable that can be used to give the offset anywhere in the File System. File address in the File System

#define FSEE_WRITE_PAGE_SIZE   (64)

#define FSEEFILE_EOF   0x40

FILE flag. When set, indicates that then end of file has been reached.

#define FSEEFILE_ERROR   0x20

FILE flag. When set, indicates that an error has occured with this file.

#define FSEEFILE_READING   0x02

FILE flag. Indicates that we are currently reading from this file. For I2C devices, this means that the memory chip is in sequencial read mode and has control of the I2C bus! Before the bus can be used by any other node, it has to be released!

#define FSEEFILE_RES   0x80

FILE flag. Reserve (don't use) signed bit, is implemented differently by different compilers

#define FSEEFILE_USED   0x01

FILE flag. When set, indicates that this file is being used.

#define FSEEFILE_WRITING   0x04

FILE flag. Indicates that we are currently writing to this file. For I2C devices, this means that the memory chip is in sequencial write mode and has control of the I2C bus! Before the bus can be used by any other node, it has to be released!

#define FSEEFLAG_AVAILABLE   0x01

File System flag. When set, indicates that the File System is available.

#define FSEEFLAG_READING_WRITING   0x02

File System flag. When set, indicates that the File System is currently busy with a read or write operation. This File System can only perform a single read or write operation at any time. This flag is set as soon as a open file is read from or written to. It is cleared as soon as the open file is released or closed.

#define fseeHasError ( fhandle   )     (FCB[0].flags & FSEEFILE_ERROR)

Tests if the last operation on the given file generated an error.

Returns:
TRUE if last operation on file generated and error.
FALSE if otherwise.

#define fseeIsEOF ( fhandle   )     (FCB[0].flags & FSEEFILE_EOF)

Tests if the given file has reached it's EOF. This will happen:

Returns:
TRUE if given file has reached end of file.
FALSE if otherwise.

 
#define fseeIsInUse (  )     ((fseeFlags & FSEEFLAG_AVAILABLE) == 0)

Indicates if the File System is currently in use.

Returns:
TRUE if it is currently being used FALSE if not

#define fseeIsOK ( fhandle   )     (FCB[0].flags & (FSEEFILE_ERROR | FSEEFILE_EOF))

Tests if the last operation on the given file completed without an EOF or Error. If this function returns false, use the fileIsEOF() and fileIsOK() functions to determine exact condition.

Returns:
TRUE if last operation on file was successfull
FALSE if the last operation on the file generated and EOF or Error

#define fseeIsValidHandle ( fhandle   )     (fhandle < FSEE_MAX_FILES)

Tests if the given FILE handle is a valid handle. A valid FILE handle is a value that could be assigned to an open file. Possible invalid FILE handles are FILE_INVALID and FSYS_NOT_AVAILABLE

Returns:
TRUE if given FILE handle value could be a valid FILE handle
FALSE if it is not a possible FILE handle value


Typedef Documentation

typedef struct _FSEE_FILE_INFO FSEE_FILE_INFO

FILE structure. Each file that is opened is assigned a FILE structure by the File System.


Function Documentation

void fseeClose ( FSEE_FILE  fhandle  ) 

Closes the given file. Seeing that the File System can only have a limited amount of files open at any time (defined by FSEE_MAX_FILES), it is very important to call this function after finished with a file!

Parameters:
fhandle FSEE_FILE handle of the file to be released

BOOL fseeCloseImage ( void   ) 

Finishes writing the File System Image

Returns:
TRUE if successful
FALSE otherwise

void fseeFlush ( FSEE_FILE  fhandle  ) 

Finishes writing any data that has not yet been written to the File System. When writing data to a file via the filePutByte() function, it is not always written straight to the File System Media, but some times to an intermediate buffer. This function will write all pending data from the buffer to the File System Media.

BOOL fseeFormat ( void   ) 

Deletes all files present on the File System

Returns:
TRUE if successful
FALSE otherwise

BYTE fseeGetByte ( FSEE_FILE  fhandle  ) 

Reads the next byte from current open file.

Caller must call fileIsEOF() to check for end of file condition before calling this function to make sure the file has not reached it's end. If the fileIsEOF() returns true, then this function will have no affect!

Caller must call fileHasError() function after calling this function to ensure byte was read without error!

This function will place the EEPROM in sequencial read mode and take control of the I2C bus! To allow other devices to use the I2C bus while the file is open, call fileRelease() when finished reading some data. When calling fileRead() after calling fileRelease(), the EEPROM will automatically be placed in sequencial read mode again and take control of the bus.

To read multiple bytes, see ex_file_read.c example file.

Pre-Condition:
fileOpen() != FSEE_FILE_INVALID and
fileGetByteBegin() == TRUE
Parameters:
fhandle FSEE_FILE handle of the file to be released
Returns:
Data byte from current address.

FSEE_POS fseeGetFAT ( BYTE name  ) 

Gets the address in the File System of the requested file's FAT entry. This address can be used as a fast way to open files in the future with the fileOpenFAT() function.

!!! IMPORTANT !!! The File System FAT entry address obtained with the fileGetFAT() function will only be valid as long as no modifications are made to the File System! If after obtaining a address with the fileGetFAT() function the File System is modified, this value might not be valid any more!

FSEE_FILE_POS fseeGetPos ( FSEE_FILE  fhandle  ) 

Get the current file pointer for the given file. This is the offset in the given file that the next read or write will be performed on. This value can be used as a parameter to the fileSetPos() function at a later stage to restore the current file position. This is NOT the file address in the file system.

BOOL fseeInit ( void   ) 

Initializes the Modtronix File System

Returns:
TRUE, if File System Storage access is initialized and File System is is ready to be used
FALSE otherwise

FSEE_FILE fseeOpen ( BYTE name,
BYTE  mode 
)

Opens the given file for reading or writing, and returns a handle to the file. The file pointer (where next read or write will occur) will be positioned at the beginning of the file. To modify the file pointer use the fileSetPos() function.

Parameters:
name NULL terminate file name.
mode Currently not used. All files are opened with read and write permission. When writing to a file, no data can be appended to it!
Returns:
- A FILE Handle (value 0 - 127) if the file is found
  • FSEE_FILE_INVALID if file could not be opened
  • FSEE_NOT_AVAILABLE if the File System is not available

FSEE_FILE fseeOpenFAT ( FSEE_POS  fatPos  ) 

Opens the given file for reading or writing, and returns a handle to the file. The file pointer (where next read or write will occur) will be positioned at the beginning of the file. To modify the file pointer use the fileSetPos() function.

!!! IMPORTANT !!! The File System FAT entry address obtained with the fileGetFAT() function will only be valid as long as no modifications are made to the File System! If after obtaining a address with the fileGetFAT() function the File System is modified, this value might not be valid any more!

Parameters:
fatPos The requested File's FAT address in the File System. This value has to be obtained from a fileGetFAT() function.
Returns:
- A FSEE_FILE Handle (value 0 - 127) if the file is found
  • FSEE_FILE_INVALID if file could not be opened
  • FSEE_NOT_AVAILABLE if the File System is not available

BOOL fseeOpenImage ( void   ) 

Prepares the File System to receive a new Image via following calls to fseePutByteImage()

!!! IMPORTANT !!! This function will overwrite the entire File System! All data will be lost!

Pre-Condition:
No files are allowed to be open! If there are any open files when calling this function, it will return FALSE!
Returns:
TRUE if successful
FALSE otherwise

BOOL fseePutByte ( FSEE_FILE  fhandle,
BYTE  b 
)

Writes a byte to the given file.

Caller must call fileIsEOF() to check for end of file condition before calling this function to make sure the file has not reached it's end. If the fileIsEOF() returns true, then this function will have no affect!

Writes a byte to the current output. Actual write may not get started until internal write page is full. To ensure that previously data gets written, caller must call fileFlush() after last call to filePutByte().

Pre-Condition:
fileOpen() was successfully called.
Parameters:
fhandle FSEE_FILE handle to the file to be activated
b byte to be written
Returns:
TRUE if successful
FALSE if otherwise

BOOL fseePutByteImage ( BYTE  b  ) 

Writes a byte to the File System Image. The File System Image contains the following "FSYS Header", "FAT Entries" and "File Data".

!!! IMPORTANT !!! This function will overwrite the entire File System! All data will be lost!

Pre-Condition:
fseeOpenImage() must have been called.
Returns:
TRUE if successful
FALSE if otherwise

void fseeRelease ( FSEE_FILE  fhandle  ) 

Releases any resources that the given open file might be reserving. On certian File Systems, like ones that use EEPROMs on a shared I2C bus for example, the File System will take control of the bus once a file is opened. To release the bus so it can be used by other modules, the fileRelease() function has to be called. At a later stage, when the file has to be used again, the fileActive() function has to be called.

This function should be called when a file has been opened, and we don't want to close it now, but still want to use it at a later stage. In this case, we can call fileRelease() and suspend operation to the system to perform other tasks. When at a later stage we want to use this file again, fileActivate() will automatically be called by the file read and write functions.

Pre-Condition:
fileOpen() was successfully called.
Parameters:
fhandle FSEE_FILE handle of the file to be released

void fseeSetPos ( FSEE_FILE  fhandle,
FSEE_FILE_POS  put 
)

Set the current file pointer for the given file. This is the offset in the given file that the next read or write will be performed on.


Variable Documentation

FSEE_FILE_INFO FCB[FSEE_MAX_FILES]

BYTE fseeFlags

BYTE fseeOpenCount


Generated on Mon Oct 9 13:22:06 2006 for SBC65EC Web Server by  doxygen 1.4.7