查看单个帖子
旧 2012-07-23, 02:34 PM   #1 (permalink)
admin
论坛管理员
 
admin 的头像
 
注册日期: 2009-07-01
帖子: 47
默认 龙笛插件系统技术白皮书

LONG-D.Cn
龙笛插件系统技术白皮书
C++
2012/7/22


详细介绍龙笛插件系统的依赖文件、导出函数、各种服务接口、各种回调接口以及各种相关结构体、事件、枚举和常量。




目录
第一章概述... 4
第二章客户端插件... 5
依赖文件... 5
插件模块导出函数... 5
插件管理器接口... 7
插件服务接口... 9
插件网络通信服务... 19
插件回调接口... 21
全局函数... 24
结构体及其它... 25
第三章服务端插件... 28
依赖文件... 28
插件模块导出函数... 28
服务端服务接口... 29
全局函数... 29
结构体... 29
第四章后台管理系统插件... 31
依赖文件... 31
插件模块导出函数... 31
插件服务接口... 32
全局函数... 32
结构体... 32
消息... 33



第一章 概述

随着企业信息化程度的越来越高,即时通讯软件(IM)在企业信息化进程中不断被强化,作为信息传递的中枢,与OA、CRM、E-mail、SMS等软件的联系越来越紧密,并朝着平台化方向演变。为了方便企业用户深度整合各种OA相关的软件,个性化地定制属于自己的企业即时通讯系统,从龙笛1.5.0.25版本开始,引入了龙笛插件体系。

在最初的版本中,龙笛插件体系仅支持客户端插件。随着龙笛版本的不断完善,插件体系也得到了发展。目前已支持三种不同的插件,分别是客户端插件、服务端插件、后台管理系统插件。三种插件从各个方面进一步完善了龙笛插件体系,为企业提供了更深入的二次开发和深度整合能力。

本文档着眼于全面介绍龙笛插件体系的细节,包括依赖文件、导出函数、各种服务接口、各种回调接口以及各种相关结构体、事件、枚举和常量。因此,本文档并不是一份有关龙笛插件开发的入门介绍。如果需要简要的入门开发指南,可以参见《龙笛插件开发快速入门手册》。

龙笛插件开发SDK随安装包一起发布,通常解压安装包后,有一个名为SDK的文件夹。该文件夹包括龙笛插件开发的全部头文件、库文件:

ZJIMDef.h
EIMPluginServiceDef.h
EIMPluginServiceInc.h
EIMPluginService.lib
EIMPLGPluginServiceDef.h
EIMPLGPluginServiceInc.h
EIMPlgPluginService.lib
EIMSysMgrPluginServiceDef.h
EIMSysMgrPluginServiceInc.h
EIMSysMgrPluginService.lib

目前的龙笛插件体系是以C++ header/lib/dll的方式工作的,由C++ header定义服务接口,lib提供接口函数的二进制链接,dll方式加载插件。因此,开发龙笛插件需要使用C++语言进行。


第二章 客户端插件

依赖文件

n 头文件:EIMPluginServiceInc.h
n 库文件:EIMPluginService.lib
插件模块导出函数

一个客户端插件的入口DLL必须导出如下三个函数才能被系统加载并被识别为客户端插件:

n PluginInitialize
插件被初始化时调用此函数,在此函数内插件通过EIMPluginInfo结构体设置插件GUID、插件名称、描述等信息,并进行插件内部状态初始化、资源分配等任务。

函数原型:
BOOL PluginInitialize(EIMPluginInfo& stPluginInfo)

函数参数:
stPluginInfo EIMPluginInfo结构体的引用,用于向系统返回插件信息。

示例代码:
BOOL PluginInitialize(EIMPluginInfo& stPluginInfo)
{
stPluginInfo.nSlotItems = EIM_SLOT_CHATDLG_EDIT_TOOLBAR|EIM_SLOT_TRIBEDLG_EDIT_TOOLBAR;
_tcscpy_s(stPluginInfo.szPluginGuid, 33, _T("CA308C19099749ae9ABAA6C4BF24DF26"));
_tcscpy_s(stPluginInfo.szPluginComp, 32, _T("龙笛开发组"));
_tcscpy_s(stPluginInfo.szPluginDesc, 256, _T("本插件实现掷骰子、抽奖功能,试一下您的运气,在单聊和群中娱乐!"));
_tcscpy_s(stPluginInfo.szPluginName, 32, EIM_PLUGIN_NAME);
_tcscpy_s(stPluginInfo.szPluginUrl, 64, _T("http://www.long-d.cn"));
return TRUE;
}

n PluginUninitialize
插件被卸载时调用此函数。在此函数内可进行插件自身的资源卸载等任务。

函数原型:
BOOL PluginUninitialize(void)

n PluginRegistered
系统在插件被加载及初始化完成后调用此函数,用于向插件提供一次机会,以便插件可以向系统的各个插槽区(slot)注册插槽对象和注册事件处理,或执行其它依赖于插件路径或插件ID的事务。

函数原型:
BOOL PluginRegistered(LPCTSTR strCurrentPluginPath, UINT nPluginID)

函数参数:
strCurrentPluginPath 字符串型,当前插件的绝对路径
nPluginID 无符号整型,系统分配给当前插件的ID

通常,插件需要以图标的形式出现在系统中某个界面的插槽区(slot)。比如,一些重要的插件常常在主界面的顶部工具栏上添加图标,或者是聊天窗口的工具栏上添加图标,甚至是在主界面的TAB标签区添加一个TAB标签,产生一个新的扩展区域。这样的功能,需要在此函数中调用系统提供的服务接口来添加插槽区(slot)对象,并添加必要的事件处理回调接口。

示例代码:
下面的代码将向聊天窗口和群窗口的工具栏注册一个插槽区对象,然后注册事件处理接口。插槽区对象通过EIMSlotItemInfo来定义,并通过IEIMPluginManager接口的AddSlotItem方法把插槽区对象注册到系统中。随后调用了IEIMPluginManager接口的AddBaseProc和AddPluginNotifyProc两个方法来添加两种事件处理的回调接口。

