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
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 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
Error Codes
The Expansion Manager defines the following error codes:
Defined Media Types
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.
Expansion Manager Functions
ExpCardGetSerialPort Function
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 Function
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
Purpose
Determines if a card is present in the given slot.
Declared In
ExpansionMgr.h
Prototype
Err ExpCardPresent( UInt16 slotRefNum )
Parameters
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
Purpose
Installs and initializes a slot driver shared library into the system table.
Declared In
ExpansionMgr.h
Prototype
Err ExpSlotDriverInstall ( UInt32 dbCreator, 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
Purpose
Closes and remove a slot driver shared library from the system table.
Declared In
ExpansionMgr.h
Prototype
Err ExpSlotDriverRemove ( UInt16 slotLibRefNum )
Parameters
Returns
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
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 toexpIteratorStop
.
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 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
}
}
Compatibility
Implemented only if the Expansion Manager Feature Set is present.
See Also
ExpCardInfo()
, ExpCardPresent()
, ExpSlotDriverRemove()
ExpSlotLibFind Function
Purpose
Retrieves the slot driver library reference number for the driver that controls the specified slot.
Declared In
ExpansionMgr.h
Prototype
Err ExpSlotLibFind( UInt16 slotRefNum, 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()