IMAPIProp::OpenProperty
適用対象: Outlook 2013 | Outlook 2016
プロパティへのアクセスに使用できるインターフェイスへのポインターを返します。
HRESULT OpenProperty(
ULONG ulPropTag,
LPCIID lpiid,
ULONG ulInterfaceOptions,
ULONG ulFlags,
LPUNKNOWN FAR * lppUnk
);
パラメーター
ulPropTag
[in]アクセスするプロパティのプロパティ タグ。 識別子と型の両方をプロパティ タグに含む必要があります。
lpiid
[in]プロパティへのアクセスに使用するインターフェイスの識別子へのポインター。 lpiid パラメーターは null にすることはできません。
ulInterfaceOptions
[in] lpiid パラメーターによって識別されるインターフェイスに関連するデータ。
ulFlags
[in]プロパティへのアクセスを制御するフラグのビットマスク。 次のフラグを設定できます。
MAPI_CREATE
プロパティが存在しない場合は、作成する必要があります。 プロパティが存在する場合は、プロパティの現在の値を破棄する必要があります。 呼び出し元が MAPI_CREATE フラグを設定する場合は、MAPI_MODIFY フラグも設定する必要があります。
MAPI_DEFERRED_ERRORS
呼び出し元がオブジェクトを完全に使用できるようになる前に、 OpenProperty が正常に返されるようにします。 オブジェクトが使用できない場合は、後続のオブジェクト呼び出しを行うとエラーが発生する可能性があります。
MAPI_MODIFY
これらの状況では、MAPI_MODIFYが必要です。
IID_IStreamなどのストリーム プロパティを開いて変更する場合。
埋め込みメッセージの添付ファイル ( IID_IMessage で開く PR_ATTACH_DATA_OBJなど) を開いて変更する場合。
lppUnk
[out]プロパティ アクセスに使用する要求されたインターフェイスへのポインター。
戻り値
S_OK
要求されたインターフェイス ポインターが正常に返されました。
MAPI_E_INTERFACE_NOT_SUPPORTED
要求されたインターフェイスは、このプロパティではサポートされていません。
MAPI_E_NO_ACCESS
呼び出し元には、プロパティにアクセスするための十分なアクセス許可がありません。
MAPI_E_NO_SUPPORT
オブジェクトは、要求されたインターフェイスを介してこのプロパティへのアクセスを提供できません。
MAPI_E_NOT_FOUND
要求されたプロパティが存在せず、 ulFlags パラメーターにMAPI_CREATEが設定されていません。
MAPI_E_INVALID_PARAMETER
タグのプロパティ型は、PT_UNSPECIFIEDに設定されます。
注釈
IMAPIProp::OpenProperty メソッドは、特定のインターフェイスを介してプロパティへのアクセスを提供します。 OpenProperty は、 IMAPIProp::GetProps メソッドと IMAPIProp::SetProps メソッドの代替手段です。 プロパティが大きすぎるか複雑すぎるため 、GetProps または SetProps のいずれかが失敗した場合は、 OpenProperty を呼び出します。 OpenProperty は通常、PT_OBJECT型のプロパティにアクセスするために使用されます。
呼び出し側への注意
メッセージ添付ファイルにアクセスするには、添付ファイルの種類に応じて、異なるインターフェイス識別子を使用して PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) プロパティを開きます。 次の表では、さまざまな種類の添付ファイルに対して OpenProperty を呼び出す方法について説明します。
| 添付ファイルの種類 | 使用するインターフェイス識別子 |
|---|---|
| バイナリ |
IID_IStream |
| String |
IID_IStream |
| メッセージ |
IID_IMessage |
| OLE 2.0 |
IID_IStreamDocfile |
IStreamDocfile は、OLE 2.0 複合ファイルに基づく IStream インターフェイスの派生関数です。 IStreamDocfile は、最小限のオーバーヘッドを伴うため、OLE 2.0 添付ファイルにアクセスするための最適な選択肢です。 IStorage インターフェイスを介して使用できる構造化ストレージに格納されているデータを含むプロパティには、IID_IStreamDocFileを使用できます。
添付ファイルで OpenProperty を 使用する方法の詳細については、「 PR_ATTACH_DATA_OBJ プロパティ」および「 添付ファイルを開く」を参照してください。
0 個の位置またはサイズ変数を使用しない限り、受信した IStream ポインターを使用してその Seek メソッドまたは SetSize メソッドを呼び出さないでください。 また、Seek 呼び出しから返される plibNewPosition 出力パラメーターの値に依存しないでください。
OpenProperty を呼び出して IStream インターフェイスを使用してプロパティにアクセスする場合は、そのインターフェイスのみを使用して変更を加えます。 他の IMAPIProp : IUnknown メソッド (SetProps や IMAPIProp::D eleteProps など) でプロパティを更新しないでください。
OpenProperty でプロパティを複数回開かないでください。 結果は、プロバイダーによって異なる可能性があるため、未定義です。
開くプロパティを変更する必要がある場合は、MAPI_MODIFY フラグを設定します。 オブジェクトが プロパティをサポートしているかどうかわからないが、必要があると思う場合は、MAPI_CREATEフラグとMAPI_MODIFYフラグを設定します。 MAPI_CREATEが設定されるたびに、MAPI_MODIFYも設定する必要があります。
lppUnk パラメーターで返されるインターフェイス ポインターを、lpiid パラメーターで指定されたインターフェイスに適したポインターに再キャストする必要があります。 また、返されたポインターを使用して、終了したときに IUnknown::Release メソッドを呼び出す必要もあります。
ulFlags パラメーターでフラグを設定するだけでは、必要なプロパティへのアクセスの種類を示すには十分でない場合があります。 フラグなどの追加データを ulInterfaceOptions パラメーターに格納できます。 このデータはインターフェイスに依存します。 一部のインターフェイス ( IStream など) はそれを使用し、使用しないインターフェイスもあります。 たとえば、 IStream で変更するプロパティを開く場合は、MAPI_MODIFYに加えて ulInterfaceOptions パラメーターにSTGM_WRITE フラグを設定します。 IMAPITable インターフェイスを使用してテーブルを開くとき、ulInterfaceOptions を MAPI_UNICODE に設定して、文字列プロパティを保持するテーブル内の列を Unicode 形式にする必要があるかどうかを示すことができます。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| StreamEditor.cpp |
CStreamEditor::ReadTextStreamFromProperty |
MFCMAPI では、 IMAPIProp::OpenProperty メソッドを使用して、大きなテキストプロパティとバイナリ プロパティのストリーム インターフェイスを取得します。 |