IMAPITable::FindRow
Gilt für: Outlook 2013 | Outlook 2016
Sucht die nächste Zeile in einer Tabelle, die bestimmten Suchkriterien entspricht, und verschiebt den Cursor in diese Zeile.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Parameter
lpRestriction
[in] Ein Zeiger auf eine SRestriction-Struktur , die die Suchkriterien beschreibt.
BkOrigin
[in] Ein Lesezeichen, das die Zeile identifiziert, in der FindRow mit der Suche beginnen soll. Ein Lesezeichen kann mithilfe der IMAPITable::CreateBookmark-Methode erstellt werden, oder einer der folgenden vordefinierten Werte kann übergeben werden.
BOOKMARK_BEGINNING
Sucht am Anfang der Tabelle.
BOOKMARK_CURRENT
Sucht aus der Zeile in der Tabelle, in der sich der Cursor befindet.
BOOKMARK_END
Sucht am Ende der Tabelle.
ulFlags
[in] Eine Bitmaske von Flags, die die Richtung der Suche steuert. Das folgende Flag kann festgelegt werden:
DIR_BACKWARD
Sucht rückwärts aus der Zeile, die durch das Lesezeichen identifiziert wird.
Rückgabewert
S_OK
Der Suchvorgang war erfolgreich.
MAPI_E_INVALID_BOOKMARK
Das Lesezeichen im BkOrigin-Parameter ist ungültig, weil es entfernt wurde oder die letzte angeforderte Zeile überschreitet.
MAPI_E_NOT_FOUND
Es wurden keine Zeilen gefunden, die mit der Einschränkung übereinstimmen.
MAPI_W_POSITION_CHANGED
Der Aufruf war erfolgreich, aber die im Vorgang verwendete Textmarke wird nicht mehr in derselben Zeile wie bei der letzten Verwendung festgelegt. Wenn das Lesezeichen nicht verwendet wurde, befindet es sich nicht mehr an der gleichen Position wie beim Erstellen. Wenn diese Warnung zurückgegeben wird, sollte der Aufruf als erfolgreich behandelt werden. Verwenden Sie zum Testen auf diese Warnung das Makro HR_FAILED . Weitere Informationen finden Sie unter Verwenden von Makros für die Fehlerbehandlung.
Hinweise
Die IMAPITable::FindRow-Methode sucht die erste Zeile in der Tabelle, um eine Reihe von Suchkriterien zu erfüllen, die in der SRestriction-Struktur beschrieben sind, auf die der lpRestriction-Parameter verweist.
In der Regel sucht FindRow über das angegebene Lesezeichen nach vorne. Der Aufrufer kann festlegen, dass die Suche vom Lesezeichen rückwärts verschoben wird, indem das flag DIR_BACKWARD im ulFlags-Parameter festgelegt wird. Die Vorwärtssuche beginnt mit dem aktuellen Lesezeichen; Die Suche nach hinten beginnt in der Zeile vor dem Lesezeichen. Die Endposition der Suche befindet sich kurz vor der ersten Gefundenen Zeile, die die Einschränkung erfüllt.
Wenn die Zeile, auf die das Lesezeichen im BkOrigin-Parameter verweist, nicht mehr in der Tabelle vorhanden ist und die Tabelle keine neue Position für das Lesezeichen festlegen kann, gibt FindRow MAPI_E_INVALID_BOOKMARK zurück. Wenn die Zeile, auf die BkOrigin verweist, nicht mehr vorhanden ist und die Tabelle eine neue Position für das Lesezeichen einrichten kann, gibt FindRow MAPI_W_POSITION_CHANGED zurück.
Wenn das in BkOrigin übergebene Lesezeichen entweder BOOKMARK_BEGINNING oder BOOKMARK_END ist, gibt FindRow MAPI_E_NOT_FOUND zurück, wenn keine übereinstimmende Zeile gefunden wird. Wenn das in BkOrigin verwendete Lesezeichen BOOKMARK_CURRENT ist, kann FindRow MAPI_W_POSITION_CHANGED, aber nicht MAPI_E_INVALID_BOOKMARK zurückgeben, da immer eine aktuelle Cursorposition vorhanden ist.
Die Eigenschaftsspalte PR_INSTANCE_KEY (PidTagInstanceKey) ist für alle Tabellen erforderlich, und alle FindRow-Implementierungen sind erforderlich, um Aufrufe zu unterstützen, die eine Zeile basierend auf PR_INSTANCE_KEY suchen.
Hinweise für Implementierer
Die von FindRow durchgeführte Präfixsuche ist nur nützlich, wenn die Suche dieselbe Richtung wie die Tabellenorganisation verfolgt. Um das erforderliche Verhalten zu erreichen, sollte die Vergleichsfunktion, die von der in der Eigenschaftseinschränkungsstruktur übergebenen RELOP_GE impliziert wird, dieselbe Vergleichsfunktion sein, auf der die Tabellensortierreihenfolge basiert.
Hinweise für Aufrufer
Sie können FindRow verwenden, um bildlauf basierend auf vom Benutzer eingegebenen Zeichenfolgen zu unterstützen, insbesondere in Listenfeldern in Adressdialogfeldern. Bei dieser Art des Bildlaufs geben Benutzer nach und nach längere Präfixe eines gewünschten Zeichenfolgenwerts ein, und Sie können regelmäßig einen FindRow-Aufruf ausgeben, um zur ersten Zeile zu springen, die dem Präfix entspricht. In welche Richtung der Cursor springt, hängt davon ab, in welche Richtung die Suche ausgeführt werden soll.
Um FindRow verwenden zu können, muss ein Lesezeichen festgelegt werden. Die Zeichenfolgensuche kann von jedem Lesezeichen stammen, einschließlich der voreingestellten Lesezeichen, die die aktuelle Position sowie den Anfang und das Ende der Tabelle angeben. Wenn die Tabelle eine große Anzahl von Zeilen enthält, kann der Suchvorgang langsam sein.
Verwenden Sie eine Einschränkung, um ein Zeichenfolgenpräfix für den Bildlauf wie folgt zu suchen. Übergeben Sie für die Vorwärtssuche in einer Spalte, die in aufsteigender Reihenfolge sortiert ist, und für die Rückwärtssuche nach einer Spalte, die in absteigender Reihenfolge sortiert ist, eine Eigenschaftseinschränkungsstruktur im lpRestriction-Parameter mit der Beziehung RELOP_GE und dem entsprechenden Eigenschaftentag und Präfix unter Verwendung des Ge-Präfixes des Formattags.
Weitere Informationen zur Verwendung von Einschränkungsstrukturen zum Angeben eines Filters finden Sie unter Informationen zu Einschränkungen.
MFCMAPI-Referenz
Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.
| Datei | Funktion | Kommentar |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI verwendet die IMAPITable::FindRow-Methode , um Zeilen zu finden, die einer Einschränkung entsprechen. |