IMAPITable::QueryRows
Hace referencia a: Outlook 2013 | Outlook 2016
Devuelve una o varias filas de una tabla, empezando por la posición actual del cursor.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Parameters
lRowCount
[in] Número máximo de filas que se van a devolver.
ulFlags
[in] Máscara de bits de marcas que controlan cómo se devuelven las filas. Se puede establecer la marca siguiente:
TBL_NOADVANCE
Impide que el cursor avance como resultado de la recuperación de filas. Si se establece la marca de TBL_NOADVANCE, el cursor apunta a la primera fila devuelta. Si no se establece la marca de TBL_NOADVANCE, el cursor apunta a la fila que sigue a la última fila devuelta.
lppRows
[out] Puntero a un puntero a una estructura SRowSet que contiene las filas de la tabla.
Valor devuelto
S_OK
Las filas se devolvieron correctamente.
MAPI_E_BUSY
Hay otra operación en curso que impide que se inicie la operación de recuperación de filas. Se debe permitir que se complete la operación en curso o se debe detener.
MAPI_E_INVALID_PARAMETER
El parámetro IRowCount se establece en cero.
Comentarios
El método IMAPITable::QueryRows obtiene una o varias filas de datos de una tabla. El valor del parámetro IRowCount afecta al punto de partida para la recuperación. Si IRowCount es positivo, las filas se leen en dirección hacia delante, empezando en la posición actual. Si IRowCount es negativo, QueryRows restablece el punto inicial moviendo hacia atrás el número de filas indicado. Una vez restablecido el cursor, las filas se leen en orden de reenvío.
El miembro cRows de la estructura SRowSet a la que apunta el parámetro lppRows indica el número de filas devueltas. Si se devuelven cero filas:
El cursor ya estaba colocado al principio de la tabla y el valor de IRowCount es negativo. -O-
El cursor ya se ha colocado al final de la tabla y el valor de IRowCount es positivo.
El número de columnas y su ordenación es el mismo para cada fila. Si una propiedad no existe para una fila o hay un error al leer una propiedad, la estructura SPropValue de la propiedad de la fila contiene los siguientes valores:
PT_ERROR para el tipo de propiedad en el miembro ulPropTag .
MAPI_E_NOT_FOUND para el miembro Value .
La memoria utilizada para las estructuras SPropValue del conjunto de filas al que apunta el parámetro lppRows debe asignarse y liberarse por separado para cada fila. Use MAPIFreeBuffer para liberar las estructuras de valor de propiedad y liberar el conjunto de filas. Sin embargo, cuando una llamada a QueryRows devuelve cero, lo que indica el principio o el final de la tabla, solo es necesario liberar la propia estructura SRowSet . Para obtener más información sobre cómo asignar y liberar memoria en una estructura SRowSet , vea Managing Memory for ADRLIST and SRowSet Structures.
Las filas devueltas y el orden en que se devuelven dependen de si se han realizado o no llamadas correctas a IMAPITable::Restrict e IMAPITable::SortTable. Restringir filtra las filas de la vista, lo que hace que QueryRows devuelva solo las filas que coincidan con los criterios especificados en la restricción. SortTable establece un criterio de ordenación estándar o clasificado, que afecta a la secuencia de filas devuelta por QueryRows. Las filas devueltas están en el orden especificado en la estructura SSortOrderSet pasada a SortTable.
Las columnas devueltas para cada fila y el orden en que se devuelven dependen de si se ha realizado o no una llamada correcta a IMAPITable::SetColumns. SetColumns establece un conjunto de columnas, especificando las propiedades que se incluirán en las columnas de la tabla y el orden en que se deben incluir. Si se ha realizado una llamada a SetColumns , las columnas concretas de cada fila y el orden de esas columnas coinciden con el conjunto de columnas especificado en la llamada. Si no se ha realizado ninguna llamada a SetColumns , la tabla devuelve su conjunto de columnas predeterminado.
Si no se ha realizado ninguna de estas llamadas, QueryRows devuelve todas las filas de la tabla. Cada fila contiene el conjunto de columnas predeterminado en orden predeterminado.
Cuando el conjunto de columnas establecido en una llamada a IMAPITable::SetColumns incluye columnas establecidas en PR_NULL, la matriz SPropValue dentro del conjunto de filas devuelto en lppRows contendrá espacios vacíos.
Notas a los implementadores
Puede permitir que un llamador solicite que se incluya una columna no admitida en el conjunto de columnas. Cuando esto ocurra, coloque PT_ERROR en la parte del tipo de propiedad de la etiqueta de propiedad y MAPI_E_NOT_FOUND en el valor de propiedad de la columna no admitida.
Trate el recuento de filas como una solicitud en lugar de un requisito. Puede devolver desde cero filas, si no hay filas en la dirección de la consulta, al número solicitado.
Devuelve solo las filas que el usuario verá cuando se soliciten filas desde una vista de tabla categorizada, lo que permite al autor de la llamada realizar suposiciones válidas sobre el ámbito de los datos y evitar un trabajo adicional.
Notas para los llamadores
Normalmente, terminará con tantas filas como haya especificado en el parámetro lRowCount . Sin embargo, cuando los límites de memoria o implementación son un problema o cuando la operación llega al principio o al final de la tabla prematuramente, QueryRows devolverá menos filas de las solicitadas.
Si QueryRows devuelve MAPI_E_BUSY, llame al método IMAPITable::WaitForCompletion y vuelva a intentar la llamada a QueryRows cuando se complete la operación asincrónica.
Al llamar a QueryRows, tenga en cuenta que el tiempo de las notificaciones asincrónicas puede hacer que el conjunto de filas que obtiene de QueryRows no represente con precisión los datos subyacentes. Por ejemplo, una llamada a QueryRows a la tabla de contenido de una carpeta después de la eliminación de un mensaje, pero antes de recibir la notificación correspondiente hará que la fila eliminada se devuelva en el conjunto de filas. Espere siempre a que llegue una notificación antes de actualizar la vista de los datos del usuario.
Para obtener más información sobre cómo recuperar filas de tablas, vea Recuperar datos de filas de tabla.
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::QueryRows para recuperar las filas de la tabla que se van a cargar en la vista. |