IMAPIProp::SaveChanges

Hace referencia a: Outlook 2013 | Outlook 2016

Realiza cambios permanentes en un objeto desde la última operación de guardado.

HRESULT SaveChanges(
  ULONG ulFlags
);

Parameters

ulFlags

[in] Máscara de bits de marcas que controla lo que ocurre con el objeto cuando se llama al método IMAPIProp::SaveChanges . Se pueden establecer las siguientes marcas:

NON_EMS_XP_SAVE

Indica que el mensaje no se ha entregado desde un Microsoft Exchange Server. Esta marca debe usarse en combinación con el método IMAPIFolder::CreateMessage y la marca ITEMPROC_FORCE para indicar a un almacén PST que el mensaje es apto para el procesamiento de reglas antes de que el almacén de archivos de carpetas personales (PST) notifique a cualquier cliente de escucha que el mensaje ha llegado. Este procesamiento de reglas solo se aplica a los mensajes nuevos que se crean con IMAPIFolder::CreateMessage en un servidor que no es un Exchange Server, en cuyo caso el Exchange Server ya habría procesado reglas en el mensaje.

FORCE_SAVE

Los cambios se deben escribir en el objeto, reemplazando los cambios anteriores realizados en el objeto y el objeto debe cerrarse. El permiso de lectura y escritura debe establecerse para que la operación se realice correctamente. La marca de FORCE_SAVE se usa después de que una llamada anterior a SaveChanges devolvió MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

Los cambios deben confirmarse y el objeto debe mantenerse abierto para su lectura. No se realizarán cambios adicionales.

KEEP_OPEN_READWRITE

Los cambios deben confirmarse y el objeto debe mantenerse abierto para el permiso de lectura y escritura. Esta marca se establece normalmente cuando el objeto se abrió por primera vez para el permiso de lectura y escritura. Se permiten los cambios posteriores en el objeto.

MAPI_DEFERRED_ERRORS

Permite que SaveChanges se devuelva correctamente, posiblemente antes de que los cambios se hayan confirmado completamente.

SPAMFILTER_ONSAVE

Habilita el filtrado de correo no deseado en un mensaje que se está guardando. El soporte de filtrado de spam solo está disponible si el tipo de dirección de correo electrónico del remitente es Protocolo simple de transferencia de correo (SMTP) y el mensaje se está guardando en un almacén de un archivo de carpetas personales (PST).

Valor devuelto

S_OK

El compromiso de los cambios se realizó correctamente.

MAPI_E_NO_ACCESS

SaveChanges no puede mantener abierto el objeto para el permiso de solo lectura si se establece KEEP_OPEN_READONLY o el permiso de lectura y escritura si se establece KEEP_OPEN_READWRITE. No se confirma ningún cambio.

MAPI_E_OBJECT_CHANGED

El objeto ha cambiado desde que se abrió.

MAPI_E_OBJECT_DELETED

El objeto se ha eliminado desde que se abrió.

Comentarios

El método IMAPIProp::SaveChanges hace que los cambios de propiedad sean permanentes para los objetos que admiten el modelo de transacción de procesamiento, como mensajes, datos adjuntos, contenedores de libreta de direcciones y objetos de usuario de mensajería. Los objetos que no admiten transacciones, como carpetas, almacenes de mensajes y secciones de perfil, realizan cambios de forma permanente inmediatamente. No se requiere ninguna llamada a SaveChanges .

Dado que los proveedores de servicios no tienen que generar un identificador de entrada para sus objetos hasta que se hayan guardado todas las propiedades, es posible que la propiedad PR_ENTRYID (PidTagEntryId) de un objeto no esté disponible hasta que se haya llamado al método SaveChanges . Algunos proveedores esperan hasta que se establezca la marca de KEEP_OPEN_READONLY en la llamada a SaveChanges . KEEP_OPEN_READONLY indica que los cambios que se guardarán en la llamada actual serán los últimos cambios que se realizarán en el objeto.

Algunas implementaciones del almacén de mensajes no muestran los mensajes recién creados en una carpeta hasta que un cliente guarda los cambios del mensaje mediante SaveChanges y libera los objetos de mensaje mediante el método IUnknown::Release . Además, algunas implementaciones de objetos no pueden generar una propiedad PR_ENTRYID para un objeto recién creado hasta que se haya llamado a SaveChanges , y algunas solo pueden hacerlo después de llamar a SaveChanges mediante KEEP_OPEN_READONLY establecido en ulFlags.

Notas a los implementadores

