iscEngineListenerPF

用途

iscEngineListenerPF 定义使用 iscEngineSetListener() 注册的用户定义的侦听器函数应符合的原型。

语法

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

函数自变量

表 139 列示用于 iscEngineSetListenerPF 函数类型的有效自变量。

表 139. iscEngineListenerPF 自变量

数据类型	自变量	使用	描述
isy_UINT32	`listenerData`	输入	通过 `iscEngineSetListener()` 将 `syncListenerData` 自变量中的数据集转发回侦听器函数。
ISCEVT*	`event`	输入	事件对象
isy_VOID*	`pExtraInfo`	输入	保留

用法

要使用用户定义的侦听器函数来监视同步的进度，必须首先使函数符合 iscEngineSetListenerPF 函数类型。下一步，使用 iscEngineSetListener() 函数注册侦听器函数。然后，当发生同步事件时，将通知用户定义的侦听器函数。event 自变量是一种结构，它包含关于该事件的各种信息。

表 140 列示事件结构中的所有字段和每个字段的用途。

表 140. iscEngineListenerPF 事件字段

字段	描述
类型	事件类型可以是以下值之一（实际值在圆括号中）： ISCEVTTYPE_Info（1）有关同步进度的信息。 ISCEVTTYPE_Conflict（2）同步过程中的冲突操作和已拒绝的操作。 ISCEVTTYPE_Query（3）需要某些信息以便同步继续进行。应用程序必须提供某些必需的信息（基于事件代码）以便同步引擎继续进行。 ISCEVTTYPE_Retry（4）发生异常，重试或取消指令需要继续同步。 ISCEVTTYPE_Error（5）发生错误，同步引擎不能继续使当前预订集同步。 ISCEVTTYPE_Fatal（6）发生致命错误，同步引擎不能继续使预订集同步。
状态	事件状态，它包含下列子字段： currSubsSet 预订集名称（如果不为空）。 currSubs 预订名称（如果不为空）。 subsType 预订类型（如果不为 0），排列如下： 100-999：保留 1000-9999：注册的预订类型 10000+ ：定制预订类型预定义的始发者是（实际值在圆括号内）： ISCSUBSTYPE_Config（100）：配置 ISCSUBSTYPE_File（101）：文件预订 ISCSUBSTYPE_DB2e（102）：DB2 Everyplace 表预订 syncProg 表示为百分比的同步进度。
重试	同一事件的重试次数（如果不为 0）。
信息	可选的特定于事件的信息（如果不为 NULL），它是非冲突事件的字符串自变量的数组。对于冲突事件，数据类型是 ISCLISTENCONFLICT。

event.info 字段包含某些可选的特定于事件的信息。事件代码用于标识和解释此信息。

表 141 按事件类型的类别列示所有事件代码。

表 141. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）	描述
事件类型：ISCEVTTYPE_Info
ISCEVT_InfGeneral（1000）	NULL	概要信息（用于调试）
ISCEVT_InfSyncStarted（1001）	NULL	同步已启动。
ISCEVT_InfPrepMsg（1002）	NULL	正在准备消息。
ISCEVT_InfSendMsg（1003）	NULL	正在发送消息。
ISCEVT_InfWaitMsg（1004）	NULL	正在等待服务器应答。
ISCEVT_InfApplyMsg（1005）	NULL	应用服务器消息。
ISCEVT_InfCancelingSync（1006）	NULL	正在取消同步。
ISCEVT_InfSubsSetStarted（1007）	NULL	预订集同步已启动。
ISCEVT_InfSyncingSubs（1008）	NULL	预订同步已启动。
ISCEVT_InfSubsSetFailed（1009）	NULL	预订集同步失败。
ISCEVT_InfSubsSetCanceled（1010）	NULL	已取消预订集同步。
ISCEVT_InfSubsSetSucceeded（1011）	NULL	预订集同步成功完成。
ISCEVT_InfSyncSucceeded（1012）	NULL	同步成功。
SCEVT_InfSyncFailed（1013）	NULL	同步（在某些预订集上）失败。
ISCEVT_InfSyncCanceled（1014）	NULL	（用户）已取消同步。
ISCEVT_InfSyncProg（1015）	NULL	表示为百分比的同步进度。
ISCEVT_InfNoNewChange（1016）	NULL	没有新的服务器更改；跳过拉出和确认阶段。
ISCEVT_InfLoginFailed（1017）	NULL	指定的登录信息通过认证过程。

