The Virtual File System (VFS) Manager is a layer of software that manages all installed file system libraries. It provides a unified API to application developers while allowing them to seamlessly access many different types of file systems —such as VFAT, HFS, and NFS—on many different types of media, including Compact Flash, Memory Stick, and SmartMedia.This chapter provides reference material for the VFS Manager API, organized as follows:
VFS Manager Structures and Types
VFS Manager Constants
VFS Manager Functions and Macros
Application-Defined Functions
The header file VFSMgr.h
declares the API that this chapter describes.
For more information on file systems in Palm OS® and the VFS Manager, see Chapter 3, "Virtual File Systems."
VFS Manager Structures and Types
FileInfoType Struct
Purpose
Contains information about a specified file or directory.
Declared In
VFSMgr.h
Prototype
typedef struct FileInfoTag { uint32_t attributes; char *nameP; uint16_t nameBufLen; uint16_t reserved; } FileInfoType, *FileInfoPtr
Fields
-
attributes
- Characteristics of the file or directory. See File and Directory Attributes for the bits that make up this field.
-
nameP
- Pointer to the buffer that receives the full name of the file or directory. Initialize this parameter to
NULL
if you don't want to receive the name. -
nameBufLen
- Size of the
nameP
buffer, in bytes. -
reserved
- Reserved for future use.
Comments
This information is returned as a parameter to VFSDirEntryEnumerate()
.
FileOrigin Typedef
Purpose
Encodes references to files and directories.
Declared In
VFSMgr.h
Prototype
typedef uint16_t FileOrigin
FileRef Typedef
Purpose
Container for a reference to an opened file or directory which is supplied to various VFSFile...
operations.
Declared In
VFSMgr.h
Prototype
typedef uint32_t FileRef
Comments
Use VFSFileOpen()
to obtain a FileRef
value.
VFSAnyMountParamType Struct
Purpose
A base structure for VFSSlotMountParamType
, VFSPOSEMountParamType
, and other similar structures that may be defined in the future. Use one or the other according to how you set the mountClass
parameter.
Declared In
VFSMgr.h
Prototype
typedef struct VFSAnyMountParamTag { uint16_t volRefNum; uint16_t size; uint32_t mountClass; } VFSAnyMountParamType
typedef VFSAnyMountParamType *VFSAnyMountParamPtr
Fields
-
volRefNum
- The volume reference number. This is initially obtained when you successfully mount a volume. It can then be used to format a volume with
VFSVolumeFormat()
or unmount a volume withVFSVolumeUnmount()
. -
size
-
mountClass
- Defines the type of mount to use with the specified volume. See Volume Mount Classes for a list of mount types.
VFSPOSEMountParamType Struct
Purpose
When you are mounting a volume through Palm OS® Emulator, the vfsMountParam->mountClass
must be set to VFSMountClass_POSE
. Note that ordinary applications and file systems shouldn't use VFSPOSEMountParamType
.
Declared In
VFSMgr.h
Prototype
typedef struct VFSPOSEMountParamTag { VFSAnyMountParamType vfsMountParam; uint8_t poseSlotNum; uint8_t reserved; uint16_t reserved2; } VFSPOSEMountParamType
Fields
-
vfsMountParam
- See the description of
VFSAnyMountParamType
for an explanation of the fields in this structure. SetvfsMountParam->mountClass
toVFSMountClass_POSE
to mount a virtual slot. -
poseSlotNum
- Number of the virtual slot number to be mounted by Palm OS Emulator.
-
reserved
- Reserved for future use.
-
reserved2
- Reserved for future use.
VFSSlotMountParamType Struct
Purpose
When you are mounting a card located in an Expansion Manager slot, the vfsMountParam->mountClass
field must be set to VFSMountClass_SlotDriver
.
Declared In
VFSMgr.h
Prototype
typedef struct VFSSlotMountParamTag { VFSAnyMountParamType vfsMountParam; uint16_t slotLibRefNum; uint16_t slotRefNum; } VFSSlotMountParamType
Fields
-
vfsMountParam
- See the description of
VFSAnyMountParamType
for an explanation of the fields in this structure. SetvfsMountParam->mountClass
toVFSMountClass_SlotDriver
to mount an Expansion Manager slot. -
slotLibRefNum
- Reference number for the slot driver library allocated to the given slot number.
-
slotRefNum
- Number of the slot to be mounted.
VolumeInfoType Struct
Purpose
Define information that is returned to VFSVolumeInfo()
and used throughout the VFS functions.
Declared In
VFSMgr.h
Prototype
typedef struct VolumeInfoTag { uint32_t attributes; uint32_t fsType; uint32_t fsCreator; uint32_t mountClass; uint16_t slotLibRefNum; uint16_t slotRefNum; uint32_t mediaType; uint32_t reserved; } VolumeInfoType, *VolumeInfoPtr
Fields
-
attributes
- Characteristics of the volume. See Volume Attributes for the bits that make up this field.
-
fsType
- File system type for this volume. See Defined File Systems for a list of the supported file systems.
-
fsCreator
- Creator ID of this volume's file system driver. This information is used with
VFSCustomControl()
. -
mountClass
- Mount class that mounted this volume. The supported mount classes are listed under Volume Mount Classes.
-
slotLibRefNum
- Reference to the slot driver library with which the volume is mounted. This field is only valid when the mount class is
vfsMountClass_SlotDriver
. -
slotRefNum
- Slot number where the card containing the volume is loaded. This field is only valid when the mount class is
vfsMountClass_SlotDriver
. -
mediaType
- Type of card media. See Defined Media Types in Chapter 25, "Expansion Manager," of Exploring Palm OS: System Management for the list of values. This field is only valid when the mount class is
vfsMountClass_SlotDriver
. -
reserved
- Reserved for future use.
VFS Manager Constants
VFS Manager Error Codes
Purpose
Error codes returned by the various VFS Manager functions.
Declared In
VFSMgr.h
Constants
-
#define vfsErrBadData (vfsErrorClass | 12)
- The operation could not be completed because of invalid data.
-
#define vfsErrBadName (vfsErrorClass | 14)
- Invalid filename, path, or volume label.
-
#define vfsErrBufferOverflow (vfsErrorClass | 1)
- The supplied buffer is too small.
-
#define vfsErrDirectoryNotFound (vfsErrorClass | 19)
- Returned when the path leading up to the file does not exist.
-
#define vfsErrDirNotEmpty (vfsErrorClass | 13)
- The directory is not empty and therefore cannot be deleted.
-
#define vfsErrFileAlreadyExists (vfsErrorClass | 6)
- A file with this name exists already in this location.
-
#define vfsErrFileBadRef (vfsErrorClass | 3)
- The file reference is invalid: it has been closed or was not obtained from
VFSFileOpen()
. -
#define vfsErrFileEOF (vfsErrorClass | 7)
- The file pointer is at the end of the file.
-
#define vfsErrFileGeneric (vfsErrorClass | 2)
- Generic file error.
-
#define vfsErrFileNotFound (vfsErrorClass | 8)
- The file was not found at the specified location.
-
#define vfsErrFilePermissionDenied (vfsErrorClass | 5)
- The requested permissions could not be granted.
-
#define vfsErrFileStillOpen (vfsErrorClass | 4)
- Returned from the underlying file system's delete function if the file is still open.
-
#define vfsErrIsADirectory (vfsErrorClass | 18)
- This operation can only be performed on a regular file, not a directory.
-
#define vfsErrNameShortened (vfsErrorClass | 20)
- A volume name or filename was automatically shortened to conform to the file system specification.
-
#define vfsErrNoFileSystem (vfsErrorClass | 11)
- None of the installed file systems support this operation.
-
#define vfsErrNotADirectory (vfsErrorClass | 17)
- This operation can only performed on a directory.
-
#define vfsErrUnimplemented (vfsErrorClass | 16)
-
#define vfsErrVolumeBadRef (vfsErrorClass | 9)
- The volume reference number is invalid.
-
#define vfsErrVolumeFull (vfsErrorClass | 15)
- There is insufficient space left on the volume.
-
#define vfsErrVolumeStillMounted (vfsErrorClass | 10)
- Returned from the underlying file system's format function if the volume is still mounted.
Defined File Systems
Purpose
Identifiers for those file systems that are currently defined by the VFS Manager. These values are used with VFSVolumeInfo()
in the VolumeInfoType.fsType parameter.
Declared In
VFSMgr.h
Constants
-
#define vfsFilesystemType_AFS 'afsu'
- Unix Andrew file system
-
#define vfsFilesystemType_EXT2 'ext2'
- Linux file system
-
#define vfsFilesystemType_FAT 'fats'
- FAT32, FAT16, and FAT12, but only using 8.3 filenames
-
#define vfsFilesystemType_FFS 'ffsb'
- Unix Berkeley block based file system
-
#define vfsFilesystemType_HFS 'hfss'
- Macintosh standard hierarchical file system
-
#define vfsFilesystemType_HFSPlus 'hfse'
- Macintosh extended hierarchical file system
-
#define vfsFilesystemType_HPFS 'hpfs'
- OS2 High Performance file system
-
#define vfsFilesystemType_MFS 'mfso'
- Macintosh original file system
-
#define vfsFilesystemType_NFS 'nfsu'
- Unix Networked file system
-
#define vfsFilesystemType_Novell 'novl'
- Novell file system
-
#define vfsFilesystemType_NTFS 'ntfs'
- Windows NT file system
-
#define vfsFilesystemType_VFAT 'vfat'
- FAT32, FAT16, and FAT12 extended to handle long filenames
Open Mode Constants
Purpose
Modes in which a file or directory is opened. They are used for the openMode
parameter to the VFSFileOpen()
function.
Declared In
VFSMgr.h
Constants
-
#define vfsModeAll (vfsModeExclusive | vfsModeRead | vfsModeWrite | vfsModeCreate | vfsModeTruncate | vfsModeReadWrite | vfsModeLeaveOpen)
- The complete set of open modes.
-
#define vfsModeCreate (0x0008U)
- Create the file if it doesn't already exist. This open mode is implemented in the VFS layer, rather than in the file system library.
-
#define vfsModeExclusive (0x0001U)
- Open and lock the file or directory. This mode excludes anyone else from using the file or directory until it is closed.
-
#define vfsModeLeaveOpen (0x0020U)
- Leave the file open even after the application exits.
-
#define vfsModeRead (0x0002U)
- Open for read access.
-
#define vfsModeReadWrite (vfsModeWrite | vfsModeRead)
- Open for read/write access.
-
#define vfsModeTruncate (0x0010U)
- Truncate the file to zero (0) bytes after opening, removing all existing data. This open mode is implemented in the VFS layer, rather than in the file system library.
-
#define vfsModeVFSLayerOnly (vfsModeCreate | vfsModeTruncate)
- Mask used to isolate those flags that are only used by the VFS layer. These flags are not passed to the file system layer.
-
#define vfsModeWrite (0x0004U | vfsModeExclusive)
- Open for write access.
File and Directory Attributes
Purpose
Bits that can be used individually or in combination when setting or interpreting the file attributes for a given file or directory. See VFSFileGetAttributes()
, VFSFileSetAttributes()
, and the FileInfoType data structure for specific use.
Declared In
VFSMgr.h
Constants
-
#define vfsFileAttrAll (0x0000007fUL)
- The complete set of file and directory attributes.
-
#define vfsFileAttrArchive (0x00000020UL)
- Archived file or directory
-
#define vfsFileAttrDirectory (0x00000010UL)
- Directory
-
#define vfsFileAttrHidden (0x00000002UL)
- Hidden file or directory
-
#define vfsFileAttrLink (0x00000040UL)
- Link to another file or directory
-
#define vfsFileAttrReadOnly (0x00000001UL)
- Read-only file or directory
-
#define vfsFileAttrSystem (0x00000004UL)
- System file or directory
-
#define vfsFileAttrVolumeLabel (0x00000008UL)
- Volume label
Volume Attributes
Purpose
Bits that can be used individually or in combination to make up the attributes field in the VolumeInfoType
structure.
Declared In
VFSMgr.h
Constants
-
#define vfsVolumeAttrHidden (0x00000004UL)
- The volume should not be visible to the user.
-
#define vfsVolumeAttrReadOnly (0x00000002UL)
- The volume is read only.
-
#define vfsVolumeAttrSlotBased (0x00000001UL)
- Reserved. Check the mount class to determine how a volume is mounted.
Volume Mount Classes
Purpose
Define how a given volume is mounted. The mountClass
field in the VFSAnyMountParamType
and VolumeInfoType
structures takes on one of these values.
Declared In
VFSMgr.h
Constants
-
#define vfsMountClass_POSE 'pose'
- Mount the volume through Palm OS Emulator. This is used for testing.
-
#define vfsMountClass_POSE_BE 'esop'
- Mount the volume through Palm OS Emulator, using big-endan ordering. This is used for testing.
-
#define vfsMountClass_SlotDriver sysFileTSlotDriver
- Mount the volume with a slot driver shared library.
-
#define vfsMountClass_SlotDriver_BE 'sbil'
- Mount the volume with a slot driver shared library, using big-endian ordering.
Date Types
Purpose
Dates that can be obtained for an open file or directory.
Declared In
VFSMgr.h
Constants
-
#define vfsFileDateAccessed (3)
- Date the file was last accessed.
-
#define vfsFileDateCreated (1)
- File creation date.
-
#define vfsFileDateModified (2)
- Date the file was last modified.
Comments
Use VFSFileGetDate()
to obtain these dates for an open file or directory, and VFSFileSetDate()
to set them.
Seek Origins
Purpose
File positions to which an offset is added (or subtracted, if the offset is negative) to get a seek position within the file.
Declared In
VFSMgr.h
Compatibility
-
#define vfsOriginBeginning (0)
- The beginning of the file.
-
#define vfsOriginCurrent (1)
- The current position within the file.
-
#define vfsOriginEnd (2)
- The end of the file. Only negative offsets are allowed when
origin
is set tovfsOriginEnd
.
Iterator Controls and Constants
Purpose
Control the directory and volume iteration process.
Declared In
VFSMgr.h
Constants
-
#define vfsIteratorStart (0L)
- Start iterating.
-
#define vfsIteratorStop (0xffffffffL)
- Iteration is complete.
-
#define vfsInvalidFileRef (0L)
- There are no more files to be enumerated or an error occurred.
-
#define vfsInvalidVolRef (0)
- There are no more volumes to be enumerated or an error occurred.
Comments
To iterate the contents of a directory, use VFSDirEntryEnumerate()
. To iterate the contents of a volume, use VFSVolumeEnumerate()
.
Volume Mount Flags
Purpose
Flags that control how a volume is mounted.
Declared In
VFSMgr.h
Constants
-
#define vfsMountFlagsReserved1 (0x08)
- Reserved for future use.
-
#define vfsMountFlagsReserved2 (0x10)
- Reserved for future use.
-
#define vfsMountFlagsReserved3 (0x20)
- Reserved for future use.
-
#define vfsMountFlagsReserved4 (0x40)
- Reserved for future use.
-
#define vfsMountFlagsReserved5 (0x80)
- Reserved for future use.
-
#define vfsMountFlagsUseThisFileSystem (0x01)
- Pass this flag to cause the volume to be mounted or formatted using the file system specified by the specified file system.
Comments
Volumes can be mounted explicitly, with VFSVolumeMount()
, or as part of the volume format process, done with VFSVolumeFormat()
.
Pass no flags (0) to have the VFS Manager attempt to mount or format the volume using a file system appropriate to the slot.
Miscellaneous Constants and Definitions
Purpose
The VFS Manager also includes these #defines
.
Declared In
VFSMgr.h
Constants
-
#define SIZEOF_LargestVFSMountParamType (128)
-
#define SIZEOF_VFSAnyMountParamType (8)
-
#define SIZEOF_VFSPOSEMountParamType (SIZEOF_VFSAnyMountParamType + 4)
-
#define SIZEOF_VFSSlotMountParamType (SIZEOF_VFSAnyMountParamType + 4)
-
#define vfsFtrIDDefaultFS (1)
- Feature number used in conjunction with a creator ID of
sysFileCVFSMgr
to determine the device's default filesystem. -
#define vfsFtrIDVersion (0)
- Feature number used to obtain the version of the VFS Manager in the device's ROM. Use this number in conjunction with a creator ID of
sysFileCVFSMgr
. -
#define vfsHandledStartPrc (0x02)
-
#define vfsHandledUIAppSwitch (0x01)
-
#define vfsMgrVersionNum ((uint16_t)300)
- The version of the VFS Manager APIs in this SDK. Compare this to the value of the
vfsFtrIDVersion
feature.
VFS Manager Functions and Macros
VFSCustomControl Function
Purpose
Make a custom API call to a particular file system, given its creator ID. You can use VFSVolumeInfo()
to determine the creator ID of the file system for a given volume.
Declared In
VFSMgr.h
Prototype
status_t VFSCustomControl ( uint32_tfsCreator
, uint32_tapiCreator
, uint16_tapiSelector
, void*valueP
, uint16_t*valueLenP
)
Parameters
-
→ fsCreator
- Creator of the file system to call. A value of zero (0) tells the VFS Manager to check each registered file system, looking for one which supports the call.
-
→ apiCreator
- Registered creator ID.
-
→ apiSelector
- Custom operation to perform.
-
↔ valueP
- A pointer to a buffer containing data specific to the operation. On exit, depending on the function of the particular custom call and on the value of
valueLenP
, the contents of this buffer may have been updated. -
↔ valueLenP
- On entry, points to the size of the
valueP
buffer. On exit, this value reflects the size of the data written to thevalueP
buffer. IfvalueLenP
isNULL
,valueP
is passed to the file system but is not updated on exit.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
expErrUnsupportedOperation
- The specified opcode and/or creator is unsupported or undefined.
-
sysErrParamErr
- The
valueP
buffer is too small. -
vfsErrNoFileSystem
- VFS Manager cannot find an appropriate file system to handle the request.
Comments
The driver identifies the call and its API by a registered creator ID and a selector. This allows file system developers to extend the API by defining selectors for their creator IDs. It also allows file system developers to support selectors (and custom calls) defined by other file system developers.
This function must return expErrUnsupportedOperation
for all unsupported or undefined opcodes and/or creators.
VFSDirCreate Function
Purpose
Declared In
VFSMgr.h
Prototype
status_t VFSDirCreate ( uint16_tvolRefNum
, const char*dirNameP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
→ dirNameP
- Pointer to the full path of the directory to be created.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- Some or all of the path, up to but not including the last component specified in the
dirNameP
parameter, does not exist. -
vfsErrFileAlreadyExists
- A file with this name already exists in this location.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The volume has not been mounted.
-
vfsErrVolumeFull
- There is not enough space left on the volume.
Comments
All parts of the path except the last component must already exist. The vfsFileAttrDirectory
attribute is set with this function.
VFSDirCreate()
does not open the directory. Any operations you want to perform on this directory require a reference, which is obtained through a call to VFSFileOpen()
.
VFSDirEntryEnumerate Function
Purpose
Enumerate the entries in a given directory. Entries can include files, links, and other directories.
Declared In
VFSMgr.h
Prototype
status_t VFSDirEntryEnumerate ( FileRefdirRef
, uint32_t*dirEntryIteratorP
, FileInfoType*infoP
)
Parameters
-
→ dirRef
- Directory reference returned from
VFSFileOpen()
. -
↔ dirEntryIteratorP
- Pointer to the index of the last entry enumerated. For the first iteration, initialize this parameter to the constant
vfsIteratorStart
. Upon return, this references the next entry in the directory. IfinfoP
is the last entry, this parameter is set tovfsIteratorStop
. -
↔ infoP
- Pointer to the
FileInfoType
data structure that contains information about the given directory entry. ThenameP
andnameBufLen
fields in this structure must be initialized prior to callingVFSDirEntryEnumerate
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrEnumerationEmpty
- There are no directory entries left to enumerate.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
sysErrParamErr
- The
dirEntryIteratorP
is not valid. -
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrIsNotADirectory
- The specified file reference is valid, but does not point to a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
Comments
The directory to be enumerated must first be opened with VFSFileOpen()
in order to obtain a file reference. In order to obtain information on all entries in a directory you must make repeated calls to VFSDirEntryEnumerate
inside a loop. Boundaries on the iteration are the defined constants vfsIteratorStart
and vfsIteratorStop
. Before the first call to VFSDirEntryEnumerate
, dirEntryIteratorP
should be initialized to vfsIteratorStart
. Each iteration then changes the value pointed to by dirEntryIteratorP
. When information on the last entry in the directory is returned, dirEntryIteratorP
is set to vfsIteratorStop
.
WARNING! Creating, renaming, or deleting any file or directory invalidates the enumeration. After any such operation, the enumeration will need to be restarted.
Example
The following code excerpt illustrates how to use VFSDirEntryEnumerate
.
FileInfoType info; FileRef dirRef; UInt32 dirIterator; char *fileName = MemPtrNew(256); // should check for err // open the directory first, to get the directory reference // volRefNum must have already been defined err = VFSFileOpen(volRefNum, "/", vfsModeRead, &dirRef); if(err == errNone) { info.nameP = fileName; // point to local buffer info.nameBufLen = 256; dirIterator = vfsIteratorStart while (dirIterator != vfsIteratorStop) { // Get the next file err = VFSDirEntryEnumerate (dirRef, &dirIterator, &info); if (err == errNone) { // Do something with the directory entry information // Pull the attributes from info.attributes // The file name is in fileName } else { // handle error, possibly by breaking out of the loop } } else { // handle directory open error here } MemPtrFree(fileName); }
VFSExportDatabaseToFile Function
Purpose
Save the specified database to a PDB or PRC file on an external storage card.
Declared In
VFSMgr.h
Prototype
status_t VFSExportDatabaseToFile ( uint16_tvolRefNum
, const char*pathNameP
, DatabaseIDdbID
)
Parameters
-
→ volRefNum
- Volume on which the destination file should be created.
-
→ pathNameP
- Pointer to the complete path and name of the destination file to be created.
-
→ dbID
- ID of the database being exported.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to perform the database export operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
Comments
This utility function exports a database from main memory to a PDB or PRC file on an external storage card. This function is the opposite of VFSImportDatabaseFromFile()
. It first creates the file specified in the pathNameP
parameter with VFSFileCreate()
. After opening the file the Exchange Manager function ExgDBWrite()
is called with an internal callback function for exporting the file from the Data Manager. The Exchange Manager makes repeated calls to this callback function, which receives the data back in blocks. Once all the data has been exported, VFS Manager closes the file.
This function is used, for example, to copy applications from main memory to a storage card.
See Also
VFSExportDatabaseToFileCustom()
, VFSFileWrite()
, VFSImportDatabaseFromFile()
VFSExportDatabaseToFileCustom Function
Purpose
Save the specified database to a PDB or PRC file on an external storage card. This function differs from VFSExportDatabaseToFile()
in that it allows you to track the progress of the export operation.
Declared In
VFSMgr.h
Prototype
status_t VFSExportDatabaseToFileCustom ( uint16_tvolRefNum
, const char*pathNameP
, DatabaseIDdbID
, VFSExportProcPtrexportProcP
, void*userDataP
)
Parameters
-
→ volRefNum
- Volume on which the destination file should be created.
-
→ pathNameP
- Pointer to the complete path and name of the destination file to be created.
-
→ dbID
- ID of the database being exported.
-
→ exportProcP
- User-defined callback function that tracks the progress of the export. This function should allow the user to cancel the export. Pass
NULL
if you don't have a progress callback function. SeeVFSExportProcPtr()
for the requirements of this function. -
→ userDataP
- Pointer to any data you want to pass to the callback function specified in
exportProcP
. This information is not used internally by the VFS Manager. PassNULL
if you don't have a progress callback function or if that function doesn't need any such data.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to perform the database export operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
This function can also return any error code other than errNone
produced by your callback function.
Comments
This function is similar to VFSExportDatabaseToFile()
in that it exports a database from main memory to a PDB or PRC file on an external storage card. It extends the functionality by allowing you to specify a callback function that tracks the progress of the export. It first creates the file specified in the pathNameP
parameter with VFSFileCreate()
. After opening the file, the Exchange Manager function ExgDBWrite()
is called with an internal callback function for exporting the file from the Data Manager. Exchange Manager makes repeated calls to this function, which receives the data back in blocks. The progress tracker, if one has been specified, is also called every time a new chunk of data is passed back. Once all the data has been exported, the VFS Manager closes the file.
See Also
VFSExportDatabaseToFile()
, VFSFileWrite()
, VFSImportDatabaseFromFileCustom()
VFSExportDatabaseToFileCustomV40 Function
Purpose
Save the specified database to a PDB or PRC file on an external storage card. This function differs from VFSExportDatabaseToFile()
in that it allows you to track the progress of the export operation.
Declared In
VFSMgr.h
Prototype
status_t VFSExportDatabaseToFileCustomV40 ( uint16_tvolRefNum
, const char*pathNameP
, uint16_tcardNo
, LocalIDdbID
, VFSExportProcPtrexportProcP
, void*userDataP
)
Parameters
-
→ volRefNum
- Volume on which the destination file should be created.
-
→ pathNameP
- Pointer to the complete path and name of the destination file to be created.
-
→ cardNo
- Card number on which the PDB or PRC being exported resides.
-
→ dbID
- ID of the database being exported.
-
→ exportProcP
- User-defined callback function that tracks the progress of the export. This function should allow the user to cancel the export. Pass
NULL
if you don't have a progress callback function. SeeVFSExportProcPtr()
for the requirements of this function. -
→ userDataP
- Pointer to any data you want to pass to the callback function specified in
exportProcP
. This information is not used internally by the VFS Manager. PassNULL
if you don't have a progress callback function or if that function doesn't need any such data.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to perform the database export operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
This function can also return any error code other than errNone
produced by your callback function.
Comments
This function is similar to VFSExportDatabaseToFile()
in that it exports a database from main memory to a PDB or PRC file on an external storage card. It extends the functionality by allowing you to specify a callback function that tracks the progress of the export. It first creates the file specified in the pathNameP
parameter with VFSFileCreate()
. After opening the file, the Exchange Manager function ExgDBWrite()
is called with an internal callback function for exporting the file from the Data Manager. Exchange Manager makes repeated calls to this function, which receives the data back in blocks. The progress tracker, if one has been specified, is also called every time a new chunk of data is passed back. Once all the data has been exported, the VFS Manager closes the file.
This function is used, for example, to copy applications from main memory to a storage card.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS; the cardNo
parameter is ignored.
See Also
VFSExportDatabaseToFile()
, VFSFileWrite()
, VFSImportDatabaseFromFileCustom()
VFSExportDatabaseToFileV40 Function
Purpose
Save the specified database to a PDB or PRC file on an external storage card.
Declared In
VFSMgr.h
Prototype
status_t VFSExportDatabaseToFileV40 ( uint16_tvolRefNum
, const char*pathNameP
, uint16_tcardNo
, LocalIDdbID
)
Parameters
-
→ volRefNum
- Volume on which the destination file should be created.
-
→ pathNameP
- Pointer to the complete path and name of the destination file to be created.
-
→ cardNo
- Card number on which the PDB or PRC being exported resides.
-
→ dbID
- ID of the database being exported.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to perform the database export operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
Comments
This utility function exports a database from main memory to a PDB or PRC file on an external storage card. This function is the opposite of VFSImportDatabaseFromFile()
. It first creates the file specified in the pathNameP
parameter with VFSFileCreate()
. After opening the file the Exchange Manager function ExgDBWrite()
is called with an internal callback function for exporting the file from the Data Manager. The Exchange Manager makes repeated calls to this callback function, which receives the data back in blocks. Once all the data has been exported, VFS Manager closes the file.
This function is used, for example, to copy applications from main memory to a storage card.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS; the cardNo
parameter is ignored.
See Also
VFSExportDatabaseToFileCustom()
, VFSFileWrite()
, VFSImportDatabaseFromFile()
VFSFileClose Function
Purpose
Close a file or directory that has been opened with VFSFileOpen()
.
Declared In
VFSMgr.h
Prototype
status_t VFSFileClose (
FileRef fileRef
)
Parameters
-
→ fileRef
- File reference number returned from
VFSFileOpen()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
VFSFileCreate Function
Purpose
Create a file. This function cannot be used to create a directory; use VFSDirCreate()
instead.
Declared In
VFSMgr.h
Prototype
status_t VFSFileCreate ( uint16_tvolRefNum
, const char*pathNameP
)
Parameters
-
→ volRefNum
- Reference number of the volume on which to create the file. This volume reference number is returned from
VFSVolumeEnumerate()
. -
→ pathNameP
- Pointer to the full path of the file to be created. All parts of the path, excluding the filename, must already exist.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The
pathNameP
is invalid. -
vfsErrFileAlreadyExists
- A file with this name already exists in this location.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The volume has not been mounted.
-
vfsErrVolumeFull
- There is not enough space left on the volume.
Comments
It is the responsibility of the file system library to ensure that all filenames are translated into a format that is compatible with the native format of the file system, such as the 8.3 convention for a FAT file system without long filename support. See "Naming Files" for a description of how to construct a valid path.
This function does not open the file. Use VFSFileOpen()
to open the file.
This function should not be used to create a directory. To create a directory use VFSDirCreate()
.
See Also
VFSFileDBGetRecord Function
Purpose
Load a record from an opened PDB file on an external card into the storage heap.
Declared In
VFSMgr.h
Prototype
status_t VFSFileDBGetRecord ( FileRefref
, uint16_trecIndex
, MemHandle*recHP
, uint8_t*recAttrP
, uint32_t*uniqueIDP
)
Parameters
-
→ ref
- The file reference returned from
VFSFileOpen()
. Note that the open file must be a PDB file. -
→ recIndex
- The index of the record to load.
-
← recHP
- Pointer to the record data's handle in the storage heap. If
NULL
is returned in this parameter there is either no data in this field or an error occurred reading this data from the file. If the handle is notNULL
, you must dispose of the allocated handle usingMemHandleFree()
. -
← recAttrP
- Pointer to the attributes of the record. The values returned are identical to the atttributes returned from
DmRecordInfoV50()
. See "Non-Schema Database Record Attributes" for a description of each attribute. PassNULL
for this parameter if you do not want to retrieve this information. -
← uniqueIDP
- Pointer to the unique identifier for this record. Pass
NULL
for this parameter if you do not want to retrieve this information.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrIndexOutOfRange
- The
recIndex
is out of range. -
dmErrNotRecordDB
- The file referenced by
ref
is not a record database. -
memErrNotEnoughSpace
- There is not enough space in memory for the requested record entry.
-
sysErrParamErr
- A
NULL
value was passed in for therecHP
,recAttrP
, anduniqueIDP
parameters. -
vfsErrBadData
- The local offsets (
localChunkID
) from the top of the PDB to the start of the raw record data for this entry are out of order.
Comments
This function is analogous to DmGetRecord()
but works with files on an external card rather than databases in main memory. This function allocates a handle of the appropriate size from the storage heap and returns it in the recHP
parameter. The caller is responsible for freeing this memory, using MemHandleFree()
, when it is no longer needed.
See Also
VFSFileDBGetResource Function
Purpose
Load a resource into the storage heap from an opened PRC file.
Declared In
VFSMgr.h
Prototype
status_t VFSFileDBGetResource ( FileRefref
, DmResourceTypetype
, DmResourceIDresID
, MemHandle*resHP
)
Parameters
-
→ ref
- The file reference returned from
VFSFileOpen()
. Note that the open file must be aPRC
file. -
→ type
- The type of resource to load. See Chapter 2, "Palm OS Databases," for more information on resources.
-
→ resID
- The ID of resource to load.
-
← resHP
- Pointer to the resource data handle that was loaded into memory.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrNotResourceDB
- The file referenced by
ref
is not a resource database. -
dmErrResourceNotFound
- The requested resource was not found.
-
memErrNotEnoughSpace
- There is not enough space in memory for the requested resource entries.
-
sysErrParamErr
-
resHP
isNULL
.
Comments
This function locates the specified resource in the open PRC file. See Exploring Palm OS: Palm OS File Formats for more information on the layout of PRC files.
Once the resource is found, VFSFileDBGetResource
allocates a handle of the appropriate size in the storage heap and reads it into memory. The handle to this memory location is returned through the resHP
parameter. The caller is responsible for freeing this memory, using MemHandleFree()
, when it is no longer needed.
VFSFileDBInfo Function
Purpose
Get information about a database represented by an open PRC or PDB file.
Declared In
VFSMgr.h
Prototype
status_t VFSFileDBInfo ( FileRefref
, char*nameP
, uint16_t*attributesP
, uint16_t*versionP
, uint32_t*crDateP
, uint32_t*modDateP
, uint32_t*bckUpDateP
, uint32_t*modNumP
, MemHandle*appInfoHP
, MemHandle*sortInfoHP
, uint32_t*typeP
, uint32_t*creatorP
, uint16_t*numRecordsP
)
Parameters
-
→ ref
- The file reference returned from
VFSFileOpen()
. Note that the open file must be a PRC or PDB file. -
← nameP
- Pointer to a 32-byte character array in which the database name is returned. Pass
NULL
for this parameter if you do not want to retrieve the database name. -
← attributesP
- Pointer to the database attributes stored in the file. The values returned are identical to the atttributes returned from
DmDatabaseInfo()
. See "Database Attributes" for a description of each attribute. PassNULL
for this parameter if you do not want to retrieve the database's attributes. -
← versionP
- Pointer to the application-specific version number of the database. The default version number is zero (0). Pass
NULL
for this parameter if you do not want to retrieve the version number. -
← crDateP
- Pointer to the date the database was created, expressed in seconds since midnight (00:00:00) January 1, 1904. Pass
NULL
for this parameter if you do not want to retrieve the creation date. -
← modDateP
- Pointer to the date the database was last modified, expressed in seconds since midnight (00:00:00) January 1, 1904. A database's modification date is updated only if a change has been made to the database when it is opened with write access. Pass
NULL
for this parameter if you do not want to retrieve the database's modification date. -
← bckUpDateP
- Pointer to the date the database was last backed up, expressed in seconds since midnight (00:00:00) January 1, 1904. Pass
NULL
for this parameter if you do not want to retrieve the database's backup date. -
← modNumP
- Pointer to the number of times the database was modified. This number is updated every time a record is added, modified, or deleted. Pass
NULL
for this parameter if you do not want to retrieve the modification count. -
← appInfoHP
- Pointer to the application info block handle. If
NULL
is returned in this parameter, either there is no data in this field or an error occurred reading this data from the file. If a value other thanNULL
is returned, you must dispose of the allocated handle usingMemHandleFree()
. If you do not want to retrieve the application info block, passNULL
for this parameter. -
← sortInfoHP
- Pointer to the sort info block handle. If
NULL
is returned in this parameter, either there is no data in this field or an error occurred reading this data from the file. If a value other thanNULL
is returned, you must dispose of the allocated handle usingMemHandleFree()
. PassNULL
for this parameter if you do not want to retrieve the sort info block handle. -
← typeP
- Pointer to the type of database as it was created. This may be a user-defined database type or a database type defined by Palm OS. Some of the more common database types returned here are:
-
'appl'
- Standard Palm™ application (resource database)
-
'libr'
- Standard shared library
-
'libf'
- File system shared library
-
'libs'
- Slot driver shared library
-
'data'
- Standard Palm data file (record database)
- Pass
NULL
for this parameter if you do not want to retrieve the database's type. -
← creatorP
- Pointer to the database's creator. Pass NULL for this parameter if you do not want to retrieve this information.
-
← numRecordsP
- Pointer to the number of records in the database. Pass
NULL
for this parameter if you do not want to retrieve this information.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
memErrNotEnoughSpace
- There is not enough space in memory for the database header.
-
vfsErrBadData
- The file referenced by the
ref
parameter is too small to contain a database header, or the database header is corrupted.
Comments
This function is analogous to DmDatabaseInfo()
, but it works with files on an external card rather than with databases in main memory. See Exploring Palm OS: Palm OS File Formats for a description of the header block in PRC and PDB files.
See Also
VFSFileGetAttributes()
, VFSFileGetDate()
VFSFileDelete Function
Purpose
Delete a closed file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileDelete ( uint16_tvolRefNum
, const char*pathNameP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
→ pathNameP
- Pointer to the full path of the file or directory to be deleted.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid. -
vfsErrDirNotEmpty
- The directory being deleted is not empty.
-
vfsErrFileStillOpen
- The file is still open.
-
vfsErrFileNotFound
- The file could not be found.
-
vfsErrFilePermissionDenied
- The requested permissions could not be granted.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The volume has not been mounted.
VFSFileEOF Function
Purpose
Get end-of-file status for an open file. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileEOF (
FileRef fileRef
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
vfsErrFileEOF
- The file pointer is at the end of file.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
VFSFileGetAttributes Function
Purpose
Obtain the attributes of an open file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileGetAttributes ( FileReffileRef
, uint32_t*attributesP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
← attributesP
- Pointer to the attributes associated with the file or directory. See "File and Directory Attributes" for a list of values that can be returned through this parameter.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
See Also
VFSFileDBInfo()
, VFSFileGetDate()
, VFSFileSetAttributes()
VFSFileGetDate Function
Purpose
Obtain the dates on an open file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileGetDate ( FileReffileRef
, uint16_twhichDate
, uint32_t*dateP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ whichDate
- Specifies which date—creation, modification, or last access—you want. Supply one of the values listed under "Date Types."
-
← dateP
- Pointer to the requested date. This field is expressed in the standard Palm OS date format — the number of seconds since midnight (00:00:00) January 1, 1904.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
expErrUnsupportedOperation
- The specified date type is not supported by the underlying file system.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
sysErrParamErr
- The
whichDate
parameter is not one of the defined constants.
Comments
Note that not all file systems are required to support all date types. If the supplied date type is not supported by the file system, VFSFileGetDate
returns expErrUnsupportedOperation
.
See Also
VFSFileDBInfo()
, VFSFileGetAttributes()
, VFSFileSetDate()
VFSFileOpen Function
Purpose
Open a file or directory and returns a reference for it.
Declared In
VFSMgr.h
Prototype
status_t VFSFileOpen ( uint16_tvolRefNum
, const char*pathNameP
, uint16_topenMode
, FileRef*fileRefP
)
Parameters
-
→ volRefNum
- The volume reference number returned from
VFSVolumeEnumerate()
. -
→ pathNameP
- Pointer to the full path of the file or directory to be opened. This must be a valid path. It cannot be empty and can not contain null characters. The format of the pathname should match what the underlying file system supports. See "Naming Files" for a description of how to construct a valid path.
-
→ openMode
- Mode to use when opening the file. See "Open Mode Constants" for a list of accepted modes.
-
← fileRefP
- Pointer to the opened file or directory reference which is supplied to various other
VFSFile...
operations. This value is filled in on return.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrCardReadOnly
- The open mode requested includes write access but the file is read-only.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The
pathNameP
parameter is invalid. -
vfsErrFileNotFound
- The specified file or directory could not be found.
-
vfsErrFilePermissionDenied
- The file cannot be opened in the requested open mode, or it has already been opened with
vfsModeExclusive
. -
vfsErrVolumeBadRef
- The specified volume has not been mounted.
See Also
VFSFileClose()
, VFSDirEntryEnumerate()
, VFSFileOpenFromURL()
VFSFileOpenFromURL Function
Purpose
Open a file or directory given a URL to that file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileOpenFromURL ( const char*fileURLP
, uint16_topenMode
, FileRef*fileRefP
, uint16_t*numOccurrencesP
)
Parameters
-
→ *fileURLP
- URL to the file or directory to be opened. This must be a valid URL. It cannot be empty and can not contain null characters.
-
→ openMode
- Mode to use when opening the file. See "Open Mode Constants" for a list of accepted modes.
-
← fileRefP
- Pointer to the opened file or directory reference number which can then be supplied to various other
VFSFile...
operations. This value is filled in on return. -
← numOccurrencesP
- The number of files the URL matched. Set this pointer to
NULL
if you don't need this information.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrCardReadOnly
- The open mode requested includes write access but the file is read-only.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The
pathNameP
parameter is invalid. -
vfsErrFileNotFound
- The specified file or directory could not be found.
-
vfsErrFilePermissionDenied
- The file cannot be opened in the requested open mode, or it has already been opened with
vfsModeExclusive
. -
vfsErrVolumeBadRef
- The specified volume has not been mounted.
Comments
VFSOpenFileFromURL()
exists to aid a higher-level entity, such as the Exchange Manager, in opening a file referenced in a URL such as file:///VolumeName/PALM/Launcher/myApp.prc
(see Exploring Palm OS: High-Level Communications for a specification of the URL format) This function differs from VFSFileOpen()
in its use of a volume name (in the URL) instead of a volume reference number to differentiate the card. This difference allows the URL to be saved in a "bookmark" and later re-used to open the same file; this wouldn't work with volume reference numbers since they change with every insertion and removal of a card. In the case where multiple cards with the same volume name are present in a device at the same time, each card is checked for the presence of the file, and if multiple instances of the same file are found on these different cards the one with the most recent modification date is opened and returned. In this instance the optional numOccurrencesP
parameter is set to the number of matching files found.
See Also
VFSFileClose()
, VFSDirEntryEnumerate()
, VFSFileOpen()
VFSFileRead Function
Purpose
Read data from a file into the dynamic heap. This function only operates on files and cannot be used with directories; use VFSDirEntryEnumerate()
to explore the contents of a directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileRead ( FileReffileRef
, uint32_tnumBytes
, void*bufP
, uint32_t*numBytesReadP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ numBytes
- Number of bytes to read.
-
← bufP
- Pointer to the destination chunk where the data is to be stored. This can be a pointer to any writable memory.
-
← numBytesReadP
- Pointer to an unsigned integer that reflects the number of bytes actually read. This value is set on return and does not need to be initialized. If no bytes are read the value is set to zero. Pass
NULL
for this parameter if you do not need to know how many bytes were read.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrFileEOF
- The end of the file has been reached.
-
vfsErrFilePermissionDenied
- Read permission is not enabled for this file.
-
vfsErrIsADirectory
- The specified file reference is for a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
Comments
The file system does not use DmWrite()
and cannot be used to read data into the storage heap.
See Also
VFSFileReadData()
, VFSFileWrite()
, VFSImportDatabaseFromFile()
VFSFileReadData Function
Purpose
Read data from a file into a chunk of memory in the storage heap. This function only operates on files and cannot be used with directories; use VFSDirEntryEnumerate()
to explore the contents of a directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileReadData ( FileReffileRef
, uint32_tnumBytes
, void*bufBaseP
, uint32_toffset
, uint32_t*numBytesReadP
)
Parameters
-
→ fileRef
- File reference returned in
VFSFileOpen()
. -
→ numBytes
- Number of bytes to read.
-
← bufBaseP
- Pointer to the destination chunk in the storage heap where the data is to be stored. This pointer must be obtained through the appropriate call to the Memory Manager API.
-
→ offset
- Offset, in bytes, within the
bufBaseP
chunk where the data is to be written. -
← numBytesReadP
- Pointer to an unsigned integer that reflects the number of bytes actually read. This value is set on return and does not need to be initialized. If no bytes are read, the value is set to zero. Pass
NULL
for this parameter if you do not need to know how many bytes were read.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrFileEOF
- The end of the file has been reached.
-
vfsErrFilePermissionDenied
- Read permission is not enabled for this file.
-
vfsErrIsADirectory
- The specified file reference is for a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
Comments
When data is read from an external card with VFSFileReadData
, it is copied into a chunk of memory in the storage heap. This chunk must be allocated by the application before the call to VFSFileReadData()
. This function calls DmWrite()
to put the data in the storage heap.
See Also
VFSFileRename Function
Purpose
Rename a closed file or directory. This function cannot be used to move a file to another directory within the file system.
Declared In
VFSMgr.h
Prototype
status_t VFSFileRename ( uint16_tvolRefNum
, const char*pathNameP
, const char*newNameP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
→ pathNameP
- Pointer to the full path of the file or directory to be renamed.
-
→ newNameP
- Pointer to the new filename. Note that this is the name of the file only and does not include the path to the file.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The name provided in either
pathNameP
ornewNameP
is invalid. This is also returned if the string pointed to bynewNameP
is a path, rather than a filename. -
vfsErrFileAlreadyExists
- A file with the new name already exists in this location.
-
vfsErrFileNotFound
- The source file could not be found.
-
vfsErrFilePermissionDenied
- Write permission is not enabled for this file.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The volume has not been mounted.
-
vfsErrVolumeFull
- There is not enough space left on the volume.
Comments
WARNING! This function invalidates directory enumeration. You cannot continue enumerating files after renaming one of them with this function. If you need to operate on additional files in the directory, you must first restart the enumeration.
Example
Below is an example of how to use VFSFileRename
. Note that the renamed file remains in the /PALM/Programs
directory; VFSFileRename
can't be used to move files from one directory to another.
// volRefNum must have been previously defined; most likely, // it was returned by VFSVolumeEnumerate err = VFSFileRename(volRefNum, "/PALM/Programs/foo.prc", "bar.prc"); if (err != errNone) { // handle error... }
VFSFileResize Function
Purpose
Change the size of an open file. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileResize ( FileReffileRef
, uint32_tnewSize
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ newSize
- The desired new size of the file. This can be larger or smaller then the current file size.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeFull
- There is not enough space left on the volume.
Comments
The location of the file pointer is undefined after a call to this function.
See Also
VFSFileSeek Function
Purpose
Set the position within an open file from which to read or write. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileSeek ( FileReffileRef
, FileOriginorigin
, int32_toffset
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ origin
- Origin to use when calculating the new position. The
offset
parameter indicates the desired new position relative to this origin, which can be one of the constants listed under "Seek Origins." -
→ offset
- Offset, either positive or negative, from the origin to which the current position should be set. A value of zero (0) positions you at the specified origin.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrFileEOF
- The file pointer is at the end of file.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
sysErrParamErr
- The specified origin is not one of the defined constants.
Comments
During a call to this function, if the resulting position would be beyond the end of the file, it sets the position to the end of the file.
See Also
VFSFileSetAttributes Function
Purpose
Change the attributes of an open file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileSetAttributes ( FileReffileRef
, uint32_tattributes
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ attributes
- Attributes to associate with the file or directory. See "File and Directory Attributes" for a list of values you can use when setting this parameter:
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
sysErrParamErr
- One of the parameters is invalid.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrNoFileSystem
The VFS Manager cannot find an appropriate file system to handle the request.
Comments
NOTE: You cannot use this function to set the
vfsFileAttrDirectory
or vfsFileAttrVolumeLabel
attributes. The vfsFileAttrDirectory
is set when you call VFSDirCreate()
. The vfsFileAttrVolumeLabel
is set when you call VFSVolumeSetLabel()
. This function may fail when setting other attributes, depending on the underlying file system.
See Also
VFSFileGetAttributes()
, VFSFileSetDate()
VFSFileSetDate Function
Purpose
Change the dates on an open file or directory.
Declared In
VFSMgr.h
Prototype
status_t VFSFileSetDate ( FileReffileRef
, uint16_twhichDate
, uint32_tdate
)
Parameters
-
→ fileRef
- File reference returned in
VFSFileOpen()
. -
→ whichDate
- Specifies which date—creation, modification, or last access—to modify. Supply one of the values listed under "Date Types."
-
→ date
- The new date. This field should be expressed in the standard Palm OS date format — the number of seconds since midnight (00:00:00) January 1, 1904.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
expErrUnsupportedOperation
- The specified date type is not supported by the underlying file system.
-
sysErrParamErr
- The
whichDate
parameter is not one of the defined constants. -
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrFilePermissionDenied
- Write permission is not enabled for this file.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
Comments
Note that not all file systems are required to support all date types. If the supplied date type is not supported by the file system, VFSFileGetDate
returns expErrUnsupportedOperation
.
See Also
VFSFileGetDate()
, VFSFileSetAttributes()
VFSFileSize Function
Purpose
Obtain the size of an open file. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileSize ( FileReffileRef
, uint32_t*fileSizeP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
← fileSizeP
- Pointer to the size of the open file.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
See Also
VFSFileResize()
, VFSFileTell()
, VFSVolumeSize()
VFSFileTell Function
Purpose
Get the current position of the file pointer within an open file. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileTell ( FileReffileRef
, uint32_t*filePosP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
← filePosP
- Pointer to the current file position.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
See Also
VFSFileWrite Function
Purpose
Write data to an open file. This function only operates on files and cannot be used with directories.
Declared In
VFSMgr.h
Prototype
status_t VFSFileWrite ( FileReffileRef
, uint32_tnumBytes
, const void*dataP
, uint32_t*numBytesWrittenP
)
Parameters
-
→ fileRef
- File reference returned from
VFSFileOpen()
. -
→ numBytes
- The number of bytes to write.
-
→ dataP
- Pointer to the data that is to be written.
-
← numBytesWrittenP
- Pointer to an unsigned integer that reflects the number of bytes actually written. This value is set on return and does not need to be initialized. If no bytes are written the value is set to zero. Pass
NULL
for this parameter if you do not need to know how many bytes were written.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrFileBadRef
- The specified file reference is invalid.
-
vfsErrFilePermissionDenied
- Write permission is not enabled for this file.
-
vfsErrIsADirectory
- The specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeFull
- There is not enough space left on the volume.
See Also
VFSExportDatabaseToFile()
, VFSExportDatabaseToFileCustom()
, VFSFileRead()
, VFSFileReadData()
VFSGetDefaultDirectory Function
Purpose
Determine the default location on the given volume for files of a particular type.
Declared In
VFSMgr.h
Prototype
status_t VFSGetDefaultDirectory ( uint16_tvolRefNum
, const char*fileTypeStr
, char*pathStr
, uint16_t*bufSizeP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
→ fileTypeStr
- Pointer to the requested file type, as a null-terminated string. The file type may either be a MIME media type/subtype pair, such as "image/jpeg", "text/plain", or "audio/basic"; or a file extension, such as "
.jpeg
." -
← pathStr
- Pointer to the buffer which receives the default directory path for the requested file type.
-
← bufSizeP
- Pointer to the size of the path (including the null terminator). Set this to the size of
pathStr
buffer on input. Reflects the number of bytes copied topathStr
on output. Note that if truncation occurred the actual length of the string might be less than indicated by this value.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
vfsErrBadName
- There is no default directory registered for the requested file type.
-
vfsErrBufferOverflow
- A match was found, but the
pathStr
buffer is too small to hold the resulting path string. A partial path is returned inpathStr
. -
vfsErrFileNotFound
- No match was found for the specified volume. The error could have occurred with either the media type specified for this volume or the file type requested.
Comments
This function returns the complete path to the default directory registered for the specified file type. A default directory can be registered for each type of media supported. The directory should be registered under media and file type. Note that this directory is typically a "root" directory for the file type; any subdirectories under this root directory should also be searched for files of the appropriate type.
This function can be used by an image viewer application, for example, to find the directory containing images without having to know what type of media the volume was on. This could be
"/DCIM", "/images", or something else depending on the type of media.
See Also
VFSDirEntryEnumerate()
, VFSRegisterDefaultDirectory()
, VFSUnregisterDefaultDirectory()
VFSImportDatabaseFromFile Function
Purpose
Create a database from a PDB or PRC file on an external storage card.
Declared In
VFSMgr.h
Prototype
status_t VFSImportDatabaseFromFile ( uint16_tvolRefNum
, const char*pathNameP
, DatabaseID*dbIDP
)
Parameters
-
→ volRefNum
- Volume on which the source file resides.
-
→ pathNameP
- Pointer to the full path and name of the source file.
-
← dbIDP
- Pointer to a variable that receives the database ID of the new database. If the database already resides in the storage heap, the database ID of the existing database is returned along with the error
dmErrAlreadyExists
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrAlreadyExists
- The PRC or PDB file already exists in the storage heap. In this case
dbIDP
is set to point to the existing file. -
expErrNotEnoughPower
- There is insufficient battery power to complete the requested operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
Comments
This utility function imports a PDB or PRC file resident on an external storage card into a new database in the storage heap. It first calls VFSFileOpen()
to open the file specified in pathNameP
. Assuming that a corresponding PRC or PDB does not already exist in the storage heap, VFSImportDatabaseFromFile()
calls the Exchange Manager function ExgDBRead()
with an internal callback function for importing a file to the Data Manager. The Exchange Manager makes repeated calls to this function, which passes the data back in blocks. Once the file has been successfully imported, the owner (the imported file, if it's an executable, or the associated application if it is not) is sent a sysAppLaunchCmdSyncNotify
launch code to make it aware of the new database.
This function only imports the specified PDB or PRC file; it does not import bundled databases or overlays. If there are bundled databases and/or overlays associated with the PDB or PRC file you are importing, you will need to write additional code to explicitly handle them.
This function doesn't provide any progress indication to the user. If you need to provide feedback to the user as the file import progresses, use VFSImportDatabaseFromFileCustom()
instead.
This function is used, for example, to copy applications from a storage card to main memory.
See Also
VFSExportDatabaseToFile()
, VFSFileRead()
VFSImportDatabaseFromFileCustom Function
Purpose
Create a database from the specified PDB or PRC file on an external storage card. This function differs from VFSImportDatabaseFromFile()
in that it allows you to track the progress of the import operation.
Declared In
VFSMgr.h
Prototype
status_t VFSImportDatabaseFromFileCustom ( uint16_tvolRefNum
, const char*pathNameP
, DatabaseID*dbIDP
, VFSImportProcPtrimportProcP
, void*userDataP
)
Parameters
-
→ volRefNum
- Volume on which the source file resides.
-
→ pathNameP
- Pointer to the full path and name of the source file.
-
← dbIDP
- Pointer to the variable that receives the database ID of the new database. If the database already resides in the storage heap, the database ID of the existing database is returned along with the error
dmErrAlreadyExists
. -
→ importProcP
- User-defined callback function that tracks the progress of the import. This function should allow the user to cancel the import. Pass
NULL
if you don't have a progress callback function. SeeVFSImportProcPtr()
for the requirements of this function. -
→ userDataP
- Pointer to any data you want to pass to the callback function specified in
importProcP
. This information is not used internally by the VFS Manager. PassNULL
if you don't have a progress callback function, or if that function doesn't need any such data.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid. -
expErrNotEnoughPower
- The power required to import a database is not available.
-
dmErrAlreadyExists
- The PRC or PDB file already exists in main memory. In this case the
cardNoP
anddbIDP
are set to point to the existing file.
Comments
This function is similar to VFSImportDatabaseFromFile()
in that it imports a PDB or PRC file on an external storage card into a new database on the storage heap. It extends the functionality by allowing you to specify a callback function that tracks the progress of the export. It first calls VFSFileOpen()
to open the file specified in pathNameP
. If a corresponding PRC or PDB does not already exist in main memory, it calls the Exchange Manager function ExgDBRead()
with an internal callback function for importing the file from the Data Manager. The Exchange Manager makes repeated calls to this function, which receives the data back in blocks. The progress tracker, if one has been specified, is also called every time a new chunk of data is passed back. Once the file has been successfully imported, the owner (the imported file, if it's an executable, or the associated application if it is not) is sent a sysAppLaunchCmdSyncNotify
launch code to make it aware of the new database.
Like VFSImportDatabaseFromFile
, this function only imports the specified PDB or PRC file; it does not import bundled databases or overlays.
This function is used, for example, to copy applications from a storage card to main memory.
See Also
VFSFileRead()
, VFSExportDatabaseToFileCustom()
VFSImportDatabaseFromFileCustomV40 Function
Purpose
Create a database from the specified PDB or PRC file on an external storage card. This function differs from VFSImportDatabaseFromFile()
in that it allows you to track the progress of the import operation.
Declared In
VFSMgr.h
Prototype
status_t VFSImportDatabaseFromFileCustomV40 ( uint16_tvolRefNum
, const char*pathNameP
, uint16_t*cardNoP
, LocalID*dbIDP
, VFSImportProcPtrimportProcP
, void*userDataP
)
Parameters
-
→ volRefNum
- Volume on which the source file resides.
-
→ pathNameP
- Pointer to the full path and name of the source file.
-
← cardNoP
- Pointer to the variable that receives the card number of the newly-created database. If the database already resides in the storage heap, the card number of the existing database is returned along with the error
dmErrAlreadyExists
. -
← dbIDP
- Pointer to the variable that receives the database ID of the new database. If the database already resides in the storage heap, the database ID of the existing database is returned along with the error
dmErrAlreadyExists
. -
→ importProcP
- User-defined callback function that tracks the progress of the import. This function should allow the user to cancel the import. Pass
NULL
if you don't have a progress callback function. SeeVFSImportProcPtr()
for the requirements of this function. -
→ userDataP
- Pointer to any data you want to pass to the callback function specified in
importProcP
. This information is not used internally by the VFS Manager. PassNULL
if you don't have a progress callback function, or if that function doesn't need any such data.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid. -
expErrNotEnoughPower
- The power required to import a database is not available.
-
dmErrAlreadyExists
- The PRC or PDB file already exists in main memory. In this case the
cardNoP
anddbIDP
are set to point to the existing file.
Comments
This function is similar to VFSImportDatabaseFromFile()
in that it imports a PDB or PRC file on an external storage card into a new database on the storage heap. It extends the functionality by allowing you to specify a callback function that tracks the progress of the export. It first calls VFSFileOpen()
to open the file specified in pathNameP
. If a corresponding PRC or PDB does not already exist in main memory, it calls the Exchange Manager function ExgDBRead()
with an internal callback function for importing the file from the Data Manager. The Exchange Manager makes repeated calls to this function, which receives the data back in blocks. The progress tracker, if one has been specified, is also called every time a new chunk of data is passed back. Once the file has been successfully imported, the owner (the imported file, if it's an executable, or the associated application if it is not) is sent a sysAppLaunchCmdSyncNotify
launch code to make it aware of the new database.
Like VFSImportDatabaseFromFile
, this function only imports the specified PDB or PRC file; it does not import bundled databases or overlays.
This function is used, for example, to copy applications from a storage card to main memory.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS. The returned *cardNoP
is always 0.
See Also
VFSFileRead()
, VFSExportDatabaseToFileCustom()
, VFSImportDatabaseFromFileCustom()
VFSImportDatabaseFromFileV40 Function
Purpose
Create a database from a PDB or PRC file on an external storage card.
Declared In
VFSMgr.h
Prototype
status_t VFSImportDatabaseFromFileV40 ( uint16_tvolRefNum
, const char*pathNameP
, uint16_t*cardNoP
, LocalID*dbIDP
)
Parameters
-
→ volRefNum
- Volume on which the source file resides.
-
→ pathNameP
- Pointer to the full path and name of the source file.
-
← cardNoP
- Pointer to a variable that receives the card number of the newly-created database. If the database already resides in the storage heap, the card number of the existing database is returned along with the error
dmErrAlreadyExists
. -
← dbIDP
- Pointer to a variable that receives the database ID of the new database. If the database already resides in the storage heap, the database ID of the existing database is returned along with the error
dmErrAlreadyExists
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
dmErrAlreadyExists
- The PRC or PDB file already exists in the storage heap. In this case
dbIDP
is set to point to the existing file. -
expErrNotEnoughPower
- There is insufficient battery power to complete the requested operation.
-
vfsErrBadName
- The path name specified in
pathNameP
is not valid.
Comments
This utility function imports a PDB or PRC file resident on an external storage card into a new database in the storage heap. It first calls VFSFileOpen()
to open the file specified in pathNameP
. Assuming that a corresponding PRC or PDB does not already exist in the storage heap, VFSImportDatabaseFromFile()
calls the Exchange Manager function ExgDBRead()
with an internal callback function for importing a file to the Data Manager. The Exchange Manager makes repeated calls to this function, which passes the data back in blocks. Once the file has been successfully imported, the owner (the imported file, if it's an executable, or the associated application if it is not) is sent a sysAppLaunchCmdSyncNotify
launch code to make it aware of the new database.
This function only imports the specified PDB or PRC file; it does not import bundled databases or overlays. If there are bundled databases and/or overlays associated with the PDB or PRC file you are importing, you will need to write additional code to explicitly handle them.
This function doesn't provide any progress indication to the user. If you need to provide feedback to the user as the file import progresses, use VFSImportDatabaseFromFileCustom()
instead.
This function is used, for example, to copy applications from a storage card to main memory.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS. The returned *cardNoP
is always 0.
See Also
VFSExportDatabaseToFile()
, VFSFileRead()
, VFSImportDatabaseFromFile()
VFSRegisterDefaultDirectory Function
Purpose
Register a specific directory as the default location for files of a given type on a particular kind of external storage card. This function is generally called by a slot driver for files and media types that are supported by that slot driver.
Declared In
VFSMgr.h
Prototype
status_t VFSRegisterDefaultDirectory ( const char*fileTypeStr
, uint32_tmediaType
, const char*pathStr
)
Parameters
-
→ fileTypeStr
- Pointer to the file type to register. This is a null-terminated string that can either be a MIME media type/subtype pair, such as "image/jpeg", "text/plain", or "audio/basic"; or a file extension, such as "
.jpeg
". -
→ mediaType
- Type of card media for which the default directory is being associated. See "Defined Media Types" in Exploring Palm OS: System Management for the list of accepted values.
-
→ pathStr
- Pointer to the default directory path to be associated with the specified file type. This string must be null-terminated, and must be the full path to the directory.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
sysErrParamErr
- Either the
fileTypeStr
parameter isNULL
or thepathStr
parameter isNULL
. -
vfsErrFileAlreadyExists
- A default directory has already been registered for this file type on the specified card media type.
Comments
This function first verifies that a default directory has not already been registered for the specified combination of file type and media type, and returns vfsErrFileAlreadyExists
if one has been registered. To change an existing entry in the registry, you must first remove the existing entry with a call to VFSUnregisterDefaultDirectory()
before re-registering it with VFSRegisterDefaultDirectory
.
The specified directory registered for a given file type is intended to be the "root" default directory. If a given default directory has one or more subdirectories, applications should also search those subdirectories for files of the appropriate type.
NOTE: Registering a directory as the default location for files of a given type on a particular type of media doesn't automatically register that file type with HotSync Exchange. See "HotSync Exchange" of Exploring Palm OS: High-Level Communications for information on registering file types with HotSync Exchange.
See Also
VFSUnregisterDefaultDirectory Function
Purpose
Sever the association between a particular file type and a default directory for a given type of card media.
Declared In
VFSMgr.h
Prototype
status_t VFSUnregisterDefaultDirectory ( const char*fileTypeStr
, uint32_tmediaType
)
Parameters
-
→ fileTypeStr
- Pointer to the file type with which the default directory is associated. This is a null-terminated string that can either be a MIME media type/subtype pair, such as "image/jpeg", "text/plain", or "audio/basic"; or a file extension, such as "
.jpeg
". -
→ mediaType
- Type of card media for which the default directory is associated. See "Defined Media Types" in Exploring Palm OS: System Management for the list of accepted values.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
sysErrParamErr
- The
fileTypeStr
parameter isNULL
. -
vfsErrFileNotFound
- A default directory could not be found in the registry for the specified file and media type.
Comments
NOTE: Caution is advised when using this function, since you may remove another application's registration, causing data to mysteriously disappear from those applications.
See Also
VFSGetDefaultDirectory()
, VFSRegisterDefaultDirectory()
VFSVolumeEnumerate Function
Purpose
Enumerate the mounted volumes.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeEnumerate ( uint16_t*volRefNumP
, uint32_t*volIteratorP
)
Parameters
-
← volRefNumP
- Pointer to the reference number for the volume represented by the current enumeration, or
vfsInvalidVolRef
if there are no more volumes to be enumerated or an error occurred. -
↔ volIteratorP
- Pointer to a variable that holds the index of the current enumeration. Set the variable to
vfsIteratorStart
prior to the first iteration. Each call toVFSVolumeEnumerate
updates the variable to the index of the next volume. When the last volume is reached, the variable pointed to byvolIteratorP
is set tovfsIteratorStop
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrEnumerationEmpty
- There are no volumes to enumerate.
-
sysErrParamErr
- The value pointed to by
volIteratorP
is not valid. This error is also returned whenvolIteratorP
isvfsIteratorStop
.
Comments
This function returns a pointer to the volume reference number in the volRefNumP
parameter. In order to traverse all volumes you must make repeated calls to VFSVolumeEnumerate()
inside a loop. Before the first call to VFSVolumeEnumerate
, the variable pointed to by volIteratorP
should be initialized to vfsIteratorStart
. Each iteration then increments volIteratorP
to the next entry after updating volRefNumP
. When the last volume is reached, *
volIteratorP
is set to vfsIteratorStop
. If there are no volumes to enumerate, VFSVolumeEnumerate
returns expErrEnumerationEmpty
when first called.
Example
Below is an example of how to use VFSVolumeEnumerate
.
UInt16 volRefNum; UInt32 volIterator = vfsIteratorStart; while (volIterator != vfsIteratorStop) { err = VFSVolumeEnumerate(&volRefNum, &volIterator); if (err == errNone) { // Do something with the volRefNum } else { // handle error... possibly by // breaking out of the loop } }
VFSVolumeFormat Function
Purpose
Format and mount the volume installed in a given slot.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeFormat ( uint8_tflags
, uint16_tfsLibRefNum
, VFSAnyMountParamPtrvfsMountParamP
)
Parameters
-
→ flags
- Flags that control how the volume should be formatted. Currently, the only flag not reserved is
vfsMountFlagsUseThisFileSystem
. Pass this flag to cause the volume to be formatted using the file system specified byfsLibRefNum
. Pass zero (0) to have the VFS Manager attempt to format the volume using a file system appropriate to the slot. -
→ fsLibRefNum
- Reference number of the file system library for which the volume should be formatted. If the
flags
field is not set tovfsMountFlagsUseThisFileSystem
, this parameter is ignored. -
↔ vfsMountParamP
- Parameters to be used when formatting the volume and when mounting the volume after it has been formatted. Supply a pointer to either a
VFSSlotMountParamType
or aVFSPOSEMountParamType
structure. Note that you'll need to cast your structure pointer to aVFSAnyMountParamPtr
. Set themountClass
field to the appropriate value: if you are mounting to an Expansion Manager slot, setmountClass
toVFSMountClass_SlotDriver
and initializeslotLibRefNum
andslotRefNum
to the appropriate values. See the descriptions ofVFSAnyMountParamType
,VFSSlotMountParamType
, andVFSPOSEMountParamType
for information on the fields that make up these data structures.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to format and/or mount a volume.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
Comments
The slot driver currently only supports one volume per slot. If the volume is successfully formatted and mounted, the reference number of the mounted volume is returned in vfsMountParamP->volRefNum
. If the format is unsuccessful or cancelled, vfsMountParamP->volRefNum
is set to vfsInvalidVolRef
.
If vfsMountFlagsUseThisFileSystem
is passed as a flag, VFSVolumeFormat
attempts to format the volume using the file system library specified by fsLibRefNum
. Typically the flag parameter is not set. In this case VFSVolumeFormat
tries to find a compatible library to format the volume, as follows:
- Check to see if the default file system library feature is set. If it is, and if that file system is installed, it is used to format the volume. You can set the default file system using
FtrSet()
; supplysysFileCVFSMgr
for the feature creator, andvfsFtrIDDefaultFS
for the feature number. - Check to see if any of the installed file systems are natively supported for the slot on which the VFS Manager is trying to format. If one of them is, it is used to format the volume.
- If none of the installed file systems can perform the format using the slot's native type, a dialog displays warning the user that their media may become incompatible with other devices if they continue with the format. The user may continue or cancel the format. If the user chooses to continue,
VFSVolumeFormat
formats the volume using the first file system library that was installed.
When calling VFSVolumeFormat
, the volume can either be mounted or unmounted. The underlying file system library call requires the volume to be unmounted. VFSVolumeFormat
checks to see if the volume is currently mounted and unmounts it, if necessary, using VFSVolumeUnmount()
before making the file system call. If the file system successfully formats the volume, VFSVolumeFormat
mounts it and posts a sysNotifyVolumeMountedEvent
notification.
Example
The following code excerpt formats a volume on an Expansion Manager slot using a compatible file system.
VFSSlotMountParamType slotParam; UInt32 slotIterator = expIteratorStart; slotParam.vfsMountParamP.mountClass = VFSMountClass_SlotDriver; err = ExpSlotEnumerate(&slotParam.slotRefNum, &slotIterator); err = ExpSlotLibFind(slotParam.slotRefNum, &slotParam.slotLibRefNum); err = VFSVolumeFormat(NULL, NULL, (VFSAnyMountParamPtr) & slotParam);
See Also
VFSVolumeGetLabel Function
Purpose
Determine the volume label for a particular volume.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeGetLabel ( uint16_tvolRefNum
, char*labelP
, size_tbufSize
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
← labelP
- Pointer to a character buffer into which the volume name is placed.
-
→ bufSize
- Length, in bytes, of the
labelP
buffer.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The specified volume has not been mounted.
-
vfsErrBufferOverflow
- The value specified in
bufSize
is not big enough to receive the full volume label. -
vfsErrNameShortened
- There was an error reading the full volume name. A shortened version is being returned.
Comments
Volume reference numbers can change each time you mount a given volume. To keep track of a particular volume, save the volume's label rather than its reference number. Volume labels can be up to 255 characters long. They can contain any normal character, including spaces and lower case characters, in any character set as well as the following special characters: $ % ' - _ @ ~ ` ! ( ) ^ # & + , ; = [ ].
See Also
VFSVolumeInfo Function
Purpose
Get information about the specified volume.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeInfo ( uint16_tvolRefNum
, VolumeInfoType*volInfoP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
← volInfoP
- Pointer to the structure that receives the volume information for the specified volume. See
VolumeInfoType
for more information on the fields in this data structure.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The specified volume reference number is invalid.
See Also
VFSVolumeGetLabel()
, VFSVolumeSize()
VFSVolumeMount Function
Purpose
Mount the card's volume on the specified slot.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeMount ( uint8_tflags
, uint16_tfsLibRefNum
, VFSAnyMountParamPtrvfsMountParamP
)
Parameters
-
→ flags
- Flags that control how the volume should be mounted. Currently, the only flag not reserved is
vfsMountFlagsUseThisFileSystem
. Pass this flag to cause the volume to be mounted using the file system specified byfsLibRefNum
. Pass zero (0) to have the VFS Manager attempt to mount the volume using a file system appropriate for the slot. -
→ fsLibRefNum
- Reference number of the file system library for which the volume should be mounted. If the
flags
field is not set tovfsMountFlagsUseThisFileSystem
, this parameter is ignored. -
↔ vfsMountParamP
- Parameters to be used when mounting the volume after it has been formatted. Supply a pointer to either a
VFSSlotMountParamType
or aVFSPOSEMountParamType
structure. Note that you'll need to cast your structure pointer to aVFSAnyMountParamPtr
. Set themountClass
field to the appropriate value: if you are mounting to an Expansion Manager slot, setmountClass
toVFSMountClass_SlotDriver
and initializeslotLibRefNum
andslotRefNum
to the appropriate values. See the descriptions ofVFSAnyMountParamType
,VFSSlotMountParamType
, andVFSPOSEMountParamType
for information on the fields that make up these data structures.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotEnoughPower
- There is insufficient battery power to mount a volume.
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
sysErrParamErr
-
vfsMountParamP
was initialized toNULL
. -
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeStillMounted
- The volume is already mounted with a different file system than was specified in
fsLibRefNum
.
Comments
The slot driver only supports one volume per slot. The reference number of the mounted volume is returned in vfsMountParamP->volRefNum
. If vfsMountFlagsUseThisFileSystem
is passed as a flag, VFSVolumeMount
attempts to mount the volume using the file system library specified by fsLibRefNum
. Otherwise VFSVolumeMount
tries to find a file system library which is able to mount the volume. If none of the installed file system libraries is able to mount the volume, VFSVolumeMount
attempts to re-format the volume (using VFSVolumeFormat()
) and then mount it. If VFSVolumeMount
manages to successfully mount the volume, it ends by posting a sysNotifyVolumeMountedEvent
notification.
After VFSVolumeMount successfully mounts a volume, it broadcasts sysNotifyVolumeMountedEvent
. The VFS Manager, upon being notified of this event, searches the newly-mounted volume for /PALM/start.prc
. If start.prc
is found in the /PALM
directory, the VFS Manager copies it to main memory and launches it. If start.prc
is not found, the VFS Manager switches to the Launcher instead. This behavior can be overridden; see "Card Insertion and Removal" of Exploring Palm OS: System Management.
When VFSVolumeMount
is called, if the volume is already mounted with a different file system than was specified in fsLibRefNum
, a vfsErrVolumeStillMounted
error is returned. If the volume is already mounted with the same file system that is specified in fsLibRefNum
, or if vfsMountFlagsUseThisFileSystem
is not set, VFSVolumeMount
returns errNone
and sets volRefNumP
to the reference number of the currently mounted volume.
Example
The following code excerpt mounts a volume on an Expansion Manager slot using a compatible file system.
VFSSlotMountParamType slotParam ; UInt32 slotIterator = expIteratorStart; slotParam.vfsMountParamP.mountClass = VFSMountClass_SlotDriver; err = ExpSlotEnumerate(&slotParam.slotRefNum, &slotIterator); err = ExpSlotLibFind(slotParam.slotRefNum, &slotParam.slotLibRefNum); err = VFSVolumeMount(NULL, NULL, (VFSAnyMountParamPtr) & slotParam);
See Also
VFSVolumeFormat()
, VFSVolumeUnmount()
VFSVolumeSetLabel Function
Purpose
Change the volume label for a mounted volume.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeSetLabel ( uint16_tvolRefNum
, const char*labelP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
→ labelP
- Pointer to the label to be applied to the specified volume. This string must be null-terminated.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrBadName
- The supplied label is invalid.
-
vfsErrNameShortened
- Indicates that the label name was too long. A shortened version of the label name was used instead.
-
vfsErrVolumeBadRef
- The specified volume has not been mounted.
Comments
Volume labels can be up to 255 characters long. They can contain any normal character, including spaces and lower case characters, in any character set as well as the following special characters: $ % ' - _ @ ~ ` ! ( ) ^ # & + , ; = [ ]. See "Naming Volumes" for guidelines on naming.
NOTE: Most clients should not need to call this function. This function may create or delete a file in the root directory, which would invalidate any current calls to
VFSDirEntryEnumerate()
.
See Also
VFSVolumeSize Function
Purpose
Determine the total amount of space on a volume, as well as the amount that is currently being used.
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeSize ( uint16_tvolRefNum
, uint32_t*volumeUsedP
, uint32_t*volumeTotalP
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
. -
← volumeUsedP
- Pointer to a variable that receives the amount of space, in bytes, in use on the volume.
-
← volumeTotalP
- Pointer to a variable that receives the total amount of space on the volume, in bytes.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The specified volume has not been mounted.
See Also
VFSVolumeUnmount Function
Purpose
Declared In
VFSMgr.h
Prototype
status_t VFSVolumeUnmount (
uint16_t volRefNum
)
Parameters
-
→ volRefNum
- Volume reference number returned from
VFSVolumeEnumerate()
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- The file system library necessary for this call has not been installed or has not been opened.
-
vfsErrNoFileSystem
- The VFS Manager cannot find an appropriate file system to handle the request.
-
vfsErrVolumeBadRef
- The specified volume has not been mounted.
Comments
This function closes any opened files and posts a sysNotifyVolumeUnmountedEvent
notification once the file system is successfully unmounted.
See Also
Application-Defined Functions
VFSExportProcPtr Function
Purpose
User-defined callback function supplied to VFSExportDatabaseToFileCustom()
that tracks the progress of the export.
Declared In
VFSMgr.h
Prototype
status_t ( *VFSExportProcPtr ) ( uint32_ttotalBytes
, uint32_toffset
, void*userDataP
)
Parameters
-
→ totalBytes
- The total number of bytes being exported.
-
→ offset
- Undefined.
-
→ userDataP
- Pointer to any application-specific data passed to the callback function. This pointer may be
NULL
if your callback doesn't need any such data.
Returns
Your progress tracker should allow the user to abort the export. Return errNone
if the export should continue, or any other value to abort the export process. If you return a value other than errNone
, that value will be returned by VFSExportDatabaseToFileCustom()
.
Comments
See "Progress Dialogs" of Exploring Palm OS: User Interface for more information on writing a progress tracker.
See Also
VFSImportProcPtr Function
Purpose
User-defined callback function supplied to VFSImportDatabaseFromFileCustom()
that tracks the progress of the import.
Declared In
VFSMgr.h
Prototype
status_t ( *VFSImportProcPtr ) ( uint32_ttotalBytes
, uint32_toffset
, void*userDataP
)
Parameters
-
→ totalBytes
- The total number of bytes being imported.
-
→ offset
- The number of bytes that have already been imported. This value, along with the total number of bytes being imported, allows you to inform the user how far along the import is.
-
→ userDataP
- Pointer to NY application-specific data passed to the callback function. This pointer may be
NULL
if your callback doesn't need any such data.
Returns
Your progress tracker should allow the user to abort the import. Return errNone
if the import should continue, or any other value to abort the import process. If you return a value other than errNone
, that value will be returned by VFSImportDatabaseFromFileCustom()
.
Comments
See "Progress Dialogs" of Exploring Palm OS: User Interface for more information on writing a progress tracker.