Palm Programmer's Laboratory
C/C++ Sync Suite Reference601/6
コンジットはこの章で説明されている必須のコンジット エントリ ポイント関数を実装しなければなりません。HotSync マネージャはコンジットを開始するためにそれらのエントリ ポイントを呼び出し、情報を渡し、ユーザがコンジットの操作をコンフィグレーションしたりコンジットから情報を取得したりすることを可能にします。
必須というマークが付いたコンジット エントリ ポイントは HotSync マネージャが呼び出すためにあなたのコンジット DLL の中に実装されなければなりません。他のエントリ ポイントはオプションであるか、あなたが特定の機能を実装する場合にのみ必須となります。これらのエントリ ポイント関数は CondAPI.h の中で宣言されています。これらの関数によって使用される他のいくつかの要素は SyncMgr.h と Subscribe.h の中で宣言されています。
この章は以下の節に分かれています:
- コンジット エントリ ポイント API 構造体
- コンジット エントリ ポイント API 定数
- コンジット定義 エントリ ポイント API 関数
- HotSync マネージャ コールバック関数
- コンジット エントリ ポイント API エラー コード
コンジット エントリ ポイントの実装については、C/C++ Sync Suite Companion の 第 3 章 「コンジット エントリ ポイントの実装」 で説明されています。
コンジット エントリ ポイント API 構造体 ^TOP^
この節では、あなたがコンジット エントリ ポイント API で使用する以下のデータ構造体について説明します。
| 構造体 | 説明 |
|---|---|
| CfgConduitInfoType | HotSync マネージャがコンジットの CfgConduit() エントリ ポイントを呼び出したときにコンジットに追加の情報を指定します。 |
| ConduitRequestInfoType | HotSync マネージャがコンジットの名前をリクエストするためにコンジットの GetConduitInfo() エントリ ポイントを呼び出したときにコンジットに追加の情報を指定します。 |
| RegistrationInfoType | HotSync マネージャがフォルダ登録コンジットの GetConduitInfo() エントリ ポイントを呼び出したときにコンジットについての登録情報を指定します。 |
CfgConduitInfoType 構造体 ^TOP^
目的
HotSync マネージャがコンジットの CfgConduit() エントリ ポイントを呼び出したときにコンジットに追加の情報を指定します。
宣言されている場所
CondAPI.h
Prototype
typedef struct CfgConduitInfoType {
UInt32 dwVersion;
UInt32 dwSize;
UInt32 dwCreatorId;
UInt32 dwUserId;
TCHAR szUser[64];
char m_PathName[BIG_PATH];
eSyncTypes syncPermanent;
eSyncTypes syncTemporary;
eSyncTypes syncNew;
eSyncPref syncPref;
} CFGCONDUITINFO
フィールド
- dwVersion
- この構造体のバージョン番号を指定します。
- dwSize
- この構造体のサイズ (バイト数) を指定します。
- dwCreatorId
- コンジットのクリエイタ ID を指定します。
- dwUserId
- 現在の HotSync ユーザ ID を指定します。
- szUser
- 現在の HotSync ユーザ名を指定します。
- m_PathName
- コンジットのフル パス。
- syncPermanent
- 指定されたコンジットのために保存されているユーザの 永久同期設定 を取得します。これは eSyncTypes 列挙値のうちの 1 つです。
- syncTemporary
- 指定されたコンジットのために保存されているユーザの 一時同期設定 を取得します。これは eSyncTypes 列挙値のうちの 1 つです。
- syncNew
- HotSync マネージャのために保存するユーザの新しい同期設定または変更された同期設定を指定します。あなたのコンジットは eSyncTypes 列挙値のうちの 1 つを指定しなければなりません。
- syncPref
- HotSync マネージャが、あなたのコンジットが syncNew フィールドで指定した設定をどのように保存すべきか - 永久同期設定として、あるいは一時同期設定としてのどちらか - を指定します。あなたのコンジットは eSyncPref 列挙値のうちの 1 つを指定しなければなりません。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
ConduitRequestInfoType 構造体 ^TOP^
目的
HotSync マネージャがコンジットの名前をリクエストするためにコンジットの GetConduitInfo() エントリ ポイントを呼び出したときにコンジットに追加の情報を指定します。
宣言されている場所
CondAPI.h
Prototype
typedef struct ConduitRequestInfoType {
UInt32 dwVersion;
UInt32 dwSize;
UInt32 dwCreatorId;
UInt32 dwUserId;
TCHAR szUser[64];
} CONDUITREQUESTINFO
- dwVersion
- この構造体のバージョン番号を指定します。
- dwSize
- この構造体のサイズ (バイト数) を指定します。
- dwCreatorId
- HotSync マネージャが呼び出しているコンジットのクリエイタ ID。
- dwUserId
- 現在の HotSync セッションを開始したユーザのユーザ ID。
- szUser
- 現在の HotSync セッションを開始したユーザの名前。
コメント
HotSync マネージャはコンジットの GetConduitInfo() エントリ ポイントの infoType パラメータに eConduitName の値を渡すとき、pInArgs パラメータにこのタイプの構造体を渡します。コンジットがこの情報を必要とするのは、例えば、単一のコンジットが複数のクリエイタ ID で登録されていて、HotSync マネージャに対して異なるコンジット名を返す必要がある場合です (この構造体によってコンジットに渡される情報に基づいて HotSync マネージャはコンジット名を表示します)。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
RegistrationInfoType 構造体 ^TOP^
目的
HotSync マネージャがフォルダ登録コンジットの GetConduitInfo() エントリ ポイントを呼び出したときにコンジットについての登録情報を指定します。
宣言されている場所
CondAPI.h
Prototype
typedef struct RegistrationInfoType {
UInt32 dwCreatorID;
UInt32 dwPriority;
TCHAR szLocalDirectory[255];
TCHAR szLocalFile[255];
TCHAR szRemoteDB[32];
TCHAR szTitle[255];
} REGISTRATIONINFO
フィールド
- dwCreatorID
- あなたのコンジットが同期に責任を持つハンドヘルド上のアプリケーションの クリエイタ ID。この値は固有キーであり、この値によって HotSync マネージャはあなたのコンジットを識別します。そのため、ある特定のクリエイタ ID に対して 1 度に 1 つだけコンジットを登録することができます。
- dwPriority
- このコンジットの実行優先度。この値は 0 から 4 までの範囲になります。値が指定されていない場合、HotSync マネージャはデフォルトの値 2 を使用します。HotSync マネージャは値 0 を持つコンジットを最初に実行し、値 4 を持つコンジットを最後に実行します。
- szLocalDirectory
- コンジットのディレクトリ名。これはデスクトップ コンピュータ上のユーザのディレクトリの中にあるサブディレクトリの名前です (フル パスではありません)。各ユーザのディレクトリ内に、各コンジットは保存ファイルを置くためのディレクトリを持つことができます。
- szLocalFile
- あなたのコンジットがハンドヘルド データベースと同期させるデスクトップ ファイルの名前。しかしながら、あなたのコンジットは複数のファイルを同期させることもできます。このコンフィグレーション エントリはフル パスとファイル名、あるいはファイル名だけのどちらかになるということに注意してください。この値がファイル名だけである場合、そのファイルは szLocalDirectory フィールドによって指定されたディレクトリの中で見つけられます。
- szRemoteDB
- このコンジットによってアクセスされるハンドヘルド データベースの名前。このオプションの値を、特定のデータベース名をハード コードされていないコンジットが使用することができます。この値はコンジットに渡され、それによりコンジットはハンドヘルド上のデータベースをオープンすることが可能になります。さらにコンジットは同期を行う前にこの名前によって指定されたデータベースがハンドヘルド上に存在しなかった場合に、この名前を遣ってデータベースをハンドヘルド上に作成することができます。データベース名は大文字/小文字の区別があります。
- szRemoteDB
- コンジットの表示名。HotSync マネージャはこの文字列をコンジットの名前としてユーザ インターフェイスに表示します - 例えば、Custom ダイアログ ボックスに。あなたがこのエントリをセットしなかった場合、HotSync マネージャはあなたのコンジットが GetConduitInfo() または GetConduitName() によって呼び出されたときに提供する名前を表示します。
互換性
- HotSync マネージャ バージョン: 6.0 以降
- Palm OS バージョン: すべて
参照
コンジット エントリ ポイント API 定数 ^TOP^
この節では、あなたがコンジット エントリ ポイント API で使用する以下の列挙対とプロセッサ定数について説明します。
| 定数 | 説明 |
|---|---|
| ConduitCfgEnum | HotSync マネージャが呼び出している CfgConduit() のバージョンを示します。 |
| ConduitInfoEnum | HotSync マネージャがコンジットの GetConduitInfo() エントリ ポイントを呼び出したときに HotSync マネージャがリクエストしている情報のタイプを示します。 |
| コンジット優先度 | コンジットを実行する最も高い、最も低い、デフォルトの優先度を定義します。 |
| MFC バージョン | あなたのコンジットが MFC を使用しているかどうか、使用している場合は MFC のバージョンを示します。 |
| コンジット エントリ ポイントの構造体サイズ | いくつかのコンジット エントリ ポイントによって使用されるさまざまな構造体のサイズを定義します。 |
| コンジット エントリ ポイントの構造体バージョン | いくつかのコンジット エントリ ポイントによって使用されるある特定のデータ構造体のバージョン番号を示します。 |
ConduitCfgEnum 列挙体 ^TOP^
目的
HotSync マネージャが呼び出している CfgConduit() のバージョンを示します。"
宣言されている場所
CondAPI.h
定数
- eConduitCfgDoNotUse = 0xffffffff
- HotSync マネージャは決してこの値を渡しません。この値はこの列挙体の上限を定めているだけです。
- eConfig1 = 0
- CfgConduit() エントリ ポイントのバージョン 1.
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
ConduitInfoEnum 列挙体 ^TOP^
目的
HotSync マネージャがコンジットの GetConduitInfo() エントリ ポイントを呼び出したときに HotSync マネージャがリクエストしている情報のタイプを示します。
宣言されている場所
CondAPI.h
定数
- eConduitName = 0
- HotSync マネージャはあなたのコンジットの表示名をリクエストしています。HotSync マネージャはコンジットが返す名前をコンジットが名前を持たずに登録されている場合にのみ使用します - つまり、Name コンジット コンフィグレーション エントリ ポイントがセットされていない場合に。
- eMfcVersion
- HotSync マネージャはあなたのコンジットが MFC を使用しているかどうか、使用している場合は MFC のバージョンをリクエストしています。このバージョン番号は実際は MFC が組み込まれている Visual C++ のバージョンであり、MFC 自体のバージョン番号であるとはかぎりません。
この列挙値は同期マネージャ バージョン 2.4 以降で使用を推奨されなくなりました。これらのバージョンの HotSync マネージャはコンジットに MFC バージョンを問い合わせしません。コンジットは、バージョン 2.3 以前の同期マネージャが存在している場合にのみ、「MFC バージョン」 で定義されている値の 1 つを返さなければなりません。
- HotSync マネージャはあなたのコンジットが MFC を使用しているかどうか、使用している場合は MFC のバージョンをリクエストしています。このバージョン番号は実際は MFC が組み込まれている Visual C++ のバージョンであり、MFC 自体のバージョン番号であるとはかぎりません。
- eDefaultAction
- HotSync マネージャはあなたのコンジットによって実行されるデフォルトのアクションのタイプをリクエストしています。コンジットは eSyncType 列挙値の 1 つを返さなければなり間sね。
- eRegistrationInfo
- HotSync マネージャはあなたのコンジットがフォルダ経由で登録されている場合にコンジット登録情報をリクエストしています。コンジットがフォルダ経由で登録されている場合、そのコンジットは情報を埋め込まれた RegistrationInfoType 構造体へのポインタを返さなければなりません。
- eDoNotDisplayInConduitListForUser
- HotSync マネージャはあなたのコンジットが HotSync マネージャの Custom ダイアログ ボックスの中に表示されるべきかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、あなたのコンジット名は Custom ダイアログ ボックスに表示されます。あなたのコンジットが非 0 値を反す場合、そのコンジットの名前は表示されません。
HotSync マネージャは、同期マネージャ バージョン 2.4 以降が存在している場合にのみ、この列挙値を渡すことができるということに注意してください。
- HotSync マネージャはあなたのコンジットが HotSync マネージャの Custom ダイアログ ボックスの中に表示されるべきかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、あなたのコンジット名は Custom ダイアログ ボックスに表示されます。あなたのコンジットが非 0 値を反す場合、そのコンジットの名前は表示されません。
- eRunAlways
- HotSync マネージャはあなたのコンジットが同じクリエイタ ID を持つアプリケーションがハンドヘルド上に存在するかどうかに関係なく実行されるべきであるかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、HotSync マネージャはあなたのコンジットを同じクリエイタ ID を持つアプリケーションがハンドヘルド上に存在する場合にのみ実行します。あなたのコンジットが非 0 値を返す場合、HotSync マネージャはあなたのコンジットを常に実行します。
HotSync マネージャは、同期マネージャ バージョン 2.4 以降が存在している場合にのみ、この列挙値を渡すことができるということに注意してください。
- HotSync マネージャはあなたのコンジットが同じクリエイタ ID を持つアプリケーションがハンドヘルド上に存在するかどうかに関係なく実行されるべきであるかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、HotSync マネージャはあなたのコンジットを同じクリエイタ ID を持つアプリケーションがハンドヘルド上に存在する場合にのみ実行します。あなたのコンジットが非 0 値を返す場合、HotSync マネージャはあなたのコンジットを常に実行します。
- eDoNotDisplayProgress
- HotSync マネージャは HotSync の最中にあなたのコンジットの名前を HotSync Progress ダイアログ ボックスに表示すべきかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、HotSync マネージャはあなたのコンジットの名前を表示します。あなたのコンジットが非 0 値を返す場合、HotSync マネージャはあなたのコンジットの名前を表示しません。
HotSync マネージャは、同期マネージャ バージョン 2.4 以降が存在している場合にのみ、この列挙値を渡すことができるということに注意してください。
- HotSync マネージャは HotSync の最中にあなたのコンジットの名前を HotSync Progress ダイアログ ボックスに表示すべきかどうかをリクエストしています。あなたのコンジットが 0 の値を返す、あるいは値を返さない場合、HotSync マネージャはあなたのコンジットの名前を表示します。あなたのコンジットが非 0 値を返す場合、HotSync マネージャはあなたのコンジットの名前を表示しません。
- eConduitInfoDoNotUse = 0xffffffff
- HotSync マネージャは決してこの値を渡しません。この値はこの列挙体の上限を定めているだけです。
互換性
- HotSync マネージャ バージョン: 上記の例外を除く、すべて
- Palm OS バージョン: すべて
参照
コンジット優先度 ^TOP^
目的
コンジットを実行する最も高い、最も低い、デフォルトの優先度を定義します。
宣言されている場所
CondAPI.h
定数
- #define PALM_DEF_PRIORITY 2
- 優先度が指定されていない場合のコンジットを実行する優先度。
- #define PALM_MAX_PRIORITY 4
- HotSync マネージャはこの優先度を持つコンジットを最後に実行します。
- #define PALM_MIN_PRIORITY 0
- HotSync マネージャはこの優先度を持つコンジットを最初に実行します。
互換性
- HotSync マネージャ バージョン: 6.0 以降
- Palm OS バージョン: すべて
MFC バージョン ^TOP^
目的
あなたのコンジットが MFC を使用しているかどうか、使用している場合は MFC のバージョンを示します。
宣言されている場所
CondAPI.h
定数
- #define MFC_NOT_USED 0x10000000
- コンジットは MFC を使用しません。
- #define MFC_VERSION_41 0x00000410
- コンジットはバージョン 4.1 を使用します。
- #define MFC_VERSION_50 0x00000500
- コンジットはバージョン 5.0 を使用します。
- #define MFC_VERSION_60 0x00000600
- コンジットはバージョン 6.0 を使用します。
コメント
バージョン番号は MFC が組み込まれている Visual C++ のバージョンに相当するものであり、必ずしも MFC 自体のバージョン番号ではありません。
- NOTE
- これらの定数は HotSync マネージャ バージョン 6.0 以降で使用を推奨されなくなりました。それらの HotSync マネージャはコンジットに MFC バージョンを問い合わせしません。
互換性
- HotSync マネージャ バージョン: 6.0 よりも前のすべて
- Palm OS バージョン: すべて
参照
コンジット エントリ ポイントの構造体サイズ ^TOP^
目的
いくつかのコンジット エントリ ポイントによって使用されるさまざまな構造体のサイズを定義します。
宣言されている場所
CondAPI.h
定数
- #define SZ_CFGCONDUITINFO sizeof(CFGCONDUITINFO)
- CfgConduitInfoType 構造体のサイズを定義します。
- #define SZ_CONDUITREQUESTINFO sizeof(CONDUITREQUESTINFO)
- ConduitRequestInfoType 構造体のサイズを定義します。
- #define SZ_REGISTRATIONINFO sizeof(REGISTRATIONINFO)
- RegistrationInfoType 構造体のサイズを定義します。
互換性
- HotSync マネージャ バージョン: すべて。バージョン 6.0 以降でのみ REGISTRATIONINFO が存在します。
- Palm OS バージョン: すべて
参照
CfgConduitInfoType, ConduitRequestInfoType, RegistrationInfoType
コンジット エントリ ポイントの構造体バージョン ^TOP^
目的
いくつかのコンジット エントリ ポイントによって使用されるある特定のデータ構造体のバージョン番号を示します。
宣言されている場所
CondAPI.h
定数
- #define CONDUITREQUESTINFO_VERSION_1 0x00000001
- この定数は ConduitRequestInfoType データ構造体のバージョン 1 を指定します。
- #define CFGCONDUITINFO_VERSION_1 0x00000001
- この定数は CfgConduitInfoType データ構造体のバージョン 1 を指定します。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
ConduitRequestInfoType, CfgConduitInfoType
コンジット定義 エントリ ポイント API 関数 ^TOP^
この節ではコンジットが実装する以下のエントリ ポイントについて説明します。
| エントリ ポイント | 説明 |
|---|---|
| CfgConduit | コンジットにユーザが HotSync マネージャ の Custom ダイアログ ボックスからそのコンジットを選択したことを知らせます。HotSync マネージャ バージョン 3.0 以降によってのみ呼び出されます (それより前のバージョンはこの関数の代わりに ConfigureConduit() を呼び出します)。 |
| ConfigureConduit | コンジットにユーザが HotSync マネージャ の Custom ダイアログ ボックスからそのコンジットを選択したことを知らせます。HotSync マネージャ バージョン 3.0 より以前のものだけがこのエントリ ポイントを呼び出します。これに対してバージョン 3.0 以降はまず CfgConduit() を呼び出し、それから CfgConduit() 呼び出しが成功しなかった場合にのみ ConfigureConduit() を呼び出します。 |
| GetConduitInfo | (必須) HotSync マネージャによって呼び出されたときにコンジットについての情報を取得します。 |
| GetConduitName | (オプション) HotSync マネージャによって呼び出されたときにあなたのコンジットの表示名を取得します。 |
| GetConduitVersion | (必須) HotSync マネージャによって呼び出されたときにあなたのコンジットのバージョン番号を取得します。 |
| OpenConduit | (必須) このエントリ ポイントが HotSync マネージャによって呼び出されたときにコンジットの同期プロセスを開始し、コンジットに現在の HotSync セッションについての情報を提供します。 |
CfgConduit 関数 ^TOP^
目的
コンジットにユーザが HotSync マネージャ の Custom ダイアログ ボックスからそのコンジットを選択したことを知らせます。HotSync マネージャ バージョン 3.0 以降によってのみ呼び出されます (それより前のバージョンはこの関数の代わりに ConfigureConduit() を呼び出します)。
宣言されている場所
CondAPI.h
Prototype
SInt32 CfgConduit ( ConduitCfgEnum cfgType, void *pArgs, UInt32 *pdwArgsSize ) typedef SInt32 ( *PCFGCONDUIT ) ( ConduitCfgEnum cfgType, void *pArgs, UInt32 *pdwArgsSize )
パラメータ
- → cfgType
- このエントリ ポイント関数のバージョン番号。これは ConduitCfgEnum 値のうちの 1 つです。
- ←→ pArgs
- CfgConduitInfoType 構造体へのポインタ。HotSync マネージャは現在の HotSync ユーザのために保存されている一時同期設定と永久同期設定を渡します。あなたのコンジットは更新された同期設定を返します。このパラメータを NULL にすることはできません。
- → pdwArgsSize
- pArgs によって参照される構造体の中にあるバイト数。
返り値
成功した場合、コンジットは 0 を返さなければなりません。
成功しなかった場合、コンジットは非 0 のエラー コード 値を返さなければなりません。エラー コードについての更なる情報は、「コンジット エントリ ポイント API エラー コード」 を参照してください。
コメント
HotSync マネージャは、ユーザが HotSync Manager > Conduit をクリックすることによってあなたのコンジットをコンフィグレーションすることを決定したときに、コンジットの CfgConduit() エントリ ポイントを呼び出します。通常、コンジットはユーザにそのコンジットが次とその後の HotSync の最中にどのように処理を行うかをコンフィグレーションさせるために Change HotSync Action ダイアログ ボックスを表示することによって応答します。更なる基礎知識は、Introduction to Conduit Development の 「ユーザのコンジット同期設定」 を参照してください。
あなたのコンジットがユーザが以前保存した設定として何を表示すべきかを決定するために pArgs パラメータに渡される情報を使用します。syncNew フィールドをユーザの新しい設定で変更し、その設定が永久的なものかあるいは一時的なものかを示すために syncPref フィールドを変更します。
CfgConduit() は同じ目的で使用される ConfigureConduit() のアップデート バージョンです。この関数は異なる情報を受け取り (pArgs パラメータで)、それを基に ConfigureConduit() は処理を行います。HotSync マネージャのバージョン 3.0 以降は ConfigureConduit() を呼び出す前に CfgConduit() を呼び出そうと試みます。あなたのコンジットが HotSync マネージャのバージョン 3.0 よりも前のものをサポートしなければならない場合、あなたは ConfigureConduit() も実行しなければなりません。
PCFGCONDUIT は CfgConduit() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: 3.0 以降
- Palm OS バージョン: すべて
参照
ConfigureConduit(), CfgConduitInfoType
ConfigureConduit 関数 ^TOP^
目的
コンジットにユーザが HotSync マネージャ の Custom ダイアログ ボックスからそのコンジットを選択したことを知らせます。HotSync マネージャ バージョン 3.0 より以前のものだけがこのエントリ ポイントを呼び出します。これに対してバージョン 3.0 以降はまず CfgConduit() を呼び出し、それから CfgConduit() 呼び出しが成功しなかった場合にのみ ConfigureConduit() を呼び出します。
宣言されている場所
CondAPI.h
Prototype
SInt32 ConfigureConduit ( CSyncPreference &syncPrefs ) typedef SInt32 ( *PCONFIGURECONDUIT ) ( CSyncPreference &syncPrefs )
パラメータ
- → syncPrefs
- CSyncPreference クラスのオブジェクト。このクラスはあなたのコンジットのための情報を保持します。
返り値
成功した場合、コンジットは 0 を返さなければなりません。
成功しなかった場合、コンジットは非 0 のエラー コード 値を返さなければなりません。エラー コードについての更なる情報は、「コンジット エントリ ポイント API エラー コード」 を参照してください。
コメント
CfgConduit() と同様に、HotSync マネージャは、ユーザが HotSync Manager > Conduit をクリックすることによってあなたのコンジットをコンフィグレーションすることを決定したときに、コンジットの ConfigureConduit() エントリ ポイントを呼び出します。通常、コンジットはユーザにそのコンジットが次とその後の HotSync の最中にどのように処理を行うかをコンフィグレーションさせるために Change HotSync Action ダイアログ ボックスを表示することによって応答します。あなたのコンジットがユーザが以前保存した設定として何を表示すべきかを決定するために syncPrefs パラメータに渡される情報を使用します。
しかしながら、ConfigureConduit() は同じ目的で使用されるが異なる情報を提供する CfgConduit() の古いバージョンです。バージョン 3.0 よりも前の HotSync マネージャは ConfigureConduit() だけを呼び出します; それより新しいバージョンの HotSync マネージャはまず CfgConduit() を呼び出そうと試み、CfgConduit() が利用できない場合にこの関数を呼び出します。
PCFGCONDUIT は ConfigureConduit() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: すべて (コメントを参照してください。)
- Palm OS バージョン: すべて
参照
GetConduitInfo 関数 ^TOP^
目的
(必須) HotSync マネージャによって呼び出されたときにコンジットについての情報を取得します。
宣言されている場所
CondAPI.h
Prototype
SInt32 GetConduitInfo ( ConduitInfoEnum infoType, void *pInArgs, void *pOut, UInt32 *pdwOutSize ) typedef SInt32 ( *PGETCONDUITINFO ) ( ConduitInfoEnum infoType, void *pInArgs, void *pOut, UInt32 *pdwOutSize )
パラメータ
- → infoType
- HotSync マネージャがリクエストしている情報のタイプ。これは ConduitInfoEnum 値のうちの 1 つです。
- → pInArgs
- infoType が eConduitName である場合、このパラメータは ConduitRequestInfoType 構造体へのポインタです。そうでない場合、この値は NULL です。
- ← pOut
- HotSync マネージャがリクエストしている情報へのポインタ。表 6.1 は、このパラメータが - HotSync マネージャが infoType パラメータ経由で何をリクエストしているかに基づいて - 何を指すべきかを説明しています。
- ← pdwOutSize
- pOut が指す値のサイズ (バイト数)。
返り値
成功した場合、コンジットは 0 を返さなければなりません。
成功しなかった場合、コンジットは非 0 のエラー コード 値を返さなければなりません。エラー コードについての更なる情報は、「コンジット エントリ ポイント API エラー コード」 を参照してください。
コメント
HotSync マネージャはあなたのコンジットについての情報を取得するために GetConduitInfo() を呼び出します。あなたのこのエントリ ポイントの実装は infoType パラメータに渡される各 ConduitInfoEnum に対して異なる応答をしなければなりません。表 6.1 はそれらの値とあなたのコンジットがどのように応答すべきなのかをリスト アップしています。
表 6.1 GetConduitInfo() リクエストとコンジットの応答
| infoType に渡される ConduitInfoEnum の値 | pOut が指すべきもの |
|---|---|
| eConduitName = 0 | TCHAR バッファ。 |
| eMfcVersion | 「MFC バージョン」 の定数の 1 つと等価な UInt32 値。 |
| eDefaultAction | eSyncTypes 列挙値。 |
| eRegistrationInfo | RegistrationInfoType 構造体。 |
| eDoNotDisplayInConduitListForUser | あなたのコンジットが Custom ダイアログ ボックスに表示されるべきである場、値 0 を返します。表示されるべきでない場合、非 0 値を返します。 |
| eRunAlways | ハンドヘルド上に一致するアプリケーションが存在する場合にのみあなたのコンジットが実行されるべきであるなら、値 0 を返します。あなたのコンジットが常に実行されるべきであるなら、非 0 値を返します。 |
| eDoNotDisplayProgress | "あなたのコンジットが HotSync Progress ダイアログ ボックスに表示されるべきである場、値 0 を返します。表示されるべきでない場合、非 0 値を返します。 |
PGETCONDUITINFO は GetConduitInfo() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: 上記の例外を除く、すべて
- Palm OS バージョン: すべて
HotSync マネージャ バージョン 6.0 以降は以下の値だけを infoType パラメータに渡すことができます:
- eConduitName
- eDefaultAction
- eRegistrationInfo
- eDoNotDisplayInCustomDialog
- eRunAlways
- eDoNotDisplayProgress
HotSync マネージャのバージョン 6.0 より前のものは以下の値だけを infoType パラメータに渡すことができます:
- eConduitName
- eMfcVersion
- eDefaultAction
- 重要
- あなたのコンジットが HotSync マネージャのバージョン 6.0 より前のものと処理を行わなければならない場合、あなたの GetConduitInfo() の実装は適切な MFC バージョン定数を返さなければなりません。あなたが古いバージョンの CDK で作成したコンジットをコンパイルし直しているところであり、そのコンジットがもともと GetConduitInfo() を実行していなかった (今は必須) 場合、HotSync マネージャはあなたのコンジットが MFC 4.1 でビルドされたものと仮定します。あなたのコンジットが MFC 4.1 でビルドされていない場合、HotSync マネージャはあなたのコンジットを呼び出したときにクラッシュします。
HotSync マネージャ バージョン 6.0 以降はコンジットの MFC バージョンをチェックする必要がありません。そのため、それらの HotSync マネージャは決して infoType パラメータ経由で eMfcVersion 値を渡すことはありません。
参照
ConduitInfoEnum, ConduitRequestInfoType
GetConduitName 関数 ^TOP^
目的
(オプション) HotSync マネージャによって呼び出されたときにあなたのコンジットの表示名を取得します。
宣言されている場所
CondAPI.h
Prototype
SInt32 GetConduitName ( char *name, UInt16 nLen ) typedef SInt32 ( *PGETCONDUITNAME ) ( char *name, UInt16 nLen )
パラメータ
- ← name
- → nLen
返り値
成功した場合、コンジットは 0 を返さなければなりません。
成功しなかった場合、コンジットは非 0 のエラー コード 値を返さなければなりません。エラー コードについての更なる情報は、「コンジット エントリ ポイント API エラー コード」 を参照してください。
コメント
HotSync マネージャ バージョン 3.0.1 以降はあなたのコンジットの名前の取得に成功するまで以下の一連のアクションを実行します:
- CondCfg ユーティリティまたはコンジット インストールの最中にコンジット マネージャで作成された Name エントリを読み込む。
- 成功しなかった場合、GetConduitInfo() を呼び出す。
- 成功しなかった場合、GetConduitName() を呼び出す。
あなたは、あなたのコンジットが HotSync マネージャ バージョン 3.0.1 以降だけと互換性を保つ必要がある場合、GetConduitName() を実装することは要求されません。
HotSync マネージャのバージョン 3.0 以前のものはあなたのコンジットが GetConduitName() を実装することを要求します。このケースでは、あなたのコンジット実装は name バッファに HotSync マネージャがユーザに対して表示すべき文字列を埋め込まなければなりません。
PGETCONDUITNAME は GetConduitName() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: 3.0.1 以降ではオプション。3.0 以前では必須。バージョンによる違いは「コメント」を参照してください。
- Palm OS バージョン: すべて
参照
GetConduitVersion 関数 ^TOP^
目的
(必須) HotSync マネージャによって呼び出されたときにあなたのコンジットのバージョン番号を取得します。
宣言されている場所
CondAPI.h
Prototype
UInt32 GetConduitVersion () typdef UInt32 (*PGETCONDUITVERSION) ()
パラメータ
ありません。
返り値
あなたのコンジットのバージョン番号。以下のように UInt32 である返り値にパックされます:
- メジャー バージョン番号は HIBYTE(LOWORD)
- マイナー バージョン番号は LOBYTE(LOWORD)
コメント
HotSync マネージャはデスクトップ コンピュータ上で実行されているあなたのコンジットのバージョンを取得するために GetConduitVersion() を呼び出します。あなたのコンジット実装は結果の low word (訳者: UInt32 の下位 2 バイト) の上位バイトにメジャー バージョン番号をパックし、low word の下位バイトにマイナー バージョン番号をパックしなければなりません。
PGETCONDUITVERSION は GetConduitVersion() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
OpenConduit 関数 ^TOP^
目的
(必須) このエントリ ポイントが HotSync マネージャによって呼び出されたときにコンジットの同期プロセスを開始し、コンジットに現在の HotSync セッションについての情報を提供します。
宣言されている場所
CondAPI.h
Prototype
SInt32 OpenConduit ( PROGRESSFN pFn, CSyncProperties &syncProps ) typedef SInt32 ( *POPENCONDUIT ) ( PROGRESSFN pFn, CSyncProperties &syncProps )
パラメータ
- → pFn
- HotSync マネージャがあなたのコンジットに渡すコールバック関数へのポインタ。更なる情報は、PROGRESSFN() を参照してください。
- → syncProps
- 同期のタイプ、カレント ユーザ名などを含む現在の HotSync 操作のプロパティ。この情報は CSyncProperties クラスのオブジェクトとして定義されています。
返り値
成功した場合、コンジットは 0 を返さなければなりません。
成功しなかった場合、コンジットは非 0 のエラー コード 値を返さなければなりません。エラー コードについての更なる情報は、「コンジット エントリ ポイント API エラー コード」 を参照してください。
コメント
HotSync マネージャはデスクトップ コンピュータとハンドヘルド間の同期処理を開始するためにコンジットの OpenConduit() エントリ ポイントを呼び出します。これはコンジットが行うメイン処理です。syncProps パラメータには、HotSync マネージャはコンジットが現在の HotSync セッションで行う必要があることを決定するために使用する現在の HotSync セッションについての情報を渡します。
syncProps.m_SyncType メンバはコンジットにユーザの保存されている設定 (同期、ハンドヘルドがデスクトップを上書き、デスクトップがハンドヘルドを上書き、何もしない) に基づいて実行する同期操作のタイプを知らせ、設定が「同期」である場合はコンジットが高速同期あるいは低速同期のどちらを実行すべきかを知らせます。
- 重要
- コンジットの m_SyncType フィールドに渡される eFast または eSlow 値は最後の HotSync 操作が現在のデスクトップと行われたかどうかにのみ基づきます。非スキーマ データベースでは、これはコンジットが高速同期と低速同期のどちらを実行するかを決定するために十分です。しかしながらスキーマ データベースでは、この値は十分ではありません。スキーマ データベースでのみ利用可能でクラシック データベースと拡張データベースでは利用できない追加変更追跡情報の利点をフルに活かすため、この値の代わりに SyncDbGetSyncMode()|C/C++ Sync Suite Reference601/2 を呼び出します。
Generic Conduit Framework を使用するコンジットでは、OpenConduit() は以下のことをします:
- CSynchronizer クラスのオブジェクトをインスタンス化し、あなたのコンジットがカテゴリやアプリケーション情報ブロックをハンドルする必要があるかどうかを指定します
- CSynchronizer の Perform() メソッドを呼び出すことによってあなたの同期を開始します
- コンジットの CSynchronizer オブジェクトを削除します
POPENCONDUIT は OpenConduit() エントリ ポイントへのポインタとして定義されています。このポインタはコンジットに応答指令信号を送るためのツールを作成するコンジット開発者に便宜を計るために提供されています。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
CSyncProperties, PROGRESSFN(), SyncDbGetSyncMode()|C/C++ Sync Suite Reference601/2
HotSync マネージャ コールバック関数 ^TOP^
この節では、コンジットが自身の OpenConduit() エントリ ポイントから HotSync マネージャにコールバックするために使用することができる PROGRESSFN 関数を定義します。
PROGRESSFN 関数 ^TOP^
目的
コンジットによって呼び出されたときに、コンジットが実行されている最中の HotSync Progress ダイアログ ボックスにメッセージを表示します。
宣言されている場所
CondAPI.h
Prototype
typedef SInt32 ( *PROGRESSFN ) ( char *progress )
パラメータ
- → progress
- HotSync Progress ダイアログ ボックスのステータス フィールドに表示される文字列。
返り値
常に 0 を返します。
コメント
はコールバック関数です。HotSync マネージャはあなたの OpenConduit() エントリ ポイントを呼び出すときにあなたのコンジットにこの関数へのポインタを渡します。あなたのコンジットは HotSync マネージャにあなたのコンジットが実行されている最中の HotSync Progress ダイアログ ボックスのステータス フィールドにメッセージは表示させるためにこの関数を呼び出すことができます。
互換性
- HotSync マネージャ バージョン: すべて
- Palm OS バージョン: すべて
参照
コンジット エントリ ポイント API エラー コード ^TOP^
表 6.2 はあなたのコンジットのエントリ ポイントが HotSync マネージャに返す可能性があるエラー コードの値をリスト アップしています。これらのエラーの 1 つが返されると、HotSync マネージャは同様のエラー メッセージを HotSync ログに書き込みます。しかしながら、PalmSource は、成功した場合にあなたが CONDERR_NONE を返し、成功しなかった場合に -1 を返してあなた自身のより詳細なメッセージをログに追加するために HotSync ログ API を呼び出すことを推奨します。
以下の名前を付けられているエラー コードはすべてヘッダ ファイル CondAPI.h で宣言されているプロセッサ定数として定義されています。
表 6.2 コンジット エントリ ポイント API エラー コード
| 値 | コード | 説明 |
|---|---|---|
| -1 | - | 以下にリスト アップされている値以外の未指定エラー。 |
| 0x0000 | CONDERR_NONE | 関数呼び出しは成功しました。 |
| 0x1000 | CONDERR_FIRST | エントリ ポイントはこの値を返すべきではありません。これは他のすべてのエラー コードのベースとなるオフセットです。 |
| 0x1001 | CONDERR_NO_REMOTE_CATEGORIES | ハンドヘルド上に定義されたカテゴリがありません。 |
| 0x1002 | CONDERR_NO_LOCAL_CATEGORIES | デスクトップ コンピュータ上に定義されたカテゴリがありません。 |
| 0x1003 | CONDERR_SAVE_REMOTE_CATEGORIES | カテゴリをハンドヘルドに保存することができませんでした。 |
| 0x1004 | CONDERR_BAD_REMOTE_TABLES | このエラー コードは HotSync マネージャ 6.0 以降では使用を推奨されなくなりました。 |
| 0x1005 | CONDERR_BAD_LOCAL_TABLES | このエラー コードは HotSync マネージャ 6.0 以降では使用を推奨されなくなりました。 |
| 0x1006 | CONDERR_BAD_LOCAL_BACKUP | このエラー コードは HotSync マネージャ 6.0 以降では使用を推奨されなくなりました。 |
| 0x1007 | CONDERR_ADD_LOCAL_RECORD | このエラー コードは HotSync マネージャ 6.0 以降では使用を推奨されなくなりました。 |
| 0x1008 | CONDERR_ADD_REMOTE_RECORD | ハンドヘルドにレコードを追加することができませんでした。 |
| 0x1009 | CONDERR_CHANGE_REMOTE_RECORD | ハンドヘルド上のレコードを変更することができませんでした。 |
| 0x100A | CONDERR_RAW_RECORD_ALLOCATE | レコードにメモリを割り当てることができませんでした。 |
| 0x100B | CONDERR_REMOTE_CHANGES_NOT_SENT | 変更をハンドヘルドに送ることに失敗しました。 |
| 0x100C | CONDERR_LOCAL_MEMORY_ALLOC_FAILED | デスクトップ コンピュータ上でメモリを割り当てることができませんでした。 |
| 0x100D | CONDERR_CONVERT_TO_REMOTE_CATS | レコードのカテゴリをハンドヘルド上のカテゴリに変換することができませんでした。 |
| 0x100E | CONDERR_CONVERT_TO_LOCAL_CATS | レコードのカテゴリをデスクトップ コンピュータ上のカテゴリに変換することができませんでした。 |
| 0x100F | CONDERR_CONVERT_TO_REMOTE_REC | デスクトップ コンピュータのレコードをハンドヘルド上のレコードに変換できませんでした。 |
| 0x1010 | CONDERR_CONVERT_FROM_REMOTE_REC | ハンドヘルドのレコードをデスクトップ コンピュータ上のレコードに変換できませんでした。 |
| 0x1011 | CONDERR_REMOTE_RECS_NOT_PURGED | ハンドヘルド上のレコードを削除 (purge) することに失敗しました。 |
| 0x1012 | CONDERR_BAD_SYNC_TYPE | 指定された同期タイプは無効です。 |
| 0x1013 | CONDERR_ABORT_DB_INSTALL | データベースのインストールは中断されました。例えば、ハンドヘルドがメモリ不足になった場合。 |
| 0x1050 | CONDERR_DATE_MOVED | 1970 年以前の日付は有効な日付に変更されました。 |
| 0x1060 | CONDERR_SUBSCRIBE_FAILED | ファイル リンクに失敗しました。このエラー コードはファイル リンク Feature が HotSync マネージャ 6.0.1 以降で削除されたために使用を推奨されなくなりました。 |
| 0x1070 | CONDERR_UNSUPPORTED_CONDUITINFO_ENUM | 指定された ConduitInfoEnum 値はサポートされません。 |
| 0x1071 | CONDERR_INVALID_PTR | ポインタが有効ではありません。 |
| 0x1072 | CONDERR_BUFFER_TOO_SMALL | このバッファはデータを保持するには小さすぎます。 |
| 0x1073 | CONDERR_INVALID_BUFFER_SIZE | このバッファ サイズはバッファに対して有効ではありません。 |
| 0x1074 | CONDERR_INVALID_INARGS_PTR | この入力引数ポインタは有効ではありません。 |
| 0x1075 | CONDERR_INVALID_INARGS_STRUCT | この入力引数構造体は有効ではありません。 |
| 0x1076 | CONDERR_CONDUIT_RESOURCE_FAILURE | あなたのコンジットの DLL からリソースを読み込むことができませんでした。 |
| 0x1077 | CONDERR_INVALID_OUTSIZE_PTR | この出力サイズ ポインタは有効ではありません。 |
| 0x1078 | CONDERR_INVALID_ARGSSIZE_PTR | この出力引数ポインタは有効ではありません。 |
| 0x1079 | CONDERR_UNSUPPORTED_CFGCONDUIT_ENUM | 指定された ConduitCfgEnum 値はサポートされません。 |
| 0x107A | CONDERR_INVALID_ARGSSIZE | この引数サイズは有効ではありません。 |
| 0x107B | CONDERR_UNSUPPORTED_STRUCT_VERSION | この構造体のバージョン番号はハンドヘルドでサポートされません。 |
| 0x107C | CONDERR_NOCLIENTINFO_AVAILABLE | 利用可能なクライアント情報がありません。 |
