C/C++ Sync Suite Reference601/9

←　8 章に戻る　↑トップへ　10 章に進む　→?

9 拡張マネージャ API

• 拡張マネージャ構造体
  • ExpCardInfoType
• 拡張マネージャ定数
  • ディレクトリ列挙定数
  • ハードウェア能力フラグ
  • メディア タイプ定数
  • その他の拡張マネージャ定数
• 拡張マネージャ関数
  • ExpCardInfo
  • ExpCardPresent
  • ExpSlotEnumerate
  • ExpSlotMediaType
• 拡張マネージャ API エラー コード

ハンドヘルド上の拡張マネージャは Palm ハンドヘルド上のハードウェア拡張カードのためのサポートを追加するオプションのシステム拡張です。ハンドヘルド拡張マネージャの主な関数はハンドヘルド上のスロットとそのスロットに関連付けされているドライバを管理するためのものです。ハンドヘルド上の個々のスロット ドライバ - それらはハンドヘルド製造者によって提供されます - は Secure Digital (SD), MultiMediaCard (MMC), CompactFlash, Sony の Memory Stick, その他を含むさまざまな拡張カード タイプのためのサポートを提供します。

この章でドキュメント化されている API は HotSync の最中にハンドヘルド上の拡張マネージャへのインタフェイスをコンジットに提供します。このインタフェイスを通して、コンジットはスロットの中に拡張カードが存在しているかどうかを決定し、そのカードについての情報を取得することができます。

この章は拡張マネージャ API についての以下の情報を提供します:

• 拡張マネージャ構造体
• 拡張マネージャ定数
• 拡張マネージャ関数
• 拡張マネージャ API エラー コード

デスクトップ拡張マネージャ関数は VFSAPI.dll の中で利用可能であり、ExpansionMgr.h で宣言されています (拡張マネージャ エラー コードは VFSErr.h で宣言されています)。拡張マネージャについての更なる情報は、C/C++ Sync Suite Companion の [[第 6 章 「拡張テクノロジの使用」|C/C++ Sync Suite Companion601/6}} を参照してください。

NOTE

拡張マネージャはハンドヘルド上のオプションのシステム拡張です。そのため、あなたは拡張マネージャ API 関数を呼び出す前にハンドヘルド上に拡張マネージャが存在しているかどうかをチェックすべきです。C/C++ Sync Suite Companion の 「ハンドヘルド互換性の検証」 を参照してください。

拡張マネージャ構造体 ^TOP^

この節では拡張マネージャのために定義されている ExpCardInfoType 構造体について説明します。

ExpCardInfoType ^TOP^

目的

拡張スロットに挿されているカードの特性を受け取ります。

宣言されている場所

ExpansionMgr.h

Prototype

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

フィールド

• manufacturerStr
  • カードの能力を説明します。これには ハードウェア能力フラグ の 1 つまたはいくつかがセットされます。
• productStr
  • カードの製造者の名前 - 例えば "Palm" や "Motorola"。
• deviceClassStr
  • カードのタイプを説明します - 例えば、"Backup" や "Ethernet"。
• deviceUniqueIDStr
  • 製品の固有識別子 - 例えばシリアル番号。この値は識別子が存在しない場合は空にセットされます。

コメント

この構造体は基本的なスロット ドライバによって初期化されます。

拡張マネージャ定数 ^TOP^

この節ではあなたが拡張マネージャ API で使用する以下のプロセッサ定数のグループについて説明します。

定数	説明
ディレクトリ列挙定数	VFSDirEntryEnumerate()|C/C++ Sync Suite Reference601/10 を使用するときにディレクトリ列挙の処理を制御します。
ハードウェア能力フラグ	ExpCardInfoType.capabilityFlags の中にあるカードの能力を示します。
メディア タイプ定数	拡張マネージャによってサポートされるメディア タイプを定義します。
その他の拡張マネージャ定数	拡張マネージャによって使用されるその他の定数を定義します。

