Important:
This is retired content. 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 content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

The GetIDsFromNamesmethod retrieves the property identifiers that correspond to one or more property names.

Note:
Windows Mobile Messaging implements this method only for IMessageand IMsgStoreinterface objects.

Syntax 

HRESULT GetIDsFromNames (
  ULONG 
cPropNames,
  LPMAPINAMEID FAR * 
lppPropNames,
  ULONG 
ulFlags,
  LPSPropTagArray FAR * 
lppPropTags
);

Parameters

cPropNames

[in] Count of property names pointed to by lppPropNames; cannot be zero.

lppPropNames

[in] Reference to an array of property names, with each property name specified by a MAPINAMEIDstructure; cannot be NULL.

ulFlags

[in] Bitmask of flags that indicates how the property identifiers should be returned. The following flag can be set:

MAPI_CREATE

Assigns a property identifier to one or more of the names included in the property name array pointed to by lppPropNamesif one has not yet been assigned .Internally registers the identifier in the name-to-identifier mapping table.

lppPropTags

[out] Reference to an SPropTagArraystructure that is an array of property tags containing existing or newly assigned property identifiers.

Note:
The returned property tags do not contain the associated type information. To retrieve the complete property tags, you must run the macro CHANGE_PROP_TYPEand apply a property type to each property tag.

Return Values

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

S_OK

Indicates success.

MAPI_E_NO_SUPPORT

The object does not support named properties.

MAPI_E_NOT_ENOUGH_MEMORY

Insufficient memory available to retrieve the identifiers.

MAPI_E_TOO_BIG

The operation cannot be performed because it requires the return of too many property tags.

MAPI_E_UNKNOWN_FLAGS

A flag other than MAPI_CREATEwas set in the ulFlagsparameter.

MAPI_W_ERRORS_RETURNED

The call succeeded, but one or more property identifiers could not be returned. The corresponding property type for each inaccessible property is set to PT_ERRORand its identifier to zero. When this warning is returned, handle the call as successful.

Remarks

GetIDsFromNamesretrieves an array of property tags that hold the property identifiers for one or more named properties. GetIDsFromNamescan be called to do the following:

  • Create identifiers for new names.

  • Retrieve identifiers for specific names.

  • Retrieve identifiers for all named properties that are included in the object's mapping.

Named properties are commonly used by message store providers for folders and messages. Other objects, such as messaging users and profile sections, might not support the association of names to property identifiers and return MAPI_E_NO_SUPPORTfrom GetIDsFromNames.

If there is an error returning an identifier for a particular name, GetIDsFromNamesreturns MAPI_W_ERRORS_RETURNEDand sets the property type in the property tag array entry that corresponds to the name to PT_ERRORand the identifier to zero.

Only MAPINAMEID::lpguid == PS_MAPIproperties are supported.

If there are no errors returning an identifier, the property types for the returned identifiers in the property tag array pointed to by lppPropTagsare set to PT_UNSPECIFIED. You need to call the GetPropsmethod to retrieve the accurate property types.

Some objects have a limit for the number of property identifiers they can name. If a call to GetIDsFromNamescauses this limit to be exceeded, the method returns MAPI_E_TOO_BIG. In this case, query by identifier.

To clean up after a successful call, you must call the MAPIFreeBufferfunction on lppPropTags.

Requirements

Header mapidefs.h
Library cemapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

IMAPIProp
MAPINAMEID
MAPIUID

Other Resources

Messaging