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

33    Expansion Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

This chapter provides the following information about the Expansion Manager:

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

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

Expansion Manager Data Structures ^TOP^

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 slot driver with the following information.

Prototype

typedef struct ExpCardInfoTag {
UInt32 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. The following flags are currently supported:
expCapabilityHasStorage
Indicates that the card supports reading and (possibly) writing.
expCapabilityHidden
Indicates that the expansion card should not be visible to the user.
expCapabilityNonRemovable
Indicates that the expansion card cannot be removed.
expCapabilityReadOnly
Indicates that the card is read only.
expCapabilitySerial
Indicates that the card supports a simple serial interface.
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^

Error Codes ^TOP^

The Expansion Manager defines the following error codes:

Constant

Description

expErrUnsupportedOperation

The operation is unsupported or undefined.

expErrNotEnoughPower

The required power is not available.

expErrCardNotPresent

There is no card present in the given slot.

expErrInvalidSlotRefNum

The slot reference number is not valid.

expErrSlotDeallocated

The slot reference number is within the valid range, but the slot has been deallocated.

expErrCardNoSectorReadWrite

The card does not support the slot driver block read/write API.

expErrCardReadOnly

The card supports the slot driver block read/write API but the card is read only.

expErrCardBadSector

The card supports the slot driver block read/write API but the sector is bad.

expErrCardProtectedSector

The card supports the slot driver block read/write API but the sector is protected.

expErrNotOpen

The slot driver library has not been opened.

expErrStillOpen

The slot driver library is still open; it may have been opened more than once.

expErrUnimplemented

The call is unimplemented.

expErrEnumerationEmpty

There are no values remaining to enumerate.

expErrIncompatibleAPIVer

The API version of the underlying slot driver is not supported by this version of Expansion Manager.

Defined Media Types ^TOP^

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.

Constant

Value

Description

expMediaType_Any

'wild'

Matches all media types when looking up a default directory

expMediaType_MemoryStick

'mstk'

Memory stick

expMediaType_CompactFlash

'cfsh'

Compact Flash

expMediaType_SecureDigital

'sdig'

Secure Digital

expMediaType_MultiMediaCard

'mmcd'

MultiMedia Card

expMediaType_SmartMedia

'smed'

SmartMedia

expMediaType_RAMDisk

'ramd'

A RAM disk based media

expMediaType_PoserHost

'pose'

Host file system emulated by the Palm OS® Emulator

expMediaType_MacSim

'PSim'

Host file system emulated by the Mac Simulator

Expansion Manager Functions ^TOP^

ExpCardGetSerialPort Function ^TOP^

Purpose

Get a card's serial port creator ID for use in serial access.

Declared In

ExpansionMgr.h

Prototype

Err ExpCardGetSerialPort(
   UInt16 slotRefNum,
   UInt32 *portP
)

Parameters

slotRefNum
Slot number of slot to check.
portP
Pointer to UInt32 into which the serial port creator ID is stored.

Returns

Returns the following result codes:

errNone
No error
expErrInvalidSlotRefNum
The specified slot number is invalid.
expErrSlotDeallocated
The specified slot number is within the valid range but has been deallocated.

Compatibility

Implemented only if the Expansion Manager Feature Set is present. If Palm OS Cobalt Feature Set is present this function is unimplemented.

See Also

ExpCardInfo()

ExpCardInfo Function ^TOP^

Purpose

Obtains information about a card in a given slot.

Declared In

ExpansionMgr.h

Prototype

Err ExpCardInfo(
   UInt16 slotRefNum,
   ExpCardInfoType *infoP
)

Parameters

slotRefNum
Slot number.
infoP
Pointer to ExpCardInfoType structure.

Returns

Returns one of the following result codes:

errNone
No error
expErrCardNotPresent
There is no card present in the specified slot.
expErrInvalidSlotRefNum
The slot number is invalid.
expErrSlotDeallocated
The 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.

Compatibility

Implemented only if the Expansion Manager Feature Set is present.

See Also

ExpCardGetSerialPort(), ExpCardPresent(), ExpSlotEnumerate()

ExpCardPresent Function ^TOP^

Purpose

Determines if a card is present in the given slot.

Declared In

ExpansionMgr.h

Prototype

Err ExpCardPresent(
   UInt16 slotRefNum
)

Parameters

slotRefNum
Slot number.

Returns

Returns the following result codes:

errNone
A card is present in the specified slot.
expErrCardNotPresent
There is no card present in the specified slot.
expErrInvalidSlotRefNum
The specified slot number is not valid.
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 slot driver.

Compatibility

Implemented only if the Expansion Manager Feature Set is present.

See Also

ExpCardInfo(), ExpSlotEnumerate()

ExpSlotDriverInstall Function ^TOP^

Purpose

Installs and initializes a slot driver shared library into the system table.

Declared In

ExpansionMgr.h

Prototype

Err ExpSlotDriverInstall (
   UInt32dbCreator,
   UInt16*slotLibRefNumP
)

Parameters

dbCreator
Database creator code of the slot driver library to be installed.
slotLibRefNumP
Pointer to variable for returning the library reference number (on failure, sysInvalidRefNum is returned in this variable).

Returns

Returns errNone if the slot driver is installed correctly. Because this function uses SysLibInstall() to install the slot driver shared library, ExpSlotDriverInstall may return any of the error codes that SysLibInstall returns, including sysErrLibNotFound, sysErrNoFreeRAM, and sysErrNoFreeLibSlots. It may also return any error code returned by SlotOpen, the implementation of which is specific to a given device manufacturer.

Comments

This function is not typically called by applications but can be used to load additional slot drivers after the device has booted. It is called internally by the Expansion Manager to install a slot driver shared library into the library table and initialize it for use. Once installed, the slotLibRefNum can be used by other functions to refer to the library.

Compatibility

Implemented only if the Expansion Manager Feature Set is present. If Palm OS Cobalt Feature Set is present this function is unimplemented.

See Also

ExpSlotDriverRemove(), ExpSlotLibFind()

ExpSlotDriverRemove Function ^TOP^

Purpose

Closes and remove a slot driver shared library from the system table.

Declared In

ExpansionMgr.h

Prototype

Err ExpSlotDriverRemove (
   UInt16slotLibRefNum
)

Parameters

slotLibRefNum
Slot driver shared library reference number.

Returns

Returns errNone.

Comments

This function is not typically called by applications but can be used to unload slot drivers associated with external slots. It is called internally by the Expansion Manager to remove the shared library from the system table, and, if appropriate, release the slot allocated to the given slotLibRefNum. Prior to removing the slot driver, it unmounts any volumes associated with the slot.

Compatibility

Implemented only if the Expansion Manager Feature Set is present. If Palm OS Cobalt Feature Set is present this function is unimplemented.

See Also

ExpSlotDriverInstall(), ExpSlotLibFind(), SysLibRemove()

ExpSlotEnumerate Function ^TOP^

Purpose

Iterates through valid slot numbers.

Declared In

ExpansionMgr.h

Prototype

Err ExpSlotEnumerate(
   UInt16 *slotRefNumP,
   UInt32*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 one of the following result codes:

errNone
The slot reference number indicated by slotRefNumP is valid.
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 
} 
} 

Compatibility

Implemented only if the Expansion Manager Feature Set is present.

See Also

ExpCardInfo(), ExpCardPresent(), ExpSlotDriverRemove()

ExpSlotLibFind Function ^TOP^

Purpose

Retrieves the slot driver library reference number for the driver that controls the specified slot.

Declared In

ExpansionMgr.h

Prototype

Err ExpSlotLibFind(
   UInt16slotRefNum,
   UInt16*slotLibRefNum
)

Parameters

slotRefNum
Slot number.
slotLibRefNum
Pointer to the reference number for the slot driver library allocated to the given slot.

Returns

Returns the following result codes:

errNone
No error.
expErrInvalidSlotRefNum
The slot number is invalid.
expErrSlotDeallocated
The slot number is within the valid range but has been deallocated.

Comments

This function returns the reference number to the slot driver library loaded for the given slotRefNum. This function is used when making calls directly to the slot driver library.

Compatibility

Implemented only if the Expansion Manager Feature Set is present. If Palm OS Cobalt Feature Set is present this function is unimplemented.

See Also

ExpSlotDriverInstall(), ExpSlotDriverRemove()