IMAPITable::QueryRows
Gilt für: Outlook 2013 | Outlook 2016
Gibt eine oder mehrere Zeilen aus einer Tabelle zurück, beginnend an der aktuellen Cursorposition.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Parameter
lRowCount
[in] Maximale Anzahl von Zeilen, die zurückgegeben werden sollen.
ulFlags
[in] Bitmaske von Flags, die steuern, wie Zeilen zurückgegeben werden. Das folgende Flag kann festgelegt werden:
TBL_NOADVANCE
Verhindert, dass der Cursor als Ergebnis des Zeilenabrufs voranschreitet. Wenn das TBL_NOADVANCE-Flag festgelegt ist, zeigt der Cursor auf die erste zurückgegebene Zeile. Wenn das TBL_NOADVANCE-Flag nicht festgelegt ist, zeigt der Cursor auf die Zeile nach der letzten zurückgegebenen Zeile.
lppRows
[out] Zeiger auf einen Zeiger auf eine SRowSet-Struktur , die die Tabellenzeilen enthält.
Rückgabewert
S_OK
Die Zeilen wurden erfolgreich zurückgegeben.
MAPI_E_BUSY
Ein weiterer Vorgang wird ausgeführt, der verhindert, dass der Zeilenabrufvorgang gestartet wird. Entweder sollte der laufende Vorgang abgeschlossen oder beendet werden.
MAPI_E_INVALID_PARAMETER
Der IRowCount-Parameter ist auf 0 (null) festgelegt.
Hinweise
Die IMAPITable::QueryRows-Methode ruft eine oder mehrere Datenzeilen aus einer Tabelle ab. Der Wert des Parameters IRowCount wirkt sich auf den Startpunkt für den Abruf aus. Wenn IRowCount positiv ist, werden Zeilen in Vorwärtsrichtung gelesen, beginnend an der aktuellen Position. Wenn IRowCount negativ ist, setzt QueryRows den Startpunkt zurück, indem die angegebene Anzahl von Zeilen rückwärts verschoben wird. Nachdem der Cursor zurückgesetzt wurde, werden Zeilen in vorwärts gerichteter Reihenfolge gelesen.
Das cRows-Element in der SRowSet-Struktur , auf die der lppRows-Parameter verweist, gibt die Anzahl der zurückgegebenen Zeilen an. Wenn null Zeilen zurückgegeben werden:
Der Cursor wurde bereits am Anfang der Tabelle positioniert, und der Wert von IRowCount ist negativ. -Oder-
Der Cursor wurde bereits am Ende der Tabelle positioniert, und der Wert von IRowCount ist positiv.
Die Anzahl der Spalten und ihre Reihenfolge sind für jede Zeile gleich. Wenn eine Eigenschaft für eine Zeile nicht vorhanden ist oder ein Fehler beim Lesen einer Eigenschaft auftritt, enthält die SPropValue-Struktur für die Eigenschaft in der Zeile die folgenden Werte:
PT_ERROR für den Eigenschaftentyp im ulPropTag-Member .
MAPI_E_NOT_FOUND für das Value-Element .
Arbeitsspeicher, der für die SPropValue-Strukturen in der Zeile verwendet wird, auf die der lppRows-Parameter verweist, muss für jede Zeile separat zugeordnet und freigegeben werden. Verwenden Sie MAPIFreeBuffer , um die Eigenschaftenwertstrukturen freizusetzen und den Zeilensatz freizusetzen. Wenn ein Aufruf von QueryRows jedoch null zurückgibt, was den Anfang oder das Ende der Tabelle angibt, muss nur die SRowSet-Struktur selbst freigegeben werden. Weitere Informationen zum Zuweisen und Freigeben von Arbeitsspeicher in einer SRowSet-Struktur finden Sie unter Verwalten von Arbeitsspeicher für ADRLIST- und SRowSet-Strukturen.
Die zurückgegebenen Zeilen und die Reihenfolge, in der sie zurückgegeben werden, hängen davon ab, ob erfolgreiche Aufrufe an IMAPITable::Restrict und IMAPITable::SortTable vorgenommen wurden. Schränken Sie Zeilen aus der Ansicht ein, sodass QueryRows nur die Zeilen zurückgibt, die den in der Einschränkung angegebenen Kriterien entsprechen. SortTable richtet eine standard- oder kategorisierte Sortierreihenfolge ein, die sich auf die Reihenfolge der von QueryRows zurückgegebenen Zeilen auswirkt. Die zurückgegebenen Zeilen befinden sich in der Reihenfolge, die in der an SortTable übergebenen SSortOrderSet-Struktur angegeben ist.
Die für jede Zeile zurückgegebenen Spalten und die Reihenfolge, in der sie zurückgegeben werden, hängen davon ab, ob ein erfolgreicher Aufruf von IMAPITable::SetColumns erfolgt ist. SetColumns richtet einen Spaltensatz ein, der die Eigenschaften angibt, die in spalten in der Tabelle enthalten sein sollen, und die Reihenfolge, in der sie eingeschlossen werden sollen. Wenn ein SetColumns-Aufruf erfolgt ist, entsprechen die bestimmten Spalten in jeder Zeile und die Reihenfolge dieser Spalten dem im Aufruf angegebenen Spaltensatz. Wenn kein SetColumns-Aufruf erfolgt ist, gibt die Tabelle ihren Standardspaltensatz zurück.
Wenn keiner dieser Aufrufe erfolgt ist, gibt QueryRows alle Zeilen in der Tabelle zurück. Jede Zeile enthält den Standardspaltensatz in der Standardreihenfolge.
Wenn der Spaltensatz, der in einem Aufruf von IMAPITable::SetColumns eingerichtet wurde, spalten enthält, die auf PR_NULL festgelegt sind, enthält das SPropValue-Array innerhalb des in lppRows zurückgegebenen Zeilensatzes leere Slots.
Hinweise für Implementierer
Sie können einem Aufrufer erlauben, anzufordern, dass eine nicht unterstützte Spalte in den Spaltensatz eingeschlossen wird. Platzieren Sie in diesem Fall PT_ERROR im Eigenschaftentypteil des Eigenschaftstags und MAPI_E_NOT_FOUND im Eigenschaftswert für die nicht unterstützte Spalte.
Behandeln Sie die Zeilenanzahl als Anforderung und nicht als Anforderung. Sie können eine beliebige Stelle von null Zeilen (wenn keine Zeilen in Der Richtung der Abfrage vorhanden sind) auf die angeforderte Zahl zurückgeben.
Gibt nur die Zeilen zurück, die dem Benutzer angezeigt werden, wenn Zeilen aus einer kategorisierten Tabellenansicht angefordert werden, sodass der Aufrufer gültige Annahmen über den Umfang der Daten treffen und zusätzliche Arbeit vermeiden kann.
Hinweise für Aufrufer
In der Regel erhalten Sie so viele Zeilen, wie Sie im lRowCount-Parameter angegeben haben. Wenn jedoch Arbeitsspeicher- oder Implementierungsgrenzwerte ein Problem sind oder der Vorgang vorzeitig den Anfang oder das Ende der Tabelle erreicht, gibt QueryRows weniger Zeilen als angefordert zurück.
Wenn QueryRows MAPI_E_BUSY zurückgibt, rufen Sie die IMAPITable::WaitForCompletion-Methode auf, und wiederholen Sie den Aufruf von QueryRows , wenn der asynchrone Vorgang abgeschlossen ist.
Beachten Sie beim Aufrufen von QueryRows, dass das Timing asynchroner Benachrichtigungen möglicherweise dazu führen kann, dass der Von QueryRows zurückgerufene Zeilensatz die zugrunde liegenden Daten nicht genau darstellt. Beispielsweise führt ein Aufruf von QueryRows an die Inhaltstabelle eines Ordners nach dem Löschen einer Nachricht, aber vor dem Empfang der entsprechenden Benachrichtigung dazu, dass die gelöschte Zeile im Zeilensatz zurückgegeben wird. Warten Sie immer, bis eine Benachrichtigung eingeht, bevor Sie die Ansicht der Daten des Benutzers aktualisieren.
Weitere Informationen zum Abrufen von Zeilen aus Tabellen finden Sie unter Abrufen von Daten aus Tabellenzeilen.
MFCMAPI-Referenz
Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.
| Datei | Funktion | Kommentar |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI verwendet die IMAPITable::QueryRows-Methode , um Zeilen in der Tabelle abzurufen, die in die Ansicht geladen werden sollen. |