MAPI での構造化ストレージ
適用対象: Outlook 2013 | Outlook 2016
構造化ストレージとは、COM で導入されたストレージの階層organizationを指します。 構造化ストレージ環境では、ストレージは 2 種類または 3 種類のオブジェクトに編成されます。
オブジェクトのStream
バイト オブジェクトをロックする
ストレージ オブジェクト
Streamバイトとロック バイトは、データに直接アクセスする下位レベルのオブジェクトです。 Stream オブジェクトは、バイトのデータの読み取り、書き込み、配置、およびコピーのメソッドを定義する IStream インターフェイスを実装します。 バイト オブジェクトをロックすると、バイト配列を使用してデータにアクセスするための別の COM インターフェイス ILockBytes が実装されます。 バイト配列は、通常、基になるストレージへのカスタマイズされたアクセスを提供するために使用されます。
ストレージ オブジェクトは、ストリーム オブジェクトまたはロック バイト オブジェクトの上に階層化されます。これらのオブジェクトの 1 つ以上と、他のストレージ オブジェクトを含めることができます。 ストレージ オブジェクトは、入れ子になったオブジェクトを作成、アクセス、保守するためのメソッドを定義する IStorage インターフェイスを実装します。
IStream、ILockBytes、IStorage は MAPI インターフェイスではなく COM インターフェイスであるため、そのメソッドは MAPI 値ではなく COM エラー値を返します。 これらのインターフェイスでメソッドを呼び出すクライアントとサービス プロバイダーは、API 関数 MapStorageSCode を使用して、これらの値を MAPI エラー値に変換する必要があります。 詳細については、「 MapStorageSCode」を参照してください。
クライアントとサービス プロバイダーは、 IMAPIProp メソッドで維持するには大きすぎるプロパティ (通常は大きな文字列プロパティとバイナリ プロパティ) を操作するために構造化ストレージを使用します。 クライアントまたはサービス プロバイダーがそれらにアクセスする一般的な方法の 1 つは、IMAPIProp::OpenProperty メソッドの呼び出しでインターフェイス識別子として IStream または IStorage を指定することです。 たとえば、クライアントはプロパティ タグとして PR_ATTACH_DATA_BIN を使用して OpenProperty を呼び出し、インターフェイス識別子としてIID_IStreamしてメッセージ内のバイナリ添付ファイルにアクセスします。
クライアントとサービス プロバイダーは、独自のストリーム オブジェクトとストレージ オブジェクトを実装したり、API 関数を呼び出して MAPI または COM によって提供される実装にアクセスしたりできます。 提供される実装はほとんどの目的に使用されるため、クライアントとサービス プロバイダーが独自の実装を作成する必要はほとんどありません。
クライアントが MAPI オブジェクトの OpenProperty を呼び出してストレージ オブジェクトを介してそのプロパティのいずれかにアクセスする場合、サービス プロバイダーは通常、直接モードでストレージ オブジェクトを開きます。 ただし、これは必須の動作ではなく一般的です。 クライアントは、サービス プロバイダーによって開かれた、または作成されたすべてのストレージ オブジェクトがトランザクションされ、 IStorage::Commit の呼び出しが必要であると想定する必要があります。 また、MAPI オブジェクトを保存する最後のコミットの後に IMAPIProp::SaveChanges を呼び出すまで、ストレージ オブジェクトに対する変更は永続的に行われません。 詳細については、「 IMAPIProp::SaveChanges」を参照してください。
MAPI と COM には、ストレージ オブジェクトとストリーム オブジェクトを定義またはアクセスするための API 関数がいくつか用意されています。 一般的に使用される関数を次の表に示します。
ストレージオブジェクトとStreamオブジェクトにアクセスするための関数
| Function | 説明 |
|---|---|
|
HrIStorageFromStream |
ストリームまたはロック バイト オブジェクトにアクセスするストレージ オブジェクトを作成します。 |
|
OpenIMsgOnIStg |
ストレージ オブジェクトにアクセスするメッセージ オブジェクトを作成します。 |
|
OpenStreamOnFile |
ファイルにアクセスするストリーム オブジェクトを作成します。 |
|
WrapCompressedRTFStream |
メッセージのリッチ テキストを保持するストリームの圧縮または非圧縮バージョンを含むストリーム オブジェクトを作成します。 |
特定のサブストレージ内のストリームの名前を取得するには
サブストレージの IStorage::EnumElements メソッドを呼び出して 、IEnumSTATSTG インターフェイスを取得します。
一度にできるだけ多くの STATSTG 構造体を使用して IEnumSTATSTG::Next を呼び出します。 一度に 100 個を要求すると、通常、pceltFetched の内容が実際に取得された数値に設定されたS_FALSEが返されます。
STGTY_STREAMでフラグが設定されている STATSTG 構造体を確認します。
pwcsName パラメーターを解放します。
既存のストリームまたはロック バイト オブジェクトにアクセスするストレージ オブジェクトを作成するには
- クライアントは HrIStorageFromStream を呼び出します。
既存のストレージ オブジェクトにアクセスするメッセージ オブジェクトを作成するには
- サービス プロバイダーとクライアントは OpenIMsgOnIStg を呼び出します。 作成されるメッセージ オブジェクトは、メッセージ ストア プロバイダーによって通常作成されるメッセージ オブジェクトとは異なります。 IMessage: IMAPIProp インターフェイス メソッド ( IMessage::SubmitMessage など) がすべてサポートされているわけではありません。 OpenIMsgOnIStg への省略可能な入力パラメーターは、MSGCALLRELEASE プロトタイプに準拠するコールバック関数です。 この関数は、メッセージの参照カウントが 0 に達すると、新しいメッセージ オブジェクトによって呼び出されます。 MSGCALLRELEASE 関数の実装は、新しいメッセージが完全に削除される前に最終処理を実行する場合に役立ちます。
OpenStreamOnFile は、ファイルの読み取りとファイルへの書き込みを行うストリームを作成するため、添付ファイルを格納するために一般的に使用されます。 プロパティ タグとしてPR_ATTACH_DATA_BINを持つ OpenProperty は、バイナリ添付ファイル データを格納するためのストリームを作成します。
リッチ テキスト形式でメッセージ テキストを含むストリームを圧縮または圧縮解除するには
- クライアントは WrapCompressedRTFStream を呼び出します。 WrapCompressedRTFStream は、RTF ストリームをラップするストリームを作成します。 ラッパー ストリームでは、すべての IStream メソッドが実装されているわけではありません。Seek、SetSize、Revert、LockRegion、UnlockRegion、Stat、Clone の各メソッドは除外されます。 これは、 WrapCompressedRTFStream によって作成されたストリーム オブジェクトが SetSize または Stat をサポートしていないため、サイズを拡張または取得する簡単な方法がないためです。 最適な方法は、適切なバッファー サイズを選択し、ループ内で読み取りまたは書き込みを行う方法です。
注:
COM には、問題のある EnumElements メソッドから IEnumSTATSTG オブジェクトを返すバイト配列に基づくストレージ オブジェクトの実装があります。 特に、 QueryInterface メソッドが正しく動作しません。 COM 実装を使用して独自のストレージ オブジェクトを実装するサービス プロバイダーは、基になる IEnumSTATSTG メソッドへの呼び出しを転送するが、独自の AddRef、Release、QueryInterface、Clone メソッドを実装する IEnumSTATSTG オブジェクトのシン ラッパーを作成する必要があります。