CMGetIDsOfNames
(Available in 01 TS COM - TS_COM_DelegateIDispatch)
Purpose
Get ID's of names
Syntax
// See MSDN doc
oDIObject:CMGetIDsOfNames( ... )
Arguments
pstruIID
|
_WinGUID
|
ppcArrayNames
|
PTR PTR
|
iCountNames
|
INT
|
dwLCID
|
DWORD
|
pDispIDArray
|
DWORD PTR
|
Description
Get the ID's ( that are provide by the type-library ) for any given number of names ( methods and properties ) provided by the interface.
MSDN ==== IDispatch::GetIDsOfNames Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to IDispatch::Invoke. The dispatch function DispGetIDsOfNames provides a standard implementation of GetIDsOfNames.
HRESULT GetIDsOfNames( REFIID riid, OLECHAR FAR* FAR* rgszNames, unsigned int cNames, LCID lcid, DISPID FAR* rgDispId );
Parameters riid Reserved for future use. Must be IID_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 identifier (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 return value obtained from the returned HRESULT is one of the following:
Return value 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 locale identifier (LCID) was not recognized.
Comments An IDispatch implementation can 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 returns DISP_E_UNKNOWNNAME, and the rgDispId array 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 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 ID as a member of a different interface, and different mapping for each time it appears as a parameter.
GetIDsOfNames is used when an IDispatch client binds to names at run time. To bind at compile time instead, an IDispatch client can map names to DISPIDs by using the type information interfaces described in Chapter 9, "Type Description Interfaces." This allows a client to bind to members at compile time and avoid calling GetIDsOfNames at run time. For a description of binding at compile time, see Chapter 9, "Type Description Interfaces."
The implementation of GetIDsOfNames is case insensitive. Users that need case-sensitive name mapping should use type information interfaces to map names to DISPIDs, rather than call GetIDsOfNames.
Returns
LONGINT, hResult
Source
METHOD CMGetIDsOfNames( pstruIID AS _WinGUID, ppcArrayNames AS PTR PTR, iCountNames ; ...
...AS INT, dwLCID AS DWORD, pDispIDArray AS DWORD PTR ) AS LONG PASCAL CLASS TS_DelegateIDispatch
LOCAL loRetVal AS LONG
TSTrace Enter
IF SELF:FInit
#IFDEF TS_TRACETIMED_ENABLE
_TS_TraceTimedEnter( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IDISPATCH, #GetIDsOfNames ; ...
... )
#ENDIF
loRetVal:=SELF:_AIDispatch:GetIDsOfNames( pstruIID ; ...
... , ppcArrayNames, iCountNames, dwLCID, pDispIDArray )
#IFDEF TS_TRACETIMED_ENABLE
_TS_TraceTimedLeave( TS_TT_SYM_EXTERNAL, TS_TT_SYM_IDISPATCH, #GetIDsOfNames ; ...
... )
#ENDIF
ELSE
TSTrace Warning