次の方法で共有

IMAPIProp::SaveChanges

  • [アーティクル]

適用対象: Outlook 2013 | Outlook 2016

最後の保存操作以降にオブジェクトに加えられた変更を永続的に行います。

HRESULT SaveChanges(
  ULONG ulFlags
);

パラメーター

ulFlags

[in] IMAPIProp::SaveChanges メソッドが呼び出されたときのオブジェクトの動作を制御するフラグのビットマスク。 次のフラグを設定できます。

NON_EMS_XP_SAVE

メッセージがMicrosoft Exchange Serverから配信されていないことを示します。 このフラグは 、IMAPIFolder::CreateMessage メソッドとITEMPROC_FORCE フラグと組み合わせて使用して、個人用フォルダー ファイル (PST) ストアがメッセージが到着したことをリッスンしているクライアントに通知する前に、メッセージがルール処理の対象であることを PST ストアに示す必要があります。 このルール処理は、Exchange Serverではないサーバーで IMAPIFolder::CreateMessage を使用して作成された新しいメッセージにのみ適用されます。この場合、Exchange Serverはメッセージのルールを既に処理しています。

FORCE_SAVE

変更をオブジェクトに書き込み、オブジェクトに対して行われた以前の変更をオーバーライドし、オブジェクトを閉じる必要があります。 操作を成功させるには、読み取り/書き込みアクセス許可を設定する必要があります。 FORCE_SAVE フラグは、 SaveChanges に対する以前の呼び出しがMAPI_E_OBJECT_CHANGEDを返した後に使用されます。

KEEP_OPEN_READONLY

変更をコミットし、オブジェクトを読み取りのために開いたままにする必要があります。 追加の変更は行われません。

KEEP_OPEN_READWRITE

変更をコミットし、読み取り/書き込みアクセス許可のためにオブジェクトを開いたままにする必要があります。 このフラグは、通常、オブジェクトが読み取り/書き込みアクセス許可のために最初に開かれたときに設定されます。 オブジェクトに対する後続の変更が許可されます。

MAPI_DEFERRED_ERRORS

変更が完全にコミットされる前に、 SaveChanges が正常に返されるようにします。

SPAMFILTER_ONSAVE

保存されているメッセージに対してスパム フィルター処理を有効にします。 スパムのフィルター処理に関するサポートは、送信者の電子メール アドレスの種類が簡易メール転送プロトコル (SMTP) であり、メッセージが個人用フォルダー ファイル (PST) 向けのストアに保存されている場合にのみ使用することができます。

戻り値

S_OK

変更のコミットメントは成功しました。

MAPI_E_NO_ACCESS

saveChanges は、KEEP_OPEN_READONLYが設定されている場合は読み取り専用アクセス許可、KEEP_OPEN_READWRITEが設定されている場合は読み取り/書き込みアクセス許可のためにオブジェクトを開いたままにすることはできません。 変更はコミットされません。

MAPI_E_OBJECT_CHANGED

オブジェクトが開かれた後に変更されました。

MAPI_E_OBJECT_DELETED

オブジェクトは、開かれた後に削除されています。

注釈

IMAPIProp::SaveChanges メソッドは、メッセージ、添付ファイル、アドレス帳コンテナー、メッセージング ユーザー オブジェクトなど、処理のトランザクション モデルをサポートするオブジェクトのプロパティ変更を永続的にします。 フォルダー、メッセージ ストア、プロファイル セクションなど、トランザクションをサポートしていないオブジェクトは、変更を直ちに永続的にします。 SaveChanges の呼び出しは必要ありません。

サービス プロバイダーは、すべてのプロパティが保存されるまでオブジェクトのエントリ識別子を生成する必要がないため、SaveChanges メソッドが呼び出されるまで、オブジェクトのPR_ENTRYID (PidTagEntryId) プロパティを使用できない場合があります。 一部のプロバイダーは、 SaveChanges 呼び出しでKEEP_OPEN_READONLY フラグが設定されるまで待機します。 KEEP_OPEN_READONLYは、現在の呼び出しで保存する変更が、オブジェクトに対して行われる最後の変更であることを示します。

一部のメッセージ ストアの実装では、 クライアントが SaveChanges を使用してメッセージの変更を保存し、 IUnknown::Release メソッドを使用してメッセージ オブジェクトを解放するまで、新しく作成されたメッセージがフォルダーに表示されません。 さらに、一部のオブジェクト実装では、SaveChanges が呼び出されるまで新しく作成されたオブジェクトのPR_ENTRYID プロパティを生成できません。また、一部のオブジェクト実装では、ulFlags で設定されたKEEP_OPEN_READONLYを使用して SaveChanges が呼び出された後にのみ生成できます。

実装に関するメモ

