Función de devolución de llamada MAPIREADMAIL (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 MAPIReadMail recupera un mensaje para leer.

Sintaxis

MAPIREADMAIL Mapireadmail;

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

Parámetros

[in] lhSession

Identificador de una sesión MAPI simple. El valor del parámetro lhSession debe representar una sesión válida; no puede ser cero.

[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 principal, 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] lpszMessageID

Puntero a una cadena de identificador de mensaje para que el mensaje se lea. El autor de la llamada asigna la cadena.

[in] flFlags

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

Valor	Significado
MAPI_BODY_AS_FILE	MAPIReadMail debe escribir el texto del mensaje en un archivo temporal y agregarlo como primer dato adjunto de la lista de datos adjuntos.
MAPI_ENVELOPE_ONLY	MAPIReadMail solo debe leer el encabezado del mensaje. Los datos adjuntos de archivo no se copian en archivos temporales y no se escriben nombres de archivo temporales ni texto de mensaje. Establecer esta marca mejora el rendimiento.
MAPI_PEEK	MAPIReadMail no marca el mensaje como leído. Marcar un mensaje como leído afecta a su apariencia en la interfaz de usuario y genera un recibo de lectura. Si el sistema de mensajería no admite esta marca, MAPIReadMail siempre marca el mensaje como leído. Si MAPIReadMail encuentra un error, deja el mensaje sin leer.
MAPI_SUPPRESS_ATTACH	MAPIReadMail no debe copiar datos adjuntos de archivo, pero debe escribir texto de mensaje en la estructura MapiMessage . MAPIReadMail omite esta marca si la aplicación que llama ha establecido la marca de MAPI_ENVELOPE_ONLY. Establecer la marca MAPI_SUPPRESS_ATTACH mejora el rendimiento.

ulReserved

Reservados; debe ser cero.

lppMessage

Valor devuelto

Esta función devuelve uno de los valores siguientes.

Código devuelto	Descripción
MAPI_E_ATTACHMENT_WRITE_FAILURE	No se pudieron escribir datos adjuntos en un archivo temporal. Compruebe los permisos de directorio.
MAPI_E_DISK_FULL	No se pudieron escribir datos adjuntos en un archivo temporal porque no había suficiente espacio en el disco.
MAPI_E_FAILURE	Se produjeron uno o varios errores no especificados al leer el mensaje.
MAPI_E_INSUFFICIENT_MEMORY	No había memoria suficiente para leer el mensaje.
MAPI_E_INVALID_MESSAGE	Se pasó un identificador de mensaje no válido en el parámetro lpszMessageID .
MAPI_E_INVALID_SESSION	Se pasó un identificador de sesión no válido en el parámetro lhSession . No se recuperó ningún mensaje.
MAPI_E_TOO_MANY_FILES	Había demasiados archivos adjuntos en el mensaje. No se pudo leer el mensaje.
MAPI_E_TOO_MANY_RECIPIENTS	Había demasiados destinatarios del mensaje. No se pudo leer el mensaje.
SUCCESS_SUCCESS	La llamada se realizó correctamente y se leyó el mensaje.

Comentarios

La función MAPIReadMail devuelve un mensaje, dividiendo el contenido del mensaje en los mismos parámetros y estructuras que se usan en la función MAPISendMail . MAPIReadMail rellena un bloque de memoria con la estructura MapiMessage que contiene elementos de mensaje, como el asunto, la clase de mensaje, el tiempo de entrega y el remitente. Los datos adjuntos de archivo se guardan en archivos temporales y los nombres se devuelven al autor de la llamada en la estructura del mensaje. Los destinatarios, los datos adjuntos y el contenido se copian del mensaje antes de que MAPIReadMail vuelva al autor de la llamada, por lo que los cambios posteriores en los archivos no afectan al contenido del mensaje.

Se proporciona una marca para especificar que solo se devolverá información sobre desde la llamada. Otra marca (en la estructura MapiMessage ) especifica si el mensaje se marca como enviado o sin enviar.

El autor de la llamada es responsable de liberar la estructura MapiMessage llamando a la función MAPIFreeBuffer y eliminando los archivos asociados a los datos adjuntos incluidos en el mensaje.

Antes de llamar a MAPIReadMail, use la función MAPIFindNext para comprobar que el mensaje que se va a leer es el que desea leer. Dado que los identificadores de mensaje son específicos del sistema y opacos y se pueden invalidar en cualquier momento, MAPIReadMail considera que un identificador de mensaje solo es válido para la sesión simple de MAPI actual.