iscEngineListenerPF

目的

iscEngineListenerPF は、iscEngineSetListener() で登録されたユーザー定義のリスナー関数が準拠しなければならないプロトタイプを定義します。

構文

typedef isy_INT32 (*iscEngineListenerPF)(
    isy_UINT32  listenerData,
    ISCEVT*     event,
    isy_VOID*   pExtraInfo);

関数の引き数

表 139 は、iscEngineSetListenerPF 関数タイプで使用される有効な引き数をリストしたものです。

表 139. iscEngineListenerPF の引き数

使用法

同期化の進行状況をモニターするためにユーザー定義のリスナー関数を使用するには、 まず、関数が iscEngineSetListenerPF 関数タイプに準拠するようにしなければなりません。 次に、iscEngineSetListener() 関数を使用してリスナー関数を登録します。 これで、同期イベントが発生するとユーザー定義のリスナー関数に通知されます。 event 引き数は、イベントに関するさまざまな情報を含む構造体です。

表 140 は、イベント構造体の全フィールドと、各フィールドの目的をリストしたものです。

表 140. iscEngineListenerPF イベントのフィールド

event.info フィールドには、イベント固有のオプショナル情報がいくつか含まれています。 この情報を識別して解釈するには、イベント・コードを使用します。

表 141 は、イベント・タイプのカテゴリー別にすべてのイベント・コードをリストしたものです。

表 141. iscEngineListenerPF のイベント・コード

表 142. iscEngineListenerPF のイベント・コード

表 143. iscEngineListenerPF のイベント・コード

表 144. iscEngineListenerPF のイベント・コード

表 145. iscEngineListenerPF のイベント・コード

表 146. iscEngineListenerPF のイベント・コード

例:

isy_INT32 mySyncListener(
    isy_UINT32 listenerData,
    ISCEVT*  event,
    isy_VOID*  pExtraInfo)
{
    char *statusMsg = appEventCodeToMessage(event);
    int   timesRetried;
 
    switch (event->type) {
      case ISCEVTTYPE_Info:
        appStatusBar(statusMsg);
        // appStatusBar can be any routine which shows the statusMsg (e.g., in a
        // status bar)
        return ISCRTNCB_Done;
 
      case ISCEVTTYPE_Retry:
        timesRetried = event->retry;
        if (timesRetried >= 3) // Try no more than 3 times
            return ISCRTNCB_ReplyNo;
        else
            return appRetryCancelBox(statusMsg, 10); // 10 sec timeout
        // appRetryCancelBox can be any routine which shows a window with two
        // buttons: Cancel and Retry.  It returns
        //   ISCRTNCB_ReplyYes, if user clicks Retry
        //   ISCRTNCB_ReplyNo, if user clicks Cancel
        // If the user doesn't make choice, it returns ISCRTNCB_Default.
        break;
 
      // all other event types, don't care
				  default:
        return ISCRTNCB_Default;
    } // switch (event->type)
} // mySyncListener

戻りコード

• ISCRTNCB_ReplyYes: ユーザーは照会に Yes と応答する
• ISCRTNCB_ReplyNo*: ユーザーは照会に No と応答する
• ISCRTNCB_Default: 応答なし。デフォルトのアクションを実行する

イベント・タイプが ISCEVTTYPE_Retry である場合、リスナー関数は以下のいずれかのコードを戻します。

イベント・タイプが ISCEVTTYPE_Query である場合、戻りコードの意味はイベント・コードの値によって決まります。 つまり、リスナーはイベント・コードをチェックし、該当する値を戻します。 しかし、ユーザーが照会に応答しない場合、アプリケーションは以下のコードを戻します。

• ISCRTNCB_Default: 応答なし。デフォルトのアクションを実行する

ISCEVTTYPE_Retry および ISCEVTTYPE_Query 以外のイベント・タイプの場合、同期エンジンは戻りコードを無視します。 リスナーは単に ISCRTNCB_Done を戻します。

注: 評価対象外のイベントの場合、リスナー関数は単に ISCRTNCB_Default を戻し、 同期エンジンでデフォルトのアクションを実行します。

注: 上記の中で示されているアスタリスク (*) は、各イベント・タイプのデフォルトのアクションを示しています。

制約事項

ユーザー定義のリスナー関数は、同期エンジンのプロトコルに従わなければなりません。 従わない場合、同期エンジンが正しく動作しない可能性があります。

関連した概念

• 同期クライアント C/C++ サンプル・アプリケーション

関連したタスク

• C/C++ を使用した DB2 Everyplace 同期クライアント・アプリケーションの開発

関連した解説

• IBM 同期クライアント C-API バージョン 8.1 と バージョン 7.2 の比較
• IBM 同期クライアント C-API のデータ・タイプ
• IBM 同期クライアント C-API の関数の要約
• iscEngineSync()
• iscEngineSetListener()