3.1.4.3 IDispatch::GetIDsOfNames (Opnum 5)

  • Article

The GetIDsOfNames method maps a single member (method or property) name, and an optional set of argument names, to a corresponding set of integer DISPIDs, which can be used on subsequent calls to IDispatch::Invoke.

 HRESULT GetIDsOfNames(
   [in] REFIID riid,
   [in, size_is(cNames)] LPOLESTR* rgszNames,
   [in, range(0,16384)] UINT cNames,
   [in] LCID lcid,
   [out, size_is(cNames)] DISPID* rgDispId
 );

riid: MUST equal IID_NULL (see section 1.9).

rgszNames: MUST be the array of strings to be mapped. The first string in the array MUST specify the name of a method or property that is supported by the server. Any additional strings MUST contain the names of all arguments for the method or property that is specified by the value in the first string. The mapping MUST be case-insensitive.

cNames: MUST equal the count of names to be mapped, and MUST<54> be between 0 and 16384.

lcid: MUST equal the locale ID in which to interpret the names.

rgDispId: MUST be an array of DISPIDs that are filled in by the server. Each DISPID corresponds, by position, to one of the names passed in rgszNames.

Return Values: The method MUST return information in an HRESULT data structure, as defined in [MS-ERREF] section 2.1. The severity bit in the structure identifies the following conditions:

  • If the severity bit is set to 0, the method completed successfully.

  • If the severity bit is set to 1 and the entire HRESULT DWORD does not match a value in the following table, a fatal failure occurred.

  • If the severity bit is set to 1 and the entire HRESULT DWORD matches a value in the following table, a failure occurred.

    Return value/code

    Description

    0x80020006

    DISP_E_UNKNOWNNAME

    One or more names were not known. The returned array of DISPIDs MUST contain at least one DISPID_UNKNOWN, and there MUST be one DISPID_UNKNOWN for each entry that corresponds to an unknown name. See [MS-ERREF].

    0x80020001

    DISP_E_UNKNOWNINTERFACE

    The interface identifier passed in riid is not IID_NULL. See [MS-ERREF].

Exceptions Thrown: No exceptions are thrown from this method except those that are thrown by the underlying RPC Protocol specified in [MS-RPCE].

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 member parameters.

The same name can map to different DISPIDs, depending on context. For example, a name can 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, or a different mapping for each time it appears as a parameter.

The implementation of GetIDsOfNames MUST be case-insensitive.

An implementation of the OLE Automation Protocol MAY<55> choose to implement a mapping for the parameter names that map to the index of the parameter in the member parameter list.