Share via

3.1.4.3.4 IWbemServices::GetObject (Opnum 6)

  • Article

The IWbemServices::GetObject method retrieves a CIM class or a CIM instance. This method MUST retrieve CIM objects from the namespace that is associated with the current IWbemServices interface.

 HRESULT GetObject(
   [in] const BSTR strObjectPath,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out, in, unique] IWbemClassObject** ppObject,
   [out, in, unique] IWbemCallResult** ppCallResult
 );

strObjectPath: MUST be the CIM path of the CIM object to be retrieved. If the parameter is NULL, the server MUST return an empty CIM Object.

lFlags: Specifies the behavior of the IWbemServices::GetObject 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 return no 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 set, the server MUST disregard any derived class when it searches the result.

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

pCtx: MUST be a pointer to an IWbemContext interface, which MUST contain additional information that the client wants to pass for processing to the implementer of the CIM object that is referred to by strObjectPath. If the parameter is set to NULL, the server MUST ignore it.

ppObject: If the parameter is set to NULL, the server MUST ignore it. In this case, the output parameter MUST be filled according to the state of the lFlags parameter (whether WBEM_FLAG_RETURN_IMMEDIATELY is set) as listed in the following table.

Flag state

Success operation

Failure operation

WBEM_FLAG_RETURN_IMMEDIATELY is not set.

MUST contain an IWbemClassObject interface pointer.

MUST be set to NULL if the input parameter is non-NULL.

WBEM_FLAG_RETURN_IMMEDIATELY is set.

MUST be set to NULL if the input parameter is non-NULL.

MUST be set to NULL if the input parameter is non-NULL.

ppCallResult: The output parameter MUST be filled according to the state of the lFlags parameter (whether WBEM_FLAG_RETURN_IMMEDIATELY is set) as listed in the following table.

Flag state

Success operation

Failure operation

WBEM_FLAG_RETURN_IMMEDIATELY is not set.

MUST be set to NULL if the ppCallResult input parameter is non-NULL.

MUST be set to NULL if the ppCallResult input parameter is non-NULL.

WBEM_FLAG_RETURN_IMMEDIATELY is set.

The ppCallResult parameter MUST NOT be NULL upon input. If NULL, the server MUST return WBEM_E_INVALID_PARAMETER. Upon output, the parameter MUST contain the IWbemCallResult interface pointer.

MUST be set to NULL if the ppCallResult input parameter is non-NULL.

Return Values: This method MUST return an HRESULT that MUST indicate the status of the method call. The HRESULT MUST have the type and values as specified in section 2.2.11. 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_REMOTE_ENABLE and WBEM_ENABLE accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

In response to the IWbemServices::GetObject method, the server MUST interpret strObjectPath as defined in [DMTF-DSP0004] section 8.5. If the path refers to a class, the server MUST look it up in the ClassTable. If found, the server MUST return an object that represents the ClassDeclaration. If strObjectPath refers to an instance, the server MUST check the InstanceProviderId for the class. If InstanceProviderId is NULL, then the server MUST look up the CIM database and return the CIM instance. If InstanceProviderId is not NULL, then the server MUST find the provider entry corresponding to InstanceProviderId in the ProviderTable.

  • If found:

    • If SupportsGet is FALSE, the server MUST return WBEM_E_PROVIDER_NOT_CAPABLE.

    • Else the server MUST use the abstract interface specified as part of 3.1.4.17 to communicate with the provider, and return the appropriate results or the error code.

  • If not found, the server MUST return WBEM_E_PROVIDER_NOT_FOUND.

The successful synchronous method execution MUST provide the retrieved IWbemClassObject interface pointer in the ppObject parameter and MUST return WBEM_S_NO_ERROR.

The method MUST fail if the CIM object that is referred to by strObjectPath does not exist, if the method parameters are not valid as specified in the preceding list, or if the server is unable to execute the method. The failed method execution MUST set the output parameters to NULL and MUST return an error in the format specified in section 2.2.11.

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

If a class is marked by a Singleton qualifier, the server MUST treat "Class-Name = @" in the object path as referencing the singleton instance of the class.