NXT File Access Functions

The NXT contains a file system capable of holding up to 64-files. Filenames consist of a name that can be up to 15 characters followed by a ‘.’ (period) and a three character file extension.

The NXT file system will support a maximum of 16 open files or search. This includes all open files including those opened by user programs, by file transfer functions over the USB or BT link and by sound and drawing functions (i.e. play a sound file, draw an icon file).

NOTE: The NXT file I/O routines require that you completely write to a file. If you create a file with 200 bytes and then only write 100 bytes to the file you’ll get an error on file close and the file will be deleted!

There is an ‘enum’ definition that defines the possible error codes from the file functions.

 

OpenRead(hFileHandle, nIoResult, nFileSize, sFileName);

Opens 'sFileName' for reading. hFileHandle is used for subsequent reads to this file. nFileSize is filled with the file length. nIoResult is non-zero when error occurs.

 

sFileName must be a valid NXT file name. The file must already exist on the NXT for this function to succeed.

 

OpenWrite(hFileHandle, nIoResult, nFileSize, sFileName);

Opens sFileName for writing with specified size of nFileSize.. hFileHandle is used for subsequent writes to this file. nIoResult is non-zero when error occurs.

 

sFileName must be a valid NXT file name. The file must not already exist on the NXT for this function to succeed.

 

Close(hFileHandle, nIoResult);

Closes the specified file or search  handle (hFileHandle). The close should be the last file I/O operation after all reads or write are completed. nIoResult is non-zero when error occurs.

 

FindFirstFile(hFileHandle, nIoResult, sSearch, sFileName, nFilesize);

This function is used to start searching (iterating) through the list of files on the NXT. nIoResult is non-zero if no files exist in the NXT file system.. ‘sSearch is the pattern match to use for the search string. For example:

“*.*” will find all files

“*.rso” will find all files with file extension “rso” which is the extension used for sound files

 ‘sFileName is the name of the first file found and nFilesize is the number of data bytes in the file.

hFileHandle returns a handle used to keep track of the search. You should use “Close” when the search is finished to release the handle so that the NXT can re-use it

 

FindNextFile(hFileHandle, nIoResult, sFileName, nFilesize);

This function continues a search initiated by “FindFirstFile” function. The parameters have the same meaning as in FindFirstFile.

 

CloseAllHandles(nIoResult);

Internal function, should not be used in user application program.. Closes all handles opened by a program. nIoResult is non-zero when error occurs. This function is used by the NXT firmware at the end of program execution to ensure that all files opened by an application program are closed.

 

Delete(sFileName, nIoResult);

Deletes the specified filename from the NXT. nIoResult is non-zero when error occurs.

 

Rename(sFileName, nIoResult, sOriginalFileName);

Renames a file. nIoResult is non-zero when error occurs.

 

ReadByte(hFileHandle, nIoResult, nParm);

ReadShort(hFileHandle, nIoResult, nParm);

ReadFloat(hFileHandle, nIoResult, fParm);

ReadLong(hFileHandle, nIoResult, nParm);

Reads a numeric  variable of the appropriate type: byte integer or character (1-byte), short integer (2-bytes), long integer (4-bytes) or float (4-bytes) from the open file represented by ‘hFileHandle

 

WriteByte(hFileHandle, nIoResult, nParm);

WriteShort(hFileHandle, nIoResult, nParm);

WriteLong(hFileHandle, nIoResult, nParm);

WriteFloat(hFileHandle, nIoResult, fParm);

Write a numeric variable of the appropriate type: byte integer or character (1-byte), short integer (2-bytes), long integer (4-bytes) or float (4-bytes) to the open file represented by ‘hFileHandle

 

WriteString(hFileHandle, nIoResult, sParm);

Writes a string to the specified file. nIoResult is non-zero when error occurs. sParm is the string to write. The string is written includintga zero-termination character at the end of the string. Also see "WriteText"

 

WriteText(hFileHandle, nIoResult, sParm);

Writes a string to the specified file. nIoResult is non-zero when error occurs. sParm is the string to write. Ther zero-termination character at the end of the string is not writte. Use this routine when writing a text file. The string is written includint a zero-termination character at the end of the string. Also see "WriteString"

 

nAvailFlash

The amount of flash that is currently unused and available for file storage. Units are 1/10 of 1K byte (i.e. 100 bytes).