MSGSERVICEENTRY

适用于:Outlook 2013 | Outlook 2016

定义消息服务入口点函数的原型以支持消息服务配置。

属性
标头文件:
Mapispi.h
通过以下方式实现的定义函数:
消息服务
通过以下方式调用的定义函数:
MAPI
HRESULT MSGSERVICEENTRY(
  HINSTANCE hInstance,
  LPMALLOC lpMalloc,
  LPMAPISUP lpMAPISup,
  ULONG_PTR ulUIParam,
  ULONG ulFlags,
  ULONG ulContext,
  ULONG cValues,
  LPSPropValue lpProps,
  LPPROVIDERADMIN lpProviderAdmin,
  LPMAPIERROR FAR * lppMapiError
);

参数

hInstance

[in]服务 providerDLL 实例的句柄。 该句柄通常用于检索资源。

lpMalloc

[in]指向公开 OLE IMalloc 接口的内存分配器对象的指针。 使用某些接口(如 IStream)时,消息服务可能需要使用此分配方法。

lpMAPISup

[in]指向 IMAPISupport 的指针:IUnknown 接口实现。

ulUIParam

[in]用于将用户界面信息传递到函数或零的特定于实现的值。 ulUIParam 参数是配置对话框的父窗口句柄,其类型为 HWND (转换为ULONG_PTR) 。 值为零表示没有父窗口。

ulFlags

[in]指示服务项函数选项的标志的位掩码。 可以设置以下标志:

MAPI_UNICODE

传入字符串采用 Unicode 格式。 如果未设置MAPI_UNICODE标志,则字符串采用 ANSI 格式。

MSG_SERVICE_UI_READ_ONLY

服务的配置用户界面应显示当前配置,但不允许用户对其进行更改。

SERVICE_UI_ALLOWED

允许在必要时显示配置对话框。 设置SERVICE_UI_ALLOWED标志时,仅当 lpProps 属性值数组为空或不包含有效配置时,才应显示对话框。 如果未设置SERVICE_UI_ALLOWED,则如果设置了SERVICE_UI_ALWAYS标志,可能仍会显示一个对话框。

UI_CURRENT_PROVIDER_FIRST

请求在其他对话框顶部显示活动提供程序的配置对话框。

SERVICE_UI_ALWAYS

要求消息服务显示配置对话框。 如果未设置SERVICE_UI_ALWAYS标志,则如果设置了SERVICE_UI_ALLOWED标志,并且 lpProps 属性值数组中没有有效的配置信息,则可能仍会显示配置对话框。 必须设置SERVICE_UI_ALLOWED或SERVICE_UI_ALWAYS才能显示用户界面。

ulContext

[in]MAPI 当前正在执行的配置操作。 ulContext 参数将包含以下值之一:

MSG_SERVICE_CONFIGURE

应在配置文件中更改服务的配置。 如果设置了SERVICE_UI_ALWAYS标志,则服务应显示其配置对话框。 如果设置了SERVICE_UI_ALLOWED标志,并且 lpProps 参数为空或不包含有效的配置数据,则还应显示对话框。 如果 lpProps 包含有效数据,则不应显示对话框,并且服务应使用此数据进行配置更改。

MSG_SERVICE_CREATE

服务正在添加到配置文件中。 如果设置了SERVICE_UI_ALWAYS或SERVICE_UI_ALLOWED标志,则服务应显示其配置对话框。 如果未设置任何标志,则服务应失败。

MSG_SERVICE_DELETE

服务正在从配置文件中删除。 收到此事件后,服务应返回S_OK。

MSG_SERVICE_INSTALL

该服务已从网络、软盘或其他外部介质安装到用户的工作站。 收到此事件后,服务通常返回S_OK。

MSG_SERVICE_PROVIDER_CREATE

请求服务创建提供程序的其他实例。 如果服务支持此操作,则应调用 IProviderAdmin::CreateProvider。 如果服务不支持此操作,则可以返回MAPI_E_NO_SUPPORT。