表 142. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）		描述
事件类型：ISCEVTTYPE_Conflict
ISCEVT_CftReject（2000）	ISCLISTENCONFLICT		在同步中发现数据冲突。实际冲突数据以 `ISCLISTENCONFLICT` 结构形式表示，而其参考指针将通过 `event.info` 给回应用程序。

表 143. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）	描述
事件类型：ISCEVTTYPE_Retry
ISCEVT_TryNetConn（4601）	NULL	重试连接到服务器。
ISCEVT_TrySendRequest（4602）	NULL	重试发送请求。
ISCEVT_TryRecvReply（4603）	NULL	重试接收应答。
ISCEVT_TryRecvTimeout（4604）	NULL	等待更长时间以接收应答。
SCEVT_TryRecvAck（4605）	NULL	重试接收确认。

表 144. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）	描述
事件类型：ISCEVTTYPE_Query
ISCEVT_QueCancel（5000）	NULL	查询用户是否取消并返回（实际值在圆括号内）： ISCRTNCB_ReplyYes（3）：如果用户取消 ISCRTNCB_ReplyNo（2）：如果用户选择继续 ISCRTNCB_Default（0）：缺省值（即 ISCRTNCB_ReplyNo）
ISCEVT_QueCancelUponError（5001）	NULL	查询用户是否取消并返回（实际值在圆括号内）： ISCRTNCB_ReplyYes（3）：如果用户取消 ISCRTNCB_ReplyNo（2）：如果用户选择继续 ISCRTNCB_Default（0）：缺省值（即 ISCRTNCB_ReplyNo）
ISCEVT_QueLogin（5002）	ISCLISTENARG(3) info->argv[0] info->argv[1] info->argv[2]	适配器请求的登录信息。侦听器必须在事件信息中提供请求的信息并应该用实际值（1）返回 `ISCRTNCB_Done`。数据源的目标名称用于保存用户名的空白缓冲区用于保存密码的空白缓冲区
ISCEVT_QueSubsTarget (5003)	ISCLISTENARG(1) info->argv[0]	适配器请求的数据库请求。侦听器可能在事件信息中提供请求的信息并返回 ISCRTNCB_Done 或返回 ISCRTNCB_Default 以使用缺省目标目录。用于预订的目录。

表 145. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）	描述
事件类型：ISCEVTTYPE_Error
ISCEVT_ErrOpenAdapter（300）	NULL	未能打开适配器 <`适配器名称`>。
ISCEVT_ErrLoadAdapter（301）	NULL	未能装入适配器 <`适配器名称`>。
ISCEVT_ErrCloseAdapter（302）	NULL	未能关闭适配器 <`适配器名称`>。
ISCEVT_ErrAuthenticateKey（306）	NULL	认证失败（加密密钥无效）；同步异常终止。
ISYNCEVT_ErrClientCryptoFailed（307）	NULL	客记机加密或解密失败；同步异常终止。
ISCEVT_ErrEncryptNotAvail（308）	NULL	加密不可用。
ISCEVT_ErrEncryptLibOpen（309）	NULL	未能打开加密库。
ISCEVT_ErrSubsNotFound（311）	NULL	服务器未找到预订。
ISCRTN_ErrSubsNotAvail（312）	NULL	服务器阻塞了预订。
ISCRTN_ErrSubsDefAltered（316）	NULL	自上次同步引擎使配置同步之后预订定义已改变。
ISCEVT_ErrAllocResource（400）	NULL	未能分配适配器资源。
ISCEVT_ErrConnectData（401）	NULL	未能连接到目标数据。
ISCEVT_ErrDisconnectData（402）	NULL	未能与目标数据断开连接。
ISCEVT_ErrNoData（403）	NULL	未找到数据。
ISCEVT_ErrMessageFormat（412）	NULL	意外的消息格式。
ISCEVT_ErrNotFound（413）	ISCLISTENARG(2) info->argv[0] info->argv[1]	未找到请求的数据。数据源的目标名称数据名称
ISCEVT_ErrEndOfData（414）	NULL	意外的数据结束。
ISCEVT_ErrDataTooLong（415）	ISCLISTENARG(3) info->argv[0] info->argv[1] info->argv[2]	数据太长被截断。数据源的目标名称数据名称数据元素名称（如果不为空）
ISCEVT_ErrSyncDisabled（417）	NULL	服务器报告未启用用户。
ISCEVT_ErrServerException（418）	NULL	服务器报告未知异常。
ISCEVT_ErrReadOnly（420）	ISCLISTENARG(2) info->argv[0] info->argv[1]	试图更新只读数据。数据源的目标名称数据名称
ISCEVT_ErrOperation（421）	NULL	对数据的非法操作。
ISCEVT_ErrUnauthorized（423）	NULL	无权存取目标数据。
ISCEVT_ErrNotAvailable（424）	ISCLISTENARG(2) info->argv[0] info->argv[1]	请求的数据不可用。数据源的目标名称数据名称
ISCEVT_ErrNotSupported（425）	ISCLISTENARG(3) info->argv[0] info->argv[1] info->argv[2]	不支持请求的数据。数据源的目标名称数据名称数据元素名称（如果不为空）
ISCEVT_ErrNetConn（601）	NULL	未能连接到服务器。
ISCEVT_ErrSendRequest（602）	NULL	未能发送请求。
ISCEVT_ErrRecvReply（603）	NULL	未能接收应答。
ISCEVT_ErrRecvTimeout（604）	NULL	接收应答时发生超时。
ISCEVT_ErrRecvAck（605）	NULL	未能接收到确认。
ISCRTN_ErrCloseNetLib（608）	NULL	未能关闭网络库
ISCEVT_ErrOutOfMemory（610）	NULL	内存不足。
ISCEVT_ErrInternal（698）	ISCLISTENARG(1) info->argv[0]	发生了其它内部错误。错误状态（作为字符串）。

