IMAPIProp::GetProps

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Recupera o valor da propriedade de uma ou mais propriedades de um objeto.

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

Parâmetros

Lpproptagarray

[in] Um ponteiro para uma matriz de marcas de propriedade que identificam as propriedades cujos valores devem ser recuperados. O parâmetro lpPropTagArray deve ser NULL, indicando que os valores de todas as propriedades do objeto devem ser retornados ou apontar para uma estrutura SPropTagArray que contém uma ou mais marcas de propriedade.

ulFlags

[in] Um bitmask de sinalizadores que indica o formato para propriedades que têm o tipo PT_UNSPECIFIED. O seguinte sinalizador pode ser definido:

MAPI_UNICODE

Os valores de cadeia de caracteres para essas propriedades devem ser retornados no formato Unicode. Se o sinalizador MAPI_UNICODE não estiver definido, os valores de cadeia de caracteres deverão ser retornados no formato ANSI.

lpcValues

[out] Um ponteiro para uma contagem de valores de propriedade apontados pelo parâmetro lppPropArray . Se lppPropArray for NULL, o conteúdo do parâmetro lpcValues será zero.

lppPropArray

[out] Um ponteiro para um ponteiro para os valores de propriedade recuperados.

Valor de retorno

S_OK

Os valores da propriedade foram recuperados com êxito.

MAPI_W_ERRORS_RETURNED

A chamada foi bem-sucedida no geral, mas uma ou mais propriedades não puderam ser acessadas. O membro aulPropTag do valor da propriedade para cada propriedade indisponível tem um tipo de propriedade de PT_ERROR e um identificador de zero. 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

Zero foi passado no membro cValues da estrutura SPropTagArray apontada por lpPropTagArray.

Comentários

O método IMAPIProp::GetProps obtém os valores de propriedade de uma ou mais propriedades de um objeto.

Os valores da propriedade são retornados na mesma ordem que foram solicitados (ou seja, a ordem das propriedades na matriz de marcas de propriedade apontada por lpPropTagArray corresponde à ordem na matriz de estruturas de valor da propriedade apontada por lppPropArray).

Os tipos de propriedade especificados nos membros aulPropTag da matriz de marcas de propriedade indicam o tipo de valor que deve ser retornado no membro Value de cada estrutura de valor da propriedade. No entanto, se o chamador não souber o tipo de uma propriedade, o tipo no membro aulPropTag poderá ser definido como PT_UNSPECIFIED. Ao recuperar o valor, GetProps define o tipo correto no membro aulPropTag da estrutura de valor da propriedade.

Se os tipos de propriedade forem especificados no SPropTagArray em lpPropTagArray, os valores de propriedade no SPropValue retornados em lppPropArray têm tipos que correspondem exatamente aos tipos solicitados, a menos que um valor de erro seja retornado.

As propriedades da cadeia de caracteres podem ter um dos dois tipos de propriedade: PT_UNICODE representar o formato Unicode e PT_STRING8 para representar o formato ANSI. Se o sinalizador MAPI_UNICODE for definido no parâmetro ulFlags , sempre que GetProps não puder determinar o formato apropriado para uma propriedade de cadeia de caracteres, ele retornará seu valor no formato Unicode. GetProps não pode determinar um tipo de propriedade de cadeia de caracteres exato nas seguintes situações:

O parâmetro lpPropTagArray é definido como NULL para solicitar todas as propriedades.
O membro aulPropTag inclui o valor PT_UNSPECIFIED como seu tipo de propriedade na matriz de marcas de propriedade.

Se o parâmetro lpPropTagArray estiver definido como NULL para recuperar todas as propriedades do objeto e nenhuma propriedade existir, GetProps fará o seguinte:

Retorna S_OK.
Define o valor de contagem no membro cValues da estrutura de valor da propriedade como 0.
Define o conteúdo de lpcValues como 0.
Define lppPropArray como NULL.

GetProps não deve retornar propriedades de vários valores com cValues definidos como 0.

Observações para implementadores

Chame a função MAPIAllocateBuffer para alocar memória inicialmente para a estrutura SPropValue apontada por lpPropTagArray; chame MAPIAllocateMore para alocar qualquer memória adicional necessária para os membros da estrutura.

