Published: July 16, 2012
Provides the property names that correspond to one or more property identifiers.
While access to most properties is by property identifier, some properties can be accessed by name. The IMAPIProp::GetNamesFromIDs method can be called to do the following:
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 does the following:
Allocates a new SPropTagArray structure, setting the cValues member to 0.
Sets the contents of lpcPropNames to 0.
Sets the contents of lpppPropNames to NULL.
If lpPropSetGuid points to a valid property set and lppPropTags is NULL, the result is undefined. You can use 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.
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 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 whether any names were returned. If so, call the MAPIFreeBuffer function to free the memory pointed to by lppPropTags and lpppPropNames when a successful result is returned. One call to MAPIFreeBuffer is sufficient for each parameter; you do not have to traverse the array of pointers and free each MAPINAMEID structure individually.
For more information about named properties, see MAPI Named Properties.