General Overview
Starting from Palm OS 4.0, applications can a utilize new set of additional system extensions that provide a unified interface for accessing various expansion capabilities. The simplest examples are SD cards, Compact Flash cards, and so forth. Another possible area is digital cameras, players. and so forth. In other words, expansion technology covers not only I/O and memory gadgets, but also proposes a convenient way for data exchange with other systems.
As a matter of fact, you can divide all this business into two co-operating parts:
- Expansion Manager
- Virtual File System Manager
Palm OS uses a term, 'slot,' to represent physical carrier of media. These slots are managed by slot drivers. Each slot driver encapsulates direct access to given hardware and exposes a set of stanrard services to Expansion Manager. Optionally, slot drives may have interfaces available from file system libraries. A slot driver itself is a shared library of type sysFileTSlotDriver.
The Virtual File System Manager from another side is a software layer that manages all installed file system libraries. The file system is implemented as a shared library of type sysFileTFileSystem. It provides a unified API to applications to get transparent access to different types of file systems such as VFAT (which is natively supported in Palm OS 4.x), HFS, or NFS on many different media types. VFS Manager abstracts all details of underlying file system, so developer can utilize it by one standard manner. You will find API for manipulating files, folders and volumes.
But, obviously VFS Manager won't do its job for free. You will pay for consistent interface to external media and interoperability by additional overhead on all read/write operations. Your responsibility is to decide if application really needs such features. If you are not required to support different media carriers, Data Manager can be a better option to go.
You first will deal with VSF Manager. As was told above, this manager provides a common API to manage and manipulate files, folders, and volumes. In the next sections, you will see all these operations in more details. Expansion Manager capabilities will be covered in the next article.
Standard Folders
You will start your "virtual tour" on Virtual File System Manager stuff by exploring the standard folders existing on expansion card.
| Folder |
Description |
| / |
Root folder for VFAT file system |
| /PALM |
This is a folder where standard Palm applications store their data. Your application can use it as well |
| /PALM/Backup |
Reserved folder for backup purposes |
| /PALM/Programs |
According to its name, it contains different applications and data, but they are not visible for the Launcher |
| /PALM/Launcher |
All applications located under this folder will be automatically added to new category while expansion card will be mounted |
An important thing to note right here is that in cases where the displayed application name and database name are different, application name can be changed if user will copy your application from expansion card to main memory and back to another card. This is due to the database name is used during copy operations to the cards. Besides, there is a notion of 'Default Folder' for specific file types. Virtual File System Manager provides an API to determine these folders' names.
Volume-Related Operations
In case the expansion card is able to support some file system, VFS Manager gives you a unified set of operations your application can proceed on volumes:
Err VFSVolumeFormat(UInt8 flags, UInt16 fsLibRefNum,
VFSAnyMountParamPtr vfsMountParamP)
Err VFSVolumeMount(UInt8 flags, UInt16 fsLibRefNum,
VFSAnyMountParamPtr vfsMountParamP)
Err VFSVolumeUnmount(UInt16 volRefNum)
Err VFSVolumeEnumerate(UInt16 *volRefNumP, UInt32 *volIteratorP)
Err VFSVolumeInfo(UInt16 volRefNum, VolumeInfoType *volInfoP)
Err VFSVolumeGetLabel(UInt16 volRefNum, Char *labelP, UInt16 bufLen)
Err VFSVolumeSetLabel(UInt16 volRefNum, const Char *labelP)
Err VFSVolumeSize(UInt16 volRefNum, UInt32 *volumeUsedP,
UInt32 *volumeTotalP)
You will find the example of using those functions in following sub-topics.
Volume enumeration
This is one of the simplest tasks to be performed. VFSVolumeEnumerate has two parameters, volRefNumP and volIteratorP. volRefNumP on exit keeps the volume reference number or is set to vfsInvalidVolRef in case of errors or no more volumes available. *volIteratorP should be set to vfsIteratorStart before the first call to VFSVolumeEnumerate. You will simply call this function in loop to obtain all available volumes in the system. When iteration is completed, *volIteratorP is set to vfsIteratorStop. When there are no volumes in the system, VFSVolumeEnumerate will return expErrEnumerationEmpty upon the very first call. Below is a small sample of volume enumeration:
Err err = errNone;
UInt16 volRefNum = -1;
UInt32 volIterator = vfsIteratorStart;
while ( volIterator != vfsIteratorStop )
{
err = VFSVolumeEnumerate(&volRefNum, &volIterator);
if (err == errNone)
{
// Do something
}
else
{
// handle the error
}
}
IE 7
Firefox 2.0
