IMAPITable::QueryRows
Aplica-se a: Outlook 2013 | Outlook 2016
Retorna uma ou mais linhas de uma tabela, começando na posição atual do cursor.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Parâmetros
lRowCount
[in] Número máximo de linhas a serem retornadas.
ulFlags
[in] Máscara de bits de sinalizadores que controlam como as linhas são retornadas. O seguinte sinalizador pode ser definido:
TBL_NOADVANCE
Impede que o cursor avance como resultado da recuperação da linha. Se o sinalizador TBL_NOADVANCE for definido, o cursor apontará para a primeira linha retornada. Se o sinalizador TBL_NOADVANCE não estiver definido, o cursor apontará para a linha após a última linha retornada.
lppRows
[out] Ponteiro para um ponteiro para uma estrutura SRowSet que contém as linhas da tabela.
Valor de retorno
S_OK
As linhas foram retornadas com êxito.
MAPI_E_BUSY
Outra operação está em andamento que impede o início da operação de recuperação de linha. A operação em andamento deve ser autorizada a ser concluída ou deve ser interrompida.
MAPI_E_INVALID_PARAMETER
O parâmetro IRowCount está definido como zero.
Comentários
O método IMAPITable::QueryRows obtém uma ou mais linhas de dados de uma tabela. O valor do parâmetro IRowCount afeta o ponto de partida da recuperação. Se IRowCount for positivo, as linhas serão lidas em direção à frente, começando na posição atual. Se IRowCount for negativo, QueryRows redefinirá o ponto de partida movendo-se para trás o número indicado de linhas. Depois que o cursor é redefinido, as linhas são lidas em ordem de encaminhamento.
O membro cRows na estrutura SRowSet apontada pelo parâmetro lppRows indica o número de linhas retornadas. Se nenhuma linha for retornada:
O cursor já estava posicionado no início da tabela e o valor de IRowCount é negativo. -Ou-
O cursor já estava posicionado no final da tabela e o valor de IRowCount é positivo.
O número de colunas e seus pedidos é o mesmo para cada linha. Se uma propriedade não existir para uma linha ou houver um erro ao ler uma propriedade, a estrutura SPropValue da propriedade na linha contém os seguintes valores:
PT_ERROR para o tipo de propriedade no membro ulPropTag .
MAPI_E_NOT_FOUND para o membro Value .
A memória usada para as estruturas SPropValue no conjunto de linhas apontada pelo parâmetro lppRows deve ser alocada separadamente e liberada para cada linha. Use MAPIFreeBuffer para liberar as estruturas de valor da propriedade e liberar o conjunto de linhas. No entanto, quando uma chamada para QueryRows retorna zero, indicando o início ou o fim da tabela, apenas a própria estrutura SRowSet precisa ser liberada. Para obter mais informações sobre como alocar e liberar memória em uma estrutura SRowSet , consulte Gerenciando memória para estruturas ADRLIST e SRowSet.
As linhas retornadas e a ordem em que são retornadas dependem se as chamadas bem-sucedidas foram feitas ou não para IMAPITable::Restrict e IMAPITable::SortTable. Restrinja linhas de filtros do modo de exibição, fazendo com que QueryRows retorne apenas as linhas que correspondem aos critérios especificados na restrição. SortTable estabelece uma ordem de classificação padrão ou categorizada, afetando a sequência de linhas retornadas por QueryRows. As linhas retornadas estão na ordem especificada na estrutura SSortOrderSet passada para SortTable.
As colunas retornadas para cada linha e a ordem na qual são retornadas dependem se uma chamada bem-sucedida foi ou não feita para IMAPITable::SetColumns. SetColumns estabelece um conjunto de colunas, especificando as propriedades a serem incluídas em colunas na tabela e a ordem em que elas devem ser incluídas. Se uma chamada SetColumns tiver sido feita, as colunas específicas em cada linha e a ordem dessas colunas corresponderão ao conjunto de colunas especificado na chamada. Se nenhuma chamada SetColumns tiver sido feita, a tabela retornará seu conjunto de colunas padrão.
Se nenhuma dessas chamadas tiver sido feita, QueryRows retornará todas as linhas da tabela. Cada linha contém o conjunto de colunas padrão em ordem padrão.
Quando o conjunto de colunas estabelecido em uma chamada para IMAPITable::SetColumns inclui colunas definidas como PR_NULL, a matriz SPropValue dentro do conjunto de linhas retornada em lppRows conterá slots vazios.
Observações para implementadores
Você pode permitir que um chamador solicite que uma coluna sem suporte seja incluída no conjunto de colunas. Quando isso ocorrer, coloque PT_ERROR na parte do tipo de propriedade da marca de propriedade e MAPI_E_NOT_FOUND no valor da propriedade para a coluna sem suporte.
Trate a contagem de linhas como uma solicitação em vez de um requisito. Você pode retornar em qualquer lugar de zero linhas, se não houver linhas na direção da consulta, para o número solicitado.
Retorne apenas as linhas que o usuário verá quando as linhas forem solicitadas de uma exibição de tabela categorizada, permitindo que o chamador faça suposições válidas sobre o escopo dos dados e evite trabalho extra.
Notas para chamadores
Normalmente, você acabará com tantas linhas quanto especificou no parâmetro lRowCount . No entanto, quando os limites de memória ou implementação forem um problema ou quando a operação atingir o início ou o fim da tabela prematuramente, o QueryRows retornará menos linhas do que o solicitado.
Se QueryRows retornar MAPI_E_BUSY, chame o método IMAPITable::WaitForCompletion e tente novamente a chamada para QueryRows quando a operação assíncrona estiver concluída.
Ao chamar QueryRows, esteja ciente de que o tempo das notificações assíncronas pode potencialmente fazer com que o conjunto de linhas que você obtém de QueryRows não represente com precisão os dados subjacentes. Por exemplo, uma chamada para QueryRows para a tabela de conteúdo de uma pasta após a exclusão de uma mensagem, mas antes do recebimento da notificação correspondente fará com que a linha excluída seja retornada no conjunto de linhas. Sempre aguarde a chegada de uma notificação antes de atualizar a exibição do usuário dos dados.
Para obter mais informações sobre como recuperar linhas de tabelas, consulte Recuperando dados de linhas de tabela.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
O MFCMAPI usa o método IMAPITable::QueryRows para recuperar linhas na tabela para carregar no modo de exibição. |