Método IWbemServices::CreateClassEnumAsync (wbemcli.h)

Artículo
03/08/2023

El método IWbemServices::CreateClassEnumAsync devuelve una enumeración de todas las clases que admite el proveedor de clases. El proveedor de clases crea cada definición de clase desde cero y solo devuelve subclases de la clase solicitada. Como método asincrónico, CreateClassEnumAsync devuelve un mensaje de estado inmediatamente y, a continuación, actualiza el receptor pasado a través del parámetro pResponseHandler , si es necesario.

Cuando una llamada se realiza correctamente, WMI llama a AddRef en el puntero pResponseHandler, devuelve inmediatamente y, a continuación, llama asincrónicamente a pResponseHandler: >indique desde otro subproceso con definiciones de clase hasta que se cumpla la consulta.

Sintaxis

HRESULT CreateClassEnumAsync(
  [in] const BSTR      strSuperclass,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Parámetros

[in] strSuperclass

Si no es NULL o en blanco, este parámetro especifica un nombre de clase primario. Solo se devuelven las clases que son subclases de esta clase en el enumerador. Si null o en blanco, y lFlags es WBEM_FLAG_SHALLOW, solo se devuelven las clases de nivel superior (las que no tienen ninguna clase primaria). Si es NULL o en blanco y lFlags es WBEM_FLAG_DEEP, se devuelven todas las clases del espacio de nombres.

[in] lFlags

Uno o varios de los valores siguientes son válidos.

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 conexión actual. Si no se establece, solo se recuperan los calificadores almacenados en el espacio de nombres inmediato.

WBEM_FLAG_BIDIRECTIONAL

Esta marca hace que WMI conserve punteros a objetos de la enumeración hasta que el cliente libere el enumerador.

WBEM_FLAG_DEEP

Esta marca obliga a que la enumeración incluya 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 una solicitud en WMI para recibir informes de estado intermedios a través de la implementación de cliente de IWbemObjectSink::SetStatus. La implementación del proveedor debe admitir informes de estado intermedios para que esta marca cambie el comportamiento.

Nota Si strSuperclass es NULL o está en blanco y se especifica WBEM_FLAG_DEEP , se devuelven todas las clases.

[in] pCtx

Normalmente NULL. De lo contrario, se trata de un puntero a un objeto IWbemContext que puede usar el proveedor que devuelve las clases solicitadas. Los valores del objeto de contexto deben especificarse en la documentación del proveedor. Para obtener más información sobre este parámetro, vea Realizar 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 mediante el método IWbemObjectSink::Indicate . Cuando no hay objetos disponibles, WMI llama al método IWbemObjectSink::SetStatus . Si se devuelve algún código de error, no se usa el puntero IWbemObjectSink proporcionado. Si se devuelve WBEM_S_NO_ERROR, se llama a la implementación IWbemObjectSink del usuario para indicar el resultado de la operación. WMI solo llama a AddRef en el puntero cuando WBEM_S_NO_ERROR devuelve. Cuando se devuelve un código de error, el recuento de referencias es el mismo que ninguna entrada. Para obtener una explicación detallada de este parámetro, vea Llamar a un método.

Valor devuelto

Este método devuelve un valor HRESULT que indica el estado de la llamada al método. Si se produce un error, puede obtener información disponible de la función COM GetErrorInfo. Los códigos de error específicos de COM se pueden devolver si los problemas de red provocan que pierda la conexión remota a WMI. Tenga en cuenta que si CreateClassEnumAsync 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. En la lista siguiente se muestra el valor contenido en un HRESULT.

Comentarios

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. Si necesita comunicación asincrónica, consulte Llamar a un método.

Para obtener más información sobre el uso de métodos de forma semiincrónica, vea IWbemServices::CreateClassEnum y Llamada a un método.

Ejemplos

En el ejemplo de código siguiente se muestra cómo implementar CreateClassEnumAsync.

HRESULT CStdProvider::CreateClassEnumAsync( 
            /* [in] */ BSTR strSuperclass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0;

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

        // Deliver the class to WMI.
        pResponseHandler->Indicate(1, &pNextClass);
        pNextClass->Release( );

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

En el ejemplo anterior, el proveedor de clases 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 el diseño de subproceso único o el diseño de subproceso dual depende de la cantidad de tiempo que el proveedor 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


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