BOOL PluginRegistered(LPCTSTR strCurrentPluginPath, UINT nPluginID)
{
EIMSlotItemInfo slot_item;
slot_item.nSlotItemInnerID = (WORD)ID_TOOLBARMENU_CAST;
slot_item.nSlotItemMenu = IDR_MENU;
slot_item.nSlotItemType = EIM_SLOT_CHATDLG_EDIT_TOOLBAR|EIM_SLOT_TRIBEDLG_EDIT_TOOLBAR;
_tcscpy_s(slot_item.szSlotItemIcon, 32, _T("lucky_icon.png"));
_tcscpy_s(slot_item.szSlotItemText, 32, _T("骰子"));
_tcscpy_s(slot_item.szSlotItemToolTip, 32, _T("掷骰子、抽奖"));
IEIMPluginManager* pPluginManager = EIMGetPluginManager();
if (pPluginManager != NULL)
{
pPluginManager->AddSlotItem(strCurrentPluginPath, nPluginID, slot_item);
pPluginManager->AddBaseProc(nPluginID, &procNotify);
pPluginManager->AddPluginNotifyProc(nPluginID, EIM_PLUGIN_ID, &procNotify);
}
return TRUE;
}
插件管理器接口

插件管理器接口IEIMPluginManager由系统提供,插件调用此接口主要用于添加、移除插槽区对象及各种事件处理的回调接口。
插件调用插件管理器接口IEIMPluginManager前,必须先获得该接口的指针,通过调用全局函数EIMGetPluginManager来实现。
该函数原型为:
__declspec(dllexport) IEIMPluginManager* EIMGetPluginManager();

插件管理器接口IEIMPluginManager主要提供了如下的方法供插件调用:

n UINT AddSlotItem(LPCTSTR strCurrentPluginPath, UINT nPluginID, const EIMSlotItemInfo& item)
功能:添加插槽区对象。
返回:成功返回插槽区对象ID,失败返回0。
参数:
strCurrentPluginPath 字符串型,当前插件绝对路径
nPluginID 无符号整型,插件ID
item EIMSlotItemInfo结构体,描述插槽区对象
n BOOL RemoveSlotItem(UINT nPluginID, UINT nItemID)
功能:移除插槽区对象。
返回:成功返回TRUE,失败返回FALSE。
参数:
nPluginID 无符号整型,插件ID
nItemID 无符号整型,插槽区对象ID
n BOOL AddBaseProc(UINT nPluginID, IEIMPluginBaseProc* pBaseProc)
功能:添加基本消息处理回调接口
返回:成功返回TRUE,失败返回FALSE。
参数:
nPluginID 无符号整型,插件ID
pBaseProc IEIMPluginBaseProc接口的指针,该接口由插件实现,用于处理基本的消息
n void RemoveBaseProc(UINT nPluginID, IEIMPluginBaseProc* pBaseProc)
功能:添加
返回:无
参数:
nPluginID 无符号整型,插件ID
pBaseProc IEIMPluginBaseProc接口的指针,该接口由插件实现,用于处理基本的消息
n BOOL AddMessageProc(UINT nPluginID, IEIMPluginMessageProc* pMessageProc)
功能:添加即时通讯消息处理回调接口
返回:成功返回TRUE,失败返回FALSE。
参数:
nPluginID 无符号整型,插件ID
pMessageProc IEIMPluginMessageProc接口的指针,该接口由插件实现,用于处理即时通讯消息
n void RemoveMessageProc(UINT nPluginID, IEIMPluginMessageProc* pMessageProc)
功能:添加
返回:无
参数:
nPluginID 无符号整型,插件ID
pMessageProc IEIMPluginMessageProc接口的指针,该接口由插件实现,用于处理即时通讯消息
n BOOL AddPluginNotifyProc(UINT nPluginID, LPCTSTR lpPluginID, IEIMPluginNotifyProc* pNotifyProc)
功能:添加插件通知处理回调接口
返回:成功返回TRUE,失败返回FALSE。
参数:
nPluginID 无符号整型,插件ID
lpPluginID 字符串型,插件字符串型ID,建议此ID由以圆点分隔的多个字符串组成,包含公司名称和插件名称,以保证插件ID的唯一性
pNotifyProc IEIMPluginNotifyProc接口指针,该接口由插件实现,用于处理插件的通知消息。
n void RemovePluginNotifyProc(LPCTSTR lpPluginID)
功能:移除插件通知处理回调接口
返回:无
参数:
lpPluginID 字符串型,插件字符串型ID
插件服务接口

为了让插件更好地控制系统,调用系统的功能,如获取当前登录用户的ID和状态,调用系统消息发送功能等,插件系统提供了多个服务接口供插件使用。
在使用这些服务接口前,插件需要先调用相应的全局函数获得这些接口的实例指针。
例如:
IEIMBaseService* pBaseService = EIMGetBaseService();
if (pBaseService != NULL)
{
TCHAR szUserName[100];
szUserName[0] = 0;
pBaseService->GetContactName(strSenderID, szUserName, 100);
}

n 基础服务接口:IEIMBaseService
该服务接口为插件提供一些最基础的服务,例如:获取龙笛系统的版本号、登录用户的ID、名称。

