IMAPIProp::GetProps

9/8/2008

The GetProps método recupera a valor da propriedade um ou mais propriedades de um objeto.

Syntax

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

Parameters

• lpPropTagArray
  [no] Referência a um SPropTagArray estrutura que é uma matriz de propriedade Marcas indicando as propriedades cujos valores são a serem recuperados; não pode ser NULL.

• ulFlags
  [no] Deve ser zero ou igual a MAPI_UNICODE. Em ambos os maiúsculas e minúsculas, no entanto, esse parâmetro é ignorado.

• lpcValues
  [out] Referência a uma contagem de valores propriedade apontado pelo lppPropArray. Se lppPropArray é NULL Na saída, lpcValues é zero na saída.

• lppPropArray
  [out] Referência a matriz de valores recuperados propriedade.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED GPSGetPosition, e E_FAIL, as well as o seguinte.

• S_OK
  Indica sucesso.

• MAPI_W_ERRORS_RETURNED
  O chamar teve êxito, mas um ou mais propriedades não pôde ser acessadas. The ulPropTag membro do valor da propriedade para cada propriedade unaccessible tem um tipo de propriedade PT_ERROR e um identificador de zero. Quando esse aviso é retornado, o chamar deve ser tratada como bem-sucedido.

• MAPI_E_INVALID_PARAMETER
  Zero foi passado a cValues membro das SPropTagArray estrutura apontada pelo lpPropTagArray, ou um parâmetro continha um valor inválido na entrada.

Remarks

Os valores de propriedade são retornados na mesma ordem como eles foram solicitados. Isto é, a ordem das propriedades na matriz de propriedade marca apontado pelo lpPropTagArray Coincide com a ordem na matriz de estruturas valor da propriedade apontadas pelo lppPropArray.

Tipos de propriedade especificados na aulPropTag Membros da matriz de propriedade marca indicam o tipo de valor que deve ser retornado na Value membro de cada estrutura valor da propriedade. No entanto, se o chamador não sabe o tipo de uma propriedade, o tipo in a aulPropTag membro pode ser definido em vez disso, para PT_UNSPECIFIED. Recuperar o valor, GetProps Define o tipo correto de ulPropTag membro da estrutura de valor da propriedade para a propriedade.

Se forem especificados na propriedade tipos de SPropTagArray Em lpPropTagArray, a propriedade Valores in a SPropValue retornados em lppPropArray Ter tipos que correspondem exatamente os tipos solicitados, a menos que um valor de erro é retornado em vez disso.

Para propriedades de tipo PT_OBJECT, chamar IMAPIProp::OpenProperty em vez de GetProps.

Liberar o retornado SPropValue estrutura por chamado de MAPIFreeBuffer função somente se GetProps Retorna S_OK ou ISpTTSEngine::Speak. MAPI_W_ERRORS_RETURNED.

Se GetProps Retorna MAPI_W_ERRORS_RETURNED porque ele não pôde acessar um ou mais propriedades, verificar as marcas propriedade das propriedades retornadas. A falha propriedades terão os seguinte valores definido na sua estrutura valor da propriedade:

• Propriedade tipo na ulPropTag membro definido como PT_ERROR.
• Valor na propriedade de Value membro definido para codificar um status para o erro, como MAPI_E_NOT_FOUND.

Propriedades que falharam porque elas são muito grandes para ser retornada na estrutura de valor da propriedade têm seus Value membro definido como MAPI_E_NOT_ENOUGH_MEMORY. Normalmente, isso ocorre com seqüência de caracteres ou binário propriedades de tipo PT_STRING8, PT_UNICODE, ou PT_BINARY Quando o valor da propriedade é 4 KB ou maior. Chamar IMAPIProp::OpenProperty Para recuperar propriedades grande.

Exemplo de código

O seguinte exemplo de código demonstra como usar GetProps.

Observação

Para tornar o exemplo de código mais fácil para ler, verificação de segurança e manipulação de erro não estão incluídos.This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT GetPropsExample(IMessage * pMsg)
{
    HRESULT hr           = E_FAIL;
    SPropValue * rgprops = NULL;
    ULONG rgTags[]       = {3, PR_SENDER_EMAIL_ADDRESS, PR_SUBJECT, PR_IMPORTANCE};
    ULONG cCount         = 0;
    // Get the message's properties.
    hr = pMsg->GetProps((LPSPropTagArray) rgTags, MAPI_UNICODE, &cCount, &rgprops);
    // Access the properties that were just retrieved.
    if (SUCCEEDED(hr))
    {
        // Check that the ulPropTag member of each property value is of the property type requested, 
        // and that it does not have a value of PT_ERROR.
        if (rgprops[0].ulPropTag == PR_SENDER_EMAIL_ADDRESS)
        {
            DEBUGMSG(TRUE, (L"From: %s \r\n", rgprops[0].Value.lpszW));
        }
        if (rgprops[1].ulPropTag == PR_SUBJECT)
        {
            DEBUGMSG(TRUE, (L"Subject: %s \r\n", rgprops[1].Value.lpszW));
        }
        if (rgprops[2].ulPropTag == PR_IMPORTANCE)
        {
            DEBUGMSG(TRUE, (L"Importance: %d \r\n", rgprops[2].Value.ul));
        }
        // Free the returned SPropValue structure.
        MAPIFreeBuffer(rgprops);
    }
    return hr;
}

Requirements

Header	mapidefs.h
Library	cemapi.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

IMAPIProp
IMAPIProp::OpenProperty
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
SPropTagArray
SPropValue

Other Resources

Messaging