IMAPIProp::SaveChangesIMAPIProp::SaveChanges

適用対象: Outlook 2013 | Outlook 2016Applies to: Outlook 2013 | Outlook 2016

前回の保存操作以降にオブジェクトに加えられたすべての変更を永続的に行います。Makes permanent any changes that were made to an object since the last save operation.

HRESULT SaveChanges(
  ULONG ulFlags
);

パラメーターParameters

ulFlagsulFlags

順番imapiprop:: SaveChangesメソッドが呼び出されたときに、オブジェクトに対して行われる処理を制御するフラグのビットマスク。[in] A bitmask of flags that controls what happens to the object when the IMAPIProp::SaveChanges method is called. 次のフラグを設定できます。The following flags can be set:

NON_EMS_XP_SAVENON_EMS_XP_SAVE

メッセージが Microsoft Exchange サーバーから配信されていないことを示します。Indicates that the message has not been delivered from a Microsoft Exchange Server. このフラグをimapifolder:: CreateMessageメソッドおよび ITEMPROC_FORCE フラグと組み合わせて使用して、個人用フォルダーファイル (pst) ストアが通知する前に、ルール処理の対象となるメッセージを pst ストアに示すように指定します。受信したクライアントメッセージが到着したこと。This flag should be used in combination with the IMAPIFolder::CreateMessage method and the ITEMPROC_FORCE flag to indicate to a PST store that the message is eligible for rules processing before the Personal Folders file (PST) store notifies any listening client that the message has arrived. このルールの処理は、exchange サーバー以外のサーバー上でimapifolder:: CreateMessageを使用して作成された新しいメッセージにのみ適用されます。この場合、exchange サーバーはメッセージに対して既にルールを処理しています。This rules processing only applies to new messages that are created with IMAPIFolder::CreateMessage on a server that is not an Exchange Server, in which case the Exchange Server would have already processed rules on the message.

FORCE_SAVEFORCE_SAVE

オブジェクトに変更を加えて、オブジェクトに対する以前の変更を上書きし、オブジェクトを閉じる必要があります。Changes should be written to the object, overriding any previous changes that were made to the object, and the object should be closed. 操作を正常に行うには、読み取り/書き込みアクセス許可が設定されている必要があります。Read/write permission must be set for the operation to succeed. FORCE_SAVE フラグは、以前にSaveChangesが MAPI_E_OBJECT_CHANGED を呼び出した後に使用されます。The FORCE_SAVE flag is used after a previous call to SaveChanges returned MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLYKEEP_OPEN_READONLY

変更を確定して、オブジェクトを読み取り用に開いたままにしておく必要があります。Changes should be committed and the object should be kept open for reading. 追加の変更は行われません。No additional changes will be made.

KEEP_OPEN_READWRITEKEEP_OPEN_READWRITE

変更をコミットし、オブジェクトを読み取り/書き込みアクセス許可のために開いたままにしておく必要があります。Changes should be committed and the object should be kept open for read/write permission. 通常、このフラグは、オブジェクトが読み取り/書き込みアクセス許可で最初に開かれたときに設定されます。This flag is usually set when the object was first opened for read/write permission. その後、オブジェクトに対する変更を行うことができます。Subsequent changes to the object are allowed.

MAPI_DEFERRED_ERRORSMAPI_DEFERRED_ERRORS

変更が完全にコミットされる前に、 SaveChangesが正常に戻ることができるようにします。Allows SaveChanges to return successfully, possibly before the changes have been fully committed.

SPAMFILTER_ONSAVESPAMFILTER_ONSAVE

保存されているメッセージに対してスパムフィルター処理を有効にします。Enables spam filtering on a message that is being saved. スパムのフィルター処理に関するサポートは、送信者の電子メール アドレスの種類が簡易メール転送プロトコル (SMTP) であり、メッセージが個人用フォルダー ファイル (PST) 向けのストアに保存されている場合にのみ使用することができます。Spam filtering support is available only if the sender's email address type is Simple Mail Transfer Protocol (SMTP), and the message is being saved to a store for a Personal Folders file (PST).

戻り値Return value

S_OKS_OK

変更のコミットメントに成功しました。The commitment of changes was successful.

MAPI_E_NO_ACCESSMAPI_E_NO_ACCESS

KEEP_OPEN_READONLY が設定されている場合は読み取り専用アクセス許可、KEEP_OPEN_READWRITE が設定されている場合は読み取り/書き込みアクセス許可の場合、 SaveChangesではオブジェクトを開いたままにすることはできません。SaveChanges cannot keep the object open for read-only permission if KEEP_OPEN_READONLY is set, or read/write permission if KEEP_OPEN_READWRITE is set. 変更はコミットされません。No changes are committed.

MAPI_E_OBJECT_CHANGEDMAPI_E_OBJECT_CHANGED

オブジェクトが開かれた後に変更されました。The object has changed since it was opened.

MAPI_E_OBJECT_DELETEDMAPI_E_OBJECT_DELETED

オブジェクトが開かれた後に削除されています。The object has been deleted since it was opened.

解説Remarks

