Visão geral do tipo de propriedade MAPI
Aplica-se a: Outlook 2013 | Outlook 2016
Tipos de propriedade são constantes definidas pelo MAPI no MAPIDEFS. Arquivo de cabeçalho H que indica o tipo de dados subjacente de um valor de propriedade. Todas as propriedades, sejam elas definidas pelo MAPI, por aplicativos cliente ou por provedores de serviços, usam um desses tipos.
Os tipos de propriedade seguem uma convenção de nomenclatura semelhante à usada para marcas de propriedade. Muitos tipos de propriedade têm uma versão de valor único e de vários valores. As propriedades com valor único contêm um valor de seu tipo, como um único inteiro ou uma cadeia de caracteres. A constante usada para representar uma propriedade de valor único tem duas partes: o prefixo PT_ e uma cadeia de caracteres que descreve o tipo real, como LONG ou STRING8.
As propriedades de vários valores contêm mais de um valor de seu tipo. Ao contrário das matrizes de varianteS OLE, cada valor em uma propriedade multivalued é do mesmo tipo. A constante usada para representar propriedades multivaluadas é criada combinando o sinalizador MV_FLAG com a constante de valor único correspondente que representa o tipo base. Há três partes: o prefixo PT_ seguido por MV_ seguido por uma cadeia de caracteres que descreve o tipo. Por exemplo, o tipo de uma propriedade que contém vários inteiros é PT_MV_LONG e para várias cadeias de caracteres é PT_MV_STRING8.
A ilustração a seguir mostra a estrutura de uma estrutura SPropValue para descrever um inteiro de vários valores, uma propriedade do tipo PT_MV_LONG. O membro Value é expandido para incluir uma contagem do número de valores inteiros na propriedade e um ponteiro para uma matriz desses valores.
Multiple-value properties
Embora o suporte para propriedades de vários valores seja opcional, o MAPI recomenda que clientes e provedores de serviços dêem suporte a ambos os tipos de propriedades, pois isso permite maior interação entre componentes compatíveis com MAPI.
A ilustração a seguir lista todas as diferentes constantes de tipo de propriedade, mostrando onde elas são armazenadas em uma estrutura SPropValue . O tamanho do membro Value depende do tipo específico. Observe que nem todos os tipos de valor único têm equivalentes de vários valores.
Property type constants
Clientes e provedores de serviços que trabalham com uma propriedade precisam seguir duas etapas:
Determine se a propriedade está disponível ou indisponível.
Se estiver disponível, recupere o valor da propriedade.
Às vezes, um cliente ou provedor de serviços precisa apenas de marcar para a existência de uma propriedade; outras vezes é necessário marcar para um valor específico. Por exemplo, os provedores de transporte têm três cursos de ação diferentes para processar a propriedade PR_SEND_RICH_INFO (PidTagSendRichInfo), um valor booliano que indica se uma mensagem deve ou não ser transmitida com texto formatado. Se PR_SEND_RICH_INFO for definido como TRUE, o provedor de transporte transmitirá o texto formatado. Se for definido como FALSE, o texto formatado será descartado antes da transmissão. Se PR_SEND_RICH_INFO não estiver disponível, o provedor de transporte seguirá seu curso de ação padrão, seja o que for para o provedor específico.
O MAPI define um tipo de propriedade especial, PT_UNSPECIFIED, que um cliente ou provedor de serviços pode usar para recuperar uma propriedade quando o tipo de propriedade é desconhecido. Para recuperar uma propriedade sem conhecimento prévio de seu tipo, um cliente ou provedor de serviços chama o método IMAPIProp::GetProps de um objeto e passa uma marca de propriedade composta pelo identificador da propriedade e pelo tipo de propriedade PT_UNSPECIFIED. GetProps retorna uma estrutura SPropValue para a propriedade, substituindo PT_UNSPECIFIED pelo tipo apropriado. Os provedores de serviço que implementam GetProps são necessários para dar suporte a PT_UNSPECIFIED.
Alguns objetos MAPI dão suporte a propriedades que são objetos próprios. As propriedades do objeto têm o tipo PT_OBJECT. Em vez de usar IMAPIProp::GetProps para acessar essas propriedades, clientes e provedores de serviço normalmente usam o método IMAPIProp::OpenProperty , especificando a interface apropriada para acesso ou um método no objeto que dá suporte à propriedade.
Como acessar o valor de uma propriedade de objeto envolve o uso de uma das interfaces do objeto, GetProps é inapropriado. Com GetProps, o chamador acessa o valor de uma propriedade por meio de uma estrutura SPropValue . Com IMAPIProp::OpenProperty, o chamador recupera um ponteiro para uma interface que pode acessar o objeto. OpenProperty sempre pode ser usado para recuperar uma propriedade de objeto. A outra opção, chamando um método no objeto, não está disponível com todas as propriedades do objeto.
Por exemplo, cada pasta dá suporte a duas tabelas, uma tabela de hierarquia e uma tabela de conteúdo. Essas tabelas são propriedades da pasta; suas marcas de propriedade são PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) e PR_CONTAINER_CONTENTS (PidTagContainerContents). Tabelas são objetos que exigem a interface IMAPITable para acesso. Um cliente pode chamar o método IMAPIContainer::GetHierarchyTable da pasta para acessar a tabela de hierarquia, o método IMAPIContainer::GetContentsTable da pasta para acessar a tabela de conteúdo ou o método IMAPIProp::OpenProperty da pasta para acessar qualquer tabela. Para chamar OpenProperty, um cliente passa a marca de propriedade para a propriedade como o primeiro parâmetro e um identificador de interface para a interface a ser usada para acesso como o segundo parâmetro. Esses parâmetros seriam PR_CONTAINER_HIERARCHY ou PR_CONTAINER_CONTENTS e IID_IMAPITable.
Para obter uma lista completa dos tipos de propriedade de valor único e de vários valores, consulte Tipos de Propriedade.