Ø void GetAppVersion(int& major, int& minor, int& modify, int& build)
功能:获取龙笛系统的版本号
返回:无
参数:
major 整型,主版本号
minor 整型,次版本号
modify 整型,修订号
build 整型,编译次序号
Ø void GetCompanyName(CString& strCompanyName)
功能:获取当前已注册的公司名称
返回:无
参数:
strCompanyName 字符串型,公司名称
Ø const CString& GetCurrentUserID()
功能:获取当前用户的ID
返回:字符串型,用户ID
参数:无
Ø long GetCurrentUserStatus()
功能:获取当前用户的在线状态
返回:长整型,表示在线状态。在线状态的定义请参见IMUserStatus 的定义。
参数:无
Ø int GetCurrentUserName(TCHAR szName[], int nBufferLen)
功能:获取当前用户姓名
返回:当前用户姓名的字符串长度
参数:
szName 字符数组
nBufferLen 字符数组的长度
Ø BOOL SetCurrentUserStatus(long lStatus)
功能:设置当前用户的状态
返回:成功返回TRUE,失败返回FALSE。
参数:
lStatus 长整型,表示在线状态。在线状态的定义请参见IMUserStatus 的定义。
Ø BOOL SetCurrentUserName(const TCHAR* szName)
功能:更改当前用户的姓名
返回:成功返回TRUE,失败返回FALSE。
参数:
szName 字符串指针,指向新的姓名字符串
Ø void Logoff()
功能:注销当前已登录的用户
返回:无
参数:无
Ø void Exit()
功能:退出龙笛系统
返回:无
参数:无
Ø int GetTribeMemberCount(const CString& strTribeID)
功能:获取指定的群包含的成员数目
返回:整型,成员数目
参数:
strTribeID 字符串型,指定群的ID
Ø int GetTribeMemberIDs(const CString& strTribeID, LPTSTR* ppMemberIDs)
功能:获取群成员列表
返回:群成员列表的数目
参数:
strTribeID 字符串型,指定群的ID
ppMemberIDs 字符串指针的指针,用于返回成员列表的字符串型ID,指向的内存由本函数分配,在调用完毕由调用者释放。
Ø int GetCurrentUserPath(TCHAR szBuffer[], int nBufferLen)
功能:获取当前用户的绝对路径
返回:整型,用户路径字符串的长度
参数:
szBuffer 字符数组
nBufferLen 字符数组的长度
Ø int GetContactName(const CString& strContactID, TCHAR szBuffer[], int nBufferLen)
功能:获取指定联系人的姓名
返回:整型,联系人姓名字符串的长度
参数:
strContactID 字符串型,联系人的ID
szBuffer 字符数组
nBufferLen 字符数组的长度
Ø int GetContactIconFile(const CString& strContactID, BOOL bOnline, TCHAR szBuffer[], int nBufferLen)
功能:获取联系人ICON文件的本地绝对路径
返回:整型,ICON文件字符串的长度
参数:
strContactID 整整,联系人ID
bOnline 布尔,指定获取在线图标,还是离线图标
szBuffer 字符数组
nBufferLen 字符数组的长度
Ø int GetContacts(std::vector<ContactBriefInfo*>& vecContacts)
功能:获取所有联系人
返回:整型,联系人数目
参数:
vecContacts vector,用于返回所有联系人,联系人结构体参见 ContactBriefInfo 的定义
Ø void ReleaseContacts(std::vector<ContactBriefInfo*>& vecContacts)
功能:释放所获得的联系人列表
返回:无
参数:
vecContacts vector,联系人列表,联系人结构体参见 ContactBriefInfo 的定义
Ø void GetMainServiceIPPort(DWORD& dwServerIpAddr, unsigned short& usServerPort)
功能:获取主服务器的IP地址和端口
返回:无
参数:
dwServerIpAddr DWORD,服务器IP地址
usServerPort short,服务器端口
Ø void GetFileServiceIPPort(DWORD& dwServerIpAddr, unsigned short& usServerPort)
功能:获取文件服务器的IP地址和端口
返回:无
参数:
dwServerIpAddr DWORD,服务器IP地址
usServerPort short,服务器端口
Ø void GetDataServiceIPPort(DWORD& dwServerIpAddr, unsigned short& usServerPort)
功能:获取数据服务器的IP地址和端口
返回:无
参数:
dwServerIpAddr DWORD,服务器IP地址
usServerPort short,服务器端口
Ø void GetPluginServiceIPPort(DWORD& dwServerIpAddr, unsigned short& usServerPort)
功能:获取插件服务器的IP地址和端口
返回:无
参数:
dwServerIpAddr DWORD,服务器IP地址
usServerPort short,服务器端口
Ø void SetMutexWnd(HWND hWnd)
功能:设置指定的窗口为互斥窗口。设为互斥窗口后,先前的互斥窗口将被关闭。系统中同一时间只会存在一个互斥窗口。
返回:无
参数:
hWnd HWND,窗口句柄
Ø HWND GetMutexWnd()
功能:获取当前的互斥窗口
返回:HWND,窗口句柄
参数:无
Ø void AddAutoDeleteWnd(HWND hWnd)
功能:添加指定的窗口到自动删除窗口队列中。该窗口关闭后,将自动删除。
返回:无
参数:
hWnd HWND,窗口句柄
Ø void RemoveAutoDeleteWnd(HWND hWnd)
功能:从自动删除窗口队列中移出指定的窗口。
返回:无
参数:
hWnd HWND,窗口句柄
Ø HWND FindUniqueWnd(LPCTSTR strWndName)
功能:查找指定名称的唯一实例窗口。
返回:HWND,窗口句柄
参数:
strWndName 字符串型,待查找的唯一实例窗口名称
Ø BOOL InsertUniqueWnd(LPCTSTR strWndName, HWND hWnd)
功能:添加指定的窗口到唯一实例窗口列表中。该窗口被添加后,同一时间将只能存在唯一的一个实例。
返回:成功返回TRUE,失败返回FALSE。
参数:
strWndName 字符串型,窗口名称,窗口名称由使用方自定义,为保证其唯一性,需要包含特定的字符串和一定的长度
hWnd HWND,窗口句柄
Ø BOOL ReleaseUniqueWnd(LPCTSTR strWndName)
功能:释放唯一实例窗口。该窗口将被关闭和释放。
返回:成功返回TRUE,失败返回FALSE。
参数:
strWndName 字符串型,窗口名称
Ø BOOL RemoveUniqueWnd(LPCTSTR strWndName)
功能:移除唯一实例窗口。该窗口仅从唯一实例列表中移除,不会被关闭和释放。
返回:成功返回TRUE,失败返回FALSE。
参数:
strWndName 字符串型,窗口名称
Ø void GetAttachedWndPos(const CSize& sizeWnd, CPoint& point)
功能:获取附着到主窗口的合适的窗口位置
返回:无
参数:
sizeWnd CSize,传入窗口的尺寸
point CPoint,传出窗口的位置
Ø void AdjustWindowPos(CWnd* pWnd, CWnd* pParentWnd = NULL, PluginChildWndPosition emPos = Plugin_Child_Attach, BOOL bSameHeight = FALSE, BOOL bLeftPriority = FALSE)
功能:自动调整窗口的位置和大小,使之附着到指定的父窗口的合适位置
返回:无
参数:
pWnd CWnd,需要被调整的窗口指针
pParentWnd CWnd,父窗口的指针
emPos PluginChildWndPosition枚举值,指定附着方式
bSameHeight BOOL,是否与父窗口高度相同
bLeftPriority BOOL,是否左边附着优先考虑
Ø void SetMainFrmMainToolBarItemText(UINT nPluginID, UINT nItemID, LPCTSTR strItemText)
功能:设置主界面主工具栏的插件图标的文字
返回:无
参数:
nPluginID UINT,插件ID
nItemID UINT,工具栏图标ID
strItemText 字符串型,图标项的文字
Ø void ShowSystemNotify(LPCTSTR szTitle, LPCTSTR szContent, LPCTSTR szUrl, UINT nPluginID, UINT nParam)
功能:显示一条系统通知
返回:无
参数:
szTitle 字符串型,系统通知的标题
szContent 字符串型,系统通知的内容
szUrl 字符串型,系统通知的URL
nPluginID UINT,插件ID
nParam UINT,额外的自定义参数
Ø INT_PTR ShowSelectContactDlg(HWND hWndParent, LPCTSTR strWndTitle, DWORD dwMask, LPCTSTR strDefContacts, LPCTSTR strDefTribes, LPTSTR* pstrContacts, LPTSTR* pstrTribes)
功能:打开联系人选择器窗口
返回:INT_PTR,窗口关闭的返回值,如ID_OK\ID_CANCEL等
参数:
hWndParent HWND,指定选择器窗口的父窗口
strWndTitle 字符串型,窗口标题
dwMask DWORD,掩码,用于指定显示何种选择器,目前其取值为 SEL_CONTACT_MASK_CONTACT、SEL_CONTACT_MASK_TRIBE
strDefContacts 字符串型,指定初始的联系人ID列表,多个联系人ID之间以英文逗号分隔
strDefTribes 字符串型,指定初始的群ID列表,多个群 ID之间以英文逗号分隔
pstrContacts 字符串指针的指针,返回选择的联系人ID, 多个联系人ID之间以英文逗号分隔。内存分配在此函数中进行,调用方需要释放。
pstrTribes 字符串指针的指针,返回选择的群ID, 多个群ID之间以英文逗号分隔。内存分配在此函数中进行,调用方需要释放。
Ø BOOL SaveCurrentUserOption(LPCTSTR strSection, LPCTSTR strKey, LPCTSTR strValue)
功能:保存当前用户的选项
返回:成功返回TRUE,失败返回FALSE。
参数:
strSection 字符串型,指定选项的section
strKey 字符串型,指定选项的key
strValue 字符串型,指定选项的value
Ø BOOL LoadCurrentUserOption(LPCTSTR strSection, LPCTSTR strKey, TCHAR szBuffer[], int nBufferLen)
功能:加载当前用户的选项
返回:成功返回TRUE,失败返回FALSE。
参数:
strSection 字符串型,指定选项的section
strKey 字符串型,指定选项的key
szBuffer 字符数组,返回指定选项的value
nBufferLen 字符数组的长度

