IMAPIProp::GetProps (Compact 7)

Article
03/14/2014

3/12/2014

This method retrieves one or more properties.

Syntax

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

Parameters

lpPropTagArray
[in] Pointer to a reference to an SPropTagArray structure that is an array of property tags indicating the properties whose values to retrieve. Cannot be NULL.

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

lpcValues
[out] Pointer to a reference to a count of property values that the lppPropArray parameter points to. If lppPropArray is NULL on output, lpcValues is zero on output.

lppPropArray
[out] Pointer to a reference to the array of retrieved property values.

Return Value

The GetProps method returns the following standard HRESULT values.

Term	Description
S_OK	The operation succeeded. Note If GetProps returns an HRESULT value of S_OK, it still might not be able to access the property. This lack of access 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.
E_FAIL	The operation failed due to an unspecified error.
E_INVALIDARG	The operation failed because one or more of the arguments is not valid.
E_OUTOFMEMORY	The operation failed because it needs more memory resources.
E_UNEXPECTED	The operation failed due to an unexpected error.
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 inaccessible 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 that the lpPropTagArray parameter points to, or a parameter contained an invalid value on input.
MAPI_E_INVALID_TYPE	An invalid property type was specified.

Remarks

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

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.

If property types are specified in the SPropTagArray structure 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.

Property values that fail because this method does not support them must set their Value member to E_INVALIDARG.

Code Example

The following code example demonstrates how to use GetProps.

Note

To make the following code example easier to read, security checking and error handling are not included. 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