IMAPITable::FindRow
Hace referencia a: Outlook 2013 | Outlook 2016
Busca la siguiente fila de una tabla que coincide con criterios de búsqueda específicos y mueve el cursor a esa fila.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Parameters
lpRestriction
[in] Puntero a una estructura SRestriction que describe los criterios de búsqueda.
BkOrigin
[in] Marcador que identifica la fila donde FindRow debe comenzar su búsqueda. Se puede crear un marcador mediante el método IMAPITable::CreateBookmark o se puede pasar uno de los siguientes valores predefinidos.
BOOKMARK_BEGINNING
Busca desde el principio de la tabla.
BOOKMARK_CURRENT
Busca desde la fila de la tabla donde se encuentra el cursor.
BOOKMARK_END
Busca desde el final de la tabla.
ulFlags
[in] Máscara de bits de marcas que controla la dirección de la búsqueda. Se puede establecer la marca siguiente:
DIR_BACKWARD
Busca hacia atrás desde la fila identificada por el marcador.
Valor devuelto
S_OK
La operación de búsqueda se realizó correctamente.
MAPI_E_INVALID_BOOKMARK
El marcador del parámetro BkOrigin no es válido porque se ha quitado o porque está más allá de la última fila solicitada.
MAPI_E_NOT_FOUND
No se encontró ninguna fila que coincidió con la restricción.
MAPI_W_POSITION_CHANGED
La llamada se realizó correctamente, pero el marcador usado en la operación ya no se establece en la misma fila que cuando se usó por última vez; si no se ha usado el marcador, ya no está en la misma posición que cuando se creó. Cuando se devuelve esta advertencia, la llamada debe controlarse correctamente. Para probar esta advertencia, use la macro HR_FAILED . Consulte Uso de macros para el control de errores.
Comentarios
El método IMAPITable::FindRow busca la primera fila de la tabla para que coincida con un conjunto de criterios de búsqueda descritos en la estructura SRestriction a la que apunta el parámetro lpRestriction .
Normalmente, FindRow busca hacia delante desde el marcador especificado. El autor de la llamada puede establecer la búsqueda para que se mueva hacia atrás desde el marcador estableciendo la marca DIR_BACKWARD en el parámetro ulFlags . La búsqueda hacia delante comienza desde el marcador actual; La búsqueda hacia atrás comienza desde la fila anterior al marcador. La posición final de la búsqueda es justo antes de que la primera fila encontrara que cumplió la restricción.
Si la fila a la que apunta el marcador en el parámetro BkOrigin ya no existe en la tabla y la tabla no puede establecer una nueva posición para el marcador, FindRow devuelve MAPI_E_INVALID_BOOKMARK. Si la fila a la que apunta BkOrigin ya no existe y la tabla puede establecer una nueva posición para el marcador, FindRow devuelve MAPI_W_POSITION_CHANGED.
Si el marcador pasado en BkOrigin es BOOKMARK_BEGINNING o BOOKMARK_END, FindRow devuelve MAPI_E_NOT_FOUND si no se encuentra ninguna fila coincidente. Si el marcador usado en BkOrigin es BOOKMARK_CURRENT, FindRow puede devolver MAPI_W_POSITION_CHANGED pero no MAPI_E_INVALID_BOOKMARK porque siempre hay una posición de cursor actual.
La columna de propiedad PR_INSTANCE_KEY (PidTagInstanceKey) es necesaria para todas las tablas y todas las implementaciones de FindRow son necesarias para admitir llamadas que buscan una fila basada en PR_INSTANCE_KEY.
Notas a los implementadores
El tipo de búsqueda de prefijos realizada por FindRow solo es útil cuando la búsqueda sigue la misma dirección que la organización de la tabla. Para lograr el comportamiento necesario, la función de comparación implícita por el RELOP_GE pasado en la estructura de restricción de propiedad debe ser la misma función de comparación en la que se basa el criterio de ordenación de la tabla.
Notas para los llamadores
Puede usar FindRow para admitir el desplazamiento en función de las cadenas que escribe el usuario, especialmente en los cuadros de lista dentro de los cuadros de diálogo de dirección. En este tipo de desplazamiento, los usuarios escriben prefijos progresivamente más largos de un valor de cadena deseado y puede emitir periódicamente una llamada FindRow para saltar a la primera fila que coincida con el prefijo. La dirección en la que salta el cursor depende de la dirección en la que se establezca la búsqueda para ejecutarse.
Para usar FindRow, se debe establecer un marcador. La búsqueda de cadenas puede originarse desde cualquier marcador, incluidos los marcadores preestablecidos que indican la posición actual y el principio y el final de la tabla. Si hay un gran número de filas en la tabla, la operación de búsqueda puede ser lenta.
Use una restricción para buscar un prefijo de cadena para desplazarse como se indica a continuación. Para la búsqueda hacia delante en una columna ordenada en orden ascendente y para la búsqueda hacia atrás en una columna ordenada en orden descendente, pase una estructura de restricción de propiedad en el parámetro lpRestriction con la relación RELOP_GE y la etiqueta de propiedad y el prefijo adecuados, utilizando el prefijoGE de etiqueta de formato.
Para obtener más información sobre el uso de estructuras de restricciones para especificar un filtro, vea Acerca de las restricciones.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI usa el método IMAPITable::FindRow para buscar filas que coincidan con una restricción. |