Contents > Library Reference > VFS |
VFS
Objects for accessing the virtual file system on expansion cards.
Objects and Structures
File | Encapsulates a file on external storage. | |
FileStream | Exposes a File as a Stream. | |
Directory | Encapsulates a directory on external storage. | |
Volume | Encapsulates a volume on external storage. | |
VolumeMgr | Exposes an enumeration of Volumes. |
Additional Topics
Using VFS | An overview of using the VFS objects. |
Contents > Library Reference > VFS > File object |
File
The File object encapsulates a file on a external memory card, allowing reading and writing to the file. A File object is retrieved by calling Volume.open(). For error codes and flags, see Using VFS.
Object Properties
int offset | Gets or sets the current file offset. | |
bool eof | True if the end of the file has been reached. | |
int size | Gets or sets the size of the file. When setting, the file is expanded or truncated to the new size. | |
int attribs | Gets or sets the file attributes. |
Object Methods
void close() | Closes the file. | |
int read(void* pdata, string type, int count) | Reads count blocks of data from the file into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset. | |
int write(void* pdata, string type, int count) | Writes count blocks of data to the file from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset. | |
int getRec(int id, DBRecord rec) | Retrieves the record at index id from the file and attaches it to rec. This method can only be called if the current file is a .pdb file. The DBRecord is opened in read-only mode. | |
int getRes(string type, int id, DBRecord rec) | Retrieves the resource of the given type with the specified id from the file and attaches it to rec. This method can only be called if the current file is a .prc file. The DBRecord is opened in read-only mode. | |
void setDate(int which, Date date) | Sets one of the dates associated with the file. | |
Date getDate(int which) | Gets one of the dates associated with the file. |
Contents > Library Reference > VFS > FileStream object |
FileStream
The FileStream is derived from Stream, providing read/write access to a file. To use this object, create and open a File object, assign it to the file property, then call the read and write methods on Stream.
Object Properties
File file | Sets the File object that this stream should read/write to. |
Object Methods
bool read(void* pdata, string type, int count) | Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool write(void* pdata, string type, int count) | Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. | |
bool readInt(int* pi) | Read an int from the stream into the memory pointed to by pi. | |
bool writeInt(int i) | Write an int to the stream. | |
bool readWord(int* pw) | Read an 2-byte word from the stream into the memory pointed to by pw. | |
bool writeWord(int w) | Write a 2-byte word to the stream. | |
bool readFloat(float* pf) | Read a float from the stream into the memory pointed to by pf. | |
bool writeFloat(float f) | Write a float to the stream. | |
bool readString(string* ps) | Read a string from the stream into the memory pointed to by ps. | |
bool writeString(string s) | Write a string to the stream. | |
bool readChar(char* pc) | Read a char from the stream into the memory pointed to by pc. | |
bool writeChar(char c) | Write a char to the stream. |
Contents > Library Reference > VFS > Directory object |
Directory
The Directory object encapsulates a directory on a external memory card, allowing enumeration of its contents. A Directory object is retrieved by calling Volume.openDir(). For error codes and flags, see Using VFS.
Object Properties
int attribs | Gets or sets the file attributes. |
Object Methods
void close() | Closes the directory. | |
void setDate(int which, Date date) | Sets one of the dates associated with the file. | |
Date getDate(int which) | Gets one of the dates associated with the file. | |
bool enumerate(int first, string* name, int* attribs) | Enumerate through files and directories in a directory. |
Contents > Library Reference > VFS > Volume object |
Volume
The Volume object represents an external storage volume, such as a compact flash, SD, or MMC card. This object is used to perform operations on files and directories. A Volume object is retrieved by calling VolumeMgr.enumerate(). For error codes, flags, and a usage overview, see Using VFS.
Object Properties
string label | Gets the Volume's label |
Object Methods
int open(string path, int mode, File file) | Opens the file at path, using the flags specified in mode. | |
int openDir(string path, Directory dir) | Opens the directory at path. | |
create(string path) | Creates an empty file at path. | |
int createDir(string path) | Creates an empty directory at path. | |
int del(string path) | Deletes the file or directory at path. If the path is a directory, it must be empty before calling this method. | |
int rename(string path, string newname) | Rename a file or directory at path to name. path is the complete path, name is just the new file/directory name. | |
int export(string name, string path) | Exports the database specified by name to a file at path. | |
int import(string path, string* name) | Imports the database at path, returning the database name in the string specified by name. | |
string getDefaultDir(string type) | Retrieves the name of the default directory for a given type, such as "image/jpeg". |
Contents > Library Reference > VFS > VolumeMgr object |
VolumeMgr
The VolumeMgr object allows an application to enumerate the volumes present on the device. See Using VFS for VFS usage overview.
Object Methods
bool enumerate(int first, Volume vol) | Enumerate through volumes present on a device. If VFS is not supported by the device, false is returned. |
Contents > Library Reference > VFS > File object > close |
File.close
void close() |
Closes the file.
Contents > Library Reference > VFS > File object > read |
File.read
int read(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: the number of values read
Reads count blocks of data from the file into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.
Contents > Library Reference > VFS > File object > write |
File.write
int write(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: the number of values written
Writes count blocks of data to the file from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type. Advances the current offset.
Contents > Library Reference > VFS > File object > getRec |
File.getRec
int getRec(int id, DBRecord rec) |
Parameters:
id | record index | |
rec | DBRecord to attach |
Return value: 0 if successful, error code otherwise
Retrieves the record at index id from the file and attaches it to rec. This method can only be called if the current file is a .pdb file. The DBRecord is opened in read-only mode.
Contents > Library Reference > VFS > File object > getRes |
File.getRes
int getRes(string type, int id, DBRecord rec) |
Parameters:
type | resource type | |
id | resource id | |
rec | DBRecord to attach |
Return value: 0 if successful, error code otherwise
Retrieves the resource of the given type with the specified id from the file and attaches it to rec. This method can only be called if the current file is a .prc file. The DBRecord is opened in read-only mode.
Contents > Library Reference > VFS > File object > setDate |
File.setDate
void setDate(int which, Date date) |
Parameters:
which | which date to set | |
date | date value |
Sets one of the dates associated with the file.
Note: Valid date ids are: vfsDateCreated, vfsDateModified, vfsDateAccessedContents > Library Reference > VFS > File object > getDate |
File.getDate
Date getDate(int which) |
Parameters:
which | which date to set |
Return value: the date value
Gets one of the dates associated with the file.
Note: Valid date ids are: vfsDateCreated, vfsDateModified, vfsDateAccessedContents > Library Reference > VFS > FileStream object > read |
FileStream.read
bool read(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was read
Reads count blocks of data from the stream into the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > VFS > FileStream object > write |
FileStream.write
bool write(void* pdata, string type, int count) |
Parameters:
pdata | data pointer | |
type | format string | |
count | format count |
Return value: true if all the data was written
Writes count blocks of data to the stream from the memory pointed to by pdata, using the format specified by the type string type. The given memory must be compatible with type.
Contents > Library Reference > VFS > FileStream object > readInt |
FileStream.readInt
bool readInt(int* pi) |
Parameters:
pi | int pointer |
Return value: true if successful
Read an int from the stream into the memory pointed to by pi.
Contents > Library Reference > VFS > FileStream object > writeInt |
FileStream.writeInt
bool writeInt(int i) |
Parameters:
i | int to write |
Return value: true if successful
Write an int to the stream.
Contents > Library Reference > VFS > FileStream object > readWord |
FileStream.readWord
bool readWord(int* pw) |
Parameters:
pw | int pointer |
Return value: true if successful
Read an 2-byte word from the stream into the memory pointed to by pw.
Contents > Library Reference > VFS > FileStream object > writeWord |
FileStream.writeWord
bool writeWord(int w) |
Parameters:
w | word to write |
Return value: true if successful
Write a 2-byte word to the stream.
Contents > Library Reference > VFS > FileStream object > readFloat |
FileStream.readFloat
bool readFloat(float* pf) |
Parameters:
pf | float pointer |
Return value: true if successful
Read a float from the stream into the memory pointed to by pf.
Contents > Library Reference > VFS > FileStream object > writeFloat |
FileStream.writeFloat
bool writeFloat(float f) |
Parameters:
f | float to write |
Return value: true if successful
Write a float to the stream.
Contents > Library Reference > VFS > FileStream object > readString |
FileStream.readString
bool readString(string* ps) |
Parameters:
ps | string pointer |
Return value: true if successful
Read a string from the stream into the memory pointed to by ps.
Contents > Library Reference > VFS > FileStream object > writeString |
FileStream.writeString
bool writeString(string s) |
Parameters:
s | string to write |
Return value: true if successful
Write a string to the stream.
Contents > Library Reference > VFS > FileStream object > readChar |
FileStream.readChar
bool readChar(char* pc) |
Parameters:
pc | char pointer |
Return value: true if successful
Read a char from the stream into the memory pointed to by pc.
Contents > Library Reference > VFS > FileStream object > writeChar |
FileStream.writeChar
bool writeChar(char c) |
Parameters:
c | char to write |
Return value: true if successful
Write a char to the stream.
Contents > Library Reference > VFS > Directory object > close |
Directory.close
void close() |
Closes the directory.
Contents > Library Reference > VFS > Directory object > setDate |
Directory.setDate
void setDate(int which, Date date) |
Parameters:
which | which date to set | |
date | date value |
Sets one of the dates associated with the file.
Note: Valid date ids are: vfsDateCreated, vfsDateModified, vfsDateAccessedContents > Library Reference > VFS > Directory object > getDate |
Directory.getDate
Date getDate(int which) |
Parameters:
which | which date to set |
Return value: the date value
Gets one of the dates associated with the file.
Note: Valid date ids are: vfsDateCreated, vfsDateModified, vfsDateAccessedContents > Library Reference > VFS > Directory object > enumerate |
Directory.enumerate
bool enumerate(int first, string* name, int* attribs) |
Parameters:
first | true to start a new enumeration, false to continue | |
name | string address of the file/directory name | |
attribs | int address of the file/directory attributes |
Return value: true if another entry was found
Enumerate through files and directories in a directory.
Example:
List all files in the root directory
void listFiles(Volume vol) { string name; int attribs; Directory dir; bool first = true; if (vol.openDir("/", dir) == 0) { // open the root directory while (dir.enumerate(first, &name, &attribs)) { first = false; if ((attribs & vfsAttrDirectory) == 0) { // don't list directories alert(name); } } dir.close(); } } |
Contents > Library Reference > VFS > Volume object > open |
Volume.open
int open(string path, int mode, File file) |
Parameters:
path | path to the file | |
mode | open mode | |
file | associated File object |
Return value: 0 if successful, error code otherwise
Opens the file at path, using the flags specified in mode.
Note: mode can be a combination of these flags: vfsModeRead, vfsModeWrite, vfsModeReadWrite, vfsModeCreate, vfsModeTruncate. See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > openDir |
Volume.openDir
int openDir(string path, Directory dir) |
Parameters:
path | path to the directory | |
dir | associated Directory object |
Return value: 0 if successful, error code otherwise
Opens the directory at path.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > create |
Volume.create
create(string path) |
Parameters:
path | path to the file |
Return value:
Creates an empty file at path.
Note: See Using VFS for error codes. Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > createDir |
Volume.createDir
int createDir(string path) |
Parameters:
path | path to the directory |
Return value: 0 if successful, error code otherwise
Creates an empty directory at path.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > del |
Volume.del
int del(string path) |
Parameters:
path | path to file |
Return value: 0 if successful, error code otherwise
Deletes the file or directory at path. If the path is a directory, it must be empty before calling this method.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > rename |
Volume.rename
int rename(string path, string newname) |
Parameters:
path | path to the file | |
newname | new name of the file |
Return value: 0 if successful, error code otherwise
Rename a file or directory at path to name. path is the complete path, name is just the new file/directory name.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > export |
Volume.export
int export(string name, string path) |
Parameters:
name | name of database | |
path | path to exported file |
Return value: 0 if successful, error code otherwise
Exports the database specified by name to a file at path.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > import |
Volume.import
int import(string path, string* name) |
Parameters:
path | path of file to import | |
name | string address of the database name |
Return value: 0 if successful, error code otherwise
Imports the database at path, returning the database name in the string specified by name.
Note: See Using VFS for error codes.Contents > Library Reference > VFS > Volume object > getDefaultDir |
Volume.getDefaultDir
string getDefaultDir(string type) |
Parameters:
type | file type |
Return value: default directory or empty string
Retrieves the name of the default directory for a given type, such as "image/jpeg".
Contents > Library Reference > VFS > VolumeMgr object > enumerate |
VolumeMgr.enumerate
bool enumerate(int first, Volume vol) |
Parameters:
first | true to start a new enumeration, false to continue | |
vol | Volume to retrieve |
Return value: true if another entry was found
Enumerate through volumes present on a device. If VFS is not supported by the device, false is returned.
Example:
List the names of all the volumes present
void listVolumes() { VolumeMgr volMgr; Volume vol; bool first = true; while (volMgr.enumerate(first, vol)) { first = false; alert(vol.label); } } |
Contents > Library Reference > VFS > Using VFS |
Using VFS
The Palm OS support for Virtual File Systems (VFS) allows an application to read and write files to removable storage, such as a compact flash card or memory stick. OrbC support for VFS is provided by the OrbVFS native add-in. To use it, you must add the line below to your application's source code. If your application is not built standalone, you must also ensure that OrbVFS.prc is installed on the device or emulator.
#include "add-ins/OrbVFS.oc"
Each removable storage device contains one or more volumes. To access a file, you must first retrieve the volume on which it resides using VolumeMgr.enumerate(). This method will enumerate all volumes on the device - if the device does not support VFS, no volumes will be returned. Once you have retrieved the Volume object, you can use it to create and open files and directories. To get a list of all the files in a directory, first open the directory with Volume.openDir(), then enumerate through the files and directories using Directory.enumerate(). The get the files in the root directory, call openDir("/").
Unlike traditional operating systems, the Palm OS VFS support does not support a concept of "current directory". Instead, all paths are fully specified for a given volume.
The following error codes may be returned from the VFS methods:
vfsErrFileNotFound | vfsErrDirNotEmpty |
vfsErrFilePermissionDenied | vfsErrBadName |
vfsErrCardReadOnly | vfsErrVolumeFull |
vfsErrFileGeneric | vfsErrNotADirectory |
vfsErrFileStillOpen | vfsErrIsADirectory |
vfsErrFileAlreadyExists | vfsErrDirectoryNotFound |
vfsErrFileEOF | vfsErrNameShortened |
The following attributes may be set on a file or directory:
vfsAttrReadOnly | vfsAttrDirectory |
vfsAttrHidden | vfsAttrArchive |
vfsAttrSystem | vfsAttrLink |
vfsAttrVolumeLabel |