QISearch 함수(shlwapi.h)

  • 아티클

IUnknown::QueryInterface 메서드의 테이블 기반 구현입니다.

구문

HRESULT QISearch(
  [in]  void     *that,
  [in]  LPCQITAB pqit,
  [in]  REFIID   riid,
  [out] void     **ppv
);

매개 변수

[in] that

형식: void*

COM 개체의 밑면에 대한 포인터입니다.

[in] pqit

형식: LPCQITAB

QITAB 구조체의 배열입니다. 배열의 마지막 구조체에는 해당 piid 멤버가 NULL 로 설정되고 dwOffset 멤버가 0으로 설정되어 있어야 합니다.

[in] riid

형식: REFIID

ppv를 통해 검색할 인터페이스의 IID에 대한 참조입니다.

[out] ppv

형식: void**

이 메서드가 성공적으로 반환되면 는 riid에서 요청된 인터페이스 포인터를 포함합니다.

반환 값

형식: HRESULT

요청된 인터페이스가 테이블에서 발견되었거나 요청된 인터페이스가 IUnknown인 경우 S_OK 반환합니다. 요청된 인터페이스를 찾을 수 없으면 E_NOINTERFACE 반환합니다.

설명

참고 Windows Vista 이전에는 QISearch 가 이름으로 내보내지 않았거나 공용 헤더 파일에 선언되지 않았습니다. 이러한 경우에 사용하려면 GetProcAddress 를 사용하고 Shlwapi.dll 서수 219를 요청하여 함수 포인터를 가져와야 합니다. Windows Vista에서 QISearch 는 Shlwapi.h에 포함되며 이는 필요하지 않습니다.
 
요청된 인터페이스가 IUnknown인 경우 QISearch 는 지정된 QITAB 구조체 배열의 첫 번째 항목을 사용합니다. 그렇지 않으면 QISearch 는 일치하는 IID를 찾거나 테이블의 끝에 도달할 때까지 테이블을 검색합니다. 일치하는 IID가 발견되면 함수는 연결된 인터페이스 포인터를 인터페이스의 QITAB 구조체의 dwOffset 멤버가 지정하고 COM 포인터로 재해석한 바이트 수만큼 진행합니다. 해당 포인터는 QISearch 함수의 ppv 매개 변수에 할당됩니다. 또한 메서드는 IUnknown::AddRef를 호출하여 인터페이스의 참조 횟수를 증분합니다.

QISearch가 인터페이스를 찾지 않고 테이블의 끝에 도달하면 E_NOINTERFACE 반환하고 ppv를 NULL로 설정합니다.

테이블에 적용 가능한 모든 인터페이스를 포함하는 것이 중요합니다. 예를 들어 개체가 파생 인터페이스를 구현하는 경우 테이블에 기본 인터페이스도 포함해야 합니다.

Objbase.h에 정의된 IID_PPV_ARGS 매크로를 사용하여 riid 및 ppv 매개 변수를 패키지하는 것이 좋습니다. 이 매크로는 ppv의 값이 가리키는 인터페이스를 기반으로 올바른 IID를 제공하므로 riid 에서 코딩 오류가 발생하여 예기치 않은 결과가 발생할 수 있습니다.

참고 ATL(활성 템플릿 라이브러리)은 QueryInterface의 테이블 기반 구현을 훨씬 더 나은 버전으로 제공합니다.
 

예제

다음 예제에서는 QISearch 를 사용하여 QueryInterface를 구현하는 방법을 보여 줍니다. ATL의 offsetofclass 매크로를 사용하여 CSample 개체의 기본에서 지정된 인터페이스로 오프셋을 계산합니다.

이 개체는 IUnknown 외에 두 개의 인터페이스를 지원하므로 QITAB 테이블에 NULL이 아닌 두 개의 항목이 있습니다. 각 인터페이스의 항목은 연결된 IID(IID_IPersist 또는 IID_IPersistFolder)에 대한 포인터와 클래스의 기본 포인터를 기준으로 하는 인터페이스 포인터의 오프셋을 지정합니다. 샘플에서는 ATL의 offsetofclass 매크로를 사용하여 해당 오프셋을 확인합니다.

참고 간접 클래스를 포함하여 모든 기본 클래스를 포함하는 것을 잊어버리는 것은 일반적인 오류입니다. IPersist 인터페이스에 대한 항목이 있습니다. 이 인터페이스는 IPersistFolder를 통해 상속되는 CSample에 대한 간접 기본 클래스입니다.
 

class CSample : public IPersistFolder
{
  public:
    CSample() { /* other construction goes here */ }
    
    STDMETHODIMP QueryInterface(REFIID riid, void **ppv);
    STDMETHODIMP_(ULONG) AddRef();
    STDMETHODIMP_(ULONG) Release();
  
    // *** IPersist ***
    STDMETHODIMP GetClassID(CLSID *pClassID);
    
    // *** IPersistFolder ***
    STDMETHODIMP Initialize(LPCITEMIDLIST pidl);
  
  private:
  // private members go here
};

HRESULT CSample::QueryInterface(REFIID riid, void **ppv)
{
    static QITAB rgqit[] = 
    {   
        QITABENT(CSample, IPersist),
        QITABENT(CSample, IPersistFolder)
        { 0 },
    };

    return QISearch(this, rgqit, IID_PPV_ARGS(&ppv));
}

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 2000 Professional, Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows 2000 Server, Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 shlwapi.h
라이브러리 Shlwapi.lib
DLL Shlwapi.dll(버전 5.0 이상)