ディレクトリ列挙定数 ^TOP^

目的

VFSDirEntryEnumerate()|C/C++ Sync Suite Reference601/10 を使用するときにディレクトリ列挙の処理を制御します。

宣言されている場所

ExpansionMgr.h

定数

• #define expIteratorStart 0L
  • 列挙を開始するためにこの値を VFSDirEntryEnumerate()|C/C++ Sync Suite Reference601/10 に提供します。
• #define expIteratorStop 0xffffffffL
  • 列挙が最後のディレクトリ エントリに達したとき、VFSDirEntryEnumerate()|C/C++ Sync Suite Reference601/10 はそのディレクトリ エントリ反復処理パラメータをこの値にセットします。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

VFSDirEntryEnumerate()|C/C++ Sync Suite Reference601/10

ハードウェア能力フラグ ^TOP^

目的

ExpCardInfoType.capabilityFlags の中にあるカードの能力を示します。

宣言されている場所

ExpansionMgr.h

定数

• #define expCapabilityHasStorage 0x00000001

カードはデータ記憶装置を持っていることを示します。しかしながら、expCapabilityReadOnly フラグはカードは書き込み可能であるかあるいは読み込みのみが可能であることを示します。

• #define expCapabilityReadOnly 0x00000002
  • カードは Read-only であることを示します。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpCardInfoType

メディア タイプ定数 ^TOP^

目的

拡張マネージャによってサポートされるメディア タイプを定義します。

宣言されている場所

ExpansionMgr.h

定数

• #define ExpMediaType_Any 'wild'
  • デフォルト ディレクトリを参照したときにすべてのメディア タイプにマッチします。
• #define ExpMediaType_CompactFlash 'cfsh'
  • CompactFlash
• #define ExpMediaType_MemoryStick 'mstk'
  • Memory Stick
• #define ExpMediaType_MultiMediaCard 'mmcd'
  • MultiMediaCard
• #define ExpMediaType_PlugNPlay 'pnps'
  • ユニバーサル「プラグ アンド プレイ」 (PnP) コネクタ
• #define ExpMediaType_PoserHost 'pose'
  • Palm OS エミュレータによってエミュレートされるホスト ファイル システム。
• #define ExpMediaType_RAMDisk 'ramd'
  • RAM ディスク ベース メディア
• #define ExpMediaType_SecureDigital 'sdig'
  • Secure Digital (SD)
• #define ExpMediaType_SmartMedia 'smed'
  • SmartMedia

コメント

これらのメディア タイプは ExpSlotMedaiType() と VFSVolumeInfo()|C/C++ Sync Suite Reference601/10 の VolumeInfoType.mediaType フィールドで使用されます。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpSlotMedaiType(), VFSVolumeInfo()|C/C++ Sync Suite Reference601/10

その他の拡張マネージャ定数 ^TOP^

目的

拡張マネージャによって使用されるその他の定数を定義します。

宣言されている場所

ExpansionMgr.h

定数

• #define expCardInfoStringMaxLen 31
  • ExpCardInfoType 構造体のメンバの中の文字列の最大長を定義します。
• #define expFtrIDVersion 0
  • 拡張マネージャのバージョンを取得するために、あなたは SyncReadFeature() を呼び出して Feature クリエイタ にsysFileCExpansionMgr を Feature 番号にこの定数を渡します。しかしながら、バージョン番号を取得するための本来の方法は VFSSupport()|C/C++ Sync Suite Reference601/10 を呼び出すことです。
• #define sysFileCExpansionMgr 'expn'
  • 拡張マネージャの Feature クリエイタ ID を定義します。expFtrIDVersion の説明を参照してください。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

拡張マネージャ関数 ^TOP^

この節では、コンジットがスロットの中に拡張カードが存在しているかどうかを決定してそのカードについての情報を取得することを可能にする以下の関数について説明します。