表 146. iscEngineListenerPF 事件代码

事件代码	事件信息（argc）	描述
事件类型：ISCEVTTYPE_Fatal
ISCEVT_FatSyncCfgAbort（303）	NULL	配置同步失败；同步异常终止。
ISCEVT_FatAuthenticateFailed（304）	NULL	认证失败；同步异常终止。
ISCEVT_FatIncompVersion（310）	NULL	不兼容的同步客户机版本。
ISCEVT_FatInvalidSession（313）	NULL	无效的会话标识。
ISCEVT_FatSyncGroup（314）	NULL	用户不属于任何同步组。
ISCEVT_FatRegisterDevice（315）	NULL	未能为用户注册设备。
ISCEVT_FatNetOpenConn（600）	NULL	未能打开与服务器的连接。
ISCEVT_FatOpenNetLib（606）	NULL	未装入“网络”库。
ISCEVT_FatResolveHost（609）	NULL	未能解析主机名。
ISCEVT_FatServerForbidden（611）	NULL	禁止与服务器同步。
ISCEVT_FatServerNotFound（612）	NULL	未找到服务器
ISCEVT_FatServer（613）	NULL	服务器错误。
ISCEVT_FatServerNotAvail（614）	NULL	服务器不响应。
ISCEVT_FatNetUnknown（699）	NULL	未知网络错误。

示例：

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 ：用户对查询应答是。
ISCRTNCB_ReplyNo* ：用户对查询应答否。
ISCRTNCB_Default ：没有应答，执行缺省操作。

如果事件类型是 ISCEVTTYPE_Retry，侦听器函数返回下列其中一个代码：

如果事件类型是 ISCEVTTYPE_Query，返回码的意义取决于事件代码的值。换句话说，侦听器检查事件代码并返回适当的值。但如果用户没有应答查询，应用程序返回下列代码：

ISCRTNCB_Default ：没有应答，执行缺省操作。

对于除 ISCEVTTYPE_Retry 和 ISCEVTTYPE_Query 以外的事件类型，同步引擎忽略返回码。侦听器只返回 ISCRTNCB_Done。

注意：对于不感兴趣的那些事件，侦听器函数只返回 ISCRTNCB_Default 并允许同步引擎执行缺省操作。

注意：以上的星号（*）指示各种事件类型的缺省操作。

限制

用户定义的侦听器函数应遵循同步引擎的协议。否则，同步引擎可能无法正常工作。

相关概念

样本 Sync Client C/C++ 应用程序

相关任务

使用 C/C++ 开发 DB2 Everyplace Sync Client 应用程序

相关参考