n 消息服务接口:IEIMMessageService
该服务接口为插件提供即时消息相关的服务,例如:打开聊天窗口、发送即时消息、发送插件通知消息。

Ø BOOL OpenChatDlg(const CString& strContactID, BOOL bActive)
功能:打开与指定联系人的聊天窗口
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,联系人ID
bActive 布尔型,窗口是否被激活
Ø void CloseChatDlg(const CString& strContactID)
功能:关闭与指定联系人的聊天窗口
返回:无
参数:
strContactID 字符串型,联系人ID
Ø BOOL OpenTribeDlg(const CString& strTribeID, BOOL bActive)
功能:打开指定的群聊天窗口
返回:成功返回TRUE,失败返回FALSE。
参数:
strTribeID 字符串型,群ID
bActive 布尔型,窗口是否被激活
Ø void CloseTribeDlg(const CString& strTribeID)
功能:关闭群聊天窗口
返回:无
参数:
strTribeID 字符串型,群ID
Ø BOOL OpenGroupSendDlg(const CString& strContactIDs, const TCHAR* szMsg)
功能:打开群发消息窗口
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactIDs 字符串型,消息接收者ID,多个ID之间以英文逗号分隔
szMsg 字符串型指针,群发的消息内容
Ø BOOL SendMsg(const CString& strContactID, const TCHAR* szMsg)
功能:发送即时消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,消息接收者ID
szMsg 字符串型指针,消息内容
Ø BOOL InputMsg(const CString& strContactID, const TCHAR* szMsg)
功能:输入消息到聊天窗口
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,消息接收者ID
szMsg 字符串型指针,消息内容
备注:该方法暂时实现
Ø BOOL SendTribeMsg(const CString& strTribeID, const TCHAR* szMsg)
功能:发送群消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strTribeID 字符串型,群ID
szMsg 字符串型指针,消息内容
Ø BOOL InputTribeMsg(const CString& strTribeID, const TCHAR* szMsg)
功能:
返回:成功返回TRUE,失败返回FALSE。
参数:
strTribeID 字符串型,群ID
szMsg 字符串型指针,消息内容
备注:该方法暂时实现
Ø BOOL SendGroupMsg(LPCTSTR lpContactIDs, const TCHAR* szMsg)
功能:发送群发消息
返回:成功返回TRUE,失败返回FALSE。
参数:
lpContactIDs 字符串型指针,消息接收者ID,多个ID之间以英文逗号分隔
szMsg 字符串型指针,群发的消息内容
Ø BOOL SendAutoReplayMsg(const CString& strContactID, const TCHAR* szMsg)
功能:发送自动回复消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,消息接收者ID
szMsg 字符串型指针,消息内容
Ø BOOL OpenSmsDlg(const TCHAR* szMobileNum)
功能:打开短信发送窗口
返回:成功返回TRUE,失败返回FALSE。
参数:
szMobileNum 字符串型,移动电话号码
Ø BOOL SendSms(const TCHAR* szMobileNum, const TCHAR* szSms)
功能:发送短信
返回:成功返回TRUE,失败返回FALSE。
参数:
szMobileNum 字符串型,移动电话号码
szSms 字符串型,短信内容
Ø BOOL GroupSendSms(TCHAR szMobileNums[][16], const TCHAR* szSms)
功能:群发短信
返回:成功返回TRUE,失败返回FALSE。
参数:
szMobileNums 字符串型数组,移动电话号码列表
szSms 字符串型,短信内容
Ø BOOL InsertSysMsg2ChatDlg(const CString& strContactID, LPCTSTR lpSender, LPCTSTR lpMsg)
功能:向聊天窗口插入系统消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,消息接收者ID
lpSender 字符串型指针,发送者名称
lpMsg 字符串型指针,消息内容
Ø BOOL InsertSysMsg2TribeDlg(const CString& strTribeID, LPCTSTR lpSender, LPCTSTR lpMsg)
功能:向群聊天窗口插入系统消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strTribeID 字符串型,群ID
lpSender 字符串型指针,发送者名称
lpMsg 字符串型指针,消息内容
Ø BOOL SendPluginNormalNotify(const CString& strContactID, LPCTSTR lpPluginID, LPCTSTR lpPluginName, LPCTSTR lpMsg)
功能:发送插件的普通通知消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,接收者的联系人ID
lpPluginID 字符串型指针,插件ID
lpPluginName 字符串型指针,插件名称
lpMsg 字符串型指针,消息内容
Ø BOOL SendPluginTribeNotify(const CString& strTribeID, LPCTSTR lpPluginID, LPCTSTR lpPluginName, LPCTSTR lpMsg)
功能:发送插件的群通知消息
返回:成功返回TRUE,失败返回FALSE。
参数:
strContactID 字符串型,接收者的联系人ID
lpPluginID 字符串型指针,插件ID
lpPluginName 字符串型指针,插件名称
lpMsg 字符串型指针,消息内容
Ø BOOL SendPluginGroupNotify(LPCTSTR lpContactIDs, LPCTSTR lpPluginID, LPCTSTR lpPluginName, LPCTSTR lpMsg)
功能:发送插件群发通知消息
返回:成功返回TRUE,失败返回FALSE。
参数:
lpContactIDs 字符串型指针,接收者的联系人ID,多个ID之间以英文逗号分隔
lpPluginID 字符串型指针,插件ID
lpPluginName 字符串型指针,插件名称
lpMsg 字符串型指针,消息内容
插件网络通信服务

