IMAPIProp::GetNamesFromIDs

The IMAPIProp::GetNamesFromIDs method provides the property names that correspond to one or more property identifiers.

Quick Info

See IMAPIProp : IUnknown.

HRESULT GetNamesFromIDs(
  LPSPropTagArray FAR * lppPropTags,   
  LPGUID lpPropSetGuid,                
  ULONG ulFlags,                       
  ULONG FAR * lpcPropNames,            
  LPMAPINAMEID FAR * FAR * lpppPropNames  
);
 

Parameters

lppPropTags

[in, out] On input, can be NULL, indicating that all names should be returned; or can be a pointer to an SPropTagArray structure containing an array of property tags. The cValues member for the property tag array cannot be zero. If lppPropTags is a valid pointer on input, GetNamesFromIDs returns names for each of the property identifiers included in the array.

lpPropSetGuid

[in] Pointer to a globally unique identifier, or GUID structure, identifying a property set. The lpPropSetGuid parameter can point to a valid property set or contain NULL.

ulFlags

[in] Bitmask of flags that indicates the type of names to be returned. The following flags can be used:

MAPI_NO_IDS

Requests that only names stored as Unicode strings be returned.

MAPI_NO_STRINGS

Requests that only names stored as numeric identifiers be returned.

If both flags are set, no names will be returned.

lpcPropNames

[out] Pointer to a count of the property name pointers in the array pointed to by lpppPropNames.

lpppPropNames

[out] Pointer to an array of pointers to MAPINAMEID structures containing property names.

Return Values

S_OK

The property names were successfully returned.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_W_ERRORS_RETURNED

The call succeeded overall, but names for one or more properties could not be returned. The property tags for the failing properties have a property type of PT_ERROR. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

MAPI_E_INVALID_PARAMETER

The cValues member of one or more of the entries in the property tag array pointed to by lppPropTags is set to zero.

Remarks

While access to most properties is by property identifier, some properties can be accessed by name. The IMAPIProp::GetNamesFromIDs method can be called to:

• Retrieve names for specific property identifiers in a specific property set.
• Retrieve names for specific property identifiers in any property set.
• Retrieve names for all named properties that are included in the object's mapping.

If lppPropTags points to a valid property tag array with one or more property identifiers and lpPropSetGuid points to a valid property set, GetNamesFromIDs ignores the property set and the property types and returns all of the names that map to the specified identifiers.

If lppPropTags points to a valid property tag array with one or more property identifiers and lpPropSetGuid is NULL, GetNamesFromIDs returns all of the names that map to the specified identifiers.

If a specified identifier does not have a name, GetNamesFromIDs returns NULL in that identifier's place in the structure returned in lpppPropNames and also returns MAPI_W_ERRORS_RETURNED.

If both lpPropSetGuid and lppPropTags are NULL, GetNamesFromIDs allocates a new property tag array and returns all of the names for all of the named properties for the object.

When there are no names to be returned, perhaps because there are no properties in the requested property set or all of the properties are of a type excluded by the flags, GetNamesFromIDs:

• Returns S_OK.
• Allocates a new SPropTagArray structure, setting the cValues member to 0.
• Sets the contents of lpcPropNames to zero.
• Sets the contents of lpppPropNames to NULL.

Notes to Implementers

If lpPropSetGuid points to a valid property set and lppPropsTags is NULL, the result is undefined. You can implement one of the following strategies:

• Ignore the property set and return the names for the identifiers in the property tag array.
• Return the names for only the identifiers in the property tag array that belong to the specified property set.
• Fail the call, returning MAPI_E_INVALID_PARAMETER.

Notes to Callers

To retrieve all of the named properties for an object, you must first call the object's IMAPIProp::GetPropList method and then pass the returned identifiers that are above the 0x8000 range to GetNamesFromIDs.

If you pass a valid property set but not a valid property tag array, be prepared for unpredictable results. Some implementations of GetNamesFromIDs ignore the property set and return the names for the identifiers in the property tag array. Some implementations return MAPI_E_INVALID_PARAMETER. Still other implementations return names for identifiers of all properties in the property set. If the property set is PS_PUBLIC_STRINGS, GetNamesFromIDs can return all names that were ever created. Whether or not the service provider stores a property under the identifiers associated with the public strings is immaterial.

When you are finished with the property names, check the contents of the lpcPropNames parameter to determine if any names were returned. If so, call MAPIFreeBuffer to free the memory pointed to by lppPropTags and lpppPropNames when success is returned. One call to MAPIFreeBuffer is sufficient for each parameter; you do not need to traverse the array of pointers and free each MAPINAMEID structure individually.

For more information about named properties, see Named Properties.

See Also

IMAPIProp::GetIDsFromNames