Virtual File System Manager
 

 < Home   < Developers   < Development Support   < Documentation

54 Virtual File System Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

54 Virtual File System Manager

VFS Manager Data Structures

FileInfoType

FileRef

VFSAnyMountParamType

VFSSlotMountParamType

VFSPOSEMountParamType

VolumeInfoType

VFS Manager Constants

Defined File Systems

Open Mode Constants

File and Directory Attributes

Volume Attributes

Volume Mount Classes

Error Codes

VFS Manager Functions

VFSCustomControl

VFSDirCreate

VFSDirEntryEnumerate

VFSExportDatabaseToFile

VFSExportDatabaseToFileCustom

VFSFileClose

VFSFileCreate

VFSFileDBGetRecord

VFSFileDBGetResource

VFSFileDBInfo

VFSFileDelete

VFSFileEOF

VFSFileGetAttributes

VFSFileGetDate

VFSFileOpen

VFSFileRead

VFSFileReadData

VFSFileRename

VFSFileResize

VFSFileSeek

VFSFileSetAttributes

VFSFileSetDate

VFSFileSize

VFSFileTell

VFSFileWrite

VFSGetDefaultDirectory

VFSImportDatabaseFromFile

VFSImportDatabaseFromFileCustom

VFSInstallFSLib

VFSRegisterDefaultDirectory

VFSRemoveFSLib

VFSUnregisterDefaultDirectory

VFSVolumeEnumerate

VFSVolumeFormat

VFSVolumeGetLabel

VFSVolumeInfo

VFSVolumeMount

VFSVolumeSetLabel

VFSVolumeSize

VFSVolumeUnmount

Application-Defined Functions

VFSExportProcPtr

VFSImportProcPtr

       

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 as follows:

VFS Manager Data Structures

VFS Manager Constants

VFS Manager Functions

Application-Defined Functions

The header file VFSMgr.h declares the VFS Manager API. For more information on the VFS Manager, see Chapter 8, "Expansion," in Palm OS Programmer's Companion, vol. I.

Note that the VFS Manager is an optional system extension; the functions described in this chapter are implemented only if the VFS Manager Feature Set is present.

VFS Manager Data Structures

FileInfoType

The FileInfoType structure contains information about a specified file or directory. This information is returned as a parameter to VFSDirEntryEnumerate. The structure is defined as follows:

typedef struct FileInfoTag { 
  UInt32 attributes; 
  Char *nameP; 
  UInt16 nameBufLen; 
} FileInfoType, *FileInfoPtr; 

Field Descriptions

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.

FileRef

The FileRef type is used to encode references to files and directories.

typedef UInt32 FileRef; 

VFSAnyMountParamType

The VFSAnyMountParamType structure is 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.

typedef struct VFSAnyMountParamTag { 
  UInt16 volRefNum; 
  UInt16 reserved; 
  UInt32 mountClass; 
} VFSAnyMountParamType; 
  
typedef VFSAnyMountParamType *VFSAnyMountParamPtr; 

Field Descriptions

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 with VFSVolumeUnmount.
reserved
Reserved for future use.
mountClass
Defines the type of mount to use with the specified volume. See Volume Mount Classes for a list of mount types.

VFSSlotMountParamType

The VFSSlotMountParamType structure is used when you are mounting a card located in an Expansion Manager slot. The vfsMountParam->mountClass field must be set to VFSMountClass_SlotDriver.

typedef struct VFSSlotMountParamTag { 
  VFSAnyMountParamType vfsMountParam; 
  UInt16 slotLibRefNum; 
  UInt16 slotRefNum; 
} VFSSlotMountParamType; 

Field Descriptions

vfsMountParam
See the description of VFSAnyMountParamType for an explanation of the fields in this structure. Set vfsMountParam->mountClass to VFSMountClass_SlotDriver to mount an Expansion Manager slot.
slotLibRefNum
Reference number for the slot driver library allocated to the given slot number. Obtain this field by calling ExpSlotLibFind.
slotRefNum
Number of the slot to be mounted.

VFSPOSEMountParamType

The VFSPOSEMountParamType structure is used when you are mounting a volume through the Palm OS® Emulator. The vfsMountParam->mountClass must be set to VFSMountClass_POSE. Note that ordinary applications and file systems shouldn't use VFSPOSEMountParamType.

typedef struct VFSPOSEMountParamTag { 
  VFSAnyMountParamType vfsMountParam;  
  UInt8 poseSlotNum; 
} VFSPOSEMountParamType 

Field Descriptions

vfsMountParam
See the description of VFSAnyMountParamType for an explanation of the fields in this structure. Set vfsMountParam->mountClass to VFSMountClass_POSE to mount a virtual slot.
poseSlotNum
Number of the virtual slot number to be mounted by the Palm OS Emulator.

VolumeInfoType

The VolumeInfoType structure defines information that is returned to VFSVolumeInfo and used throughout the VFS functions.

typedef struct VolumeInfoTag { 
  UInt32 attributes; 
  UInt32 fsType; 
  UInt32 fsCreator; 
  UInt32 mountClass; 
  UInt16 slotLibRefNum; 
  UInt16 slotRefNum; 
  UInt32 mediaType; 
  UInt32 reserved; 
} VolumeInfoType, *VolumeInfoPtr; 

Field Descriptions

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 the Expansion Manager chapter 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