MSG_SERVICE_PROVIDER_DELETE

请求服务删除提供程序实例。 如果服务支持此操作,则应调用 IProviderAdmin::D eleteProvider。 如果服务不支持此操作,则可以返回MAPI_E_NO_SUPPORT。

MSG_SERVICE_UNINSTALL

正在删除该服务。 收到此事件后,服务可以执行任何应在服务结束之前完成的清理任务,然后返回成功值。 如果用户取消删除,则服务应返回MAPI_E_USER_CANCEL。

cValues

[in] 由 lpProps 参数指向的数组中的属性值计数。 如果 MAPI 不传递任何属性值, 则 cValues 参数的值为零。

lpProps

[in]指向 SPropValue 结构的可选数组的指针,该数组指示函数在配置消息服务时将使用的提供程序支持的属性的值。 仅当 ulContext 参数设置为MSG_SERVICE_CONFIGURE时,函数才使用此参数。 此参数通常用于将路径传递给基于文件的服务(例如个人通讯簿服务)的文件。 如果 ulFlags 参数中未传递MSG_SERVICE_CONFIGURE标志, 则 lpProps 参数必须为零。

lpProviderAdmin

[in]指向 IProviderAdmin:IUnknown 接口的指针,函数可用于查找当前消息服务中特定提供程序的配置文件部分。

lppMapiError

[out]指向 MAPIERROR 结构的 指针。 结构是使用 MAPIAllocateBuffer 函数分配的。 所有成员都是可选的,尽管大多数结构在 lpszError 成员中将包含有效的错误消息字符串。 如果结构的 lpszComponentlpszError 成员存在,则最终必须通过对基结构上的 MAPIFreeBuffer 的单个调用释放其内存。

返回值

S_OK

调用成功,并返回了预期值或值。

MAPI_E_UNCONFIGURED

尚未配置服务提供程序。

MAPI_E_USER_CANCEL

用户通常通过单击对话框中的 “取消 ”按钮来取消操作。

MAPI_E_NO_SUPPORT

提供程序要么不支持对其对象进行更改,要么不支持更改通知。

MAPI_E_BAD_CHARWIDTH

设置MAPI_UNICODE标志,实现不支持 Unicode,或者未设置MAPI_UNICODE,实现仅支持 Unicode。

注解

使用 MSGSERVICEENTRY 函数原型定义的函数使消息服务能够配置自己或执行其他特定于服务的操作。 该函数主要提供一个对话框,用户可以在其中更改特定于消息服务的设置。 它还可以通过使用 lpProps 参数中传递的属性值数组来支持编程配置。 除非服务支持需要配置文件向导,否则编程配置是可选的。

MAPI 从控制面板应用程序或响应调用 IMsgServiceAdmin::CreateMsgServiceIMsgServiceAdmin::ConfigureMsgService 的客户端应用程序调用此入口点。

MAPI 对消息服务用于 MSGSERVICEENTRY 原型的函数名称没有限制,但首选名为 ServiceEntry。 函数的序号没有限制,单个提供程序 DLL 可以包含多个函数。 但是,只有一个函数可以命名为 ServiceEntry

消息服务可以使用 BuildDisplayTable 函数和 IMAPISupport::D oConfigPropsheet 方法简化配置对话框实现。

用户可以取消MSG_SERVICE_UNINSTALL操作。 在这种情况下, ServiceEntry 函数应与用户一起检查,以验证是否不应删除该服务,并在服务仍安装时返回MAPI_E_USER_CANCEL。

基于 MSGSERVICEENTRY 原型的函数返回列出的 HRESULT 值之一。 MAPI 在响应客户端对 IMsgServiceAdmin::ConfigureMsgService 的调用时转发此值。

导出服务输入函数的消息服务必须包括 MAPISVC.INF 消息服务部分中的 PR_SERVICE_DLL_NAME (PidTagServiceDllName) 和 PR_SERVICE_ENTRY_NAME (PidTagServiceEntryName) 属性。