MSGSERVICEENTRY

项目
04/04/2023

适用于：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]服务提供程序DLL 实例的句柄。句柄通常用于检索资源。

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 成员中包含有效的错误消息字符串。如果结构的 lpszComponent 或 lpszError 成员存在，则其内存最终必须通过对基本结构上的 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：：CreateMsgService 或 IMsgServiceAdmin：：ConfigureMsgService 的客户端应用程序调用此入口点。

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

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

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

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

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

MSGSERVICEENTRY

参数

返回值

备注

其他资源