IMAPIStatus::ValidateState
Область применения: Outlook 2013 | Outlook 2016
Подтверждает сведения о внешнем состоянии, доступные для ресурса MAPI или поставщика услуг. Этот метод поддерживается во всех объектах состояния.
HRESULT ValidateState(
ULONG_PTR ulUIParam,
ULONG ulFlags
);
Параметры
ulUIParam
[в] Дескриптор родительского окна всех диалоговых окон или окон, отображаемых этим методом.
ulFlags
[в] Битовая маска флагов, управляющая проверкой. Можно задать следующие флаги:
ABORT_XP_HEADER_OPERATION
Пользователь отменил операцию, обычно нажав кнопку Отмена в соответствующем диалоговом окне. Объект состояния имеет два варианта:
Продолжить работу над операцией.
Остановите операцию и верните MAPI_E_USER_CANCELED.
CONFIG_CHANGED
Изменено одно или несколько свойств конфигурации объекта состояния. Клиенты могут задать этот флаг, чтобы разрешить диспетчеру очереди MAPI динамически исправлять критические сбои поставщика транспорта.
FORCE_XP_CONNECT
Объект состояния должен выполнять подключение. Если этот флаг используется с флагом REFRESH_XP_HEADER_CACHE или PROCESS_XP_HEADER_CACHE, соединение происходит без кэширования.
FORCE_XP_DISCONNECT
Объект состояния должен выполнить операцию отключения. Если этот флаг используется с флагом REFRESH_XP_HEADER_CACHE или PROCESS_XP_HEADER_CACHE, отключение происходит без кэширования.
PROCESS_XP_HEADER_CACHE
Записи в таблице кэша заголовков должны быть обработаны, все сообщения, помеченные флагом MSGSTATUS_REMOTE_DOWNLOAD, должны быть загружены, а все сообщения, помеченные флагом MSGSTATUS_REMOTE_DELETE, должны быть удалены. Сообщения с заданными MSGSTATUS_REMOTE_DOWNLOAD и MSGSTATUS_REMOTE_DELETE должны быть перемещены.
REFRESH_XP_HEADER_CACHE
Для удаленного поставщика транспорта необходимо скачать новый список заголовков сообщений и очистить все флаги, которые помечают состояние сообщения.
SUPPRESS_UI
Запрещает объекту состояния отображать пользовательский интерфейс в рамках операции.
Возвращаемое значение
S_OK
Проверка прошла успешно.
MAPI_E_BUSY
Выполняется еще одна операция; Ему должно быть разрешено завершение или его остановка, прежде чем эта операция будет инициирована.
MAPI_E_NO_SUPPORT
Объект состояния не поддерживает метод проверки, о чем свидетельствует отсутствие флага STATUS_VALIDATE_STATE в свойстве PR_RESOURCE_METHODS (PidTagResourceMethods).
MAPI_E_USER_CANCEL
Пользователь отменил операцию проверки, обычно нажав кнопку Отмена в диалоговом окне. Это значение возвращается только удаленными поставщиками транспорта.
Замечания
Метод IMAPIStatus::ValidateState проверяет состояние ресурса, связанного с объектом состояния. ValidateState — единственный метод в интерфейсе IMAPIStatus , необходимый для всех объектов состояния. Точное поведение этого метода зависит от реализации. В следующей таблице описана реализация каждого из различных типов объектов состояния.
| Объект Status | Реализация ValidateState |
|---|---|
| Подсистема MAPI |
Проверяет состояние всех ресурсов, которыми в настоящее время владеют активные поставщики служб и сама подсистема. |
| Диспетчер очереди MAPI |
Выполняет вход всех поставщиков транспорта независимо от того, вошли ли они в систему. |
| Адресная книга MAPI |
Проверяет записи в разделе профиля. |
| Поставщик услуг |
Реализация зависит от типа поставщика и флагов, заданных в параметре ulFlags . |
Примечания для исполнителей
Удаленные клиентские приложения вызывают метод ValidateState для запуска удаленной обработки различных действий. Этот метод существует главным образом для задания битов состояния для связи с диспетчером очереди MAPI, а не для выполнения какой-либо работы. Как правило, поставщик транспорта устанавливает в строке состояния флаги, указывающие диспетчеру очереди MAPI, какие действия необходимо инициировать для выполнения запроса клиента.
В этой модели взаимодействия клиент-транспорт-spooler действия, запрошенные клиентом, являются асинхронными, при этом ValidateState возвращается до завершения запрошенных действий. Однако действия, которые не обязательно связаны с базовой системой обмена сообщениями или с интерфейсом, зависящим от транспорта, могут быть синхронными. Клиентское приложение передает битовую маску из следующих флагов, чтобы указать, какие действия должен предпринять удаленный поставщик транспорта.
ABORT_XP_HEADER_OPERATION
По возможности удаленный поставщик транспорта должен отменить все операции, связанные с загрузкой заголовков. Для этого поставщик транспорта должен задать следующие значения свойств в строке состояния объекта входа:
Очистите STATUS_INBOUND_ENABLED и STATUS_INBOUND_ACTIVE биты в свойстве PR_STATUS_CODE (PidTagStatusCode), чтобы сообщить диспетчеру очереди MAPI остановить входящий процесс очистки для этого поставщика транспорта.
Задайте бит STATUS_OFFLINE в свойстве PR_STATUS_CODE .
Задайте для свойства PR_REMOTE_VALIDATE_OK (PidTagRemoteValidateOk) значение TRUE.
Задайте для свойства PR_STATUS_STRING (PidTagStatusString) строку, указывающую пользователю состояние поставщика транспорта.
Возврат S_OK. Однако если выполняемую операцию невозможно отменить, ValidateState должна вернуть MAPI_E_BUSY.
FORCE_XP_CONNECT
Удаленный поставщик транспорта никогда не должен устанавливать подключение к общему ресурсу (например, модему или COM-порту) вне контекста взаимодействия диспетчера очереди MAPI и транспорта, связанного с методом IXPLogon::FlushQueues . Если метод ValidateState вызывается с этим флагом, поставщик транспорта должен выполнить следующие действия:
Задайте внутренний флаг состояния, указывающий, что при вызове метода IXPLogon::FlushQueues необходимо установить удаленное подключение.
Задайте правильные значения в таблице состояния, чтобы диспетчер очереди MAPI инициировал процесс очистки очереди.
После завершения очистки очередей отпустите общий ресурс.
Очистите бит STATUS_OFFLINE в свойстве PR_STATUS_CODE .
Возврат S_OK.
FORCE_XP_DISCONNECT
Удаленный поставщик транспорта должен освободить подключение к ресурсам системы обмена сообщениями. После этого необходимо задать бит STATUS_OFFLINE в свойстве PR_STATUS_CODE и вернуть S_OK.
PROCESS_XP_HEADER_CACHE
Поставщик удаленного транспорта должен обрабатывать удаленные сообщения и отправлять все отложенные сообщения. Для этого поставщик транспорта должен задать следующие значения свойств в строке состояния объекта входа:
Задайте для свойства PR_STATUS_STRING строку, указывающую пользователю состояние поставщика транспорта.
Задайте STATUS_OUTBOUND_ENABLED и STATUS_OUTBOUND_ACTIVE биты в свойстве PR_STATUS_CODE .
Задайте для свойства PR_REMOTE_VALIDATE_OK в строке состояния поставщика транспорта значение FALSE.
Если выполняется другая операция (например, скачивание заголовков) при вызове ValidateState , ValidateState должна вернуть MAPI_E_BUSY.
Выполните код для обработки флага REFRESH_XP_HEADER_CACHE, чтобы удовлетворить требования клиента Microsoft Exchange.
REFRESH_XP_HEADER_CACHE
Поставщик удаленного транспорта должен получать все новые заголовки сообщений из системы обмена сообщениями. Для этого поставщик транспорта должен выполнить следующие действия:
Задайте для свойства PR_STATUS_STRING строку, указывающую пользователю состояние поставщика транспорта.
Задайте STATUS_INBOUND_ENABLED и STATUS_INBOUND_ACTIVE биты в свойстве PR_STATUS_CODE .
Очистите бит STATUS_OFFLINE в свойстве PR_STATUS_CODE .
Задайте бит STATUS_ONLINE в свойстве PR_STATUS_CODE .
Задайте для свойства PR_REMOTE_VALIDATE_OK в строке состояния поставщика транспорта значение FALSE.
SHOW_XP_SESSION_UI
Если у поставщика транспорта есть какие-либо элементы пользовательского интерфейса для обработки заголовков сообщений (например, диалоговое окно, подтверждающее скачивание сообщений), это диалоговое окно должно отображаться. В противном случае ValidateState может вернуть MAPI_E_NO_SUPPORT.
Если передаются какие-либо флаги, отличные от этих, ValidateState должен вернуть MAPI_E_UNKNOWN_FLAGS.
Вызов клиента к поставщику транспорта часто выполняется методом IMAPIStatus::ValidateState . Во время обработки ValidateState поставщик транспорта не должен выполнять никаких действий, которые выделяют скудные системные ресурсы, такие как модем или COM-порт. Это связано с тем, что диспетчеру очереди MAPI иногда требуется сбрасывать очереди на нескольких поставщиках транспорта. Однако клиент может в любое время вызвать метод ValidateState любого поставщика транспорта. Если поставщик транспорта пытается выделить ограниченный ресурс во время обработки ValidateState, может возникнуть ошибка из-за конфликта с другим поставщиком транспорта, которому диспетчер очереди MAPI поручил очистить свои очереди. Если разрешить все скудные выделения ресурсов под руководством диспетчера очереди MAPI, можно избежать таких конфликтов. Поставщик транспорта должен поддерживать свойство PR_REMOTE_VALIDATE_OK , чтобы клиентские приложения могли обнаруживать, когда поставщик транспорта занят или ожидает запуска действия диспетчером очереди MAPI.
Примечания для вызывающих методов
Так как этот метод может вызвать другие потенциально длительные вызовы, ValidateState может вернуть MAPI_E_BUSY, чтобы сообщить, что этот метод ожидает завершения другой операции. Прежде чем выполнять другую задачу, следует подождать, пока не завершится ожидающая операция.
Вы имеете наибольший контроль над вызовами объектов состояния поставщика транспорта. В ValidateState можно передать один или несколько флагов, влияющих на операции поставщика транспорта. Например, флаг ABORT_XP_HEADER_OPERATION указывает, что пользователь отменил проверку. Поставщики транспорта могут решить прервать, вернуть MAPI_E_USER_CANCELED или продолжить.
Можно задать флаг CONFIG_CHANGED при вызове объекта состояния поставщика услуг или диспетчера очереди MAPI, чтобы указать, что параметр конфигурации был изменен. Для динамической перенастройки поставщика транспорта можно использовать CONFIG_CHANGED. При настройке CONFIG_CHANGED при вызове объекта состояния поставщика услуг поставщик отвечает вызовом IMAPISupport::SpoolerNotify , чтобы оповещать диспетчер очереди MAPI об изменении. Если задать CONFIG_CHANGED при вызове объекта состояния диспетчера очереди MAPI, он вызывает IXPLogon::AddressTypes для каждого активного поставщика транспорта. AddressTypes информирует диспетчер очереди MAPI о поддерживаемых типах адресов транспорта. Некоторые поставщики услуг также отображают индикатор хода выполнения, если проверка, как ожидается, займет много времени. Отображение индикатора хода выполнения полезно, но необязательно.
Если флаг SUPPRESS_UI задан, ни один из страниц свойств конфигурации или диалоговых окон хода выполнения не отображается.