Share via

3.1.4.3.18 IWbemServices::ExecQuery (Opnum 20)

  • Article

The IWbemServices::ExecQuery method returns an enumerable collection of IWbemClassObject interface objects based on a query.

 HRESULT ExecQuery(
   [in] const BSTR strQueryLanguage,
   [in] const BSTR strQuery,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out] IEnumWbemClassObject** ppEnum
 );

strQueryLanguage: MUST be set to "WQL".

strQuery: MUST contain the "WQL" query text as specified in [UNICODE] (UTF-16) and in section 2.2.1. This parameter MUST NOT be NULL.

lFlags: Specifies the behavior of the IWbemServices::ExecQuery method. Flag behavior MUST be interpreted as specified in the following table.

The server MUST allow any combination of zero or more flags from the following table and MUST comply with all the restrictions in a flag description. Any other DWORD value that does not match a flag condition MUST be treated as not valid.

Value

Meaning

WBEM_FLAG_USE_AMENDED_QUALIFIERS

0x00020000

If this bit is not set, the server SHOULD not return CIM localizable information.

If this bit is set, the server SHOULD return CIM localizable information for the CIM object, as specified in section 2.2.6.

WBEM_FLAG_RETURN_IMMEDIATELY

0x00000010

If this bit is not set, the server MUST make the method call synchronously.

If this bit is set, the server MUST make the method call semisynchronously.

WBEM_FLAG_DIRECT_READ

0x00000200

If this bit is not set, the server MUST consider the entire class hierarchy when it returns the result.

If this bit is set, the server MUST disregard any derived class when it searches the result.

WBEM_FLAG_PROTOTYPE

0x00000002

If this bit is not set, the server MUST run the query.

If this bit is set, the server MUST only return the class schema of the resulting objects.

WBEM_FLAG_FORWARD_ONLY

0x00000020

If this bit is not set, the server MUST return an enumerator that has reset capability.

If this bit is set, the server MUST return an enumerator without reset capability, as specified in section 3.1.4.4.

pCtx: MUST be a pointer to an IWbemContext interface, which MUST contain additional information that the client wants to pass to the server. If pCtx is NULL, the parameter MUST be ignored.

ppEnum: MUST receive the pointer to the IEnumWbemClassObject that is used to enumerate through the CIM objects that are returned for the query result set. This parameter MUST NOT be NULL.

Return Values: This method MUST return an HRESULT value that MUST indicate the status of the method call. The server MUST return WBEM_S_NO_ERROR (as specified in section 2.2.11) to indicate the successful completion of the method.

WBEM_S_NO_ERROR (0x00)

The security principal that makes the call MUST have WBEM_ENABLE and WBEM_REMOTE_ENABLE accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

In response to IWbemServices::ExecQuery, the server MUST evaluate the strQuery and strQueryLanguage parameters (as specified in this section) and MUST return all instances that match the provided query. The method MUST fail if the method parameters or their combinations are not valid, as specified earlier in this section, or if the server is unable to execute the method.

The server SHOULD enforce a maximum length for the strQuery parameter, and return WBEM_E_QUOTA_VIOLATION if the limit is exceeded.<48>

If the strQuery is not syntactically valid or one or more elements in <PROPERTY-LIST> contains undefined properties, the server MUST return WBEM_E_INVALID_QUERY.

If strQuery is evaluated successfully, the following processing rules MUST be applied. These rules use the following state variables:

QueryPropertyList: A list of properties to be retrieved, from the WQL SELECT query.

