Expansion Manager
 

 < Home   < Developers   < Development Support   < Documentation

30 Expansion Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

30 Expansion Manager

Expansion Manager Data Structures

ExpCardInfoType

Expansion Manager Constants

Error Codes

Defined Media Types

Expansion Manager Functions

ExpCardGetSerialPort

ExpCardInfo

ExpCardPresent

ExpSlotDriverInstall

ExpSlotDriverRemove

ExpSlotEnumerate

ExpSlotLibFind

       

This chapter provides the following information about the Expansion Manager:

Expansion Manager Data Structures

Expansion Manager Constants

Expansion Manager Functions

The header file ExpansionMgr.h declares the Expansion Manager API. For more information on the Expansion Manager, see Chapter 8, "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

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.

typedef struct ExpCardInfoTag { 
  UInt32 capabilityFlags;  
  Char
    manufacturerStr[expCardInfoStringMaxLen+1]; 
  Char productStr[expCardInfoStringMaxLen+1]; 
  Char
    deviceClassStr[expCardInfoStringMaxLen+1]; 
  Char
  deviceUniqueIDStr[expCardInfoStringMaxLen+1]; 
} ExpCardInfoType, *ExpCardInfoPtr; 

Field Descriptions

capabilityFlags
Describes the capabilities of the card. The following flags are currently supported:

expCapabilityHasStorage indicates that the card supports reading and writing.

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:

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

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

New ExpCardGetSerialPort

Purpose

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

Prototype

Err ExpCardGetSerialPort(UInt16 slotRefNum, UInt32 *portP)

Parameters

-> slotRefNumSlot number of slot to check.
<- portPPointer to UInt32 into which the serial port creator ID is stored.

Result

Returns the following result codes:

errNone No error
expErrInvalidSlotRefNumThe specified slot number is invalid.
expErrSlotDeallocatedThe specified slot number is within the valid range but has been deallocated.

Compatibility

Implemented only if the Expansion Manager Feature Set is present.

See Also

ExpCardInfo

New ExpCardInfo

Purpose

Obtains information about a card in a given slot.

Prototype

Err ExpCardInfo(UInt16 slotRefNum, ExpCardInfoType *infoP)

Parameters

-> slotRefNumSlot number.
<- infoPPointer to ExpCardInfoType structure.

Result

Returns one of the following result codes:

errNone No error
expErrCardNotPresentThere is no card present in the specified slot.
expErrInvalidSlotRefNumThe slot number is invalid.
expErrSlotDeallocatedThe 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

New ExpCardPresent

Purpose

Determines if a card is present in the given slot.

Prototype

Err ExpCardPresent(UInt16 slotRefNum)

Parameters

-> slotRefNumSlot number.

Result

Returns the following result codes:

errNone A card is present in the specified slot.
expErrCardNotPresentThere is no card present in the specified slot.
expErrInvalidSlotRefNumThe specified slot number is not valid.
expErrSlotDeallocatedThe 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

New ExpSlotDriverInstall

Purpose

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

Prototype

Err ExpSlotDriverInstall (UInt32 dbCreator, UInt16 *slotLibRefNumP)

Parameters

-> dbCreatorDatabase creator code of the slot driver library to be installed.
-> slotLibRefNumPPointer to variable for returning the library reference number (on failure, sysInvalidRefNum is returned in this variable).

Result

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.

See Also

ExpSlotDriverRemove, ExpSlotLibFind

New ExpSlotDriverRemove

Purpose

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

Prototype

Err ExpSlotDriverRemove (UInt16 slotLibRefNum)

Parameters

-> slotLibRefNumSlot driver shared library reference number.

Result

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.

See Also

ExpSlotDriverInstall, ExpSlotLibFind, SysLibRemove

New ExpSlotEnumerate

Purpose

Iterates through valid slot numbers.

Prototype

Err ExpSlotEnumerate(UInt16 *slotRefNumP, UInt32 *slotIteratorP)

Parameters

<- slotRefNumPReference number of the currently-enumerated slot.
-> slotIteratorPPointer 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.

Result

Returns one of the following result codes:

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

New ExpSlotLibFind

Purpose

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

Prototype

Err ExpSlotLibFind(UInt16 slotRefNum, UInt16 *slotLibRefNum)

Parameters

-> slotRefNumSlot number.
<- slotLibRefNumPointer to the reference number for the slot driver library allocated to the given slot.

Result

Returns the following result codes:

errNone No error.
expErrInvalidSlotRefNumThe slot number is invalid.
expErrSlotDeallocatedThe 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.

See Also

ExpSlotDriverInstall, ExpSlotDriverRemove