Propriedades canônicas MAPI
Aplica-se a: Outlook 2013 | Outlook 2016
Uma propriedade canônica é uma propriedade virtual que representa uma propriedade MAPI ou várias propriedades MAPI definidas com o mesmo identificador de propriedade. As propriedades canônicas destinam-se apenas a facilitar a identificação consistente de propriedades MAPI em discussões ou documentação fora do código. Ao contrário dos nomes de propriedade marcados definidos pelo MAPI, os nomes de propriedades canônicas não são definidos como constantes globais em arquivos de cabeçalho MAPI.
Convenções de nomenclatura
Os nomes de propriedades canônicas começam com um prefixo, "Pid", que representa "identificador de propriedade". Dependendo se a propriedade é uma propriedade marcada, uma propriedade nomeada com um identificador numérico ou uma propriedade nomeada com um nome de cadeia de caracteres, o prefixo é ainda mais qualificado como "PidTag", "PidLid" e "PidName" respectivamente. Por exemplo, PidTagAccount representa as propriedades marcadas, PR_ACCOUNT (PidTagAccount), PR_ACCOUNT_A (PidTagAccount) e PR_ACCOUNT_W (PidTagAccount), que especificam o nome da conta de um destinatário; PidLidContacts representa a propriedade dispidContacts , uma propriedade nomeada que tem um identificador numérico e que especifica o nome dos contatos associados a uma mensagem; e PidNamePhishingStamp representa "http://schemas.microsoft.com/outlook/phishingstamp", uma propriedade nomeada que tem um nome de cadeia de caracteres e que especifica as mensagens de marcação de cadeia de caracteres que provavelmente serão phishing.
Representando propriedades semelhantes usando uma propriedade canônica
Identificando propriedades no MAPI
Todas as propriedades no MAPI são identificadas por um identificador de propriedade que é um valor não assinado de 16 bits. O identificador de propriedade e o tipo de propriedade (outro valor não assinado de 16 bits) constituem uma marca de propriedade para a propriedade.
O MAPI usa uma marca de propriedade para definir propriedades exclusivamente. Propriedades que têm a mesma marca de propriedade, como PR_BUSINESS2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber) e PR_OFFICE2_TELEPHONE_NUMBER (PidTagBusiness2TelephoneNumber), são consideradas propriedades idênticas no MAPI. Para obter uma lista de marcas de propriedade definidas pela MAPI para suas próprias propriedades, consulte o arquivo de cabeçalho MAPI, Mapitags.h.
Observe que o MAPI divide os identificadores de propriedade em intervalos. Quando um identificador cai no intervalo indica seu uso e propriedade. Os identificadores de propriedade de propriedades marcadas caem no intervalo de 0x0001 a 0x7FFF. Dentro desse intervalo estão os identificadores de propriedade de propriedades definidas pelo MAPI, que se enquadram no intervalo de 0x0001 a 0x3FFF. Os identificadores de propriedade de propriedades nomeadas caem no intervalo de 0x8000 a 0x8FFF.
As propriedades nomeadas também são atribuídas por um conjunto de propriedades e uma LID (ID longa), que é um valor não assinado de 32 bits ou uma cadeia de caracteres. Um conjunto de propriedades é um GUID que identifica um grupo de propriedades nomeadas com uma finalidade semelhante. O conjunto de propriedades e LID ou nome da cadeia de caracteres são usados para obter ou definir a propriedade nomeada.
Tipo de propriedade
Além dos identificadores, uma propriedade é atribuída por um tipo de dados que especifica o tipo de valores permitidos para essa propriedade.
Para propriedades do tipo de cadeia de caracteres, dependendo do suporte para Unicode na plataforma subjacente, a propriedade pode ser do tipo PT_STRING8 (cadeia de caracteres de 8 bits terminada nulo) ou PT_UNICODE (cadeia de caracteres Unicode terminada em nulo). Uma propriedade pode ser definida com o tipo PT_TSTRING e, dependendo das configurações de compilação, PT_TSTRING padrões para uma cadeia de caracteres Unicode para plataformas que dão suporte ao Unicode ou a uma cadeia de caracteres PT_STRING8 para plataformas compatíveis com ANSI ou DBCS. É comum que uma propriedade tipo cadeia de caracteres seja identificada por três nomes semelhantes, como PR_ACCOUNT, PR_ACCOUNT_A e PR_ACCOUNT_W, que são do tipo PT_TSTRING, PT_STRING8 e PT_UNICODE, respectivamente.
Para obter mais informações sobre tipos de propriedade e macros relacionados a tipos, consulte o arquivo de cabeçalho MAPI, Mapidefs.h.
Identificando propriedades semelhantes
No cenário atual da propriedade MAPI, não é incomum descobrir que uma propriedade foi exposta sob nomes de propriedade diferentes, todos definidos com o mesmo identificador de propriedade. Por exemplo, as propriedades marcadas, PR_BUSINESS2_TELEPHONE_NUMBER e PR_OFFICE2_TELEPHONE_NUMBER, são definidas em Mapitags.h para ter o mesmo identificador e tipo de propriedade. Intimamente relacionadas a essas duas propriedades estão:
PR_BUSINESS2_TELEPHONE_NUMBER_A
PR_BUSINESS2_TELEPHONE_NUMBER_W
PR_OFFICE2_TELEPHONE_NUMBER_A
PR_OFFICE2_TELEPHONE_NUMBER_W
As propriedades com o sufixo "_A" são tipada como PT_STRING8, e aquelas com o sufixo "_W" são tipada como PT_UNICODE.
A finalidade de uma propriedade canônica, PidTagBusiness2TelephoneNumber neste exemplo, é facilitar a referência a propriedades MAPI afiliadas de perto usando um identificador e de forma consistente (usando o prefixo "Pid") em todas as propriedades MAPI. Para encontrar quais propriedades MAPI reais uma propriedade canônica representa, consulte Mapeando nomes de propriedades canônicas para nomes MAPI. Para encontrar a propriedade canônica à qual uma propriedade MAPI está associada, consulte Mapi Names to Canonical Property Names.
Suporte mapi de nomes de propriedades canônicas
Como as propriedades canônicas não são propriedades reais e não são definidas em arquivos de cabeçalho MAPI, você não deve usar nomes de propriedades canônicas no código; Em vez disso, você deve continuar a usar os nomes exatos da propriedade MAPI no código. Por exemplo, você pode consultar PR_BUSINESS2_TELEPHONE_NUMBER e PR_OFFICE2_TELEPHONE_NUMBER fora do código como PidTagBusiness2TelephoneNumber e usar PR_BUSINESS2_TELEPHONE_NUMBER ou PR_OFFICE2_TELEPHONE_NUMBER no código.
Se você precisar usar nomes de propriedades canônicas em seu código, primeiro defina-os em seus próprios arquivos de cabeçalho.
Nomes de propriedade canônica e especificações do protocolo exchange
Nomes canônicos são referenciados em Microsoft Exchange Server especificações de protocolo usadas por Exchange Server para se comunicar com outros produtos da Microsoft. Para obter mais informações sobre as propriedades do objeto de mensagem referenciadas pelas especificações de protocolo do Exchange, consulte [MS-OXPROPS].