IWbemServices::ExecQueryAsync 메서드(wbemcli.h)
IWbemServices::ExecQueryAsync 메서드는 쿼리를 실행하여 개체를 비동기적으로 검색합니다.
구문
HRESULT ExecQueryAsync(
[in] const BSTR strQueryLanguage,
[in] const BSTR strQuery,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
매개 변수
[in] strQueryLanguage
WMI(Windows Management Instrumentation)에서 지원하는 쿼리 언어 중 하나를 포함하는 유효한 BSTR 입니다. "WQL"이어야 합니다.
[in] strQuery
쿼리의 텍스트를 포함하는 유효한 BSTR 입니다. NULL일 수 없습니다. instance 공급자를 구현하는 경우 너무 복잡하여 공급자가 쿼리를 거부할 수 있습니다. 공급자가 쿼리가 너무 복잡하다는 것을 판단하는 경우 WMI는 간단한 쿼리를 사용하여 공급자를 다시 시도하거나 쿼리 인스턴스의 상위 집합을 검색하고 열거하도록 선택할 수 있습니다.
WMI 쿼리 문자열을 빌드하는 방법에 대한 자세한 내용은 WQL을 사용하여 쿼리 및 WQL 참조를 참조하세요.
[in] lFlags
이 매개 변수는 다음 값 중 하나일 수 있습니다.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
이 플래그가 설정되면 WMI는 현재 연결 로캘의 지역화된 네임스페이스에 저장된 수정된 한정자를 검색합니다. 설정하지 않으면 직접 네임스페이스에 저장된 한정자만 검색됩니다.
WBEM_FLAG_BIDIRECTIONAL
이 플래그를 사용하면 클라이언트가 열거자를 해제할 때까지 WMI가 열거형 개체에 대한 포인터를 유지합니다.
WBEM_FLAG_SEND_STATUS
이 플래그는 클라이언트의 IWbemObjectSink::SetStatus 구현을 통해 중간 상태 보고서를 수신하도록 WMI에 요청을 등록합니다. 공급자 구현은 이 플래그를 변경하려면 중간 상태 보고를 지원해야 합니다.
WBEM_FLAG_ENSURE_LOCATABLE
이 플래그는 반환된 개체에 충분한 정보가 있는지 확인하여 __PATH, __RELPATH 및 __SERVER 같은 시스템 속성이 NULL이 아닌지 확인합니다.
WBEM_FLAG_PROTOTYPE
이 플래그는 프로토타이핑에 사용됩니다. 쿼리를 실행하지는 않지만 일반적인 결과 개체처럼 보이는 개체를 반환합니다.
WBEM_FLAG_DIRECT_READ
이 플래그를 사용하면 부모 클래스 또는 서브클래스에 관계없이 지정된 클래스에 대한 공급자에 직접 액세스할 수 있습니다.
[in] pCtx
일반적으로 NULL입니다. 그렇지 않으면 공급자가 요청된 클래스 또는 인스턴스를 반환하는 데 사용할 수 있는 IWbemContext 개체에 대한 포인터입니다. 컨텍스트 개체의 값은 공급자에 대한 설명서에 지정해야 합니다. 이 매개 변수에 대한 자세한 내용은 WMI 호출을 참조하세요.
[in] pResponseHandler
호출자의 IWbemObjectSink 구현에 대한 포인터입니다. 이 처리기는 사용할 수 있게 되면 쿼리 결과 집합의 개체를 받습니다. 오류 코드가 반환되면 제공된 IWbemObjectSink 포인터가 사용되지 않습니다. WBEM_S_NO_ERROR 반환되면 작업의 결과를 나타내기 위해 사용자의 IWbemObjectSink 구현이 호출됩니다. WMI(Windows Management Instrumentation)는 IWbemObjectSink::Indicate를 횟수에 따라 개체로 호출한 다음 IWbemObjectSink::SetStatus를 호출하여 최종 상태 나타냅니다.
WMI는 WBEM_S_NO_ERROR 반환할 때만 포인터에 AddRef를 호출합니다. 오류 코드가 반환되면 참조 수는 항목에서와 동일합니다. 비동기 호출 메서드에 대한 자세한 설명은 메서드 호출을 참조하세요.
반환 값
이 메서드는 메서드 호출의 상태를 나타내는 HRESULT를 반환합니다. 다음 목록에는 HRESULT 내에 포함된 값이 나열되어 있습니다.
오류가 발생하면 COM 함수 GetErrorInfo에서 정보를 가져올 수 있습니다.
다른 오류 코드는 pResponseHandler 매개 변수에 지정된 개체 싱크로 반환됩니다.
네트워크 문제로 인해 WMI에 대한 원격 연결이 끊어지는 경우 COM 관련 오류 코드가 반환될 수 있습니다.
완료되면 instance 공급자는 ExecQueryAsync의 반환 코드 또는 pResponseHandler를 통해 SetStatus 호출을 통해 성공 또는 실패를 보고할 수 있습니다. SetStatus를 호출하도록 선택하면 pResponseHandler를 통해 전송된 반환 코드가 우선합니다.
설명
WQL 쿼리에 사용할 수 있는 AND 및 OR 키워드의 수에는 제한이 있습니다. 복잡한 쿼리에 사용되는 WQL 키워드가 많으면 WMI가 WBEM_E_QUOTA_VIOLATION 오류 코드를 HRESULT 값으로 반환할 수 있습니다. WQL 키워드의 제한은 쿼리가 얼마나 복잡한지에 따라 달라집니다.
호출자의 IWbemObjectSink::Indicate 메서드를 호출하여 간헐적인 상태 보고할 수 있습니다. 결과 집합의 끝을 나타내기 위해 IWbemObjectSink::SetStatus 메서드가 호출됩니다.
공급자가 쿼리 처리를 지원하지 않는 경우 WMI는 이를 지원할 수 있습니다. 그러나 쿼리 처리의 공급자 구현은 WMI 버전보다 더 효율적일 수 있습니다. 쿼리를 지원하려면 instance 공급자가 ExecQueryAsync 메서드를 구현해야 합니다. 공급자가 ExecQueryAsync를 지원하는 경우 WMI는 strQuery 매개 변수를 통해 간단한 단항 SELECT 쿼리를 공급자에게 직접 보내고 공급자는 쿼리를 구문 분석하고 관련 인스턴스를 반환해야 합니다. WMI는 쿼리가 WQL로 작성된 경우에도 쿼리를 수정하지 않으므로 공급자가 쿼리를 구문 분석해야 합니다.
쿼리 처리에 WMI를 사용하려면 __InstanceProviderRegistrationQuerySupportLevels 속성을 설정하지 마세요. 이렇게 하면 WMI가 CreateInstanceEnumAsync 의 구현을 호출하고 게시는 호출자가 쿼리 조건을 충족하는 인스턴스만 가져오도록 결과를 필터링합니다.
다음 예제에서는 ExecQueryAsync의 일반적인 instance 공급자 구현을 보여줍니다. 결과 집합의 끝을 나타내기 위해 IWbemObjectSink::SetStatus 메서드가 호출됩니다. IWbemObjectSink::오류 조건이 발생하는지 여부를 나타내기 위해 IWbemObjectSink에 대한 중간 호출 없이 호출할 수도 있습니다.
콜백은 클라이언트에서 요구하는 것과 동일한 인증 수준에서 반환되지 않을 수 있으므로 비동기 통신 대신 반동기를 사용하는 것이 좋습니다. 비동기 통신이 필요한 경우 메서드 호출을 참조하세요.
자세한 내용은 IWbemServices::ExecQuery 및 메서드 호출을 참조하세요.
HRESULT CStdProvider::ExecQueryAsync(
/* [in] */ BSTR strQueryLanguage,
/* [in] */ BSTR strQuery,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
// Parse the query.
// You must implement ParseQuery().
if (!ParseQuery(strQuery)) return WBEM_E_PROVIDER_NOT_CAPABLE;
// Assume there is an IWbemServices pointer (m_pSvc) available to
// retrieve the class definition.
HRESULT hRes = m_pSvc->GetObject(L"ClassName", 0, NULL, &pClass, 0);
if (FAILED(hRes))
return hRes;
// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
int iNumInst = GetNumberInst();
// Now loop through the private source and create each
// instance which is part of the result set of the query.
for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
{
// Prepare an empty object to receive the class definition.
IWbemClassObject *pNextInst = 0;
hRes = pClass->SpawnInstance(0, &pNextInst);
// Create the instance.
// You must implement FillInst().
/*FillInst(pNextInst, iCnt);*/
// Deliver the class to WMI.
pResponseHandler->Indicate(1, &pNextInst);
pNextInst->Release( );
}
// Clean up memory
pClass->Release();
// Send finish message to WMI.
pResponseHandler->SetStatus(0, hRes, 0, 0);
return hRes;
}
이전 예제에서 instance 공급자는 WMI에서 스레드를 획득하여 필요한 동기화 작업을 수행합니다. 싱크 AddRef 메서드를 호출하고 다른 스레드를 만들어 결과 집합의 개체를 전달할 수 있습니다. 다른 스레드를 만들면 현재 스레드가 스레드 풀을 고갈하지 않고 WMI로 돌아갈 수 있습니다. 공급자가 단일 스레드 디자인 또는 이중 스레드 디자인을 선택하는지 여부는 공급자가 WMI 스레드를 사용할 계획에 따라 달라집니다. 고정된 규칙이 없습니다. 실험을 통해 디자인이 WMI 성능에 미치는 영향을 확인할 수 있습니다.
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);
요구 사항
| 지원되는 최소 클라이언트 | Windows Vista |
| 지원되는 최소 서버 | Windows Server 2008 |
| 대상 플랫폼 | Windows |
| 헤더 | wbemcli.h(Wbemidl.h 포함) |
| 라이브러리 | Wbemuuid.lib |
| DLL | Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll |