IMAPIProp::GetIDsFromNames
Aplica-se a: Outlook 2013 | Outlook 2016
Fornece os identificadores de propriedade que correspondem a um ou mais nomes de propriedade.
HRESULT GetIDsFromNames(
ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
);
Parâmetros
cPropNames
[in] A contagem de nomes de propriedades apontados pelo parâmetro lppPropNames . Se lppPropNames for NULL, o parâmetro cPropNames deverá ser 0.
lppPropNames
[in] Um ponteiro para uma matriz de nomes de propriedade ou NULL. Passar identificadores de propriedade de solicitações NULL para todos os nomes de propriedade em todos os conjuntos de propriedades sobre os quais o objeto tem informações. O parâmetro lppPropNames não deve ser NULL se o sinalizador MAPI_CREATE for definido no parâmetro ulFlags .
ulFlags
[in] Um bitmask de sinalizadores que indica como os identificadores de propriedade devem ser retornados. O seguinte sinalizador pode ser definido:
MAPI_CREATE
Atribui um identificador de propriedade, se ainda não tiver sido atribuído, a um ou mais nomes incluídos na matriz de nomes de propriedade apontada por lppPropNames. Esse sinalizador registra internamente o identificador na tabela de mapeamento nome a identificador.
lppPropTags
[out] Um ponteiro para um ponteiro para uma matriz de marcas de propriedade que contém identificadores de propriedade existentes ou recém-atribuídos. Os tipos de propriedade para as marcas de propriedade nesta matriz são definidos como PT_UNSPECIFIED.
Valor de retorno
S_OK
Os identificadores dos nomes de propriedade especificados foram retornados com êxito.
MAPI_E_NO_SUPPORT
O objeto não dá suporte a propriedades nomeadas.
MAPI_E_NOT_ENOUGH_MEMORY
Memória insuficiente estava disponível para recuperar os identificadores.
MAPI_E_TOO_BIG
A operação não pode ser executada porque requer muitas marcas de propriedade a serem retornadas.
MAPI_W_ERRORS_RETURNED
A chamada foi bem-sucedida no geral, mas um ou mais identificadores de propriedade não puderam ser retornados. O tipo de propriedade correspondente para cada propriedade indisponível é definido como PT_ERROR e seu identificador como zero. Quando esse aviso for retornado, lide com a chamada como bem-sucedida. Para testar esse aviso, use a macro HR_FAILED . Consulte Usando macros para tratamento de erros.
Comentários
O método IMAPIProp::GetIDsFromNames recupera uma matriz de marcas de propriedade que contêm os identificadores de propriedade para uma ou mais propriedades nomeadas. IMAPIProp::GetIDsFromNames pode ser chamado para fazer o seguinte:
Crie identificadores para novos nomes.
Recupere identificadores para nomes específicos.
Recupere identificadores para todas as propriedades nomeadas incluídas no mapeamento do objeto.
As propriedades nomeadas normalmente são usadas por provedores de armazenamento de mensagens para pastas e mensagens. Outros objetos, como usuários de mensagens e seções de perfil, podem não dar suporte à associação de nomes a identificadores de propriedade e podem retornar MAPI_E_NO_SUPPORT do GetIDsFromNames.
Se houver um erro que retorna um identificador para um nome específico, GetIDsFromNames retornará MAPI_W_ERRORS_RETURNED e definirá o tipo de propriedade na entrada da matriz de marca de propriedade que corresponde ao nome a PT_ERROR e ao identificador como zero.
O mapeamento nome a identificador é representado pela propriedade PR_MAPPING_SIGNATURE de um objeto (PidTagMappingSignature). PR_MAPPING_SIGNATURE contém uma estrutura MAPIUID que indica o provedor de serviços responsável pelo objeto. Se a propriedade PR_MAPPING_SIGNATURE for a mesma para dois objetos, suponha que esses objetos usem o mesmo mapeamento nome a identificador.
Observações para implementadores
Os identificadores que você passa de volta na matriz de marcas de propriedade apontadas pelo parâmetro lppPropNames devem estar no 0x8000 para 0xFFFE intervalo. As entradas nesta matriz devem estar na mesma ordem que os nomes passados na matriz de nome da propriedade apontada por lppPropNames.
Se você dá suporte a propriedades nomeadas em um contêiner, use o mesmo mapeamento nome a identificador para todos os objetos em seu contêiner (ou seja, não use um mapeamento diferente para cada pasta em seu repositório de mensagens ou cada mensagem em sua pasta).
Notas para chamadores
Como os tipos de propriedade para os identificadores retornados na matriz de marcas de propriedade apontadas por lppPropTags estão definidos como PT_UNSPECIFIED, você terá que chamar o método IMAPIProp::SetProps para recuperar os tipos precisos.
Se você mover ou copiar objetos com propriedades nomeadas e os objetos de origem e de destino tiverem assinaturas de mapeamento diferentes, conforme indicado pelos valores de suas propriedades PR_MAPPING_SIGNATURE , você deverá preservar os nomes durante essas operações. Para preservar nomes de propriedades, ajuste os identificadores de propriedade correspondentes para corresponder ao mapeamento nome a identificador do objeto de destino.
Alguns objetos têm um limite quanto ao número de identificadores de propriedade que podem nomear. Se uma chamada para GetIDsFromNames fizer com que esse limite seja excedido, o método retornará MAPI_E_TOO_BIG. Nesse caso, consulta por identificador.
Para obter mais informações, consulte Propriedades nomeadas mapi.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl::FindAllNamedPropsUsed |
O MFCMAPI usa o método IMAPIProp::GetIDsFromNames para obter marcas de propriedade para todas as propriedades nomeadas que foram mapeadas. |