< 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 #####
-> slotRefNum | Slot number of slot to check.
#####
<- portP | Pointer to UInt32 into which the serial port creator ID is stored.
#### Result 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. #### See Also ExpCardInfo ## New ExpCardInfo #### Purpose Obtains information about a card in a given slot. #### Prototype Err ExpCardInfo(UInt16 slotRefNum, ExpCardInfoType *infoP) #### Parameters #####
-> slotRefNum | Slot number.
#####
<- infoP | Pointer to ExpCardInfoType structure.
#### Result 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 ## New ExpCardPresent #### Purpose Determines if a card is present in the given slot. #### Prototype Err ExpCardPresent(UInt16 slotRefNum) #### Parameters #####
-> slotRefNum | Slot number.
#### Result 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 ## New ExpSlotDriverInstall #### Purpose Installs and initializes a slot driver shared library into the system table. #### 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).
#### 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 #####
-> slotLibRefNum | Slot 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 #####
<- 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.
#### Result 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 ## 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 #####
-> slotRefNum | Slot number.
#####
<- slotLibRefNum | Pointer to the reference number for the slot driver library allocated to the given slot.
#### Result 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. #### See Also ExpSlotDriverInstall, ExpSlotDriverRemove |