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
[в] Дескриптор экземпляра поставщика службыDLL. Дескриптор обычно используется для получения ресурсов.
lpMalloc
[в] Указатель на объект распределителя памяти, предоставляющий интерфейс OLE IMalloc . Службе сообщений может потребоваться использовать этот метод выделения при работе с определенными интерфейсами, такими как IStream.
lpMAPISup
[в] Указатель на IMAPISupport: реализация интерфейса IUnknown .
ulUIParam
[в] Конкретное значение реализации, используемое для передачи сведений о пользовательском интерфейсе в функцию или ноль. Параметр ulUIParam является дескриптором родительского окна для диалогового окна конфигурации и имеет тип HWND (приведение к ULONG_PTR). Нулевое значение указывает на отсутствие родительского окна.
ulFlags
[в] Битовая маска флагов, указывающих параметры функции входа в службу. Можно задать следующие флаги:
MAPI_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
[в] Операция конфигурации, которую в настоящее время выполняет 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
[в] Количество значений свойств в массиве, на который указывает параметр lpProps . Значение параметра cValues равно нулю, если MAPI не передает значения свойств.
lpProps
[в] Указатель на необязательный массив структур SPropValue , указывающий значения свойств, поддерживаемых поставщиком, которые функция будет использовать при настройке службы сообщений. Функция использует этот параметр только в том случае, если для параметра ulContext задано значение MSG_SERVICE_CONFIGURE. Этот параметр обычно используется для передачи пути к файлу для файловой службы, например службы личной адресной книги. Если флаг MSG_SERVICE_CONFIGURE не передается в параметре ulFlags , параметр lpProps должен быть равен нулю.
lpProviderAdmin
[в] Указатель на интерфейс 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 и реализация не поддерживает Юникод, либо MAPI_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.