Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

25    Expansion Manager

System Management

Exploring Palm OS®

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 ^TOP^

CardMetricsType Struct ^TOP^

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 partition 0x00 (slotDrvrNonBootablePartition) is not-bootable. If the media guidelines don't specify, this value is set to 0xFF.
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 ^TOP^

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 ^TOP^

Expansion Manager Error Codes ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 of sysFileCExpansionMgr 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 of sysFileCExpansionMgr and a feature number of expFtrIDVersion.

Expansion Manager Functions and Macros ^TOP^

ExpCardInfo Function ^TOP^

Purpose

Obtains information about a card in a given slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpCardInfo (
   uint16_t slotRefNum,
   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 ^TOP^

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_t slotRefNum,
   uint32_t filesystemType
)

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 ^TOP^

Purpose

Determine the media type of the card in the given slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpCardMediaType (
   uint16_t slotRefNum,
   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

ExpSlotMediaType()

ExpCardMetrics Function ^TOP^

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_t slotRefNum,
   CardMetricsPtr cardMetricsP
)

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

ExpCardSectorWrite()

ExpCardPresent Function ^TOP^

Purpose

Determines if a card is present in the given slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpCardPresent (
   uint16_t slotRefNum
)

Parameters

slotRefNum
Slot number.

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 ^TOP^

Purpose

Read contiguous 512-byte sectors from the card in a specified slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpCardSectorRead (
   uint16_t slotRefNum,
   uint32_t sectorNumber,
   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()

ExpCardSectorWrite Function ^TOP^

Purpose

Write contiguous 512-byte sectors to the card in a specified slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpCardSectorWrite (
   uint16_t slotRefNum,
   uint32_t sectorNumber,
   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 in numSectorsP. 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 ^TOP^

Purpose

Handle a custom call for a particular slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpSlotCustomControl (
   uint16_t slotRefNum,
   uint32_t apiCreator,
   uint16_t apiSelector,
   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 to valueP 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 ^TOP^

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 to expIteratorStop.

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 or invalidSlotRefNum 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 ^TOP^

Purpose

Determine the media type supported by the given slot.

Declared In

ExpansionMgr.h

Prototype

status_t ExpSlotMediaType (
   uint16_t slotRefNum,
   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

ExpCardMediaType()

ExpSlotPowerCheck Function ^TOP^

Purpose

Determine if enough power is available to complete an operation before starting it.

Declared In

ExpansionMgr.h

Prototype

status_t ExpSlotPowerCheck (
   uint16_t slotRefNum,
   uint16_t operationFlags,
   uint16_t readBlocks,
   uint16_t writeBlocks
)

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.