当插件需要网络通信服务时,不必自行从基础的功能开始开发,可以使用系统提供的基本网络通信服务。基本的网络通信服务基于套接字(socket)进行封装,为插件提供连接服务器及双向通信的能力。

插件网络通信服务通过IEIMPluginClientSocket 接口提供,插件须调用全局函数 EIMCreatePluginClientSocket 创建一个指向IEIMPluginClientSocket接口的对象实例。然后通过调用IEIMPluginClientSocket 接口的方法进行通信。
通信完毕不再使用时,插件须调用全局函数 EIMReleasePluginClientSocket 释放先前获得的IEIMPluginClientSocket 接口指针。

IEIMPluginClientSocket接口提供了如下的方法:
Ø void SetTimeOut(DWORD dwConnectTimeOut, DWORD dwSendTimeOut, DWORD dwRecvTimeOut)
功能:设置连接、发送和接收的超时
返回:无
参数:
dwConnectTimeOut DWORD,连接超时设置,毫秒
dwSendTimeOut DWORD,发送超时设置,毫秒
dwRecvTimeOut DWORD,接收超时设置,毫秒
Ø BOOL Connect(const CString& strIpAddr, unsigned short usPort)
功能:连接服务器
返回:成功返回TRUE,失败返回FALSE
参数:
strIpAddr 字符串型,服务器IP地址
usPort 无符号短整型,服务器端口
Ø BOOL Connect(DWORD dwIpAddr, unsigned short usPort)
功能:连接服务器
返回:成功返回TRUE,失败返回FALSE
参数:
dwIpAddr DWORD,服务器IP地址(主机顺序)
usPort 无符号短整型,服务器端口
Ø BOOL ConnectByHostName(const CString& strServerName, unsigned short usPort)
功能:连接服务器
返回:成功返回TRUE,失败返回FALSE
参数:
strServerName 字符串型,主机名称
usPort 无符号短整型,服务器端口
Ø DWORD GetHostIpAddr() const
功能:获取本机的IP地址
返回:DWORD,IP地址,主机顺序
参数:无
Ø void Disconnect()
功能:断开与服务器的连接
返回:无
参数:无
Ø BOOL Send(LPBYTE pData, int nDataSize)
功能:发送消息
返回:成功返回TRUE,失败返回FALSE
参数:
pData BYTE指针,指向消息内容
nDataSize int,消息内容的字节长度
Ø BOOL RecvMsg(BYTE** ppData, int& nDataSize)
功能:接收消息
返回:成功返回TRUE,失败返回FALSE
参数:
ppData BYTE型指针的指针,其内存由本方法分配,调用方须调用ReleaseMsg释放该指针
nDataSize int,返回接收到的消息长度
Ø void ReleaseMsg(BYTE** ppData)
功能:释放通过RecvMsg分配的内存
返回:无
参数:
ppData BYTE型指针的指针,由RecvMsg返回的双指针
Ø long GetLastError()
功能:获取最后一次错误的ID
返回:错误ID
参数:无
插件回调接口

