IDispatch::GetIDsOfNames - OLE Programmer's Reference

Custom Search

IDispatch::GetIDsOfNames

riid, rgszNames, cNames, lcid, rgdispid)
REFIID riid
OLECHAR FAR* FAR* rgszNames
unsigned int cNames
LCID lcid
DISPID FAR* rgdispid

Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which may be used on subsequent calls to IDispatch::Invoke. The dispatch function DispGetIDsOfNames provides a standard implementation of GetIDsOfNames.

Parameters
riid
Reserved for future use. Must be NULL.

rgszNames
Passed-in array of names to be mapped.

cNames
Count of the names to be mapped.

lcid
The locale context in which to interpret the names.

rgdispid
Caller-allocated array, each element of which contains an ID corresponding to one of the names passed in the rgszNames array. The first element represents the member name; the subsequent elements represent each of the member's parameters.

Return Value
The SCODE obtained from the returned HRESULT is one of the following:

SCODE	Meaning
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 LCID was not recognized.

Comments
An IDispatch implementation may choose to associate any positive integer ID value with a given name. Zero is reserved for the default, or Value property;

1 is reserved to indicate an unknown name; and other negative values are defined for other purposes. For example, if GetIDsOfNames is called and the implementation does not recognize one or more of the names, it will return DISP_E_UNKNOWNNAME and the rgdispid array will contain 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 GetIDsOfNames is 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 DISPID as a member of a different interface, and different mapping for each time it appears as a parameter.

The IDispatch interface binds to names at run time. To bind at compile time instead, an IDispatch client can map names to DISPIDs using the type information interfaces described in Chapter 8, "Type Description Interfaces." This allows a client to bind to members at compile time and avoid calling GetIDsOfNames at run time.

The implementation of GetIDsOfNames must be case insensitive. Clients that need case-sensitive name mapping should use the type information interfaces to map names to DISPIDs, rather than calling GetIDsOfNames.

Examples
The following code from the Lines sample file LINE.CPP implements the GetIDsOfNames member function for the CLine class. The OLE Automation object uses the standard implementation, DispGetIDsOfNames.

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 OLE Automation controller that calls GetIDsOfNames to get the DISPID of the CLine Color property.

HRESULT hresult;

IDispatch FAR* pdisp = (IDispatch FAR*)NULL;

DISPID dispid;

OLECHAR FAR* szMember = "color";

// Omitted code that sets pdisp...

hresult = pdisp->GetIDsOfNames(

IID_NULL,

&szMember,

LOCALE_SYSTEM_DEFAULT,

&dispid);

See Also
CreateStdDispatch, DispGetIDsOfNames, ITypeInfo::GetIDsOfNames

Last news from Greatis Software

    Nostalgia .Net     .Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More »

Recommended software for developers

    Ultimate Pack     Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More »

    Form Designer .Net     Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More »

    Print Suite .Net     Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More »

    Gradient Controls .Net     Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More »

    Greatis iGrid     iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More »

All the contacts and projects

Dmitry Vasiliev (just.dmitry)

More Online Helps

Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages

greatis just4fun network