Palm Programmer's Laboratory
C/C++ Sync Suite Companion601/3
この章は、HotSync マネージャがあなたのコンジットを実行するためにあなたのコンジットが実装しなければならない必須エントリ ポイントとオプションのエントリ ポイントについて説明します。この章には以下の節があります。
概要 ^TOP^
HotSync マネージャがあなたのコンジットの中で呼び出す 2 タイプのエントリ ポイントがあります:
- 必須エントリ ポイント - 各コンジットはこれらを実装しなければなりません。
- オプションのエントリ ポイント - HotSync マネージャの Custom ダイアログ ボックス経由でユーザがあなたのコンジットをコンフィグレーションすることを可能にします。
この節では、これらのコンジット ポイントについての簡単な説明を提供します。これらの関数についての更なる情報は、C/C++ Sync Suite Reference の中の 第 6 章 「コンジット エントリ ポイント API」 を参照してください。
表 3.1 はエントリ ポイント関数の要約を提供しています。
表 3.1 HotSync マネージャによって呼び出されるコンジット エントリ ポイント
| 関数タイプ | 関数名 | 説明 |
|---|---|---|
| 必須 | GetConduitVersion() | コンジットのバージョン番号を返します。 サポートされるコンジット バージョンの範囲は 0x00000101 から 0x00000200 までです。 |
| 必須 | OpenConduit() | メイン コンジット エントリ ポイント。 |
| 必須 | GetConduitInfo() | コンジットについての情報を HotSync マネージャに返します。 |
| カスタム（オプション） | ConfigureConduit() （HotSync 3.0.1 より前） または CfgConduit() （HotSync 3.0.1 以降） |
ユーザがコンジットをコンフィグレーションすることを可能にするダイアログを表示します。 |
| オプション | GetConduitName() | コンジットの名前を HotSync マネージャが表示するために返します。HotSync マネージャ バージョン 3.0.1 よりも前では必須です。 |
必須エントリ ポイント ^TOP^
この節は、あなたがあなた自身のコンジットに実装しなければならない以下のエントリ ポイントについて説明します。
これらのエントリ ポイントの詳細は、C/C++ Sync Suite Reference の中の 第 6 章 「コンジット エントリ ポイント API」 を参照してください。
GetConduitInfo() ^TOP^
HotSync マネージャは GetConduitInfo() を呼び出してあなたのコンジットについての情報を取得します。あなたのこの関数の実装は、以下の要求を含むいくつかの異なる情報の要求に応答しなければなりません:
- あなたのコンジットのディスプレイ名
- あなたのコンジットのデフォルトのアクション
- NOTE
- HotSync マネージャ バージョン 6.0 以降は、コンジットにコンジットの MFC バージョンを問い合わせません。そのため、この問い合わせへの応答はオプションです。
しかしながら、より以前の HotSync マネージャに対して機能することを意図したコンジットは応答しなければなりません。この場合、あなたは GetConduitInfo() を実装して適切な MFC バージョン定数を返さなけらばなりません。古いバージョンの CDK で作成したコンジット - GetConduitInfo() を実装していない（今は必須です） - を再コンパイルする場合、HotSync マネージャはあなたのコンジットが MFC 4.1 でビルドされたと仮定します。そうでない場合、HotSync マネージャはあなたのコンジットを呼び出したときクラッシュします。
HotSync マネージャ バージョン 6.0 以降は、3 つの追加の - しかしオプションの - 情報を要求します。
- 登録情報。あなたのコンジットは、フォルダ-ベースで登録される（「フォルダでのコンジットの登録」} を参照してください）場合、応答しなければなりません。しかし、通常通りに登録されるコンジット|C/C++ Sync Suite Companion601/Glossary の場合は応答する必要はありません。
- あなたのコンジットの名前を HotSync マネージャの Custom ダイアログ ボックスと HotSync Progress ダイアログ ボックスに表示すべきかどうか。
- HotSync マネージャは常にあなたのコンジットを実行すべきか、それとも、ハンドヘルド上に同じ作成者 ID を持つアプリケーションがある場合のみ実行すべきか。
コード 3.1 で示されている Generic Conduit Framework バージョンの GetConduitInfo() が一般的なものです。infoType パラメータに基づき、この関数は要求される情報のタイプを返します。
コード 3.1 GetConduitInfo() エントリ ポイントの例
ExportFunc long GetConduitInfo(ConduitInfoEnum infoType, void *pInArgs,
void *pOut, DWORD *pdwOutSize)
{
// Do some error checking on passed-in parameters.
// Do not modify these lines.
if (!pOut)
return CONDERR_INVALID_PTR;
if (!pdwOutSize)
return CONDERR_INVALID_OUTSIZE_PTR;
// HotSync Manager requests information from your conduit through
// repeated calls to GetConduitInfo.
// The type of information requested is determined by infoType.
// Your conduit responds appropriately.
switch (infoType) {
case eConduitName:
// HotSync Manager wants to know the conduit name.
// When HotSync Manager requests the conduit name, it also
// passes in a ConduitRequestInfoType structure that
// your conduit can examine, if necessary. The following
// block of code shows how to check the version of this
// structure in case PalmSource, Inc. changes the structure in the
// future. You can omit this code if you do not need any
// information in the ConduitRequestInfoType structure.
if (!pInArgs)
return CONDERR_INVALID_INARGS_PTR;
ConduitRequestInfoType *pInfo;
pInfo = (ConduitRequestInfoType *)pInArgs;
if ((pInfo->dwVersion != CONDUITREQUESTINFO_VERSION_1) ||
(pInfo->dwSize != SZ_CONDUITREQUESTINFO))
return CONDERR_INVALID_INARGS_STRUCT;
// OK, actually return the name of the conduit taken from the
// resource IDS_CONDUIT_NAME.
if (!::LoadString((HINSTANCE)hLangInstance, IDS_CONDUIT_NAME,
(TCHAR*)pOut, *pdwOutSize))
return CONDERR_CONDUIT_RESOURCE_FAILURE;
break;
case eDefaultAction:
// HotSync Manager wants to know the default sync action.
if (*pdwOutSize != sizeof(eSyncTypes))
return CONDERR_INVALID_BUFFER_SIZE;
(*(eSyncTypes*)pOut) = eDoNothing;
break;
case eRegistrationInfo:
// HotSync Manager wants your folder-based conduit's registration
// information. Conventionally registered conduits do not respond.
if (*pdwOutSize != sizeof(RegistrationInfoType)) {
return CONDERR_INVALID_BUFFER_SIZE;
}
RegistrationInfoType* sRIT;
sRIT = (RegistrationInfoType*) pOut;
DWORD dwCreatorID;
int iError;
iError = CmConvertStringToCreatorID(GENERIC_CONDUIT_CREATOR_ID,
&dwCreatorID);
sRIT->dwCreatorID = dwCreatorID;
sRIT->dwPriority = GENERIC_CONDUIT_PRIORITY;
_tcscpy(sRIT->szLocalDirectory, GENERIC_CONDUIT_LOCAL_DIRECTORY);
_tcscpy(sRIT->szLocalFile, GENERIC_CONDUIT_LOCAL_FILE);
_tcscpy(sRIT->szRemoteDB, GENERIC_CONDUIT_REMOTE_DB);
if (!::LoadString((HINSTANCE)hLangInstance, IDS_CONDUIT_NAME,
sRIT->szTitle, sizeof(sRIT->szTitle))) {
return CONDERR_CONDUIT_RESOURCE_FAILURE;
}
break;
case eRunAlways:
// HotSync Manager wants to know whether to run your conduit even
// if there is no application on the device with the same creator ID.
if (*pdwOutSize != sizeof(SInt8)) {
return CONDERR_INVALID_BUFFER_SIZE;
}
// Run this conduit even if the creator ID it is registered for is
// not on the device.
*(SInt8*)pOut = 1;
break;
case eDoNotDisplayProgress:
// HotSync Manager wants to know whether to display your conduit's
// name in the HotSync Progress dialog box's Status field.
if (*pdwOutSize != sizeof(SInt8)) {
return CONDERR_INVALID_BUFFER_SIZE;
}
// Do not opt out of HotSync Progress dialog box.
*(SInt8*)pOut = 0;
break;
case eDoNotDisplayInConduitListForUser:
// HotSync Manager wants to know whether to display your conduit's
// name in HotSync Manager's Custom dialog box.
if (!pInArgs) {
return CONDERR_INVALID_INARGS_PTR;
}
if (*pdwOutSize != sizeof(SInt8)) {
return CONDERR_INVALID_BUFFER_SIZE;
}
// ConduitRequestInfoType* pInfo = (ConduitRequestInfoType*) pInArgs;
// Decide whether to display conduit name in Custom list for
// particular pInfo->szUser
*(SInt8*)pOut = 0;
break;
case eMfcVersion:
// HotSync Manager wants to know the version of MFC.
// Only HotSync Manager versions earlier than 6.0 request this
// information. If you conduit works only with HotSync Manager 6.0 or
// later, it does not need to respond.
if (*pdwOutSize != sizeof(DWORD))
return CONDERR_INVALID_BUFFER_SIZE;
(*(DWORD*)pOut) = MFC_NOT_USED;
break;
default:
return CONDERR_UNSUPPORTED_CONDUITINFO_ENUM;
}
return 0;
}
GetConduitVersion() ^TOP^
HotSync マネージャは GetConduitVersion() を呼び出してデスクトップ上で実行されているあなたのコンジットのバージョンを取得します。あなたのこの関数の実装は、あなたのメジャー バージョン番号を low word （訳者注: LOWORD, DWORD （32 ビット整数）の下位 2 バイトのこと）の上位バイトに、あなたのマイナー バージョン番号を low word の下位バイトにパックしなければなりません。
コード 3.2 で示されている Generic Conduit Framework バージョンの GetConduitVersion() 関数が一般的なものです。この関数は単純にバージョン番号を指定する定数値を返します。
コード 3.2 GetConduitVersion() エントリ ポイントの例
#define GENERIC_CONDUIT_VERSION 0x00000102
ExportFunc DWORD GetConduitVersion()
{
return GENERIC_CONDUIT_VERSION;
}
OpenConduit() ^TOP^
HotSync マネージャは OpenConduit() を呼び出して、デスクトップ コンピュータとハンドヘルド間のデータの同期プロセスを開始します。Generic Conduit Framework を使用するコンジットのために、あなたの OpenConduit() の実装は以下のようなことを実行する必要があります。
- CSynchronizer クラスをインスタンス化して、あなたのコンジットがカテゴリまたは情報ブロックを扱う必要があるかどうかを指定します。
- CSynchronizer の Perform() メソッドを呼び出すことによってあなたの同期を開始します。
- コンジットの CSynchronizer オブジェクトを削除します。
コード 3.3 は Generic Conduit Framework の OpenConduit() を示しています。
コード 3.3 OpenConduit() エントリ ポイントの例
ExportFunc long OpenConduit(PROGRESSFN pFn, CSyncProperties& rProps) {
if (pFn) {
CSynchronizer* pGeneric;
// You will need to make this decision in your code.
pGeneric = new CSynchronizer(rProps, GENERIC_FLAG_CATEGORY_SUPPORTED |
GENERIC_FLAG_APPINFO_SUPPORTED);
if (pGeneric) {
retval = pGeneric->Perform();
delete pGeneric;
}
}
return(retval);
}
オプションのエントリ ポイント ^TOP^
この節は、以下のオプションのエントリ ポイントについて説明します。
あなたはこれらの関数をあなたのコンジットの中に実装することができ、あなたは C/C++ Sync Suite Reference の中の 第 6 章 「コンジット エントリ ポイント API」 で説明されているデフォルトの機能を使用することができます。PalmSource 社は、あなたがこれらの各関数のあなた自身の実装を提供することを推奨します。
CfgConduit() ^TOP^
HotSync マネージャは、ユーザが HotSync マネージャ メニューの Custom をクリックして、あなたのコンジットを選択し、Change をクリックしたとき、CfgConduit() を呼び出します。
CfgConduit() 関数は、ConfigureConduit() の HotSync マネージャ 3.0 以降のバージョンです。CfgConduit() 関数は、ConfigureConduit() 関数よりも多くの拡張可能なデータ構造体のフォームの中の情報を取得します。
HotSync マネージャ 3.0 以降はまず CfgConduit() を呼び出そうと試みます。あなたのコンジットがこのエントリ ポイントを提供しない場合、HotSync マネージャは ConfigureConduit() 関数を呼び出そうと試みます。HotSync マネージャのバージョン 3.0 より前では、無条件に ConfigureConduit() 関数を呼び出します。
- 重要
- PalmSource 社はこのエントリ ポイントを提供することを強く推奨します。そうしないと、ユーザがあなたのコンジットをカスタマイズすることを選択したときに何も起こりません。あなたのコンジットがコンフィグレーションをサポートしない場合、この関数を実装してユーザにコンフィグレーションはサポートしないということを知らせる方がまだ良いです。
HotSync マネージャが CfgConduit() 関数を呼び出したとき、あなたのコンジットはコンフィグレーション ダイアログ ボックスを表示することによって応答します。このダイアログ ボックスは、ユーザがあなたのコンジットが実行すべきアクションを指定することを可能にします。図 3.1 は、ToDo コンジットによって表示されるコンフィグレーション ダイアログ ボックスです。
図 3.1 ToDo コンジットのための "Custom" ダイアログ ボックス
図 3.1 はミラー-イメージ同期のための一般的なコンフィグレーション ダイアログ ボックスです。あなたのコンジットは追加のコンフィグレーション オプションを許可するかもしれません。
ConfigureConduit() ^TOP^
HotSync マネージャ バージョンの 3.0 より前のものは、CfgConduit() 関数の代わりに ConfigureConduit() 関数を呼び出します。それぞれの関数の目的はまったく同じです。
GetConduitName() ^TOP^
HotSync マネージャは GetConduitName() を呼び出してあなたのコンジットの名前を取得します。あなたのこの関数の実装は、名前のためのバッファをあなたのコンジットの名前で満たし、操作が成功したかどうかを示す状態値を返すことです。
HotSync マネージャ バージョン 3.0.1 以降はあなたのコンジットの名前を以下の手順で取得しようと試みます:
- コンジットがインストールされるときにCondCfg ユーティリティまたはコンジット マネージャ API で書き込まれた Name エントリを読み込みます。
- さもなければ、GetConduitInfo() を呼び出します。
- さもなければ、GetConduitName() を呼び出します。
それゆえ、あなたのコンジットが HotSync マネージャ バージョン 3.0.1 以降とだけ互換性を持てばよい場合、あなたは GetConduitName() を実装することを要求されません。
HotSync マネージャ バージョン 3.0 とそれ以前のものは、あなたのコンジットが GetConduitName() を実装することを要求します。この場合、あなたの実装は、name バッファをユーザに向けて HotSync マネージャに表示させたい文字列で満たすことです。
コード 3.4 で示されている Generic Conduit Framework バージョンの GetConduitName() 関数が一般的なものです。この関数は文字列テーブル（IDS_CONDUIT_NAME）の中で定義されている文字列へのポインタを戻し、成功したことを示す 0 を返します。
コード 3.4 GetConduitName() エントリ ポイントの例
ExportFunc long GetConduitName(char* pszName, WORD nLen)
{
long retval = -1;
if (::LoadString((HINSTANCE)hLangInstance, IDS_CONDUIT_NAME, pszName, nLen))
retval = 0;
return retval;
}