KEEP_OPEN_READONLY フラグを受け取った場合は、オブジェクトのアクセス権を読み取り/書き込みとして残すオプションがあります。 ただし、プロバイダーは、KEEP_OPEN_READWRITE フラグが渡されたときにオブジェクトを読み取り専用の状態のままにすることはできません。

クライアントは、複数の添付ファイルを複数のメッセージに保存すると、すべての添付ファイルとすべてのメッセージに対して SaveChanges メソッドを呼び出します。 多くの場合、クライアントは、最後の呼び出しを除き、これらの呼び出しごとにMAPI_DEFERRED_ERRORSを設定します。 最後の呼び出しまたは以前の呼び出しでエラーを返すことができます。 フラグは無視することもできます。

KEEP_OPEN_READWRITEまたはKEEP_OPEN_READONLYがMAPI_DEFERRED_ERRORSと共に設定されている場合は、エラー延期要求を無視できます。 ulFlags でMAPI_DEFERRED_ERRORSが設定されていない場合は、SaveChanges 呼び出しに対して以前に遅延されたエラーのいずれかを返すことができます。

リモート トランスポート プロバイダーがこのメソッドの機能実装を提供するかどうかは省略可能であり、実装の他の設計の選択肢に依存します。 このメソッドを実装する場合は、こちらのドキュメントに従って実行してください。 フォルダー オブジェクトと状態オブジェクトはトランザクションされないため、少なくともリモート トランスポート プロバイダーの SaveChanges の実装は、実際に何も行わずにS_OKを返す必要があります。

呼び出し側への注意

クライアントがKEEP_OPEN_READONLYを渡し、 IMAPIProp::SetProps メソッドを呼び出し、 SaveChanges をもう一度呼び出すと、同じ実装が失敗する可能性があります。

KEEP_OPEN_READWRITEを設定した呼び出しからMAPI_E_NO_ACCESSを受信した後、オブジェクトに対する読み取り/書き込みアクセス許可が引き続き付与されます。 SaveChanges をもう一度呼び出して、KEEP_OPEN_READONLY フラグを渡すか、KEEP_OPEN_SUFFIXを持つフラグを渡しません。

プロバイダーが KEEP_OPEN_READWRITE フラグをサポートするかどうかは、プロバイダーの実装によって異なります。

SaveChanges の後にオブジェクトに対して行う唯一の呼び出しが IUnknown::Release であることを示すには、ulFlags パラメーターにフラグを設定しません。 SaveChanges からのエラーは、保留中の変更を永続的にできなかったことを示します。 SaveChanges 呼び出しでフラグが存在しない処理は、プロバイダーによって異なります。 一部のプロバイダーは、この状態をKEEP_OPEN_READONLYと同じように扱います。他のプロバイダーは、KEEP_OPEN_READWRITEと同じように解釈します。 引き続き他のプロバイダーは、 SaveChanges 呼び出しでフラグを受信しない場合にオブジェクトをシャットダウンします。

一部のプロパティ (通常は計算プロパティ) は、 SaveChanges を呼び出し、場合によっては Release を呼び出すまで処理できません。

添付ファイルを複数のメッセージに保存するなど、一括変更を行う場合は、 ulFlags で MAPI_DEFERRED_ERRORS フラグを設定してエラー処理を延期します。 複数の添付ファイルを複数のメッセージに保存する場合は、各添付ファイルに対して 1 つの SaveChanges 呼び出しを行い、各メッセージに対して 1 つの SaveChanges 呼び出しを行います。 各添付ファイル呼び出しと、最後のものを除くすべてのメッセージに対して、MAPI_DEFERRED_ERRORS フラグを設定します。

SaveChanges がMAPI_E_OBJECT_CHANGEDを返す場合は、元のオブジェクトが変更されているかどうかをチェックします。 その場合は、変更が以前の変更を上書きするように要求するか、オブジェクトを別の場所に保存するかをユーザーに警告します。 元のオブジェクトが削除されている場合は、別の場所にオブジェクトを保存する機会を与えるようユーザーに警告します。

削除された開いているオブジェクトに対して、FORCE_SAVE フラグを指定して SaveChanges を呼び出すことはできません。

SaveChanges からエラーが返された場合、ulFlags パラメーターに設定されているフラグに関係なく、変更を保存するオブジェクトは開いたままです。

重要

ulFlags NON_EMS_XP_SAVEとSPAMFILTER_ONSAVEは、現在使用しているダウンロード可能なヘッダー ファイルで定義されていない可能性があります。その場合は、次の値を使用してコードに追加できます。#define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

詳細については、「 MAPI プロパティの保存」を参照してください。

関連項目

IMAPIProp::SetProps
PidTagEntryId 標準プロパティ
IMAPIProp : MAPI プロパティを保存する IUnknown