Compartir a través de

Función ExecQueryWmi

  • Artículo

Ejecuta una consulta para recuperar objetos.

Nota

Esta API es solo para uso interno. No está pensada para usarla desde código del desarrollador.

Sintaxis

HRESULT ExecQueryWmi (
   [in] BSTR                    strQueryLanguage,
   [in] BSTR                    strQuery,
   [in] long                    lFlags,
   [in] IWbemContext*           pCtx,
   [out] IEnumWbemClassObject** ppEnum,
   [in] DWORD                   authLevel,
   [in] DWORD                   impLevel,
   [in] IWbemServices*          pCurrentNamespace,
   [in] BSTR                    strUser,
   [in] BSTR                    strPassword,
   [in] BSTR                    strAuthority
);

Parámetros

strQueryLanguage
[in] El valor de este parámetro se corresponde con una cadena con el lenguaje de consulta válido que se admite en la administración de Windows. Este deberá ser "WQL", que es el acrónimo del lenguaje de consulta de WMI.

strQuery
[in] El valor de este parámetro se corresponde con el texto de la consulta. Este parámetro no puede ser null.

lFlags
[in] El valor de este parámetro se corresponde con una combinación de marcas que afectan al comportamiento de esta función. Los siguientes valores se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlos como constantes en el código. Puede consultarlos a continuación:

Constante Value Descripción
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Si se establece este valor, desde la función se recuperarán los calificadores modificados que se almacenen en el espacio de nombres localizado de la configuración regional de la conexión actual.
Si este no se establece, desde la función solo se recuperarán los calificadores que se almacenen en el espacio de nombres inmediato.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 Si se establece esta marca, se producirá una llamada semisincrónica.
WBEM_FLAG_FORWARD_ONLY 0x20 Si se establece esta marca, se devolverá un enumerador que solo se lee hacia adelante de la función. Normalmente, el uso de enumeradores que solo se leen hacia adelante es más rápido y requiere un menor uso de memoria que cuando se usan enumeradores convencionales. Sin embargo, al usarlos no se permite que se realicen llamadas a la función Clone.
WBEM_FLAG_BIDIRECTIONAL 0 Si se establece este valor, la extensión WMI conservará los punteros que apunten a objetos de la enumeración hasta que estos se liberen.
WBEM_FLAG_ENSURE_LOCATABLE 0x100 Garantiza que los objetos devueltos tengan suficiente información en ellos para que las propiedades del sistema, como __PATH, __RELPATH y __SERVER, no sean null.
WBEM_FLAG_PROTOTYPE 2 Este marcador se utiliza para los prototipos. No ejecuta la consulta y, en su lugar, devuelve un objeto similar a un objeto de resultado típico.
WBEM_FLAG_DIRECT_READ 0x200 Provoca el acceso directo al proveedor de la clase especificada sin tener en cuenta su clase primaria ni sus subclases.

Las marcas cuyo uso se recomienda para obtener un mejor rendimiento son WBEM_FLAG_RETURN_IMMEDIATELY y WBEM_FLAG_FORWARD_ONLY.

pCtx
[in] Normalmente, este valor es null. De lo contrario, es un puntero que apunta a una instancia de la interfaz IWbemContext que puede usarse en el proveedor que proporciona las clases que se solicitan.

ppEnum
[out] Si no se produce ningún error, el valor de este parámetro se corresponderá con el puntero que apunta al enumerador que, a su vez, puede usarse para permitir que se recuperen las instancias del conjunto de resultados de consulta desde el llamador. La consulta puede tener un conjunto de resultados con cero instancias. Para obtener más información, consulte la sección Comentarios.

authLevel
[in] El valor de este parámetro se corresponde con el nivel de autorización.

impLevel
[in] El valor de este parámetro se corresponde con el nivel de suplantación.

pCurrentNamespace
[in] El valor de este parámetro se corresponde con un puntero que apunta a un objeto IWbemServices que, a su vez, se usa para representar el espacio de nombres actual.

strUser
[in] El valor de este parámetro se corresponde con el nombre de usuario. Consulte la función ConnectServerWmi para obtener más información.

strPassword
[in] El valor de este parámetro se corresponde con la contraseña. Consulte la función ConnectServerWmi para obtener más información.

strAuthority
[in] El valor de este parámetro se corresponde con el nombre de dominio del usuario. Consulte la función ConnectServerWmi para obtener más información.

Valor devuelto

Los siguientes valores que devuelve esta función se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlos como constantes en el código. Puede consultarlos a continuación:

Constante Value Descripción
WBEM_E_ACCESS_DENIED 0x80041003 Si se devuelve este valor, significa que el usuario no tiene permiso para visualizar una o varias de las clases que se pueden devolver desde función.
WBEM_E_FAILED 0x80041001 Error no especificado.
WBEM_E_INVALID_PARAMETER 0x80041008 Un parámetro no es válido.
WBEM_E_INVALID_QUERY 0x80041017 Si se devuelve este valor, significa que hubo un error de sintaxis en la consulta.
WBEM_E_INVALID_QUERY_TYPE 0x80041018 No se admite el lenguaje de consulta solicitado.
WBEM_E_QUOTA_VIOLATION 0x8004106c Si se devuelve este valor, significa que la consulta fue demasiado compleja.
WBEM_E_OUT_OF_MEMORY 0x80041006 Memoria insuficiente para completar la operación.
WBEM_E_SHUTTING_DOWN 0x80041033 Si se devuelve este valor, significa que es probable que WMI se encontrara en un proceso de detención y reinicio. En este caso, vuelva a llamar a la función ConnectServerWmi.
WBEM_E_TRANSPORT_FAILURE 0x80041015 Si se devuelve este valor, significará que ha ocurrido un error en el vínculo de llamada a procedimiento remoto (RPC) entre el proceso actual y WMI.
WBEM_E_NOT_FOUND 0x80041002 Si se devuelve este valor, significa que se especificó una clase que no existe en la consulta.
WBEM_S_NO_ERROR 0 Si se devuelve este valor, significará que la llamada a la función se realizó correctamente.

Comentarios

Esta función encapsula una llamada al método IWbemServices::ExecQuery.

Esta función procesa la consulta especificada en el parámetro strQuery y crea un enumerador mediante el cual el autor de la llamada puede acceder a los resultados de la consulta. El enumerador es un puntero a una interfaz IEnumWbemClassObject; los resultados de la consulta son instancias de objetos de clase disponibles mediante la interfaz IWbemClassObject.

Hay límites en el número de palabras clave AND y OR que se pueden usar en las consultas WQL. Si se usa un gran número de palabras clave WQL en una consulta compleja puede causar que, desde WMI, se devuelva el código de error WBEM_E_QUOTA_VIOLATION (o 0x8004106c) como valor HRESULT. El límite de palabras clave WQL que pueda usarse dependerá de la complejidad de la consulta.

Si se produce un error en la llamada a la función, podrá obtener información adicional sobre este mediante una llamada a la función GetErrorInfo.

Requisitos

Plataformas: Vea Requisitos de sistema.

Encabezado: WMINet_Utils.idl

Versiones de .NET Framework: está disponible desde la versión 4.7.2

Consulte también