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 |