imapiprop:: SaveChangesメソッドを使用すると、メッセージ、添付ファイル、アドレス帳コンテナー、メッセージングユーザーオブジェクトなど、処理のトランザクションモデルをサポートするオブジェクトのプロパティの変更を永続的に行うことができます。The IMAPIProp::SaveChanges method makes property changes permanent for objects that support 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. SaveChangesを呼び出す必要はありません。No call to SaveChanges is required.

すべてのプロパティが保存されるまでは、サービスプロバイダーはオブジェクトのエントリ識別子を生成する必要がないため、 SaveChangesメソッドの後までオブジェクトのPR_ENTRYID (PidTagEntryId) プロパティを使用できない場合があります。が呼び出されました。Because service providers do not have to generate an entry identifier for their objects until all properties have been saved, an object's PR_ENTRYID (PidTagEntryId) property might not be available until after its SaveChanges method has been called. 一部のプロバイダーは、 SaveChanges呼び出しで KEEP_OPEN_READONLY フラグが設定されるまで待機します。Some providers wait until the KEEP_OPEN_READONLY flag is set on the SaveChanges call. KEEP_OPEN_READONLY は、現在の呼び出しに保存される変更が、オブジェクトに対して最後に行われた変更であることを示します。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.

メッセージストアの実装によっては、クライアントがSaveChangesを使用してメッセージの変更を保存し、 IUnknown:: Releaseメソッドを使用してメッセージオブジェクトを解放するまで、新しく作成されたメッセージがフォルダーに表示されないことがあります。Some message store implementations do not show newly created messages in a folder until a client saves the message changes by using SaveChanges and releases the message objects by using the IUnknown::Release method. また、一部のオブジェクト実装では、 savechangesが呼び出されるまで、新しく作成されたオブジェクトのPR_ENTRYIDプロパティを生成できません。また、KEEP_OPEN_READONLY を使用してsavechangesが呼び出された後にのみ実行できるものもあります。_ulflags_で設定します。In addition, some object implementations cannot generate a PR_ENTRYID property for a newly created object until after SaveChanges has been called, and some can do so only after SaveChanges has been called by using KEEP_OPEN_READONLY set in ulFlags.

実装に関するメモNotes to implementers

KEEP_OPEN_READONLY フラグを受信した場合は、オブジェクトのアクセスを読み取り/書き込み可能にするオプションがあります。If you receive the KEEP_OPEN_READONLY flag, you have the option of leaving the object's access as read/write. ただし、KEEP_OPEN_READWRITE フラグが渡された場合、プロバイダーはオブジェクトを読み取り専用状態にしておくことはできません。However, a provider can never leave an object in a read-only state when the KEEP_OPEN_READWRITE flag is passed.

クライアントが複数のメッセージに複数の添付ファイルを保存すると、すべての添付ファイルとすべてのメッセージに対してSaveChangesメソッドが呼び出されます。When a client saves multiple attachments to multiple messages, it calls the SaveChanges method for every attachment and every message. 多くの場合、クライアントは、これらの呼び出しごとに MAPI_DEFERRED_ERRORS を設定します (最後の呼び出しを除く)。Often clients will set MAPI_DEFERRED_ERRORS for each of these calls except for the last one. 前回の通話または以前の呼び出しでエラーを返すことができます。You can return errors either with the last call or earlier calls. フラグは無視してもかまいません。You can even ignore the flag.

KEEP_OPEN_READWRITE または KEEP_OPEN_READONLY のどちらかが MAPI_DEFERRED_ERRORS と共に設定されている場合は、エラー繰延要求を無視できます。If either KEEP_OPEN_READWRITE or KEEP_OPEN_READONLY is set together with MAPI_DEFERRED_ERRORS, you can ignore the error deferment request. _ulflags_に MAPI_DEFERRED_ERRORS が設定されていない場合は、以前に遅延したエラーの1つをSaveChanges呼び出しに対して返すことができます。If MAPI_DEFERRED_ERRORS is not set in ulFlags, one of the previously deferred errors can be returned for the SaveChanges call.

リモートトランスポートプロバイダーがこのメソッドの機能実装を提供するかどうかはオプションであり、実装での他の設計上の選択によって異なります。Whether a remote transport provider provides a functional implementation of this method is optional and depends on other design choices in your implementation. このメソッドを実装する場合は、ここに記載されているドキュメントに従ってください。If you implement this method, do so according to the documentation here. folder オブジェクトと status オブジェクトは処理されないため、少なくともリモートトランスポートプロバイダーのSaveChangesの実装は、実際には何も作業を行わずに S_OK を返す必要があります。Because folder objects and status objects are not transacted, at a minimum a remote transport provider's implementation of SaveChanges must return S_OK without actually doing any work.

呼び出し側への注意Notes to callers

クライアントが KEEP_OPEN_READONLY に合格した場合は、 imapiprop:: setpropsメソッドを呼び出してから、再度SaveChangesを呼び出すと、同じ実装が失敗する可能性があります。If a client passes KEEP_OPEN_READONLY, calls the IMAPIProp::SetProps method, and then calls SaveChanges again, the same implementation might fail.

