IMAPIProp::GetProps

4/8/2010

The GetProps method retrieves the property value of one or more properties of an object.

Syntax

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

Parameters

• lpPropTagArray
  [in] Reference to an SPropTagArray structure that is an array of property tags indicating the properties whose values are to be retrieved; cannot be NULL.

• ulFlags
  [in] Must be zero, or equal to MAPI_UNICODE. In either case, however, this parameter is ignored.

• lpcValues
  [out] Reference to a count of property values pointed to by lppPropArray. If lppPropArray is NULL on output, lpcValues is zero on output*.*

• lppPropArray
  [out] Reference to the array of retrieved property values.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

• S_OK
  Indicates success.

  Note

  If GetProps returns an HRESULT value of S_OK, GetProps still might not be able to access the property. This can happen when the ulPropTag member of the property value has a property type of PT_ERROR and a value of MAPI_E_NOT_FOUND. In this case, use IMAPIProp::OpenProperty to access the property.

• MAPI_W_ERRORS_RETURNED
  The call succeeded, but one or more properties could not be accessed. The ulPropTag member of the property value for each unaccessible property has a property type of PT_ERROR and an identifier of zero. When this warning is returned, the call should be handled as successful.

• MAPI_E_INVALID_PARAMETER
  Zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray, or a parameter contained an invalid value on input.

Remarks

The property values are returned in the same order as they were requested. That is, the order of properties in the property tag array pointed to by lpPropTagArray matches the order in the array of property value structures pointed to by lppPropArray.

The property types specified in the aulPropTag members of the property tag array indicate the type of value that should be returned in the Value member of each property value structure. However, if the caller does not know the type of a property, the type in the aulPropTag member can be set instead to PT_UNSPECIFIED. In retrieving the value, GetProps sets the correct type in the ulPropTag member of the property value structure for the property.

If property types are specified in the SPropTagArray in lpPropTagArray, the property values in the SPropValue returned in lppPropArray have types that exactly match the requested types, unless an error value is returned instead.

For properties of type PT_OBJECT, call IMAPIProp::OpenProperty instead of GetProps.

Free the returned SPropValue structure by calling the MAPIFreeBuffer function only if GetProps returns S_OK or MAPI_W_ERRORS_RETURNED.

If GetProps returns MAPI_W_ERRORS_RETURNED because it could not access one or more properties, check the property tags of the returned properties. The failed properties will have the following values set in their property value structure:

• Property type in the ulPropTag member set to PT_ERROR.
• Property value in the Value member set to a status code for the error, such as MAPI_E_NOT_FOUND.

Properties that fail because they are too large to be returned in the property value structure have their Value member set to MAPI_E_NOT_ENOUGH_MEMORY. Typically, this occurs with string or binary properties of type PT_STRING8, PT_UNICODE, or PT_BINARY when the value of the property is 4 KB or larger. Call IMAPIProp::OpenProperty to retrieve large properties.

Code Example

The following code example demonstrates how to use GetProps.

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

See Also

Reference

IMAPIProp
IMAPIProp::OpenProperty
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
SPropTagArray
SPropValue

Other Resources

Messaging