当插件需要处理系统的消息,或插件自已的通知时,插件需要实现相应的回调接口。回调接口由插件按规范实现,系统在事件发生时进行调用。

目前有三类回调接口,插件根据需要有选择性地实现:基本消息处理接口、即时消息处理接口、插件内部通知事件处理接口。

每种回调接口实现后,插件需要把接口注册到插件系统中。注册上述三种回调接口分别是由IEIMPluginManager 接口的AddBaseProc、AddMessageProc和AddPluginNotifyProc实现的。

n 基本消息处理接口:IEIMPluginBaseProc
Ø BOOL OnWindowsMessage(UINT nMsg, WPARAM wParam, LPARAM lParam, const CString& strIDContactOrTribe, BOOL bIsTribe)
功能:该方法用于处理一般性的windows消息,诸如按钮点击、菜单选中之类。插件注册到插槽区的对象被点击,菜单被用户选中,是通过本方法通知给插件的。
返回:如果消息已被处理,则返回TRUE;否则,对于不感兴趣的消息,返回FALSE
参数:
nMsg、wParam、lParam 与Windows的消息处理函数意义相同
strIDContactOrTribe 字符串型,指示联系人或群的ID
bIsTribe 布尔型,指示strIDContactOrTribe参数是否是群ID

Ø BOOL OnCurrentUserStatusChanged(IMUserStatus emUserStatus)
功能:指示当前用户状态改变
返回:已响应返回TRUE,否则为FALSE
参数:
emUserStatus IMUserStatus枚举,指示新的状态。参见IMUserStatus定义。
Ø BOOL OnCurrentUserLogon(IMUserStatus emUserStatus)
功能:指示用户登录成功
返回:已响应返回TRUE,否则为FALSE
参数:
emUserStatus IMUserStatus枚举,指示当前状态。参见IMUserStatus定义。
Ø BOOL OnCurrentUserLogoff()
功能:指示当前用户注销
返回:已响应返回TRUE,否则为FALSE
参数:无
Ø BOOL OnContactStatusChanged(const CString& strContactID, IMUserStatus emUserStatus)
功能:指示联系人状态改变
返回:已响应返回TRUE,否则为FALSE
参数:
strContactID 字符串型,联系人ID
emUserStatus IMUserStatus枚举,指示新的状态。参见IMUserStatus定义。
Ø BOOL OnAppExit()
功能:指示龙笛系统即将退出
返回:已响应返回TRUE,否则为FALSE
参数:无

n 即时消息处理接口:IEIMPluginMessageProc
注意:本接口的回调暂未实现,将来的版本会实现,但有可能发生改变。
Ø BOOL OnNewMsg(const CString& strContactID, long lMsgType, TCHAR* szMsg)
Ø BOOL OnNewTribeMsg(const CString& strTribeID, TCHAR* szMsg)
Ø BOOL OnSendMsg(const CString& strContactID, long lMsgType, TCHAR* szMsg)
Ø BOOL OnSendTribeMsg(const CString& strTribeID, TCHAR* szMsg)
Ø BOOL OnNewSms(const TCHAR* szMobileNum, TCHAR* szSms)
Ø BOOL OnSendSms(const TCHAR* szMobileNum, TCHAR* szSms)
Ø BOOL OnNewSysMsg(const DATE* dtMsgTime, const TCHAR* szTitle, const TCHAR* szContent)
Ø BOOL OnNewEmailNotify(const DATE* dtMsgTime, const TCHAR* szSender, const TCHAR* szSubject, const TCHAR* szContent, UINT nNewMailCount)
n 插件内部通知事件处理接口:IEIMPluginNotifyProc

本接口有2个方法,一个用于接收普通即时消息,另一个用于接收群消息。

通常,插件自己内部的简单通信可通过调用IEIMMessageService 接口的SendPluginNormalNotify方法和本接口的OnRecvNormalMsg方法来完成。相应的群内的插件通信可通过调用SendPluginTribeNotify 和OnRecvTribeMsg 来完成。

Ø BOOL OnRecvNormalMsg(const DATE& dtTime, const CString& strSenderID, LPCTSTR lpMsg, BOOL bOfflineMsg)
功能:接收插件内部普通即时消息
返回:通过返回值指示本消息是否被处理,若被处理则返回TRUE,否则,返回FALSE
参数:
dtTime DATE,消息发送时间
strSenderID 字符串型,发送者ID
lpMsg 字符串型,消息内容
bOfflineMsg 布尔值,是否为离线消息
Ø BOOL OnRecvTribeMsg(const DATE& dtTime, const CString& strSenderID, const CString& strTribeID, LPCTSTR lpMsg, BOOL bOfflineMsg)
功能:接收插件内部群消息
返回:通过返回值指示本消息是否被处理,若被处理则返回TRUE,否则,返回FALSE
参数:
dtTime DATE,消息发送时间
strSenderID 字符串型,发送者ID
strTribeID 字符串型,群ID
lpMsg 字符串型,消息内容
bOfflineMsg 布尔值,是否为离线消息

全局函数

n EIMGetPluginManager
获取插件管理器对象的指针
函数原型:
__declspec(dllexport) IEIMPluginManager* EIMGetPluginManager();
n EIMGetBaseService
获取基础服务接口的指针
函数原型:
__declspec(dllexport) IEIMBaseService* EIMGetBaseService();
n EIMGetMessageService
获取消息服务接口的指针
函数原型:
__declspec(dllexport) IEIMMessageService* EIMGetMessageService();
n EIMCreatePluginClientSocket
创建可供插件使用的客户端套接字(socket)
函数原型:
__declspec(dllexport) BOOL EIMCreatePluginClientSocket(LPCTSTR szPluginGUID, IEIMPluginClientSocket** ppClientSocket);
n EIMReleasePluginClientSocket
释放可供插件使用的客户端套接字(socket)
函数原型:
__declspec(dllexport) void EIMReleasePluginClientSocket(IEIMPluginClientSocket** ppClientSocket);
结构体及其它

