IXPLogon::SubmitMessage
Область применения: Outlook 2013 | Outlook 2016
Указывает, что диспетчер очереди MAPI содержит сообщение для доставки поставщиком транспорта.
HRESULT SubmitMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
);
Параметры
ulFlags
[в] Битовая маска флагов, управляющая отправкой сообщения. Можно задать следующий флаг:
BEGIN_DEFERRED
Диспетчер очереди MAPI вызывает поставщика транспорта с сообщением, которое ранее было отложено. Идентификатор записи сообщения совпадает с идентификатором, когда оно было отложено. Сообщение было отложено путем передачи идентификатора записи обратно в диспетчер очереди MAPI с помощью метода IMAPISupport::SpoolerNotify с флагом NOTIFY_SENTDEFERRED.
lpMessage
[в] Указатель на объект сообщения (представляющий сообщение для доставки), имеющий разрешение на чтение и запись, которое поставщик транспорта использует для доступа к сообщению и управления им. Этот объект остается действительным до тех пор, пока поставщик транспорта не вернет из последующего вызова метода IXPLogon::EndMessage .
lpulMsgRef
[out] Указатель на переменную, в которой поставщик транспорта возвращает ссылочные значения, назначенные этому сообщению. Диспетчер очереди MAPI передает это значение ссылки в последующих вызовах для этого сообщения. Диспетчер очереди MAPI инициализирует значение 0, прежде чем возвращать его поставщику транспорта.
lpulReturnParm
[out] Указатель на переменную, соответствующую MAPI_E_WAIT или MAPI_E_NETWORK_ERROR значению ошибки, возвращенной SubmitMessage.
Возвращаемое значение
S_OK
Вызов выполнен успешно и возвращает ожидаемое значение или значения.
MAPI_E_BUSY
Поставщик транспорта не может обработать сообщение, так как он выполняет другую операцию. Поставщик должен использовать это возвращаемое значение, чтобы указать, что обработка не выполнялась и что диспетчер очереди MAPI не должен вызывать EndMessage. Диспетчер очереди MAPI повторите попытку вызова SubmitMessage позже.
MAPI_E_CANCEL
Несмотря на то, что поставщик транспорта попросил диспетчера очереди MAPI повторно отправить сообщение при предыдущем вызове SpoolerNotify , с тех пор условия изменились, и сообщение не следует возрождать. Диспетчер очереди MAPI будет продолжать обрабатывать что-то другое.
MAPI_E_NETWORK_ERROR
Ошибка сети помешала успешному завершению операции. Для параметра lpulReturnParm необходимо задать количество секунд, которое пройдет до повторного отправки сообщения диспетчером очереди MAPI.
MAPI_E_NOT_ME
Поставщик транспорта не может обработать это сообщение. Диспетчер очереди MAPI должен попытаться найти другого поставщика транспорта для него. Поставщик должен использовать это возвращаемое значение, чтобы указать, что обработка не выполнялась и что диспетчер очереди MAPI не должен вызывать EndMessage.
MAPI_E_WAIT
Временная проблема не позволяет поставщику транспорта обрабатывать сообщение. Для параметра lpulReturnParm необходимо задать количество секунд, которое пройдет до повторного отправки сообщения диспетчером очереди MAPI.
Замечания
Диспетчер очереди MAPI вызывает метод IXPLogon::SubmitMessage , когда у него есть сообщение для доставки поставщиком транспорта. Сообщение передается поставщику транспорта с помощью параметра lpMessage .
Если поставщик готов принять сообщение, он должен вернуть ссылочные значения с помощью параметра lpulMsgRef , обработать переданный объект и вернуть соответствующее значение (обычно S_OK). Если поставщик не готов к обработке передачи, он должен вернуть значение ошибки и, при необходимости, другое возвращаемое значение MAPI в lpulReturnParm , чтобы указать, как долго диспетчер очереди MAPI должен ждать перед повторной отправкой сообщения.
Реализация этого метода поставщиком транспорта может выполнять следующие действия:
Поместите сообщение во внутреннюю очередь, чтобы дождаться передачи, возможно, скопируйте сообщение в локальное хранилище и верните его.
Попытка выполнить фактическую передачу и вернуться по завершении передачи либо успешно, либо неудачно.
Определите, следует ли отправлять сообщение после проверки задействованного ресурса. В этом случае, если ресурс является бесплатным, поставщик может заблокировать ресурс, подготовить сообщение и отправить его. Если ресурс занят, поставщик может подготовить сообщение и отложить отправку на более позднее время.
Предпочтительный способ передачи сообщений зависит от поставщика транспорта и ожидаемого количества процессов, конкурирующих за системные ресурсы.
Во время вызова SubmitMessage поставщик транспорта управляет передачей данных сообщения из объекта message. Однако поставщик транспорта должен присвоить значение ссылки сообщению, в которое он возвращает указатель в lpulMsgRef, перед передачей данных. Это происходит потому, что в любой момент процесса диспетчер очереди MAPI может вызвать метод IXPLogon::TransportNotify с установленным флагом NOTIFY_CANCEL_MESSAGE, чтобы сообщить поставщику о том, что он должен освободить все открытые объекты и остановить передачу сообщений.
Поставщик транспорта не должен отправлять непереправляемые свойства сообщения. Когда он находит такое свойство, он должен перейти к обработке следующего свойства. Поставщик должен сделать все возможное, чтобы не отображать MAPI_P1 сведения о получателе в составе содержимого передаваемого сообщения; поставщик должен использовать эти сведения о получателе только для целей адресации. MAPI_P1 получатели являются внутренними получателями, которые используются для повторной рассылки сообщений; они не должны передаваться. Вместо этого используйте других получателей для передачи сведений о получателях. Цель этого механизма — разрешить получателям повторно отправлять ту же таблицу получателей, что и исходные получатели.
Во время вызова SubmitMessage диспетчер очереди MAPI обрабатывает методы для объектов, открытых во время передачи сообщения, и обрабатывает все вложения. Эта обработка может занять много времени. Поставщики транспорта могут часто вызывать метод IMAPISupport::SpoolerYield для диспетчера очереди MAPI во время этой обработки, чтобы освободить время ЦП для других системных задач.
Все получатели сообщения отображаются в таблице получателей сообщения, которое первоначально было передано диспетчером очереди MAPI. Поставщик транспорта должен обрабатывать только тех получателей, которые он может обрабатывать (на основе идентификатора записи, типа адреса или и того, и другого), и для которых еще не задано свойство PR_RESPONSIBILITY (PidTagResponsibility) значение TRUE. Если PR_RESPONSIBILITY уже задано значение TRUE, другой поставщик транспорта обработал этого получателя. Когда поставщик завершает достаточную обработку получателя, чтобы определить, может ли он обрабатывать сообщения для этого получателя, он должен задать свойству PR_RESPONSIBILITY этого получателя значение TRUE в переданном сообщении. Как правило, поставщик принимает это решение после завершения доставки сообщений.
Как правило, поставщик транспорта не возвращается из вызова SubmitMessage , пока не завершит передачу данных сообщения. Если ошибка не возвращается, следующим вызовом из диспетчера очереди MAPI к поставщику является вызов метода IXPLogon::EndMessage .
Если SubmitMessage возвращает ошибку, диспетчер очереди MAPI освобождает сообщение в процессе без сохранения изменений. Если поставщик транспорта требует сохранения изменений сообщения, он должен вызвать метод IMAPIProp::SaveChanges для сообщения перед возвратом.
В случае ошибок, возникающих из-за проблем с транспортировкой, диспетчер очереди MAPI сохраняет сообщение, но задерживает повторную отправку сообщения поставщику транспорта на основе значения, возвращенного в lpulReturnParm. Поставщик транспорта должен заполнить это значение, если его возвращаемое значение из SubmitMessage MAPI_E_WAIT или MAPI_E_NETWORK_ERROR. При возникновении серьезной ошибки поставщик транспорта должен вызвать метод IMAPISupport::SpoolerNotify с флагом NOTIFY_CRITICAL_ERROR.