IMAPITable::SetColumns
Gilt für: Outlook 2013 | Outlook 2016
Definiert die bestimmten Eigenschaften und die Reihenfolge der Eigenschaften, die als Spalten in der Tabelle angezeigt werden sollen.
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);
Parameter
lpPropTagArray
[in] Zeiger auf ein Array von Eigenschaftstags, das Eigenschaften identifiziert, die als Spalten in die Tabelle eingeschlossen werden sollen. Der Eigenschaftstypteil jedes Tags kann auf einen gültigen Typ oder auf PR_NULL festgelegt werden, um Speicherplatz für nachfolgende Ergänzungen zu reservieren. Der lpPropTagArray-Parameter kann nicht auf NULL festgelegt werden. Jede Tabelle muss mindestens eine Spalte aufweisen.
ulFlags
[in] Bitmaske von Flags, die die Rückgabe eines asynchronen Aufrufs an SetColumns steuert, z. B. wenn SetColumns in Benachrichtigungen verwendet wird. Die folgenden Flags können festgelegt werden:
TBL_ASYNC
Fordert an, dass der Spalteneinstellungsvorgang asynchron ausgeführt wird, wodurch SetColumns möglicherweise zurückgibt, bevor der Vorgang vollständig abgeschlossen ist.
TBL_BATCH
Ermöglicht der Tabelle das Verschieben des Spalteneinstellungsvorgangs, bis die Daten tatsächlich erforderlich sind.
Rückgabewert
S_OK
Der Vorgang zum Festlegen der Spalte war erfolgreich.
MAPI_E_BUSY
Ein weiterer Vorgang wird ausgeführt, der verhindert, dass der Spalteneinstellungsvorgang gestartet wird. Entweder sollte der laufende Vorgang abgeschlossen oder beendet werden.
Hinweise
Der Spaltensatz einer Tabelle ist die Gruppe von Eigenschaften, aus denen die Spalten für die Zeilen in der Tabelle bestehen. Es gibt einen Standardspaltensatz für jeden Tabellentyp. Der Standardspaltensatz besteht aus den Eigenschaften, die der Tabellenimplementierer automatisch einschließt. Tabellenbenutzer können diesen Standardsatz ändern, indem sie die IMAPITable::SetColumns-Methode aufrufen. Sie können anfordern, dass dem Standardsatz weitere Spalten hinzugefügt werden, wenn der Tabellenimplementierer sie unterstützt, dass Spalten entfernt werden oder dass die Reihenfolge der Spalten geändert wird. SetColumns gibt die Spalten an, die mit jeder Zeile zurückgegeben werden, und die Reihenfolge dieser Spalten innerhalb der Zeile.
Der Erfolg des SetColumns-Vorgangs wird erst nach einem nachfolgenden Aufruf zum Abrufen der Daten der Tabelle angezeigt. Dann werden alle Fehler gemeldet.
Hinweise für Implementierer
Einige Anbieter lassen einen SetColumns-Aufruf zu, um nur Tabellenspalten zu sortieren, die Teil der verfügbaren Spalten für eine Tabellenansicht sind. Andere Anbieter lassen einen SetColumns-Aufruf zu, um alle Tabellenspalten zu sortieren, einschließlich derer, die Eigenschaften enthalten, die nicht im ursprünglichen Spaltensatz enthalten sind.
Wenn TBL_BATCH für asynchrone Vorgänge festgelegt ist, sollten Anbieter den Eigenschaftstyp PT_ERROR und den Eigenschaftswert NULL für nicht unterstützte Spalten zurückgeben.
Sie müssen nicht auf das TBL_ASYNC-Flag reagieren, das anfordert, dass der Vorgang asynchron ist. Wenn Sie die asynchrone Spaltensatzdefinition nicht unterstützen, führen Sie den Vorgang synchron aus. Wenn Sie das TBL_ASYNC-Flag unterstützen können und ein weiterer asynchroner Vorgang noch ausgeführt wird, geben Sie MAPI_E_BUSY zurück. Andernfalls geben Sie S_OK zurück, unabhängig davon, ob Sie alle Eigenschaften unterstützen, die im Eigenschaftentagarray enthalten sind. Fehler, die sich aus nicht unterstützten Eigenschaften ergeben, sollten von IMAPITable-Methoden zurückgegeben werden, die Daten abrufen, z. B. QueryRows.
Generieren Sie keine Benachrichtigungen für Tabellenzeilen, die durch Aufrufe von Restrict aus der Ansicht ausgeblendet werden.
Beim Senden von Tabellenbenachrichtigungen müssen die Reihenfolge der Eigenschaften im Zeilenmember der TABLE_NOTIFICATION-Struktur und die durch den letzten SetColumns-Aufruf angegebene Reihenfolge mit dem Zeitpunkt identisch sein, zu dem die Benachrichtigungsanforderung gesendet wurde.
Mit einem anderen Flag, TBL_BATCH, können Aufrufer angeben, dass der Tabellenimplementierer die Auswertung der Ergebnisse des Vorgangs bis zu einem späteren Zeitpunkt verzögern kann. Wenn möglich, sollten Aufrufer dieses Flag festlegen, da der Batchvorgang die Leistung verbessert.
Für Anrufer ist es häufig praktisch, einige Spalten in der abgerufenen Zeilenmenge für werte zu reservieren, die später hinzugefügt werden sollen. Aufrufer platzieren dazu PR_NULL (PidTagNull) an den gewünschten Positionen im Eigenschaftentagarray, das an SetColumns übergeben wird. Die Tabelle übergibt dann PR_NULL an diesen Positionen in allen Zeilen, die mit QueryRows abgerufen wurden.
Hinweise für Aufrufer
Ordnen Sie beim Erstellen des Eigenschaftentagarrays für den lpPropTagArray-Parameter die Tags in der Reihenfolge an, in der die Spalten in der Tabellenansicht angezeigt werden sollen.
Sie können mehrwertige Eigenschaften angeben, die in den Spaltensatz eingeschlossen werden sollen, indem Sie das mehrwertige instance-Flag oder MVI_FLAG Konstante auf das Eigenschaftentag anwenden. Legen Sie dieses Flag fest, indem Sie das Eigenschaftstag für die einwertige Version der Eigenschaft wie folgt als Parameter an das makro MVI_PROP übergeben:
MVI_PROP(ulPropTag)
Das MVI_PROP Makro legt MVI_FLAG für die -Eigenschaft fest und wandelt das Tag in ein mehrwertiges Tag um. Wenn Sie fälschlicherweise versuchen, MVI_PROP für eine einwertige Eigenschaft aufzurufen, ignoriert MAPI den Aufruf und lässt das Eigenschaftstag unverändert.
Sie können Eigenschaftstags, die auf PR_NULL festgelegt sind, in das Eigenschaftentagarray einschließen, um Platz im Spaltensatz zu reservieren. Durch das Reservieren von Speicherplatz können Sie einem Spaltensatz hinzufügen, ohne ein neues Eigenschaftentagarray zuordnen zu müssen.
Wenn der Aufruf von SetColumns eine Änderung der Reihenfolge der Spalten einer Tabelle bewirkt und eine oder mehrere dieser Spalten eine mehrwertige Eigenschaft darstellen, kann die Anzahl der Zeilen in der Tabelle erhöht werden. In diesem Fall werden alle Lesezeichen für die Tabelle verworfen. Weitere Informationen dazu, wie sich mehrwertige Spalten auf Tabellen auswirken, finden Sie unter Arbeiten mit mehrwertigen Spalten.
Das Festlegen von Spalten ist standardmäßig ein synchroner Vorgang. Sie können jedoch zulassen, dass die Tabelle den Vorgang so lange zurückstellt, bis die Daten benötigt werden, indem Sie das TBL_BATCH-Flag festlegen. Das Festlegen dieses Flags kann die Leistung verbessern. Ein weiteres Flag, TBL_ASYNC, macht den Vorgang asynchron, sodass SetColumns zurückgibt, bevor der Vorgang abgeschlossen ist. Um zu bestimmen, wann der Abschluss erfolgt, rufen Sie IMAPITable::GetStatus auf.
Wenn ein Aufruf von SetColumns MAPI_E_BUSY zurückgibt, der angibt, dass ein anderer Vorgang den Start des Vorgangs verhindert, können Sie IMAPITable::Abort aufrufen, um den laufenden Vorgang zu beenden.
Sie können auch HrAddColumnsEx aufrufen, um einen Spaltensatz zu ändern. Der Unterschied zwischen HrAddColumnsEx und IMAPITable::SetColumns besteht darin, dass HrAddColumnsEx weniger flexibel ist. Es können nur Spalten hinzugefügt werden. Die zusätzlichen Spalten werden am Anfang des Spaltensatzes platziert. alle vorhandenen Spalten werden nach diesen Spalten angezeigt.
MFCMAPI-Referenz
Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.
| Datei | Funktion | Kommentar |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl::D oSetColumns |
MFCMAPI verwendet die IMAPITable::SetColumns-Methode , um die gewünschten Spalten für die Tabelle festzulegen. |