n EIMPluginInfo
该结构体用于PluginInitialize函数调用时把插件信息传给系统。插件信息包含插件GUID、插件名称等信息。

typedef struct tagEIMPluginInfo
{
TCHAR szPluginGuid[33];
TCHAR szPluginName[32];
TCHAR szPluginDesc[256];
TCHAR szPluginComp[32];
TCHAR szPluginUrl[64];
UINT nSlotItems;
}EIMPluginInfo, *LPEIMPluginInfo;

Ø szPluginGuid 字符串型,插件GUID
Ø szPluginName 字符串型,插件名称
Ø szPluginDesc 字符串型,插件描述
Ø szPluginComp 字符串型,插件开发公司名称
Ø szPluginUrl 字符串型,插件开发公司网址
Ø nSlotItems UINT,插件将在哪些区域添加插槽区对象

n EIMSlotItemInfo

该结构体用于向插件系统注册插槽区对象。注册插槽区对象一般至少需要提供插槽区对象类型,内部ID、图标或文字等信息。

typedef struct tagEIMSlotItemInfo
{
SHORT nSlotItemInnerID;
UINT nSlotItemType;
TCHAR szSlotItemIcon[32];
TCHAR szSlotItemText[32];
TCHAR szSlotItemToolTip[64];
UINT nSlotItemMenu;
UINT nSlotItemWnd;
}EIMSlotItemInfo, *LPEIMSlotItemInfo;


Ø nSlotItemInnerID 短整型,指定一个内部ID
Ø nSlotItemType 整型,插件类型的组合
Ø szSlotItemIcon 字符串型,图标文件相对路径
Ø szSlotItemText 字符串型,文字
Ø szSlotItemToolTip 字符串型,Tooltip
Ø nSlotItemMenu 整型,菜单资源ID
Ø nSlotItemWnd 暂未使用

n EIMTABSELCHANGED
该结构体用于WM_MAINTAB_SELECTED消息处理时,把LPARAM参数造型为EIMTABSELCHANGED,通过本结构体获得容器窗口的信息。
typedef struct tagEIMTABSELCHANGED
{
HWND hContainerWnd;
RECT rtContainerClient;
}EIMTABSELCHANGED, *LPEIMTABSELCHANGED;

Ø hContainerWnd HWND,容器窗口句柄
Ø rtContainerClient RECT,容器窗口位置和尺寸

n PluginChildWndPosition
本枚举定义子窗口与父窗口的相对关系,目前只有两种:居中和附着。

enum PluginChildWndPosition
{
Plugin_Child_Center,
Plugin_Child_Attach,
};


n 插件类型
Ø EIM_SLOT_MAINFRM_TOP_TOOLBAR:主界面顶部工具栏
Ø EIM_SLOT_MAINFRM_BOTTOM_TOOLBAR:主界面底部工具栏
Ø EIM_SLOT_CHATDLG_TOP_TOOLBAR:聊天窗口顶部工具栏
Ø EIM_SLOT_CHATDLG_EDIT_TOOLBAR:聊天窗口编辑工具栏
Ø EIM_SLOT_TRIBEDLG_TOP_TOOLBAR:群窗口顶部工具栏
Ø EIM_SLOT_TRIBEDLG_EDIT_TOOLBAR:群窗口编辑工具栏
Ø EIM_SLOT_MAINFRM_TAB:主界面TAB标签区
Ø EIM_SLOT_NAMECARD_TOOLBAR:名片区工具栏

n 消息
消息(message)
WPARAM wParam
LPARAM lParam
WM_SYSNOTIFY_CLICKED
调用ShowSystemNotify的nParam
unused
WM_MAINTAB_SELECTED
插件插槽对象(Slot Item)的ID
EIMTABSELCHANGED结构体指针,包括容器窗口句柄和窗口矩形尺寸
WM_MAINTAB_UNSELECTED
同上
同上
WM_MAINTAB_SIZE
CRect对象指针,指示当前容器的尺寸
unused





第三章 服务端插件

依赖文件

n 头文件:EIMPLGPluginServiceInc.h
n 库文件:EIMPLGPluginService.lib
插件模块导出函数

一个服务端插件的入口DLL必须导出如下三个函数才能被系统加载并被识别为服务端插件:

n PLGPluginInitialize
插件被初始化时调用的函数,在此函数内插件通过EIMPLGPluginInfo结构体设置插件GUID、插件名称、描述等信息,并进行插件内部状态初始化、资源分配等任务。

函数原型:
BOOL PLGPluginInitialize(EIMPLGPluginInfo& stPLGPluginInfo)

n PLGPluginUninitialize
插件被卸载时调用此函数,在此函数内可进行插件自身的资源卸载等任务。

函数原型:
BOOL PLGPluginUninitialize()

n PLGPluginNetMsg
服务端接收到客户端插件发送的消息时,将根据插件的ID进行消息派发,插件通过此函数处理客户端插件发送的消息。

函数原型:
BOOL PLGPluginNetMsg(void* pSocketHandle, LPBYTE pMsgData, int nMsgDataLen)

参数:
pSocketHandle void*,表示Socket的内部句柄,在调用IEIMPlgSvrBaseService接口的SendToClient发送消息时需要此参数
pMsgData 字节数组,保存着消息的内容
nMsgDataLen 整型,消息内容的长度
服务端服务接口

目前服务端向插件提供了基础的服务接口IEIMPlgSvrBaseService,使用该接口可以与客户端进行通信。

插件通过全局函数EIMGetPlgSvrBaseService 获取IEIMPlgSvrBaseService接口指针,然后调用该接口的方法。

