IXPLogon::SubmitMessage
Hace referencia a: Outlook 2013 | Outlook 2016
Indica que la cola MAPI tiene un mensaje para que el proveedor de transporte lo entregue.
HRESULT SubmitMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
);
Parameters
ulFlags
[in] Máscara de bits de marcas que controla cómo se envía el mensaje. Se puede establecer la marca siguiente:
BEGIN_DEFERRED
La cola MAPI llama a un proveedor de transporte con un mensaje que se aplazó anteriormente. El identificador de entrada del mensaje es el mismo que cuando se aplazó. El mensaje se aplazó pasando su identificador de entrada a la cola MAPI mediante el método IMAPISupport::SpoolerNotify con la marca NOTIFY_SENTDEFERRED.
lpMessage
[in] Puntero a un objeto de mensaje (que representa el mensaje que se va a entregar) que tiene permiso de lectura y escritura, que el proveedor de transporte usa para acceder a ese mensaje y manipularlo. Este objeto permanece válido hasta que el proveedor de transporte vuelve de una llamada posterior al método IXPLogon::EndMessage .
lpulMsgRef
[out] Puntero a una variable en la que el proveedor de transporte devuelve el valor de referencia que asignó a este mensaje. La cola MAPI pasa este valor de referencia en llamadas posteriores para este mensaje. La cola MAPI inicializa el valor en 0 antes de devolverlo al proveedor de transporte.
lpulReturnParm
[out] Puntero a una variable que corresponde al valor de error MAPI_E_WAIT o MAPI_E_NETWORK_ERROR devuelto por SubmitMessage.
Valor devuelto
S_OK
La llamada se realizó correctamente y devolvió el valor o los valores esperados.
MAPI_E_BUSY
El proveedor de transporte no puede controlar el mensaje, porque está realizando otra operación. Un proveedor debe usar este valor devuelto para indicar que no se produjo ningún procesamiento y que la cola MAPI no debe llamar a EndMessage. La cola MAPI volverá a intentar la llamada SubmitMessage más adelante.
MAPI_E_CANCEL
Aunque el proveedor de transporte solicitó que la cola MAPI vuelva a enviar el mensaje en una llamada SpoolerNotify anterior, las condiciones han cambiado desde entonces y el mensaje no debe ser resenviado. La cola MAPI continuará para controlar otra cosa.
MAPI_E_NETWORK_ERROR
Un error de red impidió la finalización correcta de la operación. El parámetro lpulReturnParm debe establecerse en el número de segundos que transcurren antes de que la cola MAPI vuelva a enviar el mensaje.
MAPI_E_NOT_ME
El proveedor de transporte no puede controlar este mensaje. La cola MAPI debe intentar buscar otro proveedor de transporte para él. Un proveedor debe usar este valor devuelto para indicar que no se produjo ningún procesamiento y que la cola MAPI no debe llamar a EndMessage.
MAPI_E_WAIT
Un problema temporal impide que el proveedor de transporte controle el mensaje. El parámetro lpulReturnParm debe establecerse en el número de segundos que transcurren antes de que la cola MAPI vuelva a enviar el mensaje.
Comentarios
La cola MAPI llama al método IXPLogon::SubmitMessage cuando tiene un mensaje para que el proveedor de transporte lo entregue. El mensaje se pasa al proveedor de transporte mediante el parámetro lpMessage .
Si el proveedor está listo para aceptar el mensaje, debe devolver un valor de referencia mediante el parámetro lpulMsgRef , procesar el objeto pasado y devolver el valor adecuado (normalmente S_OK). Si el proveedor no está preparado para controlar la transferencia, debe devolver un valor de error y, opcionalmente, otro valor devuelto MAPI en lpulReturnParm para indicar cuánto tiempo debe esperar la cola MAPI antes de volver a enviar el mensaje.
La implementación de este método por parte de un proveedor de transporte puede hacer lo siguiente:
Coloque el mensaje en una cola interna para esperar la transmisión, posiblemente copiando el mensaje en el almacenamiento local y devolverlo.
Intente realizar la transmisión real y volver cuando se complete la transmisión, ya sea correctamente o sin éxito.
Determine si desea enviar el mensaje después de comprobar el recurso implicado. En este caso, si el recurso está libre, el proveedor puede bloquear el recurso, preparar el mensaje y enviarlo. Si el recurso está ocupado, el proveedor puede preparar el mensaje y aplazar el envío a una hora posterior.
La técnica preferida para la transmisión de mensajes depende del proveedor de transporte y del número esperado de procesos que compiten por los recursos del sistema.
Durante una llamada SubmitMessage , el proveedor de transporte controla la transferencia de datos de mensajes desde el objeto de mensaje. Sin embargo, el proveedor de transporte debe asignar un valor de referencia al mensaje, al que devuelve un puntero en lpulMsgRef, antes de transferir datos. Lo hace porque, en cualquier momento del proceso, la cola MAPI puede llamar al método IXPLogon::TransportNotify con la marca NOTIFY_CANCEL_MESSAGE establecida para indicar al proveedor que debe liberar los objetos abiertos y detener la transferencia de mensajes.
El proveedor de transporte no debe enviar ninguna propiedad no transmitible del mensaje. Cuando encuentra una propiedad de este tipo, debe continuar para procesar la siguiente propiedad. El proveedor debe hacer todo lo posible para no mostrar MAPI_P1 información del destinatario como parte del contenido del mensaje transmitido; el proveedor debe usar esta información de destinatario solo con fines de direccionamiento. MAPI_P1 destinatarios son destinatarios generados internamente que se usan para volver a enviar mensajes; no deben transmitirse. En su lugar, use los demás destinatarios para transmitir información del destinatario. El propósito de este acuerdo es permitir que los destinatarios reenviados vean exactamente la misma tabla de destinatarios que los destinatarios originales.
Durante una llamada SubmitMessage , la cola MAPI procesa los métodos de los objetos que se abren durante la transferencia del mensaje y procesa los datos adjuntos. Este procesamiento puede tardar mucho tiempo. Los proveedores de transporte pueden llamar al método IMAPISupport::SpoolerYield para la cola MAPI con frecuencia durante este procesamiento para liberar el tiempo de CPU para otras tareas del sistema.
Todos los destinatarios del mensaje están visibles en la tabla de destinatarios del mensaje que la cola MAPI pasó originalmente. El proveedor de transporte solo debe procesar los destinatarios que puede controlar, en función del identificador de entrada, el tipo de dirección o ambos, y que aún no tienen su propiedad PR_RESPONSIBILITY (PidTagResponsibility) establecida en TRUE. Si PR_RESPONSIBILITY ya está establecido en TRUE, otro proveedor de transporte ha controlado ese destinatario. Cuando el proveedor completa el procesamiento suficiente de un destinatario para determinar si puede controlar los mensajes de ese destinatario, debe establecer la propiedad PR_RESPONSIBILITY del destinatario en TRUE en el mensaje pasado. Normalmente, el proveedor toma esta determinación una vez completada la entrega del mensaje.
Normalmente, el proveedor de transporte no devuelve desde una llamada SubmitMessage hasta que completa la transferencia de datos del mensaje. Si no se devuelve ningún error, la siguiente llamada desde la cola MAPI al proveedor es una llamada al método IXPLogon::EndMessage .
Si SubmitMessage devuelve un error, la cola MAPI libera el mensaje en proceso sin guardar los cambios. Si el proveedor de transporte requiere que se guarden los cambios de mensaje, debe llamar al método IMAPIProp::SaveChanges en el mensaje antes de devolverlo.
En caso de errores que se produzcan debido a problemas de transporte, la cola MAPI conserva el mensaje, pero retrasa la devolución del mensaje al proveedor de transporte en función del valor devuelto en lpulReturnParm. El proveedor de transporte debe rellenar ese valor si su valor devuelto de SubmitMessage es MAPI_E_WAIT o MAPI_E_NETWORK_ERROR. Si se produce una condición de error grave, el proveedor de transporte debe llamar al método IMAPISupport::SpoolerNotify con la marca NOTIFY_CRITICAL_ERROR.