Defined File Systems

The following file systems are currently defined by the VFS Manager. These values are used with VFSVolumeInfo in the VolumeInfoType.fsType parameter.

Constant
Value
Description
vfsFilesystemType_AFS
'afsu'
Unix Andrew file system
vfsFilesystemType_EXT2
'ext2'
Linux file system
vfsFilesystemType_FAT
'fats'
FAT12 and FAT16, which only handles 8.3 filenames
vfsFilesystemType_FFS
'ffsb'
Unix Berkeley block based file system
vfsFilesystemType_HFS
'hfss'
Macintosh standard hierarchical file system
vfsFilesystemType_HFSPlus
'hfse'
Macintosh extended hierarchical file system
vfsFilesystemType_HPFS
'hpfs'
OS2 High Performance file system
vfsFilesystemType_MFS
'mfso'
Macintosh original file system
vfsFilesystemType_NFS
'nfsu'
Unix Networked file system
vfsFilesystemType_Novell
'novl'
Novell file system
vfsFilesystemType_NTFS
'ntfs'
Windows NT file system
vfsFilesystemType_VFAT
'vfat'
FAT12 and FAT16 extended to handle long filenames

Open Mode Constants

This section describes constants that are used for the openMode parameter to the VFSFileOpen function. These constants specify the mode in which a file or directory is opened.

Constant
Value
Description
vfsModeExclusive
0x0001U
Open and lock the file or directory. This mode excludes anyone else from using the file or directory until it is closed.
vfsModeRead
0x0002U
Open for read access.
vfsModeWrite
0x0004U | vfsModeExclusive
Open for write access.
vfsModeReadWrite
vfsModeWrite | vfsModeRead
Open for read/write access.
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.
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.
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.
vfsModeLeaveOpen
0x0020U
Leave the file open even after the
application exits.

File and Directory Attributes

The constants in the following table define 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.

Constant
Value
Description
vfsFileAttrReadOnly
0x00000001UL
Read-only file or directory
vfsFileAttrHidden
0x00000002UL
Hidden file or directory
vfsFileAttrSystem
0x00000004UL
System file or directory
vfsFileAttrVolumeLabel
0x00000008UL
Volume label
vfsFileAttrDirectory
0x00000010UL
Directory
vfsFileAttrArchive
0x00000020UL
Archived file or directory
vfsFileAttrLink
0x00000040UL
Link to another file or directory

Volume Attributes

The constants in the following table define bits that can be used individually or in combination to make up the attributes field in the VolumeInfoType structure.

Constant
Value
Description
vfsVolumeAttrHidden
0x00000004UL
The volume should not be visible to the user.
vfsVolumeAttrReadOnly
0x00000002UL
The volume is read only.
vfsVolumeAttrSlotBased
0x00000001UL
Reserved. Check the mount class to determine how a volume is mounted.

Volume Mount Classes

The following constants define how a given volume is mounted. The mountClass field in the VFSAnyMountParamType and VolumeInfoType structures takes on one of these values.

Constant
Value
Description
vfsMountClass_POSE
'pose'
Mount the volume through the Palm OS Emulator. This is used for testing.
vfsMountClass_Simulator
sysFileTSimulator
Mount the volume through the simulator. This is used for testing.
vfsMountClass_SlotDriver
sysFileTSlotDriver
Mount the volume with a slot driver shared library.

Error Codes

The VFS Manager defines the following error codes:

Constant
Description
vfsErrBadData
The operation could not be completed because of invalid data.
vfsErrBadName
Invalid filename, path, or volume label.
vfsErrBufferOverflow
The supplied buffer is too small.
vfsErrDirectoryNotFound
Returned when the path leading up to the file does not exist.
vfsErrDirNotEmpty
The directory is not empty and therefore cannot be deleted.
vfsErrFileAlreadyExists
A file with this name exists already in this location.
vfsErrFileBadRef
The file reference is invalid: it has been closed or was not obtained from VFSFileOpen.
vfsErrFileEOF
The file pointer is at the end of the file.
vfsErrFileGeneric
Generic file error.
vfsErrFileNotFound
The file was not found at the specified location.
vfsErrFilePermissionDenied
The requested permissions could not be granted.
vfsErrFileStillOpen
Returned from the underlying file system's delete function if the file is still open.
vfsErrIsADirectory
This operation can only be performed on a regular file, not a directory.
vfsErrNameShortened
A volume name or filename was automatically shortened to conform to the file system specification.
vfsErrNoFileSystem
None of the installed file systems support this operation.
vfsErrNotADirectory
This operation can only performed on a directory.
vfsErrVolumeBadRef
The volume reference number is invalid.
vfsErrVolumeFull
There is insufficient space left on the volume.
vfsErrVolumeStillMounted
Returned from the underlying file system's format function if the volume is still mounted.

VFS Manager Functions

New VFSCustomControl

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.

Prototype

Err VFSCustomControl(UInt32 fsCreator, UInt32 apiCreator, UInt16 apiSelector, void *valueP, UInt16 *valueLenP)

Parameters

-> fsCreatorCreator 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.
-> apiCreatorRegistered creator ID.
-> apiSelectorCustom operation to perform.
<-> valuePA 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.
<-> valueLenPOn entry, points to the size of the valueP buffer. On exit, this value reflects the size of the data written to the valueP buffer. If valueLenP is NULL, valueP is passed to the file system but is not updated on exit.

