This chapter contains reference material for the Expansion Manager, which applications use to work with the handheld's expansion slots. Note that to perform filesystem operations on the media in the slot you use the VFS Manager, which is documented in Exploring Palm OS: Memory, Databases, and Files.
This chapter is organized into the following sections:
Expansion Manager Structures and Types
Expansion Manager Constants
Expansion Manager Functions and Macros
The header file ExpansionMgr.h
declares the API that this chapter describes.
For basic Expansion Manager concepts and instructions on using the Expansion Manager APIs, see Chapter 5, "Expansion."
Expansion Manager Structures and Types
CardMetricsType Struct
Purpose
Contains information about the physical structure of the card: the type of information that may be needed by a file system in order to format volumes on the card, for instance. This structure is passed as a parameter in ExpCardMetrics()
.
Declared In
ExpansionMgr.h
Prototype
typedef struct CardMetricsTag { uint32_t totalSectors; uint16_t bytesPerSector; uint16_t sectorsPerHead; uint16_t headsPerCylinder; uint16_t reserved1; uint8_t sectorsPerBlock; uint8_t partitionType; uint8_t bootIndicator; uint8_t reserved2; uint32_t partitionStart; uint32_t partitionSize; } CardMetricsType, *CardMetricsPtr
Fields
-
totalSectors
- The total number of sectors accessible. Some media may contain extra sectors in case one goes bad, or for storing configuration information, but they are handled internally to the block device driver, and not accessible to applications.
-
bytesPerSector
- The number of bytes in one sector. Currently for Palm OS, this must be 512.
-
sectorsPerHead
- The number of Sectors per Head as given by guidelines in the specification for this media type. Even though all Palm OS disk accesses are LBA, this is for compatibility when filling out MBRs and PBRs. If the media guidelines don't specify, this value is set to 0.
-
headsPerCylinder
- The number of Heads per Cylinder as given by guidelines in the specification for this media type. Even though all Palm OS disk accesses are LBA, this is for compatibility when filling out MBRs and PBRs. If the media guidelines don't specify, this value is set to 0.
-
reserved1
- Reserved
-
sectorsPerBlock
- A suggested number of Sectors per Block (Cluster) as given by guidelines in the specification for this media type. If the media guidelines don't specify, this value is set to 0.
-
partitionType
- The suggested partition type (System ID) of the first partition as given by guidelines in the specification for this media type. If the media guidelines don't specify, this value is set to slotDrvrNonBootablePartition. See "Partition Type Flags" for a list of defined partition types.
-
bootIndicator
- The suggested bootability of the first partition as given by guidelines in the specification for this media type. Generally,
0x80
(slotDrvrBootablePartition)is bootable, while the default boot partition0x00
(slotDrvrNonBootablePartition) is not-bootable. If the media guidelines don't specify, this value is set to0xFF
. -
reserved2
- Reserved
-
partitionStart
- The suggested starting sector of the first partition as given by guidelines in the specification for this media type. If this value is set to zero, and the partition size value is non-zero, the media guidelines suggest to not use an MBR, and only use a PBR at sector 0. If the media guidelines don't specify, the partition size value is set to 0.
-
partitionSize
- The suggested size of the first partition as given by guidelines in the specification for this media type. If the media guidelines don't specify, this value is set to 0, and the partition start parameter is ignored.
ExpCardInfoType Struct
Purpose
The ExpCardInfoType
declaration defines a structure that is passed to ExpCardInfo()
. This structure is used to determine the characteristics of the card loaded in the slot. It is initialized by the underlying block device driver with the following information.
Declared In
ExpansionMgr.h
Prototype
typedef struct ExpCardInfoTag { uint32_t capabilityFlags; char manufacturerStr[expCardInfoStringMaxLen+1]; char productStr[expCardInfoStringMaxLen+1]; char deviceClassStr[expCardInfoStringMaxLen+1]; char deviceUniqueIDStr[expCardInfoStringMaxLen+1]; } ExpCardInfoType, *ExpCardInfoPtr
Fields
-
capabilityFlags
- Describes the capabilities of the card. See "Capability Flags" for the set of flags that are currently supported.
-
manufacturerStr
- Names the manufacturer of the card. For example "Palm" or "Motorola".
-
productStr
- Name of the product. For example "SafeBackup 32MB".
-
deviceClassStr
- Describes the type of card, for example, "Backup" or "Ethernet".
-
deviceUniqueIDStr
- Unique identifier for the product. A serial number for example. This value is set to the empty string if no identifier exists.
Expansion Manager Constants
Expansion Manager Error Codes
Purpose
Error codes returned by the various Expansion Manager functions.
Declared In
ExpansionMgr.h
Constants
-
#define expErrCardBadSector (expErrorClass | 8)
- The card supports the block device driver block read/write API but the sector is bad.
-
#define expErrCardNoSectorReadWrite (expErrorClass | 6)
- The card does not support the block device driver block read/write API.
-
#define expErrCardNotPresent (expErrorClass | 3)
- There is no card present in the given slot.
-
#define expErrCardProtectedSector (expErrorClass | 9)
- The card supports the block device driver block read/write API but the sector is protected.
-
#define expErrCardReadOnly (expErrorClass | 7)
- The card supports the block device driver block read/write API but the card is read only.
-
#define expErrEnumerationEmpty (expErrorClass | 13)
- There are no values remaining to enumerate.
-
#define expErrIncompatibleAPIVer (expErrorClass | 14)
- The API version of the underlying block device driver is not supported by this version of Expansion Manager.
-
#define expErrInvalidSlotRefNum (expErrorClass | 4)
- The slot reference number is not valid.
-
#define expErrNotEnoughPower (expErrorClass | 2)
- The required power is not available.
-
#define expErrNotOpen (expErrorClass | 10)
- The block device driver library has not been opened.
-
#define expErrSlotDeallocated (expErrorClass | 5)
- The slot reference number is within the valid range, but the slot has been deallocated.
-
#define expErrStillOpen (expErrorClass | 11)
- The block device driver library is still open; it may have been opened more than once.
-
#define expErrUnimplemented (expErrorClass | 12)
- The call is unimplemented.
-
#define expErrUnsupportedOperation (expErrorClass | 1)
- The operation is unsupported or undefined.
Defined Media Types
Purpose
The following media types are defined by the Expansion Manager. These media types are used with the function VFSVolumeInfo()
in the VolumeInfoType.mediaType
field. The media type is also passed as a parameter to the VFSRegisterDefaultDirectory()
and VFSUnregisterDefaultDirectory()
functions.
Declared In
ExpansionMgr.h
Constants
-
#define expMediaType_Any 'wild'
- Matches all media types when looking up a default directory
-
#define expMediaType_CompactFlash 'cfsh'
- Compact Flash
-
#define expMediaType_MacSim 'PSim'
- Host file system emulated by the Mac Simulator
-
#define expMediaType_MemoryStick 'mstk'
- Memory stick
-
#define expMediaType_MultiMediaCard 'mmcd'
- MultiMedia Card
-
#define expMediaType_PoserHost 'pose'
- Host file system emulated by the Palm OS® Emulator
-
#define expMediaType_RAMDisk 'ramd'
- A RAM disk based media
-
#define expMediaType_SecureDigital 'sdig'
- Secure Digital
-
#define expMediaType_SmartMedia 'smed'
- SmartMedia
Capability Flags
Purpose
Describes the capabilities of the expansion card.
Declared In
ExpansionMgr.h
Constants
-
#define expCapabilityHasStorage (0x00000001)
- The card supports reading and (possibly) writing.
-
#define expCapabilityReadOnly (0x00000002)
- The card is read only.
-
#define expCapabilitySerial (0x00000004)
- The card supports a simple serial interface.
Enumeration Constants
Purpose
Control the process of slot enumeration when using ExpSlotEnumerate()
.
Declared In
ExpansionMgr.h
Constants
-
#define expIteratorStart (0L)
- Supply this value to
ExpSlotEnumerate()
to begin enumeration. -
#define expIteratorStop (0xffffffffL)
- When enumeration reaches the last slot,
ExpSlotEnumerate()
sets its slot iterator parameter to this value. -
#define expInvalidSlotRefNum (0)
- When enumerating slots, if the handheld has no expansion slots
ExpSlotEnumerate()
sets its slot reference number parameter to this value.
Partition Type Flags
Purpose
The suggested partition type (System ID) of the first partition as given by guidelines in the specification for the media type.
Declared In
ExpansionMgr.h
Constants
-
#define slotDrvrBootablePartition (0x80)
- The partition is bootable.
-
#define slotDrvrNonBootablePartition (0x00)
- The partition is non-bootable.
-
#define slotDrvrPartitionTypeFAT12 (0x01)
- The partition is formatted as FAT12.
-
#define slotDrvrPartitionTypeFAT16Over32MB (0x06)
- The partition is formatted as FAT16 and exceeds 32 MB.
-
#define slotDrvrPartitionTypeFAT16Under32MB (0x04)
- The partition is formatted as FAT16 but is less than 32 MB in size.
-
#define slotDrvrPartitionTypeFAT32 (0x0b)
- The partition is formatted as FAT32.
Comments
The partition type is returned in the partitionType
field of the CardMetricsType
structure by a call to ExpCardMetrics()
. The returned value is a combination of one of the slotDrvrPartitionType...
flags and either slotDrvrBootablePartition
or slotDrvrNonBootablePartition
. A value of zero (equivalent to slotDrvrNonBootablePartition
) is returned if the media guidelines don't specify a partition type.
Miscellaneous Expansion Manager Constants
Purpose
The Expansion Manager also defines these constants.
Declared In
ExpansionMgr.h
Constants
-
#define expCardInfoStringMaxLen (31)
- Maximum length (not including the terminating null character) of the strings in the
ExpCardInfoType
structure. -
#define expFtrIDVersion (0)
- To obtain the version of the Expansion Manager, call
FtrGet()
, supplying a feature creator ofsysFileCExpansionMgr
and this constant for the feature number. -
#define expHandledSound (0x02)
-
#define expHandledVolume (0x01)
-
#define expMgrVersionNum ((uint16_t)300)
- The current version of the Expansion Manager. To obtain the version of the Expansion Manager running on the handheld, call
FtrGet()
, supplying a feature creator ofsysFileCExpansionMgr
and a feature number ofexpFtrIDVersion
.
Expansion Manager Functions and Macros
ExpCardInfo Function
Purpose
Obtains information about a card in a given slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardInfo ( uint16_tslotRefNum
, ExpCardInfoType*infoP
)
Parameters
-
→ slotRefNum
- Slot number.
-
← infoP
- Pointer to
ExpCardInfoType
structure.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrCardNotPresent
- There is no card present in the specified slot.
-
expErrInvalidSlotRefNum
- The specified slot number is invalid.
-
expErrSlotDeallocated
- The specified slot number is within the valid range but has been deallocated.
Comments
This function returns information about a card, including whether the card supports secondary storage or is strictly read-only, by filling in the ExpCardInfoType
structure's fields.
See Also
ExpCardPresent()
, ExpSlotEnumerate()
ExpCardIsFilesystemSupported Function
Purpose
Determine whether a particular file system type is natively supported by the media in the defined slot.
Declared In
ExpansionMgr.h
Prototype
Boolean ExpCardIsFilesystemSupported ( uint16_tslotRefNum
, uint32_tfilesystemType
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
→ filesystemType
- One of the file system types that this library implements. See "Defined File Systems" in the VFS Manager chapter of Exploring Palm OS: Memory, Databases, and Files for a list of file system types.
Returns
Returns true
if the specified file system is supported, or false
if either the file system is not supported or if an error occurred.
Comments
Native support means that formatting the media for another type of file system will probably break the media when used with other devices (such as digital cameras, voice recorders etc.) for which it was designed.
The VFS Manager uses this function to determine the best file system to be used when formatting media in a slot, and to warn the user before formatting media with an incompatible type.
ExpCardMediaType Function
Purpose
Determine the media type of the card in the given slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardMediaType ( uint16_tslotRefNum
, uint32_t*mediaTypeP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
← mediaTypeP
- Set to the media type of the card in the given slot. See "Defined Media Types" for a list of possible media types.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- Block device driver library has not been opened
-
expErrInvalidSlotRefNum
- Slot reference number is not valid.
-
expErrCardNotPresent
- No card is present in the specified slot.
Comments
This function sets the mediaTypeP
to reflect the kind of media that is in the slot. Supported media types are defined in ExpansionMgr.h
. The media type is used by VFSVolumeInfo()
, VFSRegisterDefaultDirectory()
, and VFSUnregisterDefaultDirectory()
(see Exploring Palm OS: Memory, Databases, and Files for information on the VFS Manager).
See Also
ExpCardMetrics Function
Purpose
Get all of the information about the physical structure of the card. The returned information is of the type that may be needed by a file system in order to format volumes on the card.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardMetrics ( uint16_tslotRefNum
, CardMetricsPtrcardMetricsP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
← cardMetricsP
- Filled in on return with information on the physical layout of the card. Note that if the
reservedRangesP
field of this structure is filled in, it is the responsibility of the caller to dispose of this memory allocated by this function. Refer to "CardMetricsType" for a description of the fields in this structure.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- Block device driver library has not been opened
-
expErrInvalidSlotRefNum
- Slot reference number is not valid.
-
expErrCardNotPresent
- No card is present in the specified slot.
See Also
ExpCardPresent Function
Purpose
Determines if a card is present in the given slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardPresent (
uint16_t slotRefNum
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrCardNotPresent
- There is no card present in the specified slot.
-
expErrInvalidSlotRefNum
- The specified slot number is invalid.
-
expErrSlotDeallocated
- The specified slot number is within the valid range but has been deallocated.
Comments
The Expansion Manager passes the call through to the appropriate block device driver.
See Also
ExpCardInfo()
, ExpSlotEnumerate()
ExpCardSectorRead Function
Purpose
Read contiguous 512-byte sectors from the card in a specified slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardSectorRead ( uint16_tslotRefNum
, uint32_tsectorNumber
, uint8_t*bufferP
, uint32_t*numSectorsP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
→ sectorNumber
- The sector from which to start reading.
-
← bufferP
- Buffer that will receive the sectors read from the card. This buffer must be a multiple of 512 bytes long.
-
↔ numSectorsP
- When calling this function, set this to the number of sectors to read. Upon return, it is set to the number of sectors actually read.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- Block device driver library has not been opened
-
expErrInvalidSlotRefNum
- Slot reference number is not valid.
-
expErrCardNoSectorReadWrite
- The card does not support the block read/write API.
-
expErrCardBadSector
- One of the requested sectors is bad.
-
expErrCardProtectedSector
- One of the requested sectors is protected.
-
expErrCardNotPresent
- No card is present.
Comments
This function is used by the file system library to read data from the media. Information such as the MBR, PBR, Volume Label, and data itself are all obtained using this function. Applications normally use one of the VFS Manager read functions, which in turn call this one.
See Also
ExpCardSectorWrite Function
Purpose
Write contiguous 512-byte sectors to the card in a specified slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpCardSectorWrite ( uint16_tslotRefNum
, uint32_tsectorNumber
, uint8_t*bufferP
, uint32_t*numSectorsP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
→ sectorNumber
- The sector at which to start writing.
-
→ bufferP
- Buffer containing the data being written to the card, or
NULL
to clear the number of sectors indicated innumSectorsP
. This buffer must be a multiple of 512 bytes long. -
↔ numSectorsP
- When calling this function, set this to the number of sectors to write. Upon return, it is set to the number of sectors actually written.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- Block device driver library has not been opened
-
expErrInvalidSlotRefNum
- Slot reference number is not valid.
-
expErrCardNoSectorReadWrite
- The card does not support the block read/write API.
-
expErrCardReadOnly
- The card is read only
-
expErrCardBadSector
- One of the requested sectors is bad.
-
expErrCardProtectedSector
- One of the requested sectors is protected.
-
expErrCardNotPresent
- No card is present.
Comments
This function is used by the file system library to write data to the media. Information such as the Volume Label, File Name, File Attributes, as well as the files and directories themselves are all created with this function. Applications normally use one of the VFS Manager write functions, which in turn call this one.
ExpSlotCustomControl Function
Purpose
Handle a custom call for a particular slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpSlotCustomControl ( uint16_tslotRefNum
, uint32_tapiCreator
, uint16_tapiSelector
, void*valueP
, uint16_t*valueLenP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
→ apiCreator
- Registered creator code.
-
→ apiSelector
- Custom operation to perform. The value of this parameter also determines what kind of data is used with
valueP
. -
↔ valueP
- Buffer containing data specific to the operation specified in
apiSelector
. -
↔ valueLenP
- Size of the
valueP
buffer on entry, size of data written tovalueP
on exit.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrNotOpen
- Block device driver library has not been opened
-
expErrUnsupportedOperation
- The selector and/or creator is unsupported or undefined.
-
sysErrParamErr
-
valueP
buffer is too small
Comments
This function is used to make custom calls to the block device driver, calls beyond what is supported by the VFS and Expansion Managers. Depending on the block device driver, custom calls might allow you to do such things as read and write physical blocks on the media, obtain special information for diagnostics, or help with debugging.
Block device drivers identify each call by a registered creator code and a selector.
ExpSlotEnumerate Function
Purpose
Iterates through valid slot numbers.
Declared In
ExpansionMgr.h
Prototype
status_t ExpSlotEnumerate ( uint16_t*slotRefNumP
, uint32_t*slotIteratorP
)
Parameters
-
← slotRefNumP
- Reference number of the currently-enumerated slot.
-
→ slotIteratorP
- Pointer to the index of the last entry enumerated. For the first iteration, initialize this parameter to the constant
expIteratorStart
. Upon return this references the next entry in the directory. If this is the last entry, this parameter is set toexpIteratorStop
.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrEnumerationEmpty
- There are no slots left to enumerate.
slotRefNumP
is set to the slot number of the currently enumerated slot orinvalidSlotRefNum
if there are no slots.
Comments
This function iterates through the device's slots. The first time this function is called, set *
slotIteratorP
to expIteratorStart to find the initial slot. Once set this value is changed with each subsequent call to this function until it reaches the maximum number of slots, at which point ExpSlotEnumerate()
sets *
slotIteratorP
to expIteratorStop
.
Example
The following is an example of how ExpSlotEnumerate()
should be used:
UInt16 slotRefNum;
UInt32 slotIterator = expIteratorStart;
while (slotIterator != expIteratorStop) {
if ((err = ExpSlotEnumerate(&slotRefNum,
&slotIterator)) == errNone) {
// do something with the slotRefNum
else {
// handle error (by breaking out of the
// loop, most likely
}
}
See Also
ExpCardInfo()
, ExpCardPresent()
ExpSlotMediaType Function
Purpose
Determine the media type supported by the given slot.
Declared In
ExpansionMgr.h
Prototype
status_t ExpSlotMediaType ( uint16_tslotRefNum
, uint32_t*mediaTypeP
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
← mediaTypeP
- Set to the media type supported by the given slot. See "Defined Media Types" for a list of possible media types.
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
expErrInvalidSlotRefNum
- The specified slot number is invalid.
-
expErrNotOpen
- The block device driver library has not been opened.
Comments
This function returns the type of media that is supported by the slot, irrespective of whether there is a card in the slot.
See Also
ExpSlotPowerCheck Function
Purpose
Determine if enough power is available to complete an operation before starting it.
Declared In
ExpansionMgr.h
Prototype
status_t ExpSlotPowerCheck ( uint16_tslotRefNum
, uint16_toperationFlags
, uint16_treadBlocks
, uint16_twriteBlocks
)
Parameters
-
→ slotRefNum
- Slot reference number.
-
→ operationFlags
- Flags for specific operations. The two flags currently supported are:
-
slotLibPowerFlag_WakeUp
- Add the power required to bring the slot hardware out of low-power mode.
-
slotLibPowerFlag_FormatMedia
- Add the power required to perform a low-level format of the card media.
-
→ readBlocks
- Add the power required to read n blocks into main memory
-
→ writeBlocks
- Add the power required to write n blocks onto the card media
Returns
Returns errNone
if the necessary power is available, expErrNotEnoughPower if the necessary power is not available, or one of the following if an error occurred:
-
expErrInvalidSlotRefNum
- The specified slot number is invalid.
-
expErrNotOpen
- The block device driver library has not been opened.
-
expErrCardNoSectorReadWrite
- The card does not support the read/write API, but readBlocks or writeBlocks was non-zero.
-
expErrCardNotPresent
- No card is present.
Comments
This function adds up all the power indicated by the parameters and returns expErrNotEnoughPower if there isn't enough battery power to perform the operation, errNone
if there is, or an error code if the operation couldn't be completed successfully.
When formatting a volume, for example, pass slotLibPowerFlag_FormatMedia
to indicate power is needed for a low level format of the card, and pass a number greater than zero for writeBlocks
to indicate power is required to install an empty file system.