IMAPITable::SetColumns
適用対象: Outlook 2013 | Outlook 2016
テーブル内の列として表示するプロパティの特定のプロパティと順序を定義します。
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);
パラメーター
lpPropTagArray
[in]テーブルに列として含めるプロパティを識別するプロパティ タグの配列へのポインター。 各タグのプロパティ型部分は、有効な型に設定することも 、PR_NULL に設定して、後続の追加のために領域を予約することもできます。 lpPropTagArray パラメーターを NULL に設定することはできません。すべてのテーブルには、少なくとも 1 つの列が必要です。
ulFlags
[in] SetColumns への非同期呼び出しの戻りを制御するフラグのビットマスク (たとえば、 SetColumns が通知で使用されている場合)。 次のフラグを設定できます。
TBL_ASYNC
列設定操作を非同期的に実行するように要求すると、操作が完全に完了する前に SetColumns が返される可能性があります。
TBL_BATCH
データが実際に必要になるまで、テーブルで列設定操作を延期することを許可します。
戻り値
S_OK
列設定操作が成功しました。
MAPI_E_BUSY
列設定操作の開始を妨げる別の操作が進行中です。 進行中の操作の完了を許可するか、停止する必要があります。
注釈
テーブルの列セットは、テーブル内の行の列を構成するプロパティのグループです。 テーブルの種類ごとに既定の列セットがあります。 既定の列セットは、テーブル実装者が自動的に含むプロパティで構成されます。 テーブル ユーザーは、 IMAPITable::SetColumns メソッドを呼び出すことによって、この既定のセットを変更できます。 テーブル実装者が列の削除や列の順序の変更をサポートしている場合は、他の列を既定のセットに追加するように要求できます。 SetColumns は、各行で返される列と、行内のこれらの列の順序を指定します。
SetColumns 操作の成功は、テーブルのデータを取得するために後続の呼び出しが行われた後にのみ明らかです。 その後、エラーが報告されます。
実装に関するメモ
一部のプロバイダーでは 、SetColumns 呼び出しを許可して、テーブル ビューで使用可能な列の一部であるテーブル列のみを並べ替えます。 他のプロバイダーでは 、SetColumns 呼び出しを許可して、元の列セットにないプロパティを含むすべてのテーブル列を並べ替えます。
非同期操作にTBL_BATCHが設定されている場合、プロバイダーは、PT_ERRORのプロパティ型と、サポートされていない列のプロパティ値 NULL を返す必要があります。
操作を非同期にすることを要求するTBL_ASYNC フラグに応答する必要はありません。 非同期列セット定義をサポートしていない場合は、操作を同期的に実行します。 TBL_ASYNC フラグをサポートでき、別の非同期操作がまだ進行中の場合は、MAPI_E_BUSYを返します。 それ以外の場合は、プロパティ タグ配列に含まれるすべてのプロパティをサポートしているかどうかに関係なく、S_OKを返します。 サポートされていないプロパティに起因するエラーは、QueryRows などのデータを取得する IMAPITable メソッドから返す必要があります。
Restrict の呼び出しによってビューから非表示になっているテーブル行の通知を生成しないでください。
テーブル通知を送信する場合、TABLE_NOTIFICATION構造体の行メンバー内のプロパティの順序と、最新の SetColumns 呼び出しで指定された順序は、通知要求が送信された時刻と同じである必要があります。
別のフラグTBL_BATCHを使用すると、呼び出し元は、テーブル実装者が後でまで操作の結果の評価を延期できることを指定できます。 可能な限り、バッチ処理によってパフォーマンスが向上するため、呼び出し元はこのフラグを設定する必要があります。
多くの場合、呼び出し元は、後で値を追加するために、取得した行セットの一部の列を予約すると便利です。 呼び出し元は、SetColumns に渡されるプロパティ タグ配列内の目的の位置にPR_NULL (PidTagNull) を配置することでこれを行います。その後、テーブルは、QueryRows で取得されたすべての行の位置でPR_NULLを返します。
呼び出し側への注意
lpPropTagArray パラメーターのプロパティ タグ配列を作成するときは、テーブル ビューに列を表示する順序でタグを並べ替えます。
複数値インスタンス フラグ (定数) をプロパティ タグに適用することで、列セットに含める複数値プロパティMVI_FLAG指定できます。 このフラグを設定するには、プロパティの単一値バージョンのプロパティ タグをパラメーターとして、次のようにMVI_PROP マクロに渡します。
MVI_PROP(ulPropTag)
MVI_PROP マクロは、 プロパティのMVI_FLAGを設定し、タグを複数値タグに変換します。 単一値プロパティでMVI_PROPを誤って呼び出そうとした場合、MAPI は呼び出しを無視し、プロパティ タグは変更しません。
プロパティ タグ配列に PR_NULL に設定されたプロパティ タグを含め、列セット内の領域を予約できます。 領域を予約すると、新しいプロパティ タグ配列を割り当てなくても列セットに追加できます。
SetColumns を呼び出すと、テーブルの列の順序が変更され、これらの列の 1 つ以上が複数の値を持つプロパティを表す場合、テーブル内の行数が増える可能性があります。 この場合、テーブルのすべてのブックマークが破棄されます。 複数値の列がテーブルに与える影響の詳細については、「 複数値列の操作」を参照してください。
列の設定は、既定では同期操作です。 ただし、TBL_BATCH フラグを設定することで、データが必要になるまでテーブルで操作を延期できます。 このフラグを設定すると、パフォーマンスが向上します。 別のフラグTBL_ASYNC、操作が非同期になり、操作が完了する前に SetColumns が返されます。 完了がいつ発生するかを判断するには、 IMAPITable::GetStatus を呼び出します。
SetColumns の呼び出しでMAPI_E_BUSYが返された場合は、別の操作によって操作の開始が妨げになっていることを示します。IMAPITable::Abort を呼び出して、進行中の操作を停止できます。
HrAddColumnsEx を呼び出して列セットを変更することもできます。 HrAddColumnsEx と IMAPITable::SetColumns の違いは、HrAddColumnsEx の柔軟性が低い点です。列のみを追加できます。 追加の列は列セットの先頭に配置されます。既存のすべての列は、これらの列の後に表示されます。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl::D oSetColumns |
MFCMAPI では、 IMAPITable::SetColumns メソッドを使用して、テーブルの目的の列を設定します。 |