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.
A version of this page is also available for
4/8/2010

This method maps a single member name and an optional set of parameter names to a corresponding set of integer dispatch identifiers (DISPIDs), which can then be used on subsequent calls to Invoke.

Syntax 

HRESULT GetIDsOfNames( 
  REFIID 
riid, 
  OLECHAR FAR* FAR* 
rgszNames, 
  unsigned int 
cNames, 
  LCID 
lcid, 
  DISPID FAR* 
rgDispId 
);

Parameters

riid

[in] Reserved for future use; set to IID_NULL.

rgszNames

[in] Passed-in array of names to be mapped.

cNames

[in] Count of the names to be mapped.

lcid

[in] Locale context in which to interpret the names.

rgDispId

[out] Caller-allocated array, each element of which contains an identifier that corresponds to one of the names passed in the rgszNamesarray. The first element represents the member name. The subsequent elements represent each of the member's parameters.

Return Value

The following table shows the return values for this function.

Value Description

S_OK

Success.

E_OUTOFMEMORY

Out of memory.

DISP_E_UNKNOWNNAME

One or more of the names were not known. The returned array of DISPIDs contains DISPID_UNKNOWN for each entry that corresponds to an unknown name.

DISP_E_UNKNOWNLCID

The locale identifier (LCID) was not recognized.

Remarks

An IDispatchimplementation can associate any positive integer identifier value with a given name. Zero is reserved for the default, or Valueproperty; –1 is reserved to indicate an unknown name; and other negative values are defined for other purposes.

For example, if GetIDsOfNamesis called, and the implementation does not recognize one or more of the names, it returns DISP_E_UNKNOWNNAME, and the rgDispIdarray contains DISPID_UNKNOWN for the entries that correspond to the unknown names.

The member and parameter DISPIDs must remain constant for the lifetime of the object. This allows a client to obtain the DISPIDs once, and cache them for later use.

When GetIDsOfNamesis called with more than one name, the first name ( rgszNames[0]) corresponds to the member name, and subsequent names correspond to the names of the member's parameters.

The same name may map to different DISPIDs, depending on context. For example, a name may have a DISPID when it is used as a member name with a particular interface, a different identifier as a member of a different interface, and different mapping for each time it appears as a parameter.

The IDispatchinterface binds to names at run time. To bind at compile time instead, an IDispatchclient can map names to DISPIDs by using the ITypeLib, ITypeLib2, ITypeInfo, ITypeInfo2, and ITypeCompinterfaces. This allows a client to bind to members at compile time and avoid calling GetIDsOfNamesat run time.

The implementation of GetIDsOfNamesis case insensitive. Users that need case-sensitive name mapping should use type information interfaces to map names to DISPIDs, rather than call GetIDsOfNames.

Example

The following code from the Lines sample file Lines.cpp implements the GetIDsOfNamesmember function for the CLineclass. The ActiveX or OLE object uses the standard implementation, DispGetIDsOfNames.

Copy Code 
STDMETHODIMP 
CLine::GetIDsOfNames(
REFIID riid,
OLECHAR FAR* FAR* rgszNames,
UINT cNames,
LCID lcid,
DISPID FAR* rgDispId)
{
return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

The following code might appear in an ActiveX client that calls GetIDsOfNamesto get the DISPID of the CLine Colorproperty.

Copy Code 
HRESULT hresult;
IDispatch FAR* pdisp = (IDispatch FAR*)NULL;
DISPID dispid;
OLECHAR FAR* szMember = "color";
// Code that sets a pointer to the dispatch (pdisp) is omitted.
hresult = pdisp->GetIDsOfNames(
IID_NULL,
&szMember,
1, LOCALE_SYSTEM_DEFAULT,
&dispid);

Requirements

Header oaidl.h, oaidl.idl
Library oleaut32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also