Result

Returns one of the following error codes:

errNoneNo error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
expErrUnsupportedOperationThe specified opcode and/or creator is unsupported or undefined.
sysErrParamErrThe valueP buffer is too small.
vfsErrNoFileSystemVFS 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSDirCreate

Purpose

Create a new directory.

Prototype

Err VFSDirCreate(UInt16 volRefNum, const Char *dirNameP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
-> dirNamePPointer to the full path of the directory to be created.

Result

Returns one of the following error codes:

errNone No error
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameSome or all of the path, up to but not including the last component specified in the dirNameP parameter, does not exist.
vfsErrFileAlreadyExistsA file with this name already exists in this location.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe volume has not been mounted.
vfsErrVolumeFullThere 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSDirEntryEnumerate

Purpose

Enumerate the entries in a given directory. Entries can include files, links, and other directories.

Prototype

Err VFSDirEntryEnumerate (FileRef dirRef, UInt32 *dirEntryIteratorP, FileInfoType *infoP)

Parameters

-> dirRefDirectory 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. If infoP is the last entry, this parameter is set to vfsIteratorStop.
<-> infoPPointer to the FileInfoType data structure that contains information about the given directory entry. The nameP and nameBufLen fields in this structure must be initialized prior to calling VFSDirEntryEnumerate.

Result

Returns one of the following error codes:

errNoneNo error.
expErrEnumerationEmptyThere are no directory entries left to enumerate.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
sysErrParamErrThe dirEntryIteratorP is not valid.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrIsNotADirectoryThe specified file reference is valid, but does not point to a directory.
vfsErrNoFileSystemThe 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 = sizeof(fileName); 
   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); 
} 

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSExportDatabaseToFile

Purpose

Save the specified database to a .pdb or .prc file on an external storage card.

Prototype

Err VFSExportDatabaseToFile (UInt16 volRefNum, const Char *pathNameP, UInt16 cardNo, LocalID dbID)

Parameters

-> volRefNumVolume on which the destination file should be created.
-> pathNamePPointer to the complete path and name of the destination file to be created.
-> cardNoCard number on which the .pdb or .prc being exported resides.
-> dbIDID of the database being exported.

Result

Returns one of the following error codes:

errNone No error
expErrNotEnoughPowerThere is insufficient battery power to perform the database export operation.
vfsErrBadNameThe 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

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSExportDatabaseToFileCustom, VFSFileWrite, VFSImportDatabaseFromFile

New VFSExportDatabaseToFileCustom

Purpose

Saves 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.

Prototype

Err VFSExportDatabaseToFileCustom (UInt16 volRefNum, const Char *pathNameP, UInt16 cardNo, LocalID dbID, VFSExportProcPtr exportProcP, void *userDataP)

Parameters

-> volRefNumVolume on which the destination file should be created.
-> pathNamePPointer to the complete path and name of the destination file to be created.
-> cardNoCard number on which the .pdb or .prc being exported resides.
-> dbIDID of the database being exported.
-> exportProcPUser-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. See VFSExportProcPtr for the requirements of this function.
-> userDataPPointer to any data you want to pass to the callback function specified in exportProcP. This information is not used internally by the VFS Manager. Pass NULL if you don't have a progress callback function or if that function doesn't need any such data.

Result

Returns one of the following error codes:

errNone No error.
expErrNotEnoughPowerThere is insufficient battery power to perform the database export operation.
vfsErrBadNameThe 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

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSExportDatabaseToFile, VFSFileWrite, VFSImportDatabaseFromFileCustom

New VFSFileClose

Purpose

Closes a file or directory that has been opened with VFSFileOpen.

Prototype

Err VFSFileClose (FileRef fileRef)

Parameters

-> fileRefFile reference number returned from VFSFileOpen.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSFileCreate

Purpose

Create a file. This function cannot be used to create a directory; use VFSDirCreate instead.

Prototype

Err VFSFileCreate(UInt16 volRefNum, const Char *pathNameP)

Parameters

-> volRefNumReference number of the volume on which to create the file. This volume reference number is returned from VFSVolumeEnumerate.
-> pathNamePPointer to the full path of the file to be created. All parts of the path, excluding the filename, must already exist.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameThe pathNameP is invalid.
vfsErrFileAlreadyExistsA file with this name already exists in this location.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe volume has not been mounted.
vfsErrVolumeFullThere 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 in the Expansion chapter of the Palm OS Programmer's Companion, vol. I 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileDelete

New VFSFileDBGetRecord

Purpose

Load a record from an opened .pdb file on an external card into the storage heap.

Prototype

Err VFSFileDBGetRecord (FileRef ref, UInt16 recIndex, MemHandle *recHP, UInt8 *recAttrP, UInt32 *uniqueIDP)

Parameters

-> refThe file reference returned from VFSFileOpen. Note that the open file must be a .pdb file.
-> recIndexThe index of the record to load.
<- recHPPointer 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 not NULL, you must dispose of the allocated handle using MemHandleFree.
<- recAttrPPointer to the attributes of the record. The values returned are identical to the atttributes returned from DmRecordInfo. See Record Attribute Constants in the Data and Resource Manager chapter for a description of each attribute. Pass NULL for this parameter if you do not want to retrieve this information.
<- uniqueIDPPointer to the unique identifier for this record. Pass NULL for this parameter if you do not want to retrieve this information.

