IMAPITable::ExpandRow
Aplica-se a: Outlook 2013 | Outlook 2016
Localiza a linha seguinte numa tabela que corresponde a critérios de pesquisa específicos e move o cursor para essa linha.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Parâmetros
lpRestriction
[in] Um ponteiro para uma estrutura SRestriction que descreve os critérios de pesquisa.
BkOrigin
[in] Um marcador que identifica a linha onde FindRow deve iniciar a pesquisa. Um marcador pode ser criado com o método IMAPITable::CreateBookmark ou pode ser transmitido um dos seguintes valores predefinidos.
BOOKMARK_BEGINNING
Procura a partir do início da tabela.
BOOKMARK_CURRENT
Procura a partir da linha na tabela onde o cursor está localizado.
BOOKMARK_END
Procura a partir do fim da tabela.
ulFlags
[in] Uma máscara de bits de sinalizadores que controla a direção da pesquisa. Pode definir o seguinte sinalizador:
DIR_BACKWARD
Procura para trás a partir da linha identificada pelo marcador.
Valor de retorno
S_OK
A operação de localização foi concluída com êxito.
MAPI_E_INVALID_BOOKMARK
O marcador no parâmetro BkOrigin é inválido porque foi removido ou porque está para além da última linha pedida.
MAPI_E_NOT_FOUND
Não foram encontradas linhas que correspondam à restrição.
MAPI_W_POSITION_CHANGED
A chamada foi efetuada com êxito, mas o marcador utilizado na operação já não está definido na mesma linha da última vez que foi utilizada; Se o marcador não tiver sido utilizado, deixará de estar na mesma posição que quando foi criado. Quando este aviso é devolvido, a chamada deve ser processada com êxito. Para testar este aviso, utilize a macro HR_FAILED . Veja Utilizar Macros para Processamento de Erros.
Comentários
O método IMAPITable::FindRow localiza a primeira linha na tabela para corresponder a um conjunto de critérios de pesquisa descritos na estrutura SRestriction apontada pelo parâmetro lpRestriction .
Normalmente, FindRow procura para a frente a partir do marcador especificado. O autor da chamada pode definir a pesquisa para retroceder a partir do marcador ao definir o sinalizador DIR_BACKWARD no parâmetro ulFlags . A pesquisa para a frente começa a partir do marcador atual; procurar para trás começa a partir da linha anterior ao marcador. A posição final da pesquisa é imediatamente antes de a primeira linha ter sido encontrada que satisfez a restrição.
Se a linha apontada pelo marcador no parâmetro BkOrigin já não existir na tabela e a tabela não conseguir estabelecer uma nova posição para o marcador, FindRow devolve MAPI_E_INVALID_BOOKMARK. Se a linha apontada por BkOrigin já não existir e a tabela conseguir estabelecer uma nova posição para o marcador, FindRow devolve MAPI_W_POSITION_CHANGED.
Se o marcador transmitido em BkOrigin for BOOKMARK_BEGINNING ou BOOKMARK_END, FindRow devolve MAPI_E_NOT_FOUND se não for encontrada nenhuma linha correspondente. Se o marcador utilizado em BkOrigin for BOOKMARK_CURRENT, FindRow pode devolver MAPI_W_POSITION_CHANGED, mas não MAPI_E_INVALID_BOOKMARK porque existe sempre uma posição atual do cursor.
A coluna de propriedades PR_INSTANCE_KEY (PidTagInstanceKey) é necessária para todas as tabelas e todas as implementações de FindRow são necessárias para suportar chamadas que procuram uma linha com base em PR_INSTANCE_KEY.
Observações para implementadores
O tipo de pesquisa de prefixo efetuada por FindRow só é útil quando a pesquisa segue a mesma direção que a organização da tabela. Para alcançar o comportamento necessário, a função de comparação implícita na RELOP_GE transmitida na estrutura de restrição de propriedades deve ser a mesma função de comparação na qual a sequência de ordenação da tabela se baseia.
Notas para chamadores
Pode utilizar FindRow para suportar o deslocamento com base em cadeias escritas pelo utilizador, especialmente em caixas de listagem nas caixas de diálogo de endereço. Neste tipo de deslocamento, os utilizadores introduzem prefixos progressivamente mais longos de um valor de cadeia pretendido e pode emitir periodicamente uma chamada FindRow para saltar para a primeira linha que corresponde ao prefixo. A direção em que o cursor salta depende da direção em que a pesquisa está definida para ser executada.
Para utilizar FindRow, tem de ser definido um marcador. A pesquisa de cadeias pode ter origem em qualquer marcador, incluindo a partir dos marcadores predefinidos que indicam a posição atual e o início e o fim da tabela. Se houver um grande número de linhas na tabela, a operação de pesquisa pode ser lenta.
Utilize uma restrição para localizar um prefixo de cadeia para deslocar da seguinte forma. Para reencaminhar a pesquisa numa coluna ordenada por ordem ascendente e para retroceder numa coluna ordenada por ordem descendente, transmita uma estrutura de restrição de propriedades no parâmetro lpRestriction com a relação RELOP_GE e a etiqueta de propriedade e prefixo adequados, utilizando o prefixoGE da etiqueta de formato.
Para obter mais informações sobre como utilizar estruturas de restrição para especificar um filtro, veja Acerca das Restrições.
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 utiliza o método IMAPITable::FindRow para encontrar linhas que correspondam a uma restrição. |