Retorne MAPI_W_ERRORS_RETURNED se não puder recuperar o valor de uma ou mais propriedades solicitadas. Na estrutura de valor da propriedade, defina o tipo no membro aulPropTag como PT_ERROR e o membro Value como um código status que descreve o erro. Por exemplo, se você precisar converter uma cadeia de caracteres em Unicode e não dar suporte ao Unicode, defina o membro Value como MAPI_E_BAD_CHARWIDTH. Se a propriedade for muito grande, defina-a como MAPI_E_NOT_ENOUGH_MEMORY. Se o objeto não der suporte à propriedade, defina-a como MAPI_E_NOT_FOUND.

A implementação de um provedor de transporte remoto do método GetProps deve retornar os valores de propriedade da pasta para propriedades solicitadas pelo chamador. Sua implementação deve fazer o seguinte:

Aloque uma matriz de valor de propriedade para retornar ao chamador e armazene seu endereço no parâmetro ponteiro de valor da propriedade passado para essa finalidade.
Copie as marcas de propriedade das propriedades da pasta para as marcas de propriedade na matriz de valor da propriedade de acordo com a matriz de marcas de propriedade passadas para GetProps.
Verifique se o tipo de propriedade está definido para todas as marcas de propriedade passadas para GetProps. O chamador pode passar um tipo de propriedade de PT_UNSPECIFIED, nesse caso GetProps deve definir o tipo de propriedade correto para essa marca de propriedade.
Defina o valor de cada propriedade na matriz de valor da propriedade de acordo com sua marca. Por exemplo, se a marca de propriedade solicitada pelo chamador for PR_OBJECT_TYPE (PidTagObjectType), GetProps poderá definir o valor como MAPI_FOLDER.
Se o chamador passar em marcas de propriedade que sua implementação não manipula, você poderá definir a marca de propriedade como PT_ERROR para essas propriedades e definir o valor da propriedade como MAPI_E_NOT_FOUND.
Retorne S_OK se não houver erros ou MAPI_W_ERRORS_RETURNED se houver erros.

A implementação de um provedor de transporte remoto do método GetProps deve dar suporte às seguintes propriedades no mínimo:

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

Notas para chamadores

Para propriedades do tipo PT_OBJECT, chame o método IMAPIProp::OpenProperty em vez de GetProps.

Para propriedades seguras, não espere recuperá-las chamando GetProps com o parâmetro lppPropTagArray definido como NULL. Você deve definir explicitamente o identificador de uma propriedade segura no membro aulPropTag de sua matriz de marcas de propriedade ao chamar GetProps. Quando e como uma propriedade segura está disponível cabe ao provedor de serviços.

Libere a estrutura SPropValue retornada chamando a função MAPIFreeBuffer somente se GetProps retornar S_OK ou MAPI_W_ERRORS_RETURNED.

Se GetProps retornar MAPI_W_ERRORS_RETURNED porque não pôde acessar uma ou mais propriedades, marcar as marcas de propriedade das propriedades retornadas. As propriedades com falha terão os seguintes valores definidos em sua estrutura de valor de propriedade:

O tipo de propriedade no membro aulPropTag definido como PT_ERROR.
O valor da propriedade no membro Value definido como um código status para o erro, como MAPI_E_NOT_FOUND.

As propriedades que falham porque são muito grandes para serem retornadas convenientemente na estrutura de valor da propriedade têm seu membro Value definido como MAPI_E_NOT_ENOUGH_MEMORY. Normalmente, isso ocorre com propriedades de cadeia de caracteres ou binárias do tipo PT_STRING8, PT_UNICODE ou PT_BINARY quando o valor da propriedade é 4 KB ou maior. Chame IMAPIProp::OpenProperty para recuperar propriedades grandes.

Nem todas as implementações do GetProps dão suporte aos formatos Unicode e ANSI para cadeias de caracteres. Quando uma propriedade específica requer conversão de formato de cadeia de caracteres e GetProps não pode dar suporte a ela, o membro Value da propriedade é definido como MAPI_E_BAD_CHARWIDTH.

Para marcar se um PST for um PST do SharePoint, monte o PST usando IMAPISession::OpenMsgStore e chame GetProps no objeto do repositório de mensagens solicitando essa propriedade. Se ele existir, você pode assumir que o PST foi configurado para o SharePoint; se não, o PST não foi configurado como um PST do SharePoint.

Para obter mais informações sobre como usar GetProps para acessar propriedades, consulte Recuperando propriedades MAPI.

Referência do MFCMAPI

Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.

Arquivo	Função	Comentário
MAPIFunctions.cpp	GetPropsNULL	O MFCMAPI usa o método IMAPIProp::GetProps para obter todas as propriedades de um objeto passando NULL ou a matriz retornada pelo método IMAPIProp::GetPropList no parâmetro lpPropTagArray .