Función de devolución de llamada MAPISAVEMAIL (mapi.h)

Artículo
03/09/2023

[No se recomienda el uso de esta función. Puede modificarse o no estar disponible en versiones posteriores de Windows.

La función MAPISaveMail guarda un mensaje en el almacén de mensajes.

Sintaxis

MAPISAVEMAIL Mapisavemail;

ULONG Mapisavemail(
  [in] LHANDLE lhSession,
  [in] ULONG_PTR ulUIParam,
  [in] lpMapiMessage lpMessage,
  [in] FLAGS flFlags,
       ULONG ulReserved,
  [in] LPSTR lpszMessageID
)
{...}

Parámetros

[in] lhSession

Identificador de una sesión MAPI simple o cero. El valor del parámetro lhSession no debe ser cero si el parámetro lpszMessageID contiene un identificador de mensaje válido. Sin embargo, si lpszMessageID no contiene un identificador de mensaje válido y el valor de lhSession es cero, MAPI inicia sesión en el usuario y crea una sesión que solo existe durante la llamada. Esta sesión temporal puede ser una sesión compartida existente o una nueva. Si es necesario, se muestra el cuadro de diálogo de inicio de sesión.

[in] ulUIParam

Identificador de ventana principal o cero, que indica que si se muestra un cuadro de diálogo, es modal de la aplicación. Si el parámetro ulUIParam contiene un identificador de ventana primario, es de tipo HWND (convertido a un ULONG_PTR). Si no se muestra ningún cuadro de diálogo durante la llamada, se omite ulUIParam .

[in] lpMessage

Parámetro de entrada que apunta a una estructura MapiMessage que contiene el contenido del mensaje que se va a guardar. Se omite el miembro lpOriginator . Las aplicaciones pueden omitir el miembro flFlags o, si el mensaje nunca se ha guardado, pueden establecer las marcas MAPI_SENT y MAPI_UNREAD.

[in] flFlags

Máscara de bits de marcas de opción. Se pueden establecer las marcas siguientes.

Valor	Significado
MAPI_LOGON_UI	Se debe mostrar un cuadro de diálogo para pedir al usuario que inicie sesión si es necesario. Cuando no se establece la marca MAPI_LOGON_UI, la aplicación cliente no muestra un cuadro de diálogo de inicio de sesión y devuelve un valor de error si el usuario no ha iniciado sesión. MAPISaveMail omite esta marca si el parámetro lpszMessageID está vacío.
MAPI_LONG_MSGID	Se espera que el identificador del mensaje devuelto tenga 512 caracteres. Si se establece esta marca, el parámetro lpszMessageID debe ser lo suficientemente grande como para dar cabida a 512 caracteres.
MAPI_NEW_SESSION	Se debe intentar crear una nueva sesión en lugar de adquirir la sesión compartida del entorno. Si no se establece la marca MAPI_NEW_SESSION, MAPISaveMail usa una sesión compartida existente.

ulReserved

Reservados; debe ser cero.

[in] lpszMessageID

Puntero al identificador de mensaje que se va a reemplazar por la operación de guardado o una cadena vacía, lo que indica que se va a crear un nuevo mensaje. El autor de la llamada debe asignar la cadena y debe contener al menos 512 caracteres si el parámetro flFlags está establecido en MAPI_LONG_MSGID. Si el parámetro flFlags no está establecido en MAPI_LONG_MSGID, la cadena de identificador de mensaje puede contener 64 caracteres.

Valor devuelto

Esta función devuelve uno de los valores siguientes.

Código devuelto	Descripción
MAPI_E_ATTACHMENT_NOT_FOUND	No se pudo encontrar datos adjuntos en la ruta de acceso especificada. La letra de unidad no era válida, la ruta de acceso no se encontró en esa unidad o el archivo no se encontró en esa ruta de acceso.
MAPI_E_BAD_RECIPTYPE	El tipo de destinatario en lpMessage no era válido.
MAPI_E_FAILURE	Se produjeron uno o varios errores no especificados al guardar el mensaje. No se guardó ningún mensaje.
MAPI_E_INSUFFICIENT_MEMORY	No había memoria suficiente para guardar el mensaje. No se guardó ningún mensaje.
MAPI_E_INVALID_MESSAGE	Se pasó un identificador de mensaje no válido en el parámetro lpszMessageID ; no se guardó ningún mensaje.
MAPI_E_INVALID_RECIPS	Uno o varios destinatarios del mensaje no eran válidos o no se podían identificar.
MAPI_E_INVALID_SESSION	Se pasó un identificador de sesión no válido en el parámetro lhSession . No se guardó ningún mensaje.
MAPI_E_LOGIN_FAILURE	No había ningún inicio de sesión predeterminado y el usuario no pudo iniciar sesión correctamente cuando se mostraba el cuadro de diálogo de inicio de sesión. No se guardó ningún mensaje.
MAPI_E_NOT_SUPPORTED	El sistema de mensajería subyacente no admite la operación.
MAPI_E_USER_ABORT	El usuario canceló uno de los cuadros de diálogo. No se guardó ningún mensaje.
SUCCESS_SUCCESS	La llamada se realizó correctamente y se guardó el mensaje.

Comentarios

La función MAPISaveMail guarda un mensaje, reemplazando opcionalmente un mensaje existente. Antes de llamar a MAPISaveMail, use la función MAPIFindNext para comprobar que el mensaje que se va a guardar es el que desea guardar. Los elementos del mensaje identificado por el parámetro lpszMessageID se reemplazan por los elementos del parámetro lpMessage . Si lpszMessageID está vacío, se crea un nuevo mensaje. Todos los mensajes reemplazados se guardan en sus carpetas adecuadas. Los nuevos mensajes se guardan en la carpeta adecuada para los mensajes entrantes de esa clase.

No todos los sistemas de mensajería admiten el almacenamiento de mensajes. Si el sistema de mensajería subyacente no admite el almacenamiento de mensajes, MAPISaveMail devuelve el valor de MAPI_E_NOT_SUPPORTED.

Dado que los identificadores de mensaje son específicos del sistema y opacos y se pueden invalidar en cualquier momento, MAPISaveMail considera que un identificador de mensaje solo es válido para la sesión simple mapI actual. MAPISaveMail controla identificadores de mensaje no válidos devolviendo el valor de MAPI_E_INVALID_MESSAGE.