3.11.4.9 ITypeLib::FindName (Opnum 11)

  • Article

The FindName method retrieves references to types, or type members, contained in the automation type library whose names match a specified string.

 HRESULT FindName(
   [in] LPOLESTR szNameBuf,
   [in] ULONG lHashVal,
   [out, size_is(*pcFound), length_is(*pcFound)] 
     ITypeInfo** ppTInfo,
   [out, size_is(*pcFound), length_is(*pcFound)] 
     MEMBERID* rgMemId,
   [in, out] USHORT* pcFound,
   [out] BSTR* pBstrNameInLibrary
 );

szNameBuf: MUST be a string.

lHashVal: MUST be either the hash value corresponding to the value of szNameBuf (as specified in section 2.2.51), or 0.

ppTInfo: MUST be set to an array of references to ITypeInfo server instances (see section 3.7.4). Each entry of ppTInfo MUST correspond to a type whose name matches the value of szNameBuf according to the string matching criteria (as specified in section 2.2.50) or that contains a member whose name matches the value of szNameBuf.

The array MUST be empty if there are no types or method or data members of types defined in the automation scope whose names match the value of szNameBuf. Otherwise, the array MUST contain one entry for each named nonparameter element defined in the automation scope whose name matches szNameBuf. The array MAY contain entries for matching types or type members that are referenced, but not defined in the automation scope. <62>

If szNameBuf matches the name of a dual interface or one of its members, the corresponding entry in ppTInfo MUST refer to the partner dispinterface and MUST NOT refer to the partner interface.

The length of the array MUST NOT be greater than the value of pcFound set by the client.

rgMemId: MUST be set to an array of MEMBERIDs (see section 2.2.35) corresponding to the ITypeInfo instances in the ppTInfo array. For each entry in the ppTInfo array, the corresponding value in the rgMemId array MUST specify the MEMBERID of the type member whose name matches the value of szNameBuf, or MEMBERID_NIL to specify that the name of the type matches the value of szNameBuf.

pcFound: The client MUST set pcFound to the maximum number of matches that can be returned. The server MUST set pcFound to the number of elements in the ppTInfo and rgMemId arrays.

pBstrNameInLibrary: MUST be set to a string whose value matches the value of szNameBuf according to the string-matching rules (as specified in section 2.2.50), if the ppTInfo array is not empty. MUST be set to a NULL BSTR otherwise.

Return Values: The method MUST return information in an HRESULT data structure, 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, the method failed and encountered a fatal error.