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, vfsDateAccessed
Contents > 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, vfsDateAccessed
Contents > 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, vfsDateAccessed
Contents > 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, vfsDateAccessed
Contents > 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