IMAPIProp::GetNamesFromIDs
Aplica-se a: Outlook 2013 | Outlook 2016
Fornece os nomes de propriedade que correspondem a um ou mais identificadores de propriedade.
HRESULT GetNamesFromIDs(
LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
);
Parâmetros
lppPropTags
[in, out] Na entrada, um ponteiro para uma estrutura SPropTagArray que contém uma matriz de marcas de propriedade; caso contrário, NULL, indicando que todos os nomes devem ser retornados. O membro cValues da matriz de marcas de propriedade não pode ser 0. Se lppPropTags for um ponteiro válido na entrada, GetNamesFromIDs retornará nomes para cada identificador de propriedade incluído na matriz.
lpPropSetGuid
[in] Um ponteiro para uma estrutura GUID ou GUID que identifica um conjunto de propriedades. O parâmetro lpPropSetGuid pode apontar para um conjunto de propriedades válido ou pode ser NULL.
ulFlags
[in] Um bitmask de sinalizadores que indica o tipo de nomes a serem retornados. Os sinalizadores a seguir podem ser usados (se ambos os sinalizadores forem definidos, nenhum nome será retornado):
MAPI_NO_IDS
Solicita que apenas nomes armazenados como cadeias de caracteres Unicode sejam retornados.
MAPI_NO_STRINGS
Solicitações para que apenas nomes armazenados como identificadores numéricos sejam retornados.
lpcPropNames
[out] Um ponteiro para uma contagem dos ponteiros de nome da propriedade na matriz apontada pelo parâmetro lppPropNames .
lpppPropNames
[out] Um ponteiro para uma matriz de ponteiros para estruturas MAPINAMEID que contém nomes de propriedade.
Valor de retorno
S_OK
Os nomes da propriedade foram retornados com êxito.
MAPI_E_NO_SUPPORT
O objeto não dá suporte a propriedades nomeadas.
MAPI_W_ERRORS_RETURNED
A chamada foi bem-sucedida no geral, mas os nomes de uma ou mais propriedades não puderam ser retornados. As marcas de propriedade das propriedades com falha têm um tipo de propriedade de PT_ERROR. Quando esse aviso é retornado, a chamada deve ser tratada como bem-sucedida. Para testar esse aviso, use a macro HR_FAILED . Para obter mais informações, confira Usando macros para tratamento de erros.
MAPI_E_INVALID_PARAMETER
O membro cValues de uma ou mais das entradas na matriz de marcas de propriedade apontada por lppPropTags está definido como 0.
Comentários
Embora o acesso à maioria das propriedades seja por identificador de propriedade, algumas propriedades podem ser acessadas pelo nome. O método IMAPIProp::GetNamesFromIDs pode ser chamado para fazer o seguinte:
Recupere nomes para identificadores de propriedade específicos em um conjunto de propriedades específico.
Recupere nomes para identificadores de propriedade específicos em qualquer conjunto de propriedades.
Recupere nomes para todas as propriedades nomeadas incluídas no mapeamento do objeto.
Se lppPropTags apontar para uma matriz de marca de propriedade válida com um ou mais identificadores de propriedade e lpPropSetGuid apontar para um conjunto de propriedades válido, GetNamesFromIDs ignorará o conjunto de propriedades e os tipos de propriedade e retornará todos os nomes que mapeiam para os identificadores especificados.
Se lppPropTags apontar para uma matriz de marca de propriedade válida com um ou mais identificadores de propriedade e lpPropSetGuid for NULL, GetNamesFromIDs retornará todos os nomes que mapeiam para os identificadores especificados.
Se um identificador especificado não tiver um nome, GetNamesFromIDs retornará NULL no lugar desse identificador na estrutura retornada em lpppPropNames e também retornará MAPI_W_ERRORS_RETURNED.
Se lpPropSetGuid e lppPropTags forem NULL, GetNamesFromIDs alocará uma nova matriz de marcas de propriedade e retornará todos os nomes para todas as propriedades nomeadas para o objeto.
Quando não há nomes a serem retornados, talvez porque não haja propriedades no conjunto de propriedades solicitadas ou todas as propriedades sejam de um tipo excluído pelos sinalizadores, GetNamesFromIDs faz o seguinte:
Retorna S_OK.
Aloca uma nova estrutura SPropTagArray , definindo o membro cValues como 0.
Define o conteúdo de lpcPropNames como 0.
Define o conteúdo de lpppPropNames como NULL.
Observações para implementadores
Se lpPropSetGuid apontar para um conjunto de propriedades válido e lppPropTags for NULL, o resultado será indefinido. Você pode usar uma das seguintes estratégias:
Ignore o conjunto de propriedades e retorne os nomes dos identificadores na matriz de marcas de propriedade.
Retorne os nomes apenas para os identificadores na matriz de marcas de propriedade que pertencem ao conjunto de propriedades especificado.
Falha na chamada, retornando MAPI_E_INVALID_PARAMETER.
Notas para chamadores
Para recuperar todas as propriedades nomeadas para um objeto, primeiro você deve chamar o método IMAPIProp::GetPropList do objeto e, em seguida, passar os identificadores retornados que estão acima do intervalo 0x8000 para GetNamesFromIDs.
Se você passar um conjunto de propriedades válido, mas não uma matriz de marca de propriedade válida, prepare-se para resultados imprevisíveis. Algumas implementações de GetNamesFromIDs ignoram o conjunto de propriedades e retornam os nomes para os identificadores na matriz de marcas de propriedade. Algumas implementações retornam MAPI_E_INVALID_PARAMETER. Outras implementações retornam nomes para identificadores de todas as propriedades no conjunto de propriedades. Se o conjunto de propriedades for PS_PUBLIC_STRINGS, GetNamesFromIDs poderá retornar todos os nomes que já foram criados. Se o provedor de serviços armazena uma propriedade sob os identificadores associados às cadeias de caracteres públicas é imaterial.
Quando você terminar com os nomes da propriedade, marcar o conteúdo do parâmetro lpcPropNames para determinar se algum nome foi retornado. Nesse caso, chame a função MAPIFreeBuffer para liberar a memória apontada por lppPropTags e lpppPropNames quando um resultado bem-sucedido for retornado. Uma chamada para MAPIFreeBuffer é suficiente para cada parâmetro; você não precisa percorrer a matriz de ponteiros e liberar cada estrutura MAPINAMEID individualmente.
Para obter mais informações sobre propriedades nomeadas, 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::FindAllNamedProps |
O MFCMAPI usa o método IMAPIProp::GetNamesFromIDs para pesquisar propriedades nomeadas que foram mapeadas anteriormente. |