IMAPITable::SetColumns
Aplica-se a: Outlook 2013 | Outlook 2016
Define as propriedades específicas e a ordem das propriedades a serem exibidas como colunas na tabela.
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);
Parâmetros
Lpproptagarray
[in] Ponteiro para uma matriz de marcas de propriedade que identificam propriedades a serem incluídas como colunas na tabela. A parte do tipo de propriedade de cada marca pode ser definida como um tipo válido ou para PR_NULL reservar espaço para adições subsequentes. O parâmetro lpPropTagArray não pode ser definido como NULL; cada tabela deve ter pelo menos uma coluna.
ulFlags
[in] Bitmask de sinalizadores que controla o retorno de uma chamada assíncrona para SetColumns, por exemplo, quando SetColumns é usado na notificação. Os seguintes sinalizadores podem ser definidos:
TBL_ASYNC
Solicita que a operação de configuração de coluna seja executada de forma assíncrona, fazendo com que SetColumns retorne potencialmente antes que a operação seja totalmente concluída.
TBL_BATCH
Permite que a tabela adie a operação de configuração de coluna até que os dados sejam realmente necessários.
Valor de retorno
S_OK
A operação de configuração de coluna foi bem-sucedida.
MAPI_E_BUSY
Outra operação está em andamento que impede o início da operação de configuração de coluna. A operação em andamento deve ser autorizada a ser concluída ou deve ser interrompida.
Comentários
O conjunto de colunas de uma tabela é o grupo de propriedades que compõem as colunas para as linhas na tabela. Há um conjunto de colunas padrão para cada tipo de tabela. O conjunto de colunas padrão é composto pelas propriedades que o implementador de tabela inclui automaticamente. Os usuários da tabela podem alterar esse conjunto padrão chamando o método IMAPITable::SetColumns . Eles podem solicitar que outras colunas sejam adicionadas ao conjunto padrão se o implementador de tabela dá suporte a elas para que as colunas sejam removidas ou que a ordem das colunas seja alterada. SetColumns especifica as colunas que são retornadas com cada linha e a ordem dessas colunas dentro da linha.
O sucesso da operação SetColumns é aparente somente após uma chamada subsequente ter sido feita para recuperar os dados da tabela. É então que todos os erros são relatados.
Observações para implementadores
Alguns provedores permitem que uma chamada SetColumns peça apenas colunas de tabela que fazem parte das colunas disponíveis para uma exibição de tabela. Outros provedores permitem que uma chamada SetColumns peça todas as colunas de tabela, incluindo aquelas que contêm propriedades que não estão no conjunto de colunas original.
Quando TBL_BATCH é definido para operações assíncronas, os provedores devem retornar um tipo de propriedade de PT_ERROR e um valor de propriedade de NULL para colunas que não têm suporte.
Você não precisa responder ao sinalizador TBL_ASYNC solicitando que a operação seja assíncrona. Se você não dá suporte à definição de conjunto de colunas assíncrona, execute a operação de forma síncrona. Se você puder dar suporte ao sinalizador TBL_ASYNC e outra operação assíncrona ainda estiver em andamento, retorne MAPI_E_BUSY. Caso contrário, retorne S_OK independentemente de dar suporte ou não a todas as propriedades incluídas na matriz de marcas de propriedade. Erros resultantes de propriedades sem suporte devem ser retornados de métodos IMAPITable que recuperam dados, como QueryRows.
Não gere notificações para linhas de tabela ocultas do modo de exibição por chamadas para Restringir.
Ao enviar notificações de tabela, a ordem das propriedades no membro da linha da estrutura TABLE_NOTIFICATION e a ordem especificada pela chamada SetColumns mais recente devem ser as mesmas do momento em que a solicitação de notificação foi enviada.
Outro sinalizador, TBL_BATCH, permite que os chamadores especifiquem que o implementador de tabela pode adiar a avaliação dos resultados da operação até uma hora posterior. Sempre que possível, os chamadores devem definir esse sinalizador porque a operação em lote melhora o desempenho.
Geralmente, é conveniente que os chamadores reservem algumas colunas no conjunto de linhas recuperadas para que os valores sejam adicionados posteriormente. Os chamadores fazem isso colocando PR_NULL (PidTagNull) nas posições desejadas na matriz de marcas de propriedade passadas para SetColumns; em seguida, a tabela passará PR_NULL nessas posições em todas as linhas recuperadas com QueryRows.
Notas para chamadores
Ao criar a matriz de marcas de propriedade para o parâmetro lpPropTagArray , peça as marcas na ordem em que você deseja que as colunas apareçam no modo de exibição da tabela.
Você pode especificar propriedades multivaloradas a serem incluídas no conjunto de colunas aplicando o sinalizador de instância multivalued ou MVI_FLAG constante à marca de propriedade. Defina esse sinalizador passando a marca de propriedade para a versão de valor único da propriedade como um parâmetro para a macro MVI_PROP da seguinte maneira:
MVI_PROP(ulPropTag)
A macro MVI_PROP definirá MVI_FLAG para a propriedade, transformando a marca em uma marca multivalida. Se você tentar chamar erroneamente MVI_PROP em uma propriedade de valor único, a MAPI ignorará a chamada e deixará a marca de propriedade inalterada.
Você pode incluir marcas de propriedade definidas como PR_NULL na matriz de marcas de propriedade para reservar espaço no conjunto de colunas. Reservar espaço permite que você adicione a um conjunto de colunas sem precisar alocar uma nova matriz de marcas de propriedade.
Quando sua chamada para SetColumns causa uma alteração na ordem das colunas de uma tabela e uma ou mais dessas colunas representam uma propriedade multivalida, é possível aumentar o número de linhas na tabela. Se isso ocorrer, todos os indicadores da tabela serão descartados. Para obter mais informações sobre como as colunas multivalorizadas afetam tabelas, consulte Trabalhando com Colunas Multivaluadas.
Definir colunas é, por padrão, uma operação síncrona. No entanto, você pode permitir que a tabela adie a operação até que os dados sejam necessários definindo o sinalizador TBL_BATCH. Definir esse sinalizador pode melhorar o desempenho. Outro sinalizador, TBL_ASYNC, torna a operação assíncrona, permitindo que SetColumns retorne antes que a operação seja concluída. Para determinar quando ocorre a conclusão, chame IMAPITable::GetStatus.
Se uma chamada para SetColumns retornar MAPI_E_BUSY, indicando que outra operação está impedindo que sua operação seja iniciada, você poderá chamar IMAPITable::Abort para interromper a operação em andamento.
Você também pode chamar HrAddColumnsEx para alterar um conjunto de colunas. A diferença entre HrAddColumnsEx e IMAPITable::SetColumns é que HrAddColumnsEx é menos flexível; ele só pode adicionar colunas. As colunas adicionais são colocadas no início do conjunto de colunas; todas as colunas existentes aparecem seguindo essas colunas.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl::D oSetColumns |
O MFCMAPI usa o método IMAPITable::SetColumns para definir as colunas desejadas para a tabela. |