IEIMPlgSvrBaseService提供的方法:
n BOOL SendToClient(void* pSocketHandle, int nMsgType, LPBYTE pMsgData, int nMsgDataLen)
功能:该方法向客户端插件发送一条消息
返回:发送成功返回TRUE,失败返回FALSE
参数:
pSocketHandle void*,由PLGPluginNetMsg函数传的socket句柄
nMsgType int,自定义的消息ID,由插件客户端与服务端协定。
pMsgData BYTE指针,指向消息数据
nMsgDataLen int,消息数据的字节长度
全局函数

n EIMGetPlgSvrBaseService
该函数用于获取基础服务接口。

函数原型:
__declspec(dllexport) IEIMPlgSvrBaseService* EIMGetPlgSvrBaseService();

结构体

n EIMPLGPluginInfo
该结构体用PLGPluginInitialize函数调用时把插件信息传给系统。插件信息包含插件GUID、插件名称等信息。
typedef struct tagEIMPLGPluginInfo
{
TCHAR szPluginGuid[33];
TCHAR szPluginName[32];
TCHAR szPluginDesc[256];
TCHAR szPluginComp[32];
TCHAR szPluginUrl[64];
}EIMPLGPluginInfo, *LPEIMPLGPluginInfo;

Ø szPluginGuid 字符串型,插件GUID
Ø szPluginName 字符串型,插件名称
Ø szPluginDesc 字符串型,插件描述
Ø szPluginComp 字符串型,插件开发公司名称
Ø szPluginUrl 字符串型,插件开发公司网址



第四章 后台管理系统插件

依赖文件

n 头文件:EIMSysMgrPluginServiceInc.h
n 库文件:EIMSysMgrPluginService.lib
插件模块导出函数

一个后台管理系统插件的入口DLL必须导出如下三个函数才能被系统加载并被识别为后台管理插件:

n SysMgr_PluginInitialize

插件被初始化时调用的函数,在此函数内插件通过EIMSysMgrPluginInfo结构体设置插件GUID、插件名称、描述等信息,并进行插件内部状态初始化、资源分配等任务。

函数原型:
BOOL SysMgr_PluginInitialize(EIMSysMgrPluginInfo& stPluginInfo);

n SysMgr_PluginUninitialize
插件被卸载时调用此函数,在此函数内可进行插件自身的资源卸载等任务。

函数原型:
BOOL SysMgr_PluginUninitialize();

n SysMgr_PluginMsg

后台管理程序通过该函数通知插件有关插件视图显示、隐藏和尺寸变化等事件。插件应当响应这些事件,执行相应的动作。例如,SysMgrHostMsg_ShowView事件发生时,创建插件的窗体,SysMgrHostMsg_HideView事件发生时,销毁插件的窗体。

函数原型:
BOOL SysMgr_PluginMsg(UINT message, WPARAM wParam, LPARAM lParam);

函数参数:
UINT message—指示事件ID,其值可能是SysMgrHostMsg_ShowView、SysMgrHostMsg_HideView或SysMgrHostMsg_OnSize等;
WPARAM wParam—消息参数,其意义视消息ID而定;
LPARAM lParam—消息参数,其意义视消息ID而定。
插件服务接口

n IEIMSysMgrHostService

该服务接口用于向插件提供一种访问系统数据的能力,目前主要用于从系统中获取当前公司名称和员工简要信息。

该服务接口通过全局函数 EIMGetSysMgrHostService 获取
__declspec(dllexport) IEIMSysMgrHostService* EIMGetSysMgrHostService();
该服务接口包含如下方法:
l BOOL GetCompanyName(CString& strCompanyName)
获取公司名称。公司名称通过strCompanyName返回。
l BOOL GetStaffInfos(std::vector<LPEIMStaffBriefInfo>& vecStaffInfos)
获取员工简要信息列表。员工简要信息列表通过vecStaffInfos返回。LPEIMStaffBriefInfo结构体的具体定义见下文结构体部分的描述。
全局函数

n EIMGetSysMgrHostService
该函数用于获取后台管理系统提供的服务接口

函数原型:
__declspec(dllexport) IEIMSysMgrHostService* EIMGetSysMgrHostService();
结构体

n EIMSysMgrPluginInfo
该结构体用于SysMgr_PluginInitialize函数调用时把插件信息传给系统。插件信息包含插件GUID、插件名称等信息。

typedef struct tagEIMSysMgrPluginInfo
{
TCHAR szPluginGuid[33];
TCHAR szPluginName[32];
TCHAR szPluginDesc[256];
TCHAR szPluginComp[32];
TCHAR szPluginUrl[64];
}EIMSysMgrPluginInfo, *LPEIMSysMgrPluginInfo;

Ø szPluginGuid 字符串型,插件GUID
Ø szPluginName 字符串型,插件名称
Ø szPluginDesc 字符串型,插件描述
Ø szPluginComp 字符串型,插件开发公司名称
Ø szPluginUrl 字符串型,插件开发公司网址

n EIMStaffBriefInfo
该结构体用于通过IEIMSysMgrHostService接口的GetStaffInfos方法返回员工的简单描述信息。

typedef struct tagEIMStaffBriefInfo
{
CString m_strStaffID;
CString m_strName;
CString m_strSignature;
IMUserSex m_emSex;
}EIMStaffBriefInfo, *LPEIMStaffBriefInfo;

l m_strStaffID 字符串型,员工ID
l m_strName 字符串型,员工名字
l m_strSignature 字符串型,员工签名
l m_emSex 枚举类型,员工性别
消息

SysMgr_PluginMsg函数的消息及其参数的意见见下表:
消息(message) WPARAM wParam LPARAM lParam
l SysMgrHostMsg_ShowView 插件容器窗口句柄 Unused
l SysMgrHostMsg_HideView 插件容器窗口句柄 Unused
l ysMgrHostMsg_OnSize 插件容器窗口句柄 Unused
__________________

让世界倾听我们的笛声。
admin 当前离线   回复时引用此帖