KEEP_OPEN_READWRITE を設定した呼び出しから MAPI_E_NO_ACCESS を受信した後、そのオブジェクトに対する読み取り/書き込みアクセス許可が引き続き付与されます。After receiving MAPI_E_NO_ACCESS from a call in which you set KEEP_OPEN_READWRITE, you will continue to have read/write permission to the object. 再度、 SaveChangesを呼び出すことができます。 KEEP_OPEN_READONLY フラグを渡すか、KEEP_OPEN_SUFFIX を使用してフラグを設定する必要はありません。You can call SaveChanges again, passing either the KEEP_OPEN_READONLY flag or no flags with KEEP_OPEN_SUFFIX.

プロバイダーが KEEP_OPEN_READWRITE フラグをサポートしているかどうかは、プロバイダーの実装によって異なります。Whether a provider supports the KEEP_OPEN_READWRITE flag depends on the provider's implementation.

SaveChangesIUnknown:: Releaseの後にのみオブジェクトで行われる呼び出しを示すには、 _ulflags_パラメーターにフラグを設定しません。To indicate that the only call to be made on the object after SaveChanges is IUnknown::Release, set no flags for the ulFlags parameter. SaveChangesからのエラーは、保留中の変更を永続的にできないことを示します。An error from SaveChanges indicates that it could not make the pending changes permanent. さまざまなプロバイダーが、 SaveChanges呼び出しでのフラグの欠落を異なる方法で処理します。Different providers handle the absence of flags on the SaveChanges call differently. プロバイダーによっては、この状態を KEEP_OPEN_READONLY と同じものとして扱います。他のプロバイダーは、KEEP_OPEN_READWRITE と同じように解釈します。Some providers treat this state the same as KEEP_OPEN_READONLY; other providers interpret it the same as KEEP_OPEN_READWRITE. その他のプロバイダーは、 SaveChanges呼び出しでフラグを受信しない場合、そのオブジェクトをシャットダウンします。Still other providers shut down the object when they do not receive flags on the SaveChanges call.

一部のプロパティ (通常は計算プロパティ) は、 SaveChangesを呼び出し、場合によっては解放されるまで処理できません。Some properties, typically computed properties, cannot be processed until you call SaveChanges and, in some cases, Release.

添付ファイルを複数のメッセージに保存するなどの一括変更を行う場合は、 _ulflags_で MAPI_DEFERRED_ERRORS フラグを設定することにより、エラー処理を延期します。When you make bulk changes, such as saving attachments to multiple messages, defer error processing by setting the MAPI_DEFERRED_ERRORS flag in ulFlags. 複数の添付ファイルを複数のメッセージに保存する場合は、各添付ファイルにsavechanges呼び出しを1つずつ、各メッセージにsavechanges呼び出しを1つ行います。If you save multiple attachments to multiple messages, make one SaveChanges call to each attachment and one SaveChanges call to each message. 添付ファイルの各呼び出しに対して MAPI_DEFERRED_ERRORS フラグを設定し、最後のメッセージ以外のすべてのメッセージに対して設定します。Set the MAPI_DEFERRED_ERRORS flag for each attachment call and for all messages except for the last one.

SaveChangesが MAPI_E_OBJECT_CHANGED を返す場合は、元のオブジェクトが変更されていないかどうかを確認します。If SaveChanges returns MAPI_E_OBJECT_CHANGED, check whether 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 elsewhere. 元のオブジェクトが削除されている場合は、オブジェクトを別の場所に保存する機会をユーザーに提供するようにユーザーに警告します。If the original object has been deleted, warn the user to give them the opportunity to save the object in another location.

開いているオブジェクトが削除されている場合、FORCE_SAVE フラグを使用してSaveChangesを呼び出すことはできません。You cannot call SaveChanges with the FORCE_SAVE flag on an open object that has been deleted.

SaveChangesがエラーを返す場合、 _ulflags_パラメーターに設定されているフラグに関係なく、変更を保存しようとしたオブジェクトは開いたままになります。If SaveChanges returns an error, the object whose changes were to be saved remains open, regardless of the flags set in the ulFlags parameter.

重要

ulflags NON_EMS_XP_SAVE および SPAMFILTER_ONSAVE は、現在のダウンロード可能なヘッダーファイルでは定義されていない場合があります。その場合は、次の値を使用してコードに追加できます。 >#define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)> #define NON_EMS_XP_SAVE ((ULONG) 0x00001000)The ulFlags NON_EMS_XP_SAVE and SPAMFILTER_ONSAVE might not be defined in the downloadable header file you currently have, in which case you can add it to your code using the following values: > #define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)> #define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

詳細については、「 MAPI プロパティの保存」を参照してください。For more information, see Saving MAPI Properties.

関連項目See also

IMAPIProp::SetPropsIMAPIProp::SetProps

PidTagEntryId 標準プロパティPidTagEntryId Canonical Property

IMAPIProp : IUnknownIMAPIProp : IUnknown

MAPI プロパティの保存Saving MAPI Properties