Si recibe la marca de KEEP_OPEN_READONLY, tiene la opción de dejar el acceso del objeto como de lectura y escritura. Sin embargo, un proveedor nunca puede dejar un objeto en un estado de solo lectura cuando se pasa la marca de KEEP_OPEN_READWRITE.

Cuando un cliente guarda varios datos adjuntos en varios mensajes, llama al método SaveChanges para cada dato adjunto y cada mensaje. A menudo, los clientes establecerán MAPI_DEFERRED_ERRORS para cada una de estas llamadas, excepto para la última. Puede devolver errores con la última llamada o con llamadas anteriores. Incluso puede omitir la marca.

Si KEEP_OPEN_READWRITE o KEEP_OPEN_READONLY se establecen junto con MAPI_DEFERRED_ERRORS, puede omitir la solicitud de aplazamiento de errores. Si MAPI_DEFERRED_ERRORS no se establece en ulFlags, se puede devolver uno de los errores aplazados anteriormente para la llamada a SaveChanges .

Si un proveedor de transporte remoto proporciona una implementación funcional de este método es opcional y depende de otras opciones de diseño en la implementación. Si implementa este método, hágalo de acuerdo con la documentación que se encuentra aquí. Dado que los objetos de carpeta y los objetos de estado no se realizan transacciones, como mínimo, la implementación de SaveChanges de un proveedor de transporte remoto debe devolver S_OK sin realizar realmente ningún trabajo.

Notas para los llamadores

Si un cliente pasa KEEP_OPEN_READONLY, llama al método IMAPIProp::SetProps y, a continuación, llama a SaveChanges de nuevo, es posible que se produzca un error en la misma implementación.

Después de recibir MAPI_E_NO_ACCESS de una llamada en la que establezca KEEP_OPEN_READWRITE, seguirá teniendo permiso de lectura y escritura para el objeto. Puede volver a llamar a SaveChanges , pasando la marca KEEP_OPEN_READONLY o ninguna marca con KEEP_OPEN_SUFFIX.

Si un proveedor admite la marca de KEEP_OPEN_READWRITE depende de la implementación del proveedor.

Para indicar que la única llamada que se va a realizar en el objeto después de SaveChanges es IUnknown::Release, no establezca ninguna marca para el parámetro ulFlags . Un error de SaveChanges indica que no pudo hacer que los cambios pendientes fueran permanentes. Los distintos proveedores controlan la ausencia de marcas en la llamada a SaveChanges de forma diferente. Algunos proveedores tratan este estado igual que KEEP_OPEN_READONLY; otros proveedores lo interpretan igual que KEEP_OPEN_READWRITE. Todavía otros proveedores apagan el objeto cuando no reciben marcas en la llamada a SaveChanges .

Algunas propiedades, normalmente propiedades calculadas, no se pueden procesar hasta que se llama a SaveChanges y, en algunos casos, a Release.

Al realizar cambios masivos, como guardar datos adjuntos en varios mensajes, aplaza el procesamiento de errores estableciendo la marca de MAPI_DEFERRED_ERRORS en ulFlags. Si guarda varios datos adjuntos en varios mensajes, realice una llamada a SaveChanges a cada dato adjunto y una llamada a SaveChanges a cada mensaje. Establezca la marca de MAPI_DEFERRED_ERRORS para cada llamada de datos adjuntos y para todos los mensajes excepto para la última.

Si SaveChanges devuelve MAPI_E_OBJECT_CHANGED, compruebe si se ha modificado el objeto original. Si es así, advierta al usuario, que puede solicitar que los cambios sobrescriban los cambios anteriores o guarde el objeto en otro lugar. Si se ha eliminado el objeto original, advierta al usuario que le dé la oportunidad de guardar el objeto en otra ubicación.

No se puede llamar a SaveChanges con la marca FORCE_SAVE en un objeto abierto que se ha eliminado.

Si SaveChanges devuelve un error, el objeto cuyos cambios se guardarían permanece abierto, independientemente de las marcas establecidas en el parámetro ulFlags .

Importante

Es posible que los NON_EMS_XP_SAVE y SPAMFILTER_ONSAVE ulFlags no se definan en el archivo de encabezado descargable que tiene actualmente, en cuyo caso puede agregarlo al código mediante los siguientes valores: #define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

Para obtener más información, vea Guardar propiedades MAPI.

Vea también

IMAPIProp::SetProps
Propiedad canónica PidTagEntryId
IMAPIProp: IUnknownGuardar propiedades MAPI