Partager via

IMAPIProp::GetProps

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Retrieves the property value of one or more properties of an object.

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

Parameters

  • lpPropTagArray
    [in] A pointer to an array of property tags that identify the properties whose values are to be retrieved. The lpPropTagArray parameter must be either NULL, indicating that values for all properties of the object should be returned, or point to an SPropTagArray structure that contains one or more property tags.

  • ulFlags
    [in] A bitmask of flags that indicates the format for properties that have the type PT_UNSPECIFIED. The following flag can be set:

    • MAPI_UNICODE
      The string values for these properties should be returned in the Unicode format. If the MAPI_UNICODE flag is not set, the string values should be returned in the ANSI format.

  • lpcValues
    [out] A pointer to a count of property values pointed to by the lppPropArray parameter. If lppPropArray is NULL, the content of the lpcValues parameter is zero.

  • lppPropArray
    [out] A pointer to a pointer to the retrieved property values.

Return Value

  • S_OK
    The property values were successfully retrieved.

  • MAPI_W_ERRORS_RETURNED
    The call succeeded overall, but one or more properties could not be accessed. The aulPropTag member of the property value for each unavailable 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. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

  • MAPI_E_INVALID_PARAMETER
    Zero was passed in the cValues member of the SPropTagArray structure pointed to by lpPropTagArray.

Remarks

The IMAPIProp::GetProps method obtains the property values of one or more properties of an object.

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 aulPropTag 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.

String properties can have one of two property types: PT_UNICODE to represent the Unicode format and PT_STRING8 to represent the ANSI format. If the MAPI_UNICODE flag is set in the ulFlags parameter, whenever GetProps cannot determine the appropriate format for a string property, it returns its value in the Unicode format. GetProps cannot determine an exact string property type in the following situations:

  • The lpPropTagArray parameter is set to NULL to request all properties.

  • The aulPropTag member includes the value PT_UNSPECIFIED as its property type in the property tag array.

If the lpPropTagArray parameter is set to NULL to retrieve all of the properties of the object and no properties exist, GetProps does the following:

  • Returns S_OK.

  • Sets the count value in the cValues member of the property value structure to 0.

  • Sets the contents of lpcValues to 0.

  • Sets lppPropArray to NULL.

GetProps must not return multiple-value properties with cValues set to 0.

Notes to Implementers

Call the MAPIAllocateBuffer function to allocate memory initially for the SPropValue structure pointed to by lpPropTagArray; call MAPIAllocateMore to allocate any additional memory needed for the structure's members.

Return MAPI_W_ERRORS_RETURNED if you cannot retrieve the value for one or more of the requested properties. In the property value structure, set the type in the aulPropTag member to PT_ERROR and the Value member to a status code that describes the error. For example, if you have to convert a string to Unicode and do not support Unicode, set the Value member to MAPI_E_BAD_CHARWIDTH. If the property is too large, set it to MAPI_E_NOT_ENOUGH_MEMORY. If the object does not support the property, set it to MAPI_E_NOT_FOUND.

A remote transport provider's implementation of the GetProps method must return the folder's property values for properties requested by the caller. Your implementation must do the following:

  • Allocate a property value array to return to the caller and store its address in the property value pointer parameter passed in for that purpose.

  • Copy the property tags from the folder's properties into the property tags in the property value array according to the array of property tags passed to GetProps.

  • Ensure that the property type is set for all property tags passed to GetProps. The caller can pass in a property type of PT_UNSPECIFIED, in which case GetProps must set the correct property type for that property tag.

  • Set the value of each property in the property value array according to its tag. For example, if the property tag requested by the caller is PR_OBJECT_TYPE (PidTagObjectType), GetProps can set the value to MAPI_FOLDER.

  • If the caller passes in any property tags that your implementation does not handle, you can set the property tag to PT_ERROR for those properties, and set the property value to MAPI_E_NOT_FOUND.

  • Return S_OK if no errors occurred or MAPI_W_ERRORS_RETURNED if there were errors.

A remote transport provider's implementation of the GetProps method must support the following properties at a minimum:

Notes to Callers

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

For secure properties, do not expect to retrieve them by calling GetProps with the lppPropTagArray parameter set to NULL. You must explicitly set a secure property's identifier in the aulPropTag member of its property tag array when you call GetProps. When and how a secure property is available is up to the service provider.

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:

  • The property type in the aulPropTag member set to PT_ERROR.

  • The 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 conveniently 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.

Not all implementations of GetProps support both the Unicode and ANSI formats for character strings. When a particular property requires string format conversion and GetProps cannot support it, the Value member for the property is set to MAPI_E_BAD_CHARWIDTH.

For more information about how to use GetProps to access properties, see Retrieving MAPI Properties.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIFunctions.cpp

GetPropsNULL

MFCMAPI uses the IMAPIProp::GetProps method to obtain all properties for an object by passing either NULL or the array returned by the IMAPIProp::GetPropList method in the lpPropTagArray parameter.

See Also

Reference

IMAPIProp::GetPropList

IMAPIProp::OpenProperty

MAPIAllocateBuffer

MAPIAllocateMore

MAPIFreeBuffer

SPropTagArray

SPropValue

IMAPIProp : IUnknown

Concepts

MFCMAPI as a Code Sample

Retrieving MAPI Properties

Using Macros for Error Handling