IMAPITable::SeekRow
Aplica-se a: Outlook 2013 | Outlook 2016
Move o cursor para uma posição específica na tabela.
HRESULT SeekRow(
BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
);
Parâmetros
bkOrigin
[in] O indicador que identifica a posição inicial da operação de busca. Um indicador pode ser criado usando o método IMAPITable::CreateBookmark ou um dos seguintes valores predefinidos pode ser passado.
BOOKMARK_BEGINNING
Inicia a operação de busca desde o início da tabela.
BOOKMARK_CURRENT
Inicia a operação de busca da linha na tabela em que o cursor está localizado.
BOOKMARK_END
Inicia a operação de busca do final da tabela.
lRowCount
[in] A contagem assinada do número de linhas a serem movidas, a partir do indicador identificado pelo parâmetro bkOrigin .
lplRowsSought
[out] Se lRowCount for um ponteiro válido na entrada, lplRowsSought apontará para o número de linhas processadas na operação de busca, cujo sinal indica a direção da pesquisa, para frente ou para trás. Se lRowCount for negativo, lplRowsSought será negativo.
Valor de retorno
S_OK
A operação de busca foi bem-sucedida.
MAPI_E_BUSY
Outra operação está em andamento que impede o início da operação de busca de linhas. A operação em andamento deve ser autorizada a ser concluída ou deve ser interrompida.
MAPI_E_INVALID_BOOKMARK
O indicador especificado no parâmetro bkOrigin é inválido porque foi removido ou porque está além da última linha solicitada.
MAPI_W_POSITION_CHANGED
A chamada foi bem-sucedida, mas o indicador especificado no parâmetro bkOrigin não é mais definido na mesma linha que era quando foi usado pela última vez. Se o indicador não tiver sido usado, ele não estará mais na mesma posição que estava quando foi criado. Quando esse aviso é retornado, a chamada deve ser tratada como bem-sucedida. Para testar esse aviso, use a macro HR_FAILED . Para obter mais informações, confira Usando macros para tratamento de erros.
Comentários
O método IMAPITable::SeekRow estabelece uma nova posição BOOKMARK_CURRENT para o cursor. O parâmetro lRowCount indica o número de linhas que o cursor move e a direção do movimento.
Se a posição resultante estiver além da última linha da tabela, o cursor será posicionado após a última linha. Se a posição resultante for antes da primeira linha da tabela, o cursor será posicionado no início da primeira linha.
Observações para implementadores
Se a linha apontada por bkOrigin não existir mais na tabela e você não puder estabelecer uma nova posição para o indicador, retorne MAPI_E_INVALID_BOOKMARK. Se a linha apontada para by_bkOrigin_no existir mais e você puder estabelecer uma nova posição para o indicador, retorne MAPI_W_POSITION_CHANGED.
Um indicador que aponta para uma linha que é recolhida do modo de exibição da tabela ainda pode ser usado. Se o chamador tentar mover o cursor para esse indicador, mova o cursor para a próxima linha visível e retorne MAPI_W_POSITION_CHANGED.
Você pode mover indicadores para posições recolhidas fora de exibição, no momento do uso ou no momento em que a linha é recolhida. Se um indicador for movido no momento em que a linha é recolhida, mantenha um pouco no indicador que indica se o indicador foi movido desde seu último uso ou, se nunca foi usado, desde sua criação.
Notas para chamadores
Para indicar um movimento para trás para SeekRow, passe um valor negativo em lRowCount. Para pesquisar até o início da tabela, passe zero no lRowCount e o valor BOOKMARK_BEGINNING no bkOrigin.
Se houver muitas linhas na tabela, a operação SeekRow poderá ser lenta. O desempenho também poderá ser afetado se você precisar que uma contagem de linhas seja retornada no conteúdo do parâmetro lplRowsSought .
SeekRow retorna o número de linhas realmente pesquisadas, positivas ou negativas, na variável apontada por lRowCount. Na operação comum, ele deve retornar o mesmo valor para lplRowsSought conforme passado para lRowCount, a menos que a pesquisa tenha atingido o início ou o final da tabela.
Não defina lRowCount como um número maior que 50. Para procurar por um número maior de linhas, use o método IMAPITable::SeekRowApprox .
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| MAPIProcessor.cpp |
CMAPIProcessor::P rocessMailboxTable |
O MFCMAPI usa o método IMAPITable::SeekRow para localizar o início da tabela antes do processamento. |