IMAPIProp::SetProps
適用対象: Outlook 2013 | Outlook 2016
1 つ以上のプロパティを更新します。
HRESULT SetProps(
ULONG cValues,
LPSPropValue lpPropArray,
LPSPropProblemArray FAR * lppProblems
);
パラメーター
cValues
[in] lpPropArray パラメーターによって指されるプロパティ値の数。 cValues パラメーターは 0 にすることはできません。
lpPropArray
[in]更新するプロパティ値を含む SPropValue 構造体の配列へのポインター。
lppProblems
[in, out]入力時に、 SPropProblemArray 構造体へのポインターへのポインター。それ以外の場合は、エラー情報の必要がないことを示す NULL。 lppProblems が入力の有効なポインターである場合、SetProps は 1 つ以上のプロパティを更新するときのエラーに関する詳細情報を返します。
戻り値
S_OK
プロパティが正常に更新されました。
SPropProblemArray 構造体では次の値を返すことができますが、SetProps の戻り値としては返されません。
MAPI_E_BAD_CHARWIDTH
MAPI_UNICODE フラグが設定され、実装で Unicode がサポートされていないか、MAPI_UNICODEが設定されておらず、実装で Unicode のみがサポートされています。
MAPI_E_COMPUTED
プロパティは、オブジェクトを担当するサービス プロバイダーによって計算される読み取り専用であるため、更新できません。
MAPI_E_INVALID_TYPE
プロパティの種類が無効です。
MAPI_E_NO_ACCESS
読み取り専用オブジェクトを変更するか、ユーザーがアクセス許可が不十分なオブジェクトにアクセスしようとしました。
MAPI_E_NOT_ENOUGH_MEMORY
プロパティは、リモート プロシージャ呼び出し (RPC) バッファー サイズよりも大きいため、更新できません。
MAPI_E_UNEXPECTED_TYPE
プロパティ型は、呼び出し元の実装で予期される型ではありません。
実装に関するメモ
PR_NULL (PidTagNull) プロパティ タグと、PT_ERRORの種類を持つすべてのプロパティを無視します。 SPropProblemArray 構造体に変更を加えたり、問題を報告したりしないでください。
PT_OBJECT型のプロパティがプロパティ値配列に含まれている場合は、 MAPI_E_INVALID_PARAMETER を返します。 また、複数値プロパティが配列に含まれ、その cValues メンバーが 0 に設定されている場合も、このエラーが返されます。
呼び出しが全体的に成功したが、一部のプロパティの設定に問題がある場合は、S_OKを返し、lppProblems パラメーターが指す SPropProblemArray 構造体の適切なエントリに問題に関する情報を配置します。
呼び出し側への注意
サービス プロバイダーによっては、特定のプロパティ識別子で以前に使用されていた型とは異なる型を含むプロパティ タグを渡すことで、プロパティの種類を変更することもできます。
オブジェクトでサポートされていないプロパティのプロパティ タグを含め、 SetProps の実装で新しいプロパティを作成できる場合、プロパティは オブジェクトに追加されます。 新しいプロパティに使用されたプロパティ識別子と共に格納された以前の値はすべて破棄されます。
S_OK戻り値は、すべてのプロパティが正常に更新されたことを保証するものではありません。 一部のプロバイダーは、プロバイダーの介入を必要とする呼び出し (IMAPIProp::SaveChanges や IMAPIProp::GetProps など) を受信するまで SetProps 呼び出しをキャッシュします。 したがって、後の呼び出しで SetProps 呼び出しに関連するエラー値を受け取る可能性があります。
SetProps がS_OKを返す場合は、個々のプロパティの更新に関する問題について、lppProblem が指す SPropProblemArray 構造体をチェックします。 SetProps がエラーを返す場合は、プロパティの問題の配列をチェックしないでください。 代わりに、オブジェクトの IMAPIProp::GetLastError メソッドを 呼び出します。
大規模なプロパティを更新すると、 SetProps が 失敗し、MAPI_E_NOT_ENOUGH_MEMORYが返される可能性があります。 プロパティの最大サイズはなく、オブジェクトによって制限が異なる場合があります。 大きくなる可能性があるプロパティを処理する場合は、SetProps がこのエラー値を返す場合は、IID_IStreamをインターフェイス識別子として使用して IMAPIProp::OpenProperty メソッドを呼び出す準備をしてください。
MAPIFreeBuffer 関数を呼び出して、SPropProblemArray 構造体を解放します。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| PropertyEditor.cpp |
CPropertyEditor::WriteSPropValueToObject |
MFCMAPI では、 IMAPIProp::SetProps メソッドを使用して、プロパティを編集した後にオブジェクトにプロパティを書き戻します。 |