関数	説明
ExpCardInfo	与えられたスロットの中にある拡張カードについての情報を取得します。
ExpCardPresent	与えられたスロットの中にカードが存在しているかどうかを決定します。
ExpSlotEnumerate	スロット参照番号のリストを取得するために有効なスロットを列挙します。
ExpSlotMediaType	指定されたスロットのメディア タイプ識別子を取得します。

ExpCardInfo ^TOP^

目的

与えられたスロットの中にある拡張カードについての情報を取得します。

宣言されている場所

ExpansionMgr.h

Prototype

SInt32 ExpCardInfo (
   UInt16 slotRefNumber,
   ExpCardInfoType *pCardInfo,
   void *pVoid
)

パラメータ

• → slotRefNumber
  • ExpSlotEnumerate() によって返されるスロット参照番号。
• ← pCardInfo
  • 指定されたスロットの中にあるカードについての情報を保持する ExpCardInfoType 構造体へのポインタ。
• ←→ pVoid
  • このパラメータはこのバージョンの拡張マネージャでは使用されません。NULL を渡して、返される値は無視してください。

返り値

成功した場合、SYNCERR_NONE を返します。

失敗した場合、以下のエラー コードの 1 つを返します:

• expErrCardNoSectorReadWrite
• expErrCardNotPresent
• expErrInvalidSlotRefNumber
• expErrSlotDeallocated
• expErrUnsupportedOperation

すべてのエラー コードについての説明は、「拡張マネージャ API エラー コード」 を参照してください。

コメント

このルーチンはカードについての情報 - カードが補助記憶装置をサポートするかどうか、完全に Read-only であるかどうかを含む - を ExpCardInfoType 構造体のフィールドに返します。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpCardPresent(), ExpSlotEnumerate()

ExpCardPresent ^TOP^

目的

与えられたスロットの中にカードが存在しているかどうかを決定します。

宣言されている場所

ExpansionMgr.h

Prototype

SInt32 ExpCardPresent (
   UInt16 slotRefNumber,
   void *pVoid
)

パラメータ

• → slotRefNumber
  • ExpSlotEnumerate() によって返されるスロット参照番号。
• ←→ pVoid
  • このパラメータはこのバージョンの拡張マネージャでは使用されません。NULL を渡して、返される値は無視してください。

返り値

成功した場合、SYNCERR_NONE を返します。

失敗した場合、以下のエラー コードの 1 つを返します:

• expErrCardNotPresent
• expErrInvalidSlotRefNumber
• expErrSlotDeallocated
• expErrUnsupportedOperation

すべてのエラー コードについての説明は、「拡張マネージャ API エラー コード」 を参照してください。

コメント

カード上のファイルにアクセスするために VFS マネージャ API を呼び出す前に、スロットの中にカードが存在しているかどうかをテストするためにこの関数を呼び出します。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpCardInfo(), ExpSlotEnumerate()

ExpSlotEnumerate ^TOP^

目的

スロット参照番号のリストを取得するために有効なスロットを列挙します。

宣言されている場所

ExpansionMgr.h

Prototype

SInt32 ExpSlotEnumerate (
   UInt16 *pNumSlotRefListEntires,
   UInt16 *pSlotRefNumList,
   void *pVoid
)

パラメータ

• ←→ pNumSlotRefListEntires
  • 呼び出し時には、割り当てられたスロット参照番号の数へのポインタです。返り時には、pSlotRefNumList に埋め込まれたスロット参照番号の数へのポインタになります。
• ← pSlotRefNumList
  • スロット参照番号の配列へのポインタ。呼び出し元はこの関数を呼び出す前にこのバッファに割り当てを行わなければなりません。
• ←→ pVoid
  • このパラメータはこのバージョンの拡張マネージャでは使用されません。NULL を渡して、返される値は無視してください。

返り値

成功した場合、SYNCERR_NONE を返します。

失敗した場合、以下のエラー コードの 1 つを返します:

• expErrUnsupportedOperation

すべてのエラー コードについての説明は、「拡張マネージャ API エラー コード」 を参照してください。

コメント

この関数はハンドヘルド上のスロットのスロット参照番号のリストを返します。あなたはこの関数を呼び出す前に pSlotRefNumList に十分な容量を割り当てなければならないということに注意してください。

例

以下の例は ExpSlotEnumerate() を呼び出す前に十分な容量を割り当てる方法を示しています。

WORD wSlotRefList[32]; // Buffer for slot reference numbers.
                       //(スロット参照番号のためのバッファ)
WORD wSlotRefCount;    // Number of entries allocated for list.
                       //(リストに割り当てるエントリの数)
long retval; 

// Allocate enough space for buffer. (バッファに十分な容量を割り当てます。)
wSlotRefCount = sizeof (wSlotRefList) / sizeof (wSlotRefList[0]); 
retval = ExpSlotEnumerate(&wSlotRefCount, wSlotRefList, NULL); 

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpCardInfo(), ExpCardPresent()

ExpSlotMediaType ^TOP^

目的

指定されたスロットのメディア タイプ識別子を取得します。

宣言されている場所

ExpansionMgr.h

Prototype

SInt32 ExpSlotMediaType (
   UInt16 slotRefNum,
   UINT32 *pui32SlotMediaType
)

パラメータ

• → slotRefNum
  • メディア タイプを決定するスロットの参照番号 (ExpSlotEnumerate() によって返されます)。
• ← pui32SlotMediaType
  • 指定されたスロットのメディア タイプを示す UINT32 へのポインタ。「メディア タイプ定数」 で取り得る値がリスト アップされています。

返り値

成功した場合、SYNCERR_NONE を返します。

失敗した場合、以下のエラー コードの 1 つを返します:

• expErrCardNotPresent
• expErrSlotDeallocated
• expErrUnsupportedOperation

すべてのエラー コードについての説明は、「拡張マネージャ API エラー コード」 を参照してください。

互換性

• 拡張マネージャ バージョン: すべて
• Palm OS バージョン: 4.0 以降

ハンドヘルド上の拡張マネージャの存在を確認するための方法は、C/C++ Sync Suite Companion の 「拡張カードのチェック」 を参照してください。

参照

ExpCardInfo(), ExpSlotEnumerate()

拡張マネージャ API エラー コード ^TOP^

表 9.1 は拡張マネージャ関数が返す可能性のあるエラー コードの値をリスト アップしています。各関数の説明でそれぞれの関数が返す可能性のあるエラーについて述べています。

以下の名前を付けられているエラー コードはすべてプロセッサ定数として定義されていて、VFSErr.h ヘッダ ファイルで宣言されています。

表 9.1 拡張マネージャ API エラー コード

値	コード	説明
0x00002901L	expErrUnsupportedOperation	この操作はサポートされていないか定義されていません。
0x00002902L	expErrNotEnoughPower	この操作を実行するにはハンドヘルドの電源パワーが不足しています。
0x00002903L	expErrCardNotPresent	与えられたスロットの中にカードは存在しません。
0x00002904L	expErrInvalidSlotRefNumber	このスロット参照番号は無効です。
0x00002905L	expErrSlotDeallocated	このスロット参照番号は有効な範囲内にあります。しかしながら、拡張マネージャはハンドヘルド上のそのスロットのドライバをアンロードしていません。
0x00002906L	expErrCardNoSectorReadWrite	このカードはスロット ドライバ ブロック読み込み/書き込み API をサポートしません。
0x0000290AL	expErrNotOpen	この呼び出しで必要とされるハンドヘルド上のファイル システム ライブラリはインストールされていないかオープンされていません。
0x0000290DL	expErrEnumerationEmpty	列挙するボリュームは存在しないか、残っていません。

←　8 章に戻る　↑トップへ　10 章に進む　→?