QueryWhereFilter: The WHERE clause of the query.

  1. If strQuery begins with SELECT, the server MUST do the following:

    1. Find the NamespaceConnection matching the current session.

    2. Populate the QueryPropertyList and QueryWhereFilter data from the query.

    3. Search the ClassTable for the class-name specified in the FROM clause and find all the classes in the inheritance hierarchy (through the DerivedClassTable).

    4. For each class:

      • If InstanceProviderId is not zero:

        • Find QuerySupportLevels corresponding to the given ProviderId in the ProviderTable.

        • If QuerySupportLevels contains "WQL:UnarySelect" or "WQL:V1ProviderDefined", the server MUST call the provider method specified in 3.1.4.17.15 by passing the strQuery.

        • If the results are returned from the provider, then the server MUST skip the remaining steps.

        • If the provider returned WBEM_E_PROVIDER_NOT_CAPABLE, the server MUST call the provider method specified in 3.1.4.17.1 to obtain the instances of the class.

      • If InstanceProviderId is zero:

        • The server MUST find the instances for the class in ClassInstancesTable in the ClassTable corresponding to the class.

  2. Filter the enumerated instances using the QueryWhereFilter (see WQL Query (section 2.2.1)).

  3. From the filtered instances, select only the properties on the QueryPropertyList to form the result of the query.

  4. If strQuery begins with ASSOCIATORS OF, the server MUST do the following:

    1. Find the NamespaceConnection matching the current session.

    2. Populate the QueryWhereFilter data from the query.

    3. Get all the WMI instances matching the object-path in the query.

    4. From the __CLASS property of each instance, get the class-name of all returned WMI objects.

    5. Search in the NamespaceConnection.ClassTable for those classes with properties of type REF [DMTF-DSP0004] with the class-name matching one of the class names from step 4. Call the resulting list AssociationClasses.

    6. For each RequiredAssocQualifier clause in the query, remove from AssociationClasses any class not containing the qualifier value specified with RequiredAssocQualifier.

    7. For each class in AssociationClasses:

      • If InstanceProviderId is not zero:

        • Find QuerySupportLevels corresponding to the given ProviderId in the ProviderTable.

        • If QuerySupportLevels contains "WQL:UnarySelect" or "WQL:V1ProviderDefined", the server MUST call the provider method specified in 3.1.4.17.15 by passing the strQuery.

        • If the results are returned from the provider, then the server MUST skip the remaining steps.

        • If the provider returned WBEM_E_PROVIDER_NOT_CAPABLE, the server MUST call the provider method specified in 3.1.4.17.1 to obtain the instances of the class.

      • If InstanceProviderId is zero:

        • The server MUST find the instances for the class in ClassInstancesTable in the ClassTable corresponding to the class.

      1. After all the instances are obtained from the preceding step, select the instances where the REF property matched one of the instances from step 3.

      2. For each remaining instance, look for all other ref properties in the instance and get the object referenced by them.

      3. Filter this list of instances using the QueryWhereFilter.

      4. The server SHOULD<49> process the following step. If KeysOnly is specified as part of the QueryWhereFilter, search the class table again for the classes of the filtered instances and get the list of key properties from ClassDeclaration (key properties will have a qualifier 'key'). Select the values of (only) the key properties to form the result of the query.

      5. If ClassDefsOnly is specified as part of the QueryWhereFilter, search the ClassTable again for the classDeclaration of the filtered instances and return the class declaration instead of the instances as the result of the query.

  5. If strQuery begins with REFERENCES OF, the server MUST do the following:

    1. Find the NamespaceConnection matching the current session.

    2. Populate the QueryWhereFilter data from the query.

    3. Get all the WMI instances matching the object-path in the query.

    4. From the __CLASS property, get the class-name of all returned WMI objects.

    5. Search in the NamespaceConnection.ClassTable for those classes with properties of type REF [DMTF-DSP0004] with the class-name matching one of the class names from step 4. Call the resulting list AssociationClasses.

    6. For each class in AssociationClasses:

      • If InstanceProviderId is not zero:

        • Find QuerySupportLevels corresponding to the given ProviderId in the ProviderTable.

        • If QuerySupportLevels  contains "WQL:UnarySelect" or "WQL:V1ProviderDefined", the server MUST call the Provider method specified in 3.1.4.17.15 by passing the strQuery.

        • If the results are returned from the provider, then the server MUST skip the remaining steps.

        • If the provider returned WBEM_E_PROVIDER_NOT_CAPABLE, the server MUST call the provider method specified in 3.1.4.17.1 to obtain the instances of the class.

      • If InstanceProviderId is zero:

        • The server MUST find the instances for the class in ClassInstancesTable in the ClassTable corresponding to the class.

  6. After all the instances are obtained from the above step, select the instances where the REF property matched one of the instances from step 3.

  7. Filter this list of instances using the QueryWhereFilter.

  8. The server SHOULD<50> process the following step. If Keysonly is specified as part of QueryWhereFilter, search the ClassTable again for the classes of the filtered instances and get the list of keys from ClassDeclaration (key properties will have a qualifier 'key'). Select the values of (only) the key properties to form the result of the query.

  9. If classdefsonly is specified as part of the QueryWhereFilter, search the ClassTable again for the ClassDeclaration of the filtered instances and return the class declaration instead of the instances as the result of the query.

The successful synchronous method execution MUST fill the ppEnum parameter with a IEnumWbemClassObject interface pointer after all instances are collected and MUST return WBEM_S_NO_ERROR.

The semisynchronous method execution MUST follow the rules that are specified in section 3.1.1.1.2.

The failed method execution MUST set the value that is referenced by the output parameters to NULL and MUST return an error in the format specified in section 2.2.11.