IMAPIProp::SaveChanges

The IMAPIProp::SaveChanges method makes permanent any changes made to an object since the last save operation.

Quick Info

See IMAPIProp : IUnknownHP08HX.

HRESULT SaveChanges(

Parameters

ulFlags

[in] Bitmask of flags that controls what happens to the object when the IMAPIProp::SaveChanges method is called.

The following flags can be set:

FORCE_SAVE

Changes should be written to be object, overriding any previous changes made to the object, and the object closed. Read/write access must have been set for the operation to succeed. The FORCE_SAVE flag is used after a previous call to SaveChanges returned MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

Changes should be committed and the object should be kept open for reading. No further changes will be made.

KEEP_OPEN_READWRITE

Changes should be committed and the object should be kept open for read/write access. This flag is usually set when the object was initially opened for read/write access. Subsequent changes to the object are allowed.

MAPI_DEFERRED_ERRORS

Allows SaveChanges to return successfully, possibly before the changes have been fully committed.

Return Values

S_OK

The commitment of changes has been successful.

MAPI_E_NO_ACCESS

SaveChanges cannot keep the object open for read-only access, if KEEP_OPEN_READONLY is set, or read/write access, if KEEP_OPEN_READWRITE is set. No changes are committed.

MAPI_E_OBJECT_CHANGED

The object has changed since it was opened.

MAPI_E_OBJECT_DELETED

The object has been deleted since it was opened.

Remarks

The IMAPIProp::SaveChanges method makes property changes permanent for an object that supports the transaction model of processing, such as messages, attachments, address book containers, and messaging user objects. Objects that do not support transactions, such as folders, message stores, and profile sections, make changes permanent immediately. No call to SaveChanges is required.

Because service providers are not required to generate an entry identifier for their objects until all properties have been saved, an object s PR_ENTRYID2JH9H8T property might not be available until after its SaveChanges method has been called. Some providers wait until the KEEP_OPEN_READONLY flag is set on the SaveChanges call. KEEP_OPEN_READONLY indicates that the changes to be saved in the current call will be the last changes that will be made on the object.

Some message store implementations do not show newly created messages in a folder until a client saves the message changes using SaveChanges and releases the message objects using the IUnknown::Release method. In addition, some object implementations cannot generate a PR_ENTRYID2JH9H8T property for a newly created object until after SaveChanges has been called, and some can only do so after SaveChanges has been called with KEEP_OPEN_READONLY set in ulFlags.

Notes to Implementers

If you receive the KEEP_OPEN_READONLY flag, you have the option of leaving the object s access as read/write.

However, in no case can a provider leave an object in a read-only state when the KEEP_OPEN_READWRITE flag is passed.

When a client is saving multiple attachments to multiple messages, it will be calling the SaveChanges method for every attachment and every message. Often clients will set the MAPI_DEFERRED_ERRORS for each of these calls except for the last one. You can return errors either with the last call or earlier. You can even ignore the flag.

If either KEEP_OPEN_READWRITE or KEEP_OPEN_READONLY is set along with MAPI_DEFERRED_ERRORS, you can ignore the error deferment request. If MAPI_DEFERRED_ERRORS is not set in ulFlags, one of the previously deferred errors can be returned for the SaveChanges call.

Notes to Callers

If a client passes KEEP_OPEN_READONLY, then calls the IMAPIProp::SetPropsXCFLAC method and then SaveChanges again, the same implementation might stop.

After receiving MAPI_E_NO_ACCESS from a call where you set KEEP_OPEN_READWRITE, you will continue to have read/write access to the object. You can call SaveChanges again, passing either the KEEP_OPEN_READONLY flag or no flags with the KEEP_OPEN_suffix.

Whether a provider supports the KEEP_OPEN_READWRITE flag depends on the provider s implementation.

To indicate that the only call to be made on the object after SaveChanges will be IUnknown::Release, set no flags for the ulFlags parameter. An error from SaveChanges indicates that it could not make the pending changes permanent. Different providers handle the absence of flags on the SaveChanges call differently. Some treat this state as the same as KEEP_OPEN_READONLY; others interpret it as the same as KEEP_OPEN_READWRITE. Still other providers shut down the object when they receive no flags on the SaveChanges call.

Some properties, typically computed properties, cannot be processed until you call SaveChanges and, in particular cases, Release.

When making bulk changes, such as saving attachments to multiple messages, defer error processing by setting the MAPI_DEFERRED_ERRORS flag in ulFlags. If you are saving multiple attachments to multiple messages, make one SaveChanges call to each attachment and one SaveChanges call to each message. Set the MAPI_DEFERRED_ERRORS flag for each attachment call and for all messages except for the last one.

If SaveChanges returns MAPI_E_OBJECT_CHANGED, check if the original object has been modified. If so, warn the user, who can either request that the changes overwrite the previous changes or save the object somewhere else. If the original object has been deleted, warn the user so that the user can be given the opportunity to save the object in an alternate location.

You cannot call SaveChanges with the FORCE_SAVE flag on an open object that has been deleted.

If SaveChanges returns an error, then the object whose changes were to be saved remains open, regardless of the flags set in the ulFlags parameter.

For more information, see Saving Properties269A1E5.