Método IWbemServices::CreateInstanceEnumAsync (wbemcli.h)
El método IWbemServices::CreateInstanceEnumAsync crea un enumerador que devuelve asincrónicamente las instancias de una clase especificada según los criterios de selección especificados por el usuario. Este método admite consultas simples del lenguaje de consulta WMI (WQL). Las consultas más complejas se pueden procesar mediante el método IWbemServices::ExecQueryAsync .
Sintaxis
HRESULT CreateInstanceEnumAsync(
[in] const BSTR strFilter,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parámetros
[in] strFilter
BSTR válido que contiene el nombre de la clase para la que se desean las instancias. Este parámetro no puede ser NULL.
[in] lFlags
Este parámetro puede ser uno de los valores siguientes.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Si se establece esta marca, Instrumental de administración de Windows (WMI) recupera los calificadores modificados almacenados en el espacio de nombres localizado de la configuración regional de la conexión actual. Si no se establece, solo se recuperan los calificadores almacenados en el espacio de nombres inmediato.
WBEM_FLAG_DEEP
Esta marca obliga a la enumeración a incluir instancias de esta y todas las subclases de la jerarquía.
WBEM_FLAG_SHALLOW
Esta marca obliga a la enumeración a incluir solo instancias puras de esta clase, excepto todas las instancias de subclases, que proporcionan propiedades que no se encuentran en esta clase.
WBEM_FLAG_SEND_STATUS
Esta marca registra con administración de Windows una solicitud para recibir informes de estado intermedios a través de la implementación de clientes de IWbemObjectSink::SetStatus. La implementación del proveedor debe admitir informes de estado intermedios para que esta marca cambie el comportamiento.
WBEM_FLAG_BIDIRECTIONAL
Esta marca hace que La administración de Windows conserve punteros a objetos de la enumeración hasta que el cliente libere el enumerador.
WBEM_FLAG_DIRECT_READ
Esta marca hace que el acceso directo al proveedor de la clase especificada sin tener en cuenta su clase o subclases primarias.
[in] pCtx
Normalmente NULL. De lo contrario, se trata de un puntero a un objeto IWbemContext que puede usar el proveedor que devuelve las instancias solicitadas. Los valores del objeto de contexto deben especificarse en la documentación del proveedor en cuestión. Para más información, consulte Llamadas a WMI.
[in] pResponseHandler
Puntero a la implementación del autor de la llamada de IWbemObjectSink. Este controlador recibe los objetos a medida que están disponibles. Si se devuelve algún código de error, no se usa el puntero IWbemObjectSink proporcionado. Si se devuelve WBEM_S_NO_ERROR , se llamará a la implementación IWbemObjectSink del usuario para indicar el resultado de la operación. Administración de Windows solo llama a AddRef en el puntero en los casos en los que WBEM_S_NO_ERROR devuelve. En los casos en los que se devuelve un código de error, el recuento de referencias es el mismo que en la entrada. Para más información, vea Llamada a un método.
Valor devuelto
Este método devuelve un valor HRESULT que indica el estado de la llamada al método. En la lista siguiente se muestra el valor contenido en un HRESULT.
Si se produce un error, puede obtener más información de la función COM GetErrorInfo.
También se pueden devolver códigos de error específicos de COM si los problemas de red hacen que pierda la conexión remota a la administración de Windows.
Un proveedor de instancias puede notificar el éxito o el error con el código devuelto de CreateInstanceEnumAsync, o a través de una llamada a SetStatus realizada a través de pResponseHandler. Si decide llamar a SetStatus, el código de retorno enviado a través de pResponseHandler tiene prioridad.
Si CreateInstanceEnumAsync devuelve WBEM_S_NO_ERROR, WMI espera un resultado del método SetStatus del controlador de respuesta. WMI espera indefinidamente en una conexión local o hasta que se agote el tiempo de espera de una conexión remota.
Comentarios
Se llama al método IWbemObjectSink::SetStatus para indicar el final del conjunto de resultados. También se puede llamar sin llamadas intermedias a IWbemObjectSink::Indicar si se producen condiciones de error.
Dado que es posible que la devolución de llamada no se devuelva en el mismo nivel de autenticación que requiere el cliente, se recomienda usar semisynchronous en lugar de la comunicación asincrónica.
Para obtener más información, vea IWbemServices::CreateInstanceEnum y Llamada a un método.
Ejemplos
En el ejemplo siguiente se muestra cómo implementar CreateInstanceEnumAsync.
#define NUM_OF_INSTANCES 3
HRESULT CStdProvider::CreateInstanceEnumAsync(
/* [in] */ BSTR strClass,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
IWbemClassObject *pNextInst = 0;
// Assume there is an IWbemServices pointer available to
// retrieve the class definition.
HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
if (hRes)
return hRes;
// Now loop through the private source and create each instance.
for (int i = 0; i < NUM_OF_INSTANCES; i++)
{
// Prepare an empty object to receive the class definition.
pClass->SpawnInstance(0, &pNextInst);
// Create the instance.
// For example, create the instance in a
// FillInst method you implement:
/*FillInst(pNextInst);*/
// Deliver the class to WMI.
pResponseHandler->Indicate(1, &pNextInst);
pNextInst->Release();
}
// Send a finish message to WMI.
pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
// Free memory resources.
SysFreeString(strClass);
pClass->Release();
m_pSvc->Release();
return WBEM_S_NO_ERROR;
}
En el ejemplo anterior, el proveedor de instancias adquiere un subproceso de WMI para realizar las operaciones necesarias. Es posible que desee llamar al método AddRef receptor y crear otro subproceso para entregar los objetos en el conjunto de resultados. La creación de otro subproceso permite que el subproceso actual vuelva a WMI sin agotar el grupo de subprocesos. Si el proveedor elige o no el diseño de subproceso único en el diseño de subproceso dual depende de cuánto tiempo planea usar el subproceso WMI. No hay reglas fijas. La experimentación puede ayudarle a determinar cómo afecta el diseño al rendimiento de WMI.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Plataforma de destino | Windows |
| Encabezado | wbemcli.h (include Wbemidl.h) |
| Library | Wbemuuid.lib |
| Archivo 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 |