Result

Returns one of the following error codes:

errNone No error.
dmErrIndexOutOfRangeThe recIndex is out of range.
dmErrNotRecordDBThe file referenced by ref is not a record database.
memErrNotEnoughSpaceThere is not enough space in memory for the requested record entry.
sysErrParamErrA NULL value was passed in for the recHP, recAttrP, and uniqueIDP parameters.
vfsErrBadDataThe 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.


NOTE: This function is not efficient for multiple accesses and should be used sparingly.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileReadData

New VFSFileDBGetResource

Purpose

Load a resource into the storage heap from an opened .prc file.

Prototype

Err VFSFileDBGetResource (FileRef ref, DmResType type, DmResID resID, MemHandle *resHP)

Parameters

-> refThe file reference returned from VFSFileOpen. Note that the open file must be a .prc file.
-> typeThe type of resource to load. See the Data and Resource Manager chapter for more information on resources.
-> resIDThe ID of resource to load.
<- resHPPointer to the resource data handle that was loaded into memory.

Result

Returns one of the following error codes:

errNone No error.
dmErrNotResourceDBThe file referenced by ref is not a resource database.
dmErrResourceNotFoundThe requested resource was not found.
memErrNotEnoughSpaceThere is not enough space in memory for the requested resource entries.
sysErrParamErrresHP is NULL.

Comments

This function locates the specified resource in the open .prc file. See the Palm OS File Format Specification 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.


NOTE: This function is not efficient for multiple accesses and should be used sparingly.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSFileDBInfo

Purpose

Get information about a database represented by an open .prc or .pdb file.

Prototype

Err VFSFileDBInfo (FileRef ref, Char *nameP, UInt16 *attributesP, UInt16 *versionP, UInt32 *crDateP, UInt32 *modDateP, UInt32 *bckUpDateP, UInt32 *modNumP, MemHandle *appInfoHP, MemHandle *sortInfoHP, UInt32 *typeP, UInt32 *creatorP, UInt16 *numRecordsP)

Parameters

-> refThe file reference returned from VFSFileOpen. Note that the open file must be a .prc or .pdb file.
<- namePPointer 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.
<- attributesPPointer to the database attributes stored in the file. The values returned are identical to the atttributes returned from DmDatabaseInfo. See the Database Attribute Constants section for a description of each attribute. Pass NULL for this parameter if you do not want to retrieve the database's attributes.
<- versionPPointer 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.
<- crDatePPointer 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.
<- modDatePPointer 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.
<- bckUpDatePPointer 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.
<- modNumPPointer 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.
<- appInfoHPPointer 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 than NULL is returned, you must dispose of the allocated handle using MemHandleFree. If you do not want to retrieve the application info block, pass NULL for this parameter
<- sortInfoHPPointer 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 than NULL is returned, you must dispose of the allocated handle using MemHandleFree. Pass NULL for this parameter if you do not want to retrieve the sort info block handle.
<- typePPointer to the type of database as it was created. This may be a user-defined database type or a database type defined by the Palm OS. Some of the more common database types returned here are:
Type
Description
'appl'
Standard PalmTM 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.
<- creatorPPointer to the database's creator. Pass NULL for this parameter if you do not want to retrieve this information.
<- numRecordsPPointer to the number of records in the database. Pass NULL for this parameter if you do not want to retrieve this information.

Result

Returns one of the following error codes:

errNone No error
memErrNotEnoughSpaceThere is not enough space in memory for the database header.
vfsErrBadDataThe 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 the Palm OS File Format Specification for a description of the header block in  .prc and .pdb files.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileGetAttributes, VFSFileGetDate

New VFSFileDelete

Purpose

Deletes a closed file or directory.

Prototype

Err VFSFileDelete(UInt16 volRefNum, const Char *pathNameP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
-> pathNamePPointer to the full path of the file or directory to be deleted.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameThe path name specified in pathNameP is not valid.
vfsErrDirNotEmptyThe directory being deleted is not empty.
vfsErrFileStillOpenThe file is still open.
vfsErrFileNotFoundThe file could not be found.
vfsErrFilePermissionDeniedThe requested permissions could not be granted.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe volume has not been mounted.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSFileEOF

Purpose

Get end-of-file status for an open file. This function only operates on files and cannot be used with directories.

Prototype

Err VFSFileEOF (FileRef fileRef)

Parameters

-> fileRefFile reference returned from VFSFileOpen.

Result

Returns one of the following error codes:

errNone No error. File pointer is not at end of the file.
vfsErrFileEOFThe file pointer is at the end of file.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSFileGetAttributes

Purpose

Obtain the attributes of an open file or directory.

Prototype

Err VFSFileGetAttributes (FileRef fileRef, UInt32 *attributesP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
<- attributesPPointer 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.

Result

Returns one of the following error codes:

errNone No error
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileDBInfo, VFSFileGetDate, VFSFileSetAttributes

New VFSFileGetDate

Purpose

Obtain the dates on an open file or directory.

Prototype

Err VFSFileGetDate (FileRef fileRef, UInt16 whichDate, UInt32 *dateP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> whichDateSpecifies which date-creation, modification, or last access-you want. Supply one of the following values:
vfsFileDateCreated
vfsFileDateModified
vfsFileDateAccessed
Note that not all file systems are required to support the above dates. If the supplied date type is not supported by the file system, VFSFileGetDate returns expErrUnsupportedOperation.
<- datePPointer 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
expErrUnsupportedOperationThe specified date type is not supported by the underlying file system.
vfsErrFileBadRefThe specified file reference is invalid.
sysErrParamErrThe whichDate parameter is not one of the defined constants.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileDBInfo, VFSFileGetAttributes, VFSFileSetDate

New VFSFileOpen

Purpose

Opens a file or directory and returns a reference for it.

Prototype

Err VFSFileOpen (UInt16 volRefNum, const Char *pathNameP, UInt16 openMode, FileRef *fileRefP)

Parameters

-> volRefNumThe volume reference number returned from VFSVolumeEnumerate.
-> pathNamePPointer 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" in Chapter 8, "Expansion," of the Palm OS Programmer's Companion, vol. I for a description of how to construct a valid path.
-> openModeMode to use when opening the file. See the Open Mode Constants section for a list of accepted modes.
<- fileRefPPointer to the opened file or directory reference which is supplied to various other VFSFile... operations. This value is filled in on return.

Result

Returns one of the following error codes:

errNone No error.
expErrCardReadOnlyThe open mode requested includes write access but the file is read-only.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameThe pathNameP parameter is invalid.
vfsErrFileNotFoundThe specified file or directory could not be found.
vfsErrFilePermissionDeniedThe file cannot be opened in the requested open mode, or it has already been opened with vfsModeExclusive.
vfsErrVolumeBadRefThe specified volume has not been mounted.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileClose, VFSDirEntryEnumerate

New VFSFileRead

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.

Prototype

Err VFSFileRead (FileRef fileRef, UInt32 numBytes, void *bufP, UInt32 *numBytesReadP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> numBytesNumber of bytes to read.
<- bufPPointer to the destination chunk where the data is to be stored. This can be a pointer to any writable memory.
<- numBytesReadPPointer 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrFileEOFThe end of the file has been reached.
vfsErrFilePermissionDeniedRead permission is not enabled for this file.
vfsErrIsADirectoryThe specified file reference is for a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileReadData, VFSFileWrite, VFSImportDatabaseFromFile

New VFSFileReadData

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.

Prototype

Err VFSFileReadData (FileRef fileRef, UInt32 numBytes, void *bufBaseP, UInt32 offset, UInt32 *numBytesReadP)

Parameters

-> fileRefFile reference returned in VFSFileOpen.
-> numBytesNumber of bytes to read.
<- bufBasePPointer 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.
-> offsetOffset, in bytes, within the bufBaseP chunk where the data is to be written.
<- numBytesReadPPointer 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrFileEOFThe end of the file has been reached.
vfsErrFilePermissionDeniedRead permission is not enabled for this file.
vfsErrIsADirectoryThe specified file reference is for a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileRead, VFSFileWrite

New VFSFileRename

Purpose

Rename a closed file or directory. This function cannot be used to move a file to another directory within the file system.

Prototype

Err VFSFileRename (UInt16 volRefNum, const Char *pathNameP, const Char *newNameP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
-> pathNamePPointer to the full path of the file or directory to be renamed.
-> newNamePPointer to the new filename. Note that this is the name of the file only and does not include the path to the file.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameThe name provided in either pathNameP or newNameP is invalid. This is also returned if the string pointed to by newNameP is a path, rather than a filename.
vfsErrFileAlreadyExistsA file with the new name already exists in this location.
vfsErrFileNotFoundThe source file could not be found.
vfsErrFilePermissionDeniedWrite permission is not enabled for this file.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe volume has not been mounted.
vfsErrVolumeFullThere 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... 
} 

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSFileResize

Purpose

Change the size of an open file. This function only operates on files and cannot be used with directories.

Prototype

Err VFSFileResize (FileRef fileRef, UInt32 newSize)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> newSizeThe desired new size of the file. This can be larger or smaller then the current file size.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeFullThere is not enough space left on the volume.

Comments

The location of the file pointer is undefined after a call to this function.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileSize

New VFSFileSeek

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.

Prototype

Err VFSFileSeek (FileRef fileRef, FileOrigin origin, Int32 offset)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> originOrigin 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 following:
vfsOriginBeginningThe beginning of the file.
vfsOriginCurrentThe current position within the file.
vfsOriginEndThe end of the file. Only negative offsets are allowed when origin is set to vfsOriginEnd.
-> offsetOffset, 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrFileEOFThe file pointer is at the end of file.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
sysErrParamErrThe 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileSize, VFSFileTell

New VFSFileSetAttributes

Purpose

Change the attributes of an open file or directory.

Prototype

Err VFSFileSetAttributes (FileRef fileRef, UInt32 attributes)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> attributesAttributes to associate with the file or directory. See File and Directory Attributes for a list of values you can use when setting this parameter:

Result

Returns one of the following error codes:

errNoneNo error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
sysErrParamErrOne of the parameters is invalid.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrNoFileSystemThe 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileGetAttributes, VFSFileSetDate

New VFSFileSetDate

Purpose

Changes the dates on an open file or directory.

Prototype

Err VFSFileSetDate (FileRef fileRef, UInt16 whichDate, UInt32 date)

Parameters

-> fileRefFile reference returned in VFSFileOpen.
-> whichDateSpecifies which date-creation, modification, or last access-to modify. Supply one of the following values:
vfsFileDateCreated
vfsFileDateModified
vfsFileDateAccessed
Note that not all file systems are required to support the above dates. If the supplied date type is not supported by the file system, VFSFileGetDate returns expErrUnsupportedOperation.
-> dateThe 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
expErrUnsupportedOperationThe specified date type is not supported by the underlying file system.
sysErrParamErrThe whichDate parameter is not one of the defined constants.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrFilePermissionDeniedWrite permission is not enabled for this file.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileGetDate, VFSFileSetAttributes

New VFSFileSize

Purpose

Obtain the size of an open file. This function only operates on files and cannot be used with directories.

Prototype

Err VFSFileSize (FileRef fileRef, UInt32 *fileSizeP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
<- fileSizePPointer to the size of the open file.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileResize, VFSFileTell, VFSVolumeSize

New VFSFileTell

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.

Prototype

Err VFSFileTell (FileRef fileRef, UInt32 *filePosP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
<- filePosPPointer to the current file position.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileSeek, VFSFileSize

New VFSFileWrite

Purpose

Write data to an open file. This function only operates on files and cannot be used with directories.

Prototype

Err VFSFileWrite (FileRef fileRef, UInt32 numBytes, const void *dataP, UInt32 *numBytesWrittenP)

Parameters

-> fileRefFile reference returned from VFSFileOpen.
-> numBytesThe number of bytes to write.
-> dataPPointer to the data that is to be written.
<- numBytesWrittenPPointer 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.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrFileBadRefThe specified file reference is invalid.
vfsErrFilePermissionDeniedWrite permission is not enabled for this file.
vfsErrIsADirectoryThe specified file reference points to a directory instead of a file. This is an invalid operation on a directory.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeFullThere is not enough space left on the volume.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSExportDatabaseToFile, VFSExportDatabaseToFileCustom, VFSFileRead, VFSFileReadData

New VFSGetDefaultDirectory

Purpose

Determine the default location on the given volume for files of a particular type.

Prototype

Err VFSGetDefaultDirectory (UInt16 volRefNum, const Char *fileTypeStr, Char *pathStr, UInt16 *bufLenP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
-> fileTypeStrPointer 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."
<- pathStrPointer to the buffer which receives the default directory path for the requested file type.
<-> bufLenPPointer to the size of the path. Set this to the size of pathStr buffer on input. Reflects the number of bytes copied to pathStr on output.

Result

Returns one of the following error codes:

errNone No error.
vfsErrBadNameThere is no default directory registered for the requested file type.
vfsErrBufferOverflowA match was found, but the pathStr buffer is too small to hold the resulting path string. A partial path is returned in pathStr.
vfsErrFileNotFoundNo 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSDirEntryEnumerate, VFSRegisterDefaultDirectory, VFSUnregisterDefaultDirectory

New VFSImportDatabaseFromFile

Purpose

Creates a database from a .pdb or .prc file on an external storage card.

Prototype

Err VFSImportDatabaseFromFile (UInt16 volRefNum, const Char *pathNameP, UInt16 *cardNoP, LocalID *dbIDP)

Parameters

-> volRefNumVolume on which the source file resides.
-> pathNamePPointer 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.
<- dbIDPPointer 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.

Result

Returns one of the following error codes:

errNone No error.
dmErrAlreadyExistsThe .prc or .pdb file already exists in the storage heap. In this case the cardNoP and dbIDP are set to point to the existing file.
expErrNotEnoughPowerThere is insufficient battery power to complete the requested operation.
vfsErrBadNameThe 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 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

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSExportDatabaseToFile, VFSFileRead

New VFSImportDatabaseFromFileCustom

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.

Prototype

Err VFSImportDatabaseFromFileCustom (UInt16 volRefNum, const Char *pathNameP, UInt16 *cardNoP, LocalID *dbIDP, VFSImportProcPtr importProcP, void *userDataP)

Parameters

-> volRefNumVolume on which the source file resides.
-> pathNamePPointer 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.
<- dbIDPPointer 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.
-> importProcPUser-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. See VFSImportProcPtr for the requirements of this function.
-> userDataPPointer to any data you want to pass to the callback function specified in importProcP. This information is not used internally by the VFS Manager. Pass NULL if you don't have a progress callback function, or if that function doesn't need any such data.

Result

Returns one of the following error codes:

errNone No error
vfsErrBadNameThe path name specified in pathNameP is not valid.
expErrNotEnoughPowerThe power required to import a database is not available.
dmErrAlreadyExistsThe .prc or .pdb file already exists in main memory. In this case the cardNoP and dbIDP 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.

This function is used, for example, to copy applications from a storage card to main memory.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSFileRead, VFSExportDatabaseToFileCustom

New VFSInstallFSLib

Purpose

Install a file system library so that the VFS Manager can use it.

Prototype

Err VFSInstallFSLib (UInt32 creator, UInt16 *fsLibRefNumP)

Parameters

-> creatorCreator ID of the database containing the file system library to be installed.
<- fsLibRefNumPPointer to the reference number for the newly installed file system library. Supply NULL for this parameter if you don't need the library reference number.

Result

If the file system library was loaded and installed without error, errNone is returned. Any error generated by the underlying file system while opening the file system library or determining its type will be returned from VFSInstallFSLib. Other errors that can be generated during the file system library installation process include:

expErrIncompatibleAPIVerThe file system library has an incompatible API version.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
memErrNotEnoughSpace, memErrChunkNotLocked, or memErrChunkLockedA memory problem occurred while inserting the library reference into the list of installed libraries.
sysErrLibNotFound, sysErrNoFreeRAM, sysErrNoFreeLibSlots (or some other error returned from the library's install entry point)An error occurred while loading the library.

Comments

This function calls SysLibLoad to load the file system library into the library table. Once loaded the appropriate file system is asked to open the library. At boot time VFSInstallFSLib is called internally by the Expansion Manager to load all installed file system libraries and initialize them for use.

VFSInstallFSLib is not normally called by applications.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSRemoveFSLib

New VFSRegisterDefaultDirectory

Purpose

Registers 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.

Prototype

Err VFSRegisterDefaultDirectory (const Char *fileTypeStr, UInt32 mediaType, const Char *pathStr)

Parameters

-> fileTypeStrPointer 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".
-> mediaTypeType of card media for which the default directory is being associated. See Defined Media Types in the Expansion Manager chapter for the list of accepted values.
-> pathStrPointer 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.

Result

Returns one of the following error codes:

errNone No error.
sysErrParamErrEither the fileTypeStr parameter is NULL or the pathStr parameter is NULL.
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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSGetDefaultDirectory

New VFSRemoveFSLib

Purpose

Remove a file system library from the library table, so that the VFS Manager can no longer use it.

Prototype

Err VFSRemoveFSLib (UInt16 fsLibRefNum)

Parameters

-> fsLibRefNumLibrary reference number of the file system library to remove from the library table.

Result

Returns one of the following error codes:

errNoneNo error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemVFS Manager can not find the file system specified in fsLibRefNum.

Comments

This function is not normally called by applications. It unmounts any volumes that the specified file system may have mounted. It then closes the library and removes it from the library table with SysLibRemove.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSUnregisterDefaultDirectory

Purpose

Sever the association between a particular file type and a default directory for a given type of card media.

Prototype

Err VFSUnregisterDefaultDirectory (const Char *fileTypeStr, UInt32 mediaType)

Parameters

-> fileTypeStrPointer 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".
-> mediaTypeType of card media for which the default directory is associated. See Defined Media Types in the Expansion Manager chapter for the list of accepted values.

Result

Returns one of the following error codes:

errNone No error.
sysErrParamErrThe fileTypeStr parameter is NULL.
vfsErrFileNotFoundA 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSGetDefaultDirectory, VFSRegisterDefaultDirectory

New VFSVolumeEnumerate

Purpose

Enumerate the mounted volumes.

Prototype

Err VFSVolumeEnumerate (UInt16 *volRefNumP, UInt32 *volIteratorP)

Parameters

<- volRefNumPPointer 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.
<-> volIteratorPPointer to a variable that holds the index of the current enumeration. Set the variable to vfsIteratorStart prior to the first iteration. Each call to VFSVolumeEnumerate updates the variable to the index of the next volume. When the last volume is reached, the variable pointed to by volIteratorP is set to vfsIteratorStop.

Result

Returns one of the following error codes:

errNone No error
expErrEnumerationEmptyThere are no volumes to enumerate.
sysErrParamErrThe value pointed to by volIteratorP is not valid. This error is also returned when volIteratorP is vfsIteratorStop.

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 
   } 
} 

Compatibility

Implemented only if the VFS Manager Feature Set is present.

New VFSVolumeFormat

Purpose

Format and mount the volume installed in a given slot.

Prototype

Err VFSVolumeFormat (UInt8 flags, UInt16 fsLibRefNum, VFSAnyMountParamPtr vfsMountParamP)

Parameters

-> flagsFlags 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 by fsLibRefNum. Pass zero (0) to have the VFS Manager attempt to format the volume using a file system appropriate to the slot.
-> fsLibRefNumReference number of the file system library for which the volume should be formatted. This number is obtained through a call to SysLibFind with the name of the library you want to use. If the flags field is not set to vfsMountFlagsUseThisFileSystem, this parameter is ignored.
<->vfsMountParamPParameters 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 a VFSPOSEMountParamType structure. Note that you'll need to cast your structure pointer to a VFSAnyMountParamPtr. Set the mountClass field to the appropriate value: if you are mounting to an Expansion Manager slot, set mountClass to VFSMountClass_SlotDriver and initialize slotLibRefNum and slotRefNum to the appropriate values. See the descriptions of VFSAnyMountParamType, VFSSlotMountParamType, and VFSPOSEMountParamType for information on the fields that make up these data structures.

Result

Returns one of the following error codes:

errNone No error.
expErrNotEnoughPowerThere is insufficient battery power to format and/or mount a volume.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemThe 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:

1. 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; supply sysFileCVFSMgr for the feature creator, and vfsFtrIDDefaultFS for the feature number.

2. 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.

3. 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); 

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeMount

New VFSVolumeGetLabel

Purpose

Determine the volume label for a particular volume.

Prototype

Err VFSVolumeGetLabel(UInt16 volRefNum, Char *labelP, UInt16 bufLen)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
<- labelPPointer to a character buffer into which the volume name is placed.
-> bufLenLength, in bytes, of the labelP buffer.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe specified volume has not been mounted.
vfsErrBufferOverflowThe value specified in bufLen is not big enough to receive the full volume label.
vfsErrNameShortenedThere 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: $ % ' - _ @ ~ ` ! ( ) ^ # & + , ; = [ ].

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeSetLabel

New VFSVolumeInfo

Purpose

Get information about the specified volume.

Prototype

Err VFSVolumeInfo(UInt16 volRefNum, VolumeInfoType *volInfoP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
<- volInfoPPointer to the structure that receives the volume information for the specified volume. See VolumeInfoType for more information on the fields in this data structure.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe specified volume reference number is invalid.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeGetLabel, VFSVolumeSize

New VFSVolumeMount

Purpose

Mount the card's volume on the specified slot.

Prototype

Err VFSVolumeMount(UInt8 flags, UInt16 fsLibRefNum, VFSAnyMountParamPtr vfsMountParamP)

Parameters

-> flagsFlags 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 by fsLibRefNum. Pass zero (0) to have the VFS Manager attempt to mount the volume using a file system appropriate for the slot.
-> fsLibRefNumReference number of the file system library for which the volume should be mounted. This number is obtained through a call to SysLibFind with the name of the library you want to use. If the flags field is not set to vfsMountFlagsUseThisFileSystem, this parameter is ignored.
<->vfsMountParamPParameters to be used when mounting the volume after it has been formatted. Supply a pointer to either a VFSSlotMountParamType or a VFSPOSEMountParamType structure. Note that you'll need to cast your structure pointer to a VFSAnyMountParamPtr. Set the mountClass field to the appropriate value: if you are mounting to an Expansion Manager slot, set mountClass to VFSMountClass_SlotDriver and initialize slotLibRefNum and slotRefNum to the appropriate values. See the descriptions of VFSAnyMountParamType, VFSSlotMountParamType, and VFSPOSEMountParamType for information on the fields that make up these data structures.

Result

Returns one of the following error codes:

errNone No error.
expErrNotEnoughPowerThere is insufficient battery power to mount a volume.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
sysErrParamErrvfsMountParamP was initialized to NULL.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeStillMountedThe 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 in Chapter 8, "Expansion," Palm OS Programmer's Companion, vol. I.

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); 

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeFormat, VFSVolumeUnmount

New VFSVolumeSetLabel

Purpose

Changes the volume label for a mounted volume.

Prototype

Err VFSVolumeSetLabel(UInt16 volRefNum, const Char *labelP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
-> labelPPointer to the label to be applied to the specified volume. This string must be null-terminated.

Result

Returns one of the following error codes:

errNone No error
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrBadNameThe supplied label is invalid.
vfsErrNameShortenedIndicates that the label name was too long. A shortened version of the label name was used instead.
vfsErrVolumeBadRefThe 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 in Chapter 8, "Expansion,"Palm OS Programmer's Companion, vol. I 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeGetLabel

New VFSVolumeSize

Purpose

Determine the total amount of space on a volume, as well as the amount that is currently being used.

Prototype

Err VFSVolumeSize(UInt16 volRefNum, UInt32 *volumeUsedP, UInt32 *volumeTotalP)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.
<- volumeUsedPPointer to a variable that receives the amount of space, in bytes, in use on the volume.
<- volumeTotalPPointer to a variable that receives the total amount of space on the volume, in bytes.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe specified volume has not been mounted.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeInfo

New VFSVolumeUnmount

Purpose

Unmount the given volume.

Prototype

Err VFSVolumeUnmount(UInt16 volRefNum)

Parameters

-> volRefNumVolume reference number returned from VFSVolumeEnumerate.

Result

Returns one of the following error codes:

errNone No error.
expErrNotOpenThe file system library necessary for this call has not been installed or has not been opened.
vfsErrNoFileSystemThe VFS Manager cannot find an appropriate file system to handle the request.
vfsErrVolumeBadRefThe 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.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSVolumeMount

Application-Defined Functions

New VFSExportProcPtr

Purpose

User-defined callback function supplied to VFSExportDatabaseToFileCustom that tracks the progress of the export.

Prototype

typedef Err (*VFSExportProcPtr) (UInt32 totalBytes, UInt32 offset, void *userDataP)

Parameters

totalBytesThe total number of bytes being exported.
offsetUndefined.
userDataPPointer to any application-specific data passed to the callback function. This pointer may be NULL if your callback doesn't need any such data.

Result

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 the Progress Dialogs section in the Palm OS Programmer's Companion, vol. I for more information on writing a progress tracker.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSImportProcPtr

New VFSImportProcPtr

Purpose

User-defined callback function supplied to VFSImportDatabaseFromFileCustom that tracks the progress of the import.

Prototype

typedef Err (*VFSImportProcPtr) (UInt32 totalBytes, UInt32 offset, void *userDataP)

Parameters

totalBytesThe total number of bytes being imported.
offsetThe 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.
userDataPPointer to NY application-specific data passed to the callback function. This pointer may be NULL if your callback doesn't need any such data.

Result

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 the Progress Dialogs section in the Palm OS Programmer's Companion, vol. I for more information on writing a progress tracker.

Compatibility

Implemented only if the VFS Manager Feature Set is present.

See Also

VFSExportProcPtr