- 追加された行はこのように表示されます。
- 削除された行は
このように表示されます。
{{div_begin}}
[[← 2 章に戻る|C/C++ Sync Suite Companion601/2]] [[↑トップへ|C/C++ Sync Suite Companion601]] [[4 章に進む →|C/C++ Sync Suite Companion601/4]]
{{div_end}}
{{div_begin style="margin-bottom:-10px"}}
!!!3 コンジット エントリ ポイントの実装
{{div_end}}
{{div_begin "style='position:absolute;right:0px;font-size:70%;margin-right:15px;margin-top:15px;width:250px;'"}}
*{{goto Overview,概要}}
*{{goto Required Entry Points,必須エントリ ポイント}}
**{{goto GetConduitInfo(),GetConduitInfo()}}
**{{goto GetConduitVersion(),GetConduitVersion()}}
**{{goto OpenConduit(),OpenConduit()}}
*{{goto Optional Entry Points,オプションのエントリ ポイント}}
**{{goto CfgConduit(),CfgConduit()}}
**{{goto ConfigureConduit(),ConfigureConduit()}}
**{{goto GetConduitName(),GetConduitName()}}
{{div_end}}
{{div_begin "style='position:relative;padding:0px;padding-right:5px;padding-left:10px;margin-right:250px;margin-top:20px;width:auto;border-right-style:dotted;border-right-width:2px;border-right-color:silver;'"}}
この章は、HotSync マネージャがあなたのコンジットを実行するためにあなたのコンジットが実装しなければならない必須エントリ ポイントとオプションのエントリ ポイントについて説明します。この章には以下の節があります。
*{{goto Overview,概要}}
*{{goto Required Entry Points,必須エントリ ポイント}}
*{{goto Optional Entry Points,オプションのエントリ ポイント}}
!!{{anchor Overview}}概要 {{goto top,^TOP^}}
HotSync マネージャがあなたのコンジットの中で呼び出す 2 タイプのエントリ ポイントがあります:
*{{goto Required Entry Points,必須エントリ ポイント}} - 各コンジットはこれらを実装しなければなりません。
*{{goto Optional Entry Points,オプションのエントリ ポイント}} - HotSync マネージャの '''Custom''' ダイアログ ボックス経由でユーザがあなたのコンジットをコンフィグレーションすることを可能にします。
この節では、これらのコンジット ポイントについての簡単な説明を提供します。これらの関数についての更なる情報は、''C/C++ Sync Suite Reference'' の中の [[第 6 章 「コンジット エントリ ポイント API」|C/C++ Sync Suite Reference601/6]] を参照してください。
{{goto Table 3.1,表 3.1}} はエントリ ポイント関数の要約を提供しています。
{{anchor Table 3.1}}
'''表 3.1 HotSync マネージャによって呼び出されるコンジット エントリ ポイント'''
,関数タイプ,関数名,説明
,必須,"{{goto GetConduitVersion,GetConduitVersion()|C/C++ Sync Suite Reference601/6}}","コンジットのバージョン番号を返します。{{br}}サポートされるコンジット バージョンの範囲は {{span style='color:blue;font-family:monospace;',0x00000101}} から {{span style='color:blue;font-family:monospace;',0x00000200}} までです。"
,必須,"{{goto OpenConduit,OpenConduit()|C/C++ Sync Suite Reference601/6}}",メイン コンジット エントリ ポイント。
,必須,"{{goto GetConduitInfo,GetConduitInfo()|C/C++ Sync Suite Reference601/6}}",コンジットについての情報を HotSync マネージャに返します。
,カスタム（オプション）,"{{goto ConfigureConduit,ConfigureConduit()|C/C++ Sync Suite Reference601/6}}{{br}}（HotSync 3.0.1 より前）{{br}}または{{br}}{{goto CfgConduit,CfgConduit()|C/C++ Sync Suite Reference601/6}}{{br}}（HotSync 3.0.1 以降）",ユーザがコンジットをコンフィグレーションすることを可能にするダイアログを表示します。
,オプション,"{{goto GetConduitName,GetConduitName()|C/C++ Sync Suite Reference601/6}}",コンジットの名前を HotSync マネージャが表示するために返します。HotSync マネージャ バージョン 3.0.1 よりも前では必須です。
!!{{anchor Required Entry Points}}必須エントリ ポイント {{goto top,^TOP^}}
この節は、あなたがあなた自身のコンジットに実装しなければならない以下のエントリ ポイントについて説明します。
*{{goto GetConduitInfo(),GetConduitInfo()}}
*{{goto GetConduitVersion(),GetConduitVersion()}}
*{{goto OpenConduit(),OpenConduit()}}
これらのエントリ ポイントの詳細は、''C/C++ Sync Suite Reference'' の中の [[第 6 章 「コンジット エントリ ポイント API」|C/C++ Sync Suite Reference601/6]] を参照してください。
!{{anchor GetConduitInfo()}}GetConduitInfo() {{goto top,^TOP^}}
HotSync マネージャは {{goto GetConduitInfo,GetConduitInfo()|C/C++ Sync Suite Reference601/6}} を呼び出してあなたのコンジットについての情報を取得します。あなたのこの関数の実装は、以下の要求を含むいくつかの異なる情報の要求に応答しなければなりません:
*あなたのコンジットのディスプレイ名
*あなたのコンジットのデフォルトのアクション
::NOTE
:::HotSync マネージャ バージョン 6.0 以降は、コンジットにコンジットの MFC バージョンを問い合わせません。そのため、この問い合わせへの応答はオプションです。{{br}}
:::しかしながら、より以前の HotSync マネージャに対して機能することを意図したコンジットは応答しなければなりません。この場合、あなたは {{span style='color:blue;font-family:monospace;',GetConduitInfo()}} を実装して適切な MFC バージョン定数を返さなけらばなりません。古いバージョンの CDK で作成したコンジット - {{span style='color:blue;font-family:monospace;',GetConduitInfo()}} を実装していない（今は必須です） - を再コンパイルする場合、HotSync マネージャはあなたのコンジットが MFC 4.1 でビルドされたと仮定します。そうでない場合、HotSync マネージャはあなたのコンジットを呼び出したときクラッシュします。
HotSync マネージャ バージョン 6.0 以降は、3 つの追加の - しかしオプションの - 情報を要求します。
*登録情報。あなたのコンジットは、フォルダ-ベースで登録される（{{goto Registering a Conduit by Folder,「フォルダでのコンジットの登録」|C/C++ Sync Suite Companion601/9-1}}} を参照してください）場合、応答しなければなりません。しかし、{{goto conventionally registered conduit,通常通りに登録されるコンジット|C/C++ Sync Suite Companion601/Glossary}} の場合は応答する必要はありません。
*あなたのコンジットの名前を HotSync マネージャの '''Custom''' ダイアログ ボックスと '''HotSync Progress''' ダイアログ ボックスに表示すべきかどうか。
*HotSync マネージャは常にあなたのコンジットを実行すべきか、それとも、ハンドヘルド上に同じ作成者 ID を持つアプリケーションがある場合のみ実行すべきか。
{{goto Listing 3.1,コード 3.1}} で示されている Generic Conduit Framework バージョンの {{span style='color:blue;font-family:monospace;',GetConduitInfo()}} が一般的なものです。{{span style='color:blue;font-family:monospace;',infoType}} パラメータに基づき、この関数は要求される情報のタイプを返します。
{{anchor Listing 3.1}}
'''コード 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;
}
!{{anchor GetConduitVersion()}}GetConduitVersion() {{goto top,^TOP^}}
HotSync マネージャは {{goto GetConduitVersion,GetConduitVersion()|C/C++ Sync Suite Reference601/6}} を呼び出してデスクトップ上で実行されているあなたのコンジットのバージョンを取得します。あなたのこの関数の実装は、あなたのメジャー バージョン番号を low word （訳者注: LOWORD, DWORD （32 ビット整数）の下位 2 バイトのこと）の上位バイトに、あなたのマイナー バージョン番号を low word の下位バイトにパックしなければなりません。
{{goto Listing 3.2,コード 3.2}} で示されている Generic Conduit Framework バージョンの {{span style='color:blue;font-family:monospace;',GetConduitVersion()}} 関数が一般的なものです。この関数は単純にバージョン番号を指定する定数値を返します。
{{anchor Listing 3.2}}
'''コード 3.2 GetConduitVersion() エントリ ポイントの例'''
#define GENERIC_CONDUIT_VERSION 0x00000102
ExportFunc DWORD GetConduitVersion()
{
return GENERIC_CONDUIT_VERSION;
}
!{{anchor OpenConduit()}}OpenConduit() {{goto top,^TOP^}}
HotSync マネージャは {{goto OpenConduit,OpenConduit()|C/C++ Sync Suite Reference601/6}} を呼び出して、デスクトップ コンピュータとハンドヘルド間のデータの同期プロセスを開始します。Generic Conduit Framework を使用するコンジットのために、あなたの {{span style='color:blue;font-family:monospace;',OpenConduit()}} の実装は以下のようなことを実行する必要があります。
*{{span style='color:blue;font-family:monospace;',CSynchronizer}} クラスをインスタンス化して、あなたのコンジットがカテゴリまたは情報ブロックを扱う必要があるかどうかを指定します。
*{{span style='color:blue;font-family:monospace;',CSynchronizer}} の {{span style='color:blue;font-family:monospace;',Perform()}} メソッドを呼び出すことによってあなたの同期を開始します。
*コンジットの {{span style='color:blue;font-family:monospace;',CSynchronizer}} オブジェクトを削除します。
{{goto Listing 3.3,コード 3.3}} は Generic Conduit Framework の {{span style='color:blue;font-family:monospace;',OpenConduit()}} を示しています。
{{anchor Listing 3.3}}
'''コード 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);
}
!!{{anchor Optional Entry Points}}オプションのエントリ ポイント {{goto top,^TOP^}}
この節は、以下のオプションのエントリ ポイントについて説明します。
*{{goto CfgConduit(),CfgConduit()}}
*{{goto ConfigureConduit(),ConfigureConduit()}}
*{{goto GetConduitName(),GetConduitName()}}
あなたはこれらの関数をあなたのコンジットの中に実装することができ、あなたは ''C/C++ Sync Suite Reference'' の中の [[第 6 章 「コンジット エントリ ポイント API」|C/C++ Sync Suite Reference601/6}} で説明されているデフォルトの機能を使用することができます。PalmSource 社は、あなたがこれらの各関数のあなた自身の実装を提供することを推奨します。
あなたはこれらの関数をあなたのコンジットの中に実装することができ、あなたは ''C/C++ Sync Suite Reference'' の中の [[第 6 章 「コンジット エントリ ポイント API」|C/C++ Sync Suite Reference601/6]] で説明されているデフォルトの機能を使用することができます。PalmSource 社は、あなたがこれらの各関数のあなた自身の実装を提供することを推奨します。
!{{anchor CfgConduit()}}CfgConduit() {{goto top,^TOP^}}
HotSync マネージャは、ユーザが HotSync マネージャ メニューの '''Custom''' をクリックして、あなたのコンジットを選択し、'''Change''' をクリックしたとき、{{goto CfgConduit,CfgConduit()|C/C++ Sync Suite Reference601/6}} を呼び出します。
{{span style='color:blue;font-family:monospace;',CfgConduit()}} 関数は、{{goto ConfigureConduit,ConfigureConduit()|C/C++ Sync Suite Reference601/6}} の HotSync マネージャ 3.0 以降のバージョンです。{{span style='color:blue;font-family:monospace;',CfgConduit()}} 関数は、{{span style='color:blue;font-family:monospace;',ConfigureConduit()}} 関数よりも多くの拡張可能なデータ構造体のフォームの中の情報を取得します。
HotSync マネージャ 3.0 以降はまず {{span style='color:blue;font-family:monospace;',CfgConduit()}} を呼び出そうと試みます。あなたのコンジットがこのエントリ ポイントを提供しない場合、HotSync マネージャは {{span style='color:blue;font-family:monospace;',ConfigureConduit()}} 関数を呼び出そうと試みます。HotSync マネージャのバージョン 3.0 より前では、無条件に {{span style='color:blue;font-family:monospace;',ConfigureConduit()}} 関数を呼び出します。
::重要
:::PalmSource 社はこのエントリ ポイントを提供することを強く推奨します。そうしないと、ユーザがあなたのコンジットをカスタマイズすることを選択したときに何も起こりません。あなたのコンジットがコンフィグレーションをサポートしない場合、この関数を実装してユーザにコンフィグレーションはサポートしないということを知らせる方がまだ良いです。
HotSync マネージャが {{span style='color:blue;font-family:monospace;',CfgConduit()}} 関数を呼び出したとき、あなたのコンジットはコンフィグレーション ダイアログ ボックスを表示することによって応答します。このダイアログ ボックスは、ユーザがあなたのコンジットが実行すべきアクションを指定することを可能にします。{{goto Figure 3.1,図 3.1}} は、ToDo コンジットによって表示されるコンフィグレーション ダイアログ ボックスです。
{{anchor Figure 3.1}}
'''図 3.1 ToDo コンジットのための "Custom" ダイアログ ボックス'''
{{img custom-changedialog.gif,style='width:399px;height:254px;'}}
{{goto Figure 3.1,図 3.1}} はミラー-イメージ同期のための一般的なコンフィグレーション ダイアログ ボックスです。あなたのコンジットは追加のコンフィグレーション オプションを許可するかもしれません。
!{{anchor ConfigureConduit()}}ConfigureConduit() {{goto top,^TOP^}}
HotSync マネージャ バージョンの 3.0 より前のものは、{{goto CfgConduit,CfgConduit()|C/C++ Sync Suite Reference601/6}} 関数の代わりに {{goto ConfigureConduit,ConfigureConduit()|C/C++ Sync Suite Reference601/6}} 関数を呼び出します。それぞれの関数の目的はまったく同じです。
!{{anchor GetConduitName()}}GetConduitName() {{goto top,^TOP^}}
HotSync マネージャは {{goto GetConduitName,GetConduitName()|C/C++ Sync Suite Reference601/6}} を呼び出してあなたのコンジットの名前を取得します。あなたのこの関数の実装は、名前のためのバッファをあなたのコンジットの名前で満たし、操作が成功したかどうかを示す状態値を返すことです。
HotSync マネージャ バージョン 3.0.1 以降はあなたのコンジットの名前を以下の手順で取得しようと試みます:
+コンジットがインストールされるときにCondCfg ユーティリティまたはコンジット マネージャ API で書き込まれた {{goto Name 1,Name|Introduction to Conduit Development601/A}} エントリを読み込みます。
+さもなければ、{{goto GetConduitInfo,GetConduitInfo()|C/C++ Sync Suite Reference601/6}} を呼び出します。
+さもなければ、{{goto GetConduitName,GetConduitName()|C/C++ Sync Suite Reference601/6}} を呼び出します。
それゆえ、あなたのコンジットが HotSync マネージャ バージョン 3.0.1 以降とだけ互換性を持てばよい場合、あなたは {{span style='color:blue;font-family:monospace;',GetConduitName()}} を実装することを要求されません。
HotSync マネージャ バージョン 3.0 とそれ以前のものは、あなたのコンジットが {{span style='color:blue;font-family:monospace;',GetConduitName()}} を実装することを要求します。この場合、あなたの実装は、{{span style='color:blue;font-family:monospace;',name}} バッファをユーザに向けて HotSync マネージャに表示させたい文字列で満たすことです。
{{goto Listing 3.4,コード 3.4}} で示されている Generic Conduit Framework バージョンの {{span style='color:blue;font-family:monospace;',GetConduitName()}} 関数が一般的なものです。この関数は文字列テーブル（{{span style='color:blue;font-family:monospace;',IDS_CONDUIT_NAME}}）の中で定義されている文字列へのポインタを戻し、成功したことを示す 0 を返します。
{{anchor Listing 3.4}}
'''コード 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;
}
{{div_end}}
{{div_begin "style='border-top-style:solid;border-top-width:1px;border-top-color:silver;'"}}
[[← 2 章に戻る|C/C++ Sync Suite Companion601/2]] [[↑トップへ|C/C++ Sync Suite Companion601]] [[4 章に進む →|C/C++ Sync Suite Companion601/4]]
{{div_end}}
