Interface IWbemServices

Interface IWbemServices

Rev 1.07, 26-Aug-98, RayMcc

CIMOM exports the IWbemServices interface. It is used by clients and providers to access WBEM services. It is also exported by dynamic class and instance providers to expose their CIM objects to CIMOM (WinMgmt).

Providers implementing this interface must obey the documented semantics of each method that they implement. Also, providers must support the specified error return codes. While CIMOM implements all of the methods, each provider usually implements a small subset of the available functionality on this interface. A provider must return WBEM_E_PROVIDER_NOT_CAPABLE for any method that it does not implement.

Note: All outbound interface pointers from any IWbemServices method should be initialized to NULL before calling the interface method. For example, IWbemServices::GetObject returns an IWbemClassObject interface pointer. This pointer should be pre-initialized to NULL (or zero) before making the call:

IWbemClassObject *pObj = 0;
pWbemSvc->GetObject(strPath, 0, 0, &pObj, 0);

IWbemServices Methods	Description
OpenNamespace	Opens a particular child namespace for operations.
CancelAsyncCall	Cancels a currently executing asynchronous call.
QueryObjectSink	Allows the caller to obtain a notification handler sink.
GetObject	Retrieves an object, whether an instance or class definition.
GetObjectAsync	Asynchronously retrieves an object (an instance or class definition).
PutClass	Creates or updates a class definition.
PutClassAsync	Asynchronously creates or updates a class definition.
DeleteClass	Deletes a class.
DeleteClassAsync	Deletes a class and receives confirmation asynchronously.
CreateClassEnum	Creates a class enumerator.
CreateClassEnumAsync	Creates a class enumerator that executes asynchronously.
PutInstance	Creates or updates an instance of a particular class.
PutInstanceAsync	Asynchronously creates or updates an instance of a particular class.
DeleteInstance	Deletes a particular instance of a class.
DeleteInstanceAsync	Deletes an instance and provides confirmation asynchronously.
CreateInstanceEnum	Creates an instance enumerator.
CreateInstanceEnumAsync	Creates an instance enumerator that executes asynchronously.
ExecQuery	Executes a query to retrieve classes or instances.
ExecQueryAsync	Executes a query to retrieve classes or instances asynchronously.
ExecNotificationQuery	Executes a query to receive events.
ExecNotificationQueryAsync	Executes a query to receive events asynchronously.
ExecMethod	Executes an object method.
ExecMethodAsync	Executes an object method asynchronously.

IWbemServices::OpenNamespace

The IWbemServices::OpenNamespace method provides the caller with a new IWbemServices pointer that has the specified child namespace as its operating context. All operations through the new pointer, such as class or instance creation, only affect that namespace. The namespace must be a child namespace of the current object through which this method is called.

HRESULT IWbemServices::OpenNamespace(
    [in] BSTR strNamespace,
    [in] LONG lFlags,
    [in] IWbemContext *pCtx,
    [out, OPTIONAL] IWbemServices **ppWorkingNamespace
    [out, OPTIONAL] IWbemCallResult **ppResult
    );

Parameters

strNamespace
The object path to the target namespace. This namespace path can only be relative to the current namespace associated with the IWbemServices interface pointer. This parameter cannot be an absolute path or NULL.

lFlags
This parameter can be set to zero to make this a synchronous call. Otherwise, to make this a semisynchronous call set lFlags to WBEM_FLAG_RETURN_IMMEDIATELY, provide a valid pointer for the ppResult parameter and this call will return immediately.

pCtx
Reserved. Must be NULL.

ppWorkingNamespace
Receives the object representing the new namespace context. The returned pointer has a positive reference count. The caller must call Release on this pointer when it is no longer needed. This pointer is not modified when an error code is returned.

ppResult
Typically NULL. If not NULL, then ppWorkingNamespace must be NULL. In this case, the parameter receives a pointer to a new IWbemCallResult object. If the lFlags parameter is set to WBEM_FLAG_RETURN_IMMEDIATELY this call will return immediately. Then the caller can periodically poll the IWbemCallResult::GetResultServices method until the pointer for the requested namespace becomes available. This parameter is set to point to NULL when there is an error and a new object is not returned.

It is important to note that when you use this parameter, you must set ppResult to point to NULL before calling the method. This is a DCOM rule.

Return Values

WBEM_E_ACCESS_DENIED	The user does not have permission to access the requested namespace.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_NAMESPACE	The specified namespace does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	The communications link between the current process and CIMOM has failed.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes may also be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

IWbemLocator::ConnectServer can also be used to open the same namespace. The only difference is that the OpenNamespace method allows you to place relative object paths in the Namespace parameter to open child namespaces. IWbemLocator::ConnectServer requires a full object path and does user and password authentication.

For example, if the current namespace associated with the IWbemServices interface pointer is Root, then using Default in the Namespace parameter yields a new pointer bound to the Root\Default namespace.

The namespace is closed when Release is called and the reference count reaches zero.

See Also

IWbemLocator::ConnectServer

IWbemServices::CancelAsyncCall

The IWbemServices::CancelAsyncCall method cancels any currently pending asynchronous call based on the IWbemObjectSink pointer originally passed to an asynchronous method of IWbemServices. Before this method returns, it calls the Release method on the outstanding IWbemObjectSink pointer that was passed to the original asynchronous call. If the same IWbemObjectSink instance was used in multiple calls, all of those calls will be canceled simultaneously.

HRESULT IWbemServices::CancelAsyncCall(
[in] IWbemObjectSink *pSink
);

Parameters

pSink
The pointer to the IWbemObjectSink implementation provided by the client to any of the asynchronous methods of IWbemServices.

Return Values

WBEM_E_FAILED	This is an unspecified error.
WBEM_E_INVALID_PARAMETER	The supplied interface in pSink did not correspond to a pending asynchronous request
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

It is possible to make numerous asynchronous calls using the same object sink. In this case the IWbemServices::CancelAsyncCall method will cancel all asynchronous calls sharing this object sink. It is strongly recommend that there is one instance of the of an object sink for each asynchronous call outstanding.

See Also

IWbemObjectSink

IWbemServices::QueryObjectSink

The IWbemServices::QueryObjectSink method allows the caller to obtain a notification handler that is exported by CIMOM. This allows the caller to write notifications and events directly to CIMOM. The caller should only write extrinsic event types to CIMOM. This API consumes many resources and it no designed for a large number of events. Rather, it is provided so that client applications, especially setup and configuration applications, can quickly provide individual events to activate WBEM event consumers during installation and configuration sessions. If many events must be provided with low overhead, an event provider must be constructed.

HRESULT IWbemServices::QueryObjectSink(
    [in] LONG lFlags,
    [out] IWbemObjectSink **ppResponseHandler
    );

Parameters

lFlags
Reserved. It must be zero.

ppResponseHandler
May not be NULL. This parameter receives the interface pointer to the notification handler. The returned pointer has a positive reference count, and the caller must call Release on the pointer when it is no longer needed.

Return Values

WBEM_E_ACCESS_DENIED	The caller does not have permission to provide notifications to CIMOM.
WBEM_E_FAILED	This is an unspecified error.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

IWbemObjectSink

‹^# $ K + ›IWbemServices::GetObject�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::GetObject method retrieves a class or instance.

This method only retrieves objects from the namespace associated with the current IWbemServices object.

HRESULT IWbemServices::GetObject(

[in] BSTR strObjectPath,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out, OPTIONAL] IWbemClassObject **ppObject,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

strObjectPath

The object path of the object to retrieve. If this is NULL, an empty object is returned that can become a new class. See Class Creation_hmm_Declaring_Classes.

lFlags

This parameter can be set to zero to make this a synchronous call. Otherwise, to make this a semisynchronous call set lFlags to WBEM_FLAG_RETURN_IMMEDIATELY, provide a valid pointer for the ppCallResult parameter and this call will return immediately. See Making a Semisynchronous Call_hmm_Making_a_Semisynchronous_Call for more information on semisynchronous calls.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is producing the requested class or instance. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppObject

If not NULL, this receives the object, if it is found. The returned object has a positive reference count. The caller must use Release when the object is no longer needed. In all cases of error, this parameter is set to point to NULL.

ppCallResult

If NULL, this parameter is not used. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call will return immediately with WBEM_S_NO_ERROR. The ppCallResult parameter will receive a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which can then be polled to obtain the result using the GetCallStatus_hmm_IWbemCallresult_GetCallStatus method. The caller can call IWbemCallResult::GetResultObject_hmm_IWbemCallResult_GetResultObject to retrieve the object when it becomes available.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to access the object.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_PATH	The specified path was invalid.
WBEM_E_NOT_FOUND	The requested object could not be found.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Class Creation_hmm_Declaring_Classes, Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemCallResult_hmm_IWbemCallResult, IWbemServices::GetObjectAsync_hmm_IWbemServices_GetObjectAsync, Object Paths_hmm_Object_Paths

‹^# $ K + ›IWbemServices::GetObjectAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::GetObjectAsync method retrieves an object, either a class definition or instance, based on its path. This is similar to IWbemServices::GetObject_hmm_IWbemServices_GetObject except that the call returns immediately, and the object is provided to the supplied object sink.

Currently, this method retrieves objects only from the namespace associated with the IWbemServices pointer.

HRESULT IWbemServices::GetObjectAsync(

[in] BSTR strObjectPath,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strObjectPath

The object path of the object to retrieve. If this is NULL, an empty object, which can become a new class, is returned. See Class Creation_hmm_Declaring_Classes.

lFlags

WBEM_FLAG_SEND_STATUS registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is producing the requested class or instance. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the requested object when it becomes available through the IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus method. The pObjParam parameter contains the object. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef to the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see also Asynchronous Methods_hmm_making_an_asynchronous_call.

Return Values

WBEM_E_FAILED	Other error codes are returned asynchronously to the IWbemObjectSink.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_CLASS	The specified class does not exist.
WBEM_E_INVALID_PATH	The specified object path was invalid.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, Class Creation_hmm_Declaring_Classes, IWbemServices::GetObject_hmm_IWbemServices_GetObject, Object Paths_hmm_Object_Paths

‹^# $ K + ›IWbemServices::PutClass�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::PutClass method creates a new class or updates an existing one. The class specified by the pObject parameter must have been correctly initialized with all of the required property values.

The user may not create classes with names that begin or end with an underscore. This is reserved for system classes.

HRESULT IWbemServices::PutClass(

[in] IWbemClassObject *pObject,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

pObject

Must point to a valid class definition. The reference count is not changed.

lFlags

The following flags affect the behavior of this method.

Flag	Description
WBEM_FLAG_CREATE_OR_UPDATE	This flag causes the class to be created if it does not exist or overwritten if it exists already.
WBEM_FLAG_UPDATE_ONLY	This flag causes this call to update. The class must exist for the call to be successful.
WBEM_FLAG_CREATE_ONLY	This flag is used for creation only. The call will fail if the class already exists.
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisycnronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_OWNER_UPDATE	Push providers must specify this flag when calling PutClass to indicate that this class has changed.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppCallResult

If NULL, this parameter is not used. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call will return immediately with WBEM_S_NO_ERROR. The ppCallResult parameter will receive a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which can then be polled to obtain the result using the IWbemCallResult::GetCallStatus_hmm_IWbemCallresult_GetCallStatus method.

Return Values

WBEM_E_ACCESS_DENIED	The current user is not permitted to create or modify classes.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_CLASS	The class specified is invalid. You will see this error if a instance object is specified in the pObject parameter
WBEM_E_CLASS_HAS_CHILDREN	An attempt was made to make a change that would invalidate a subclass.
WBEM_E_INCOMPLETE_CLASS	The required properties for classes have not all been set.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.
WBEM_E_ALREADY_EXISTS	WBEM_FLAG_CREATE_ONLY flag was specified, but the class already exists.
WBEM_E_NOT_FOUND	WBEM_FLAG_UPDATE_ONLY was specified in lFlags, and the class was not found.
WBEM_E_INVALID_OPERATION	An invalid operation was attempted. This would include actions such as attempting to put a class with a name beginning with "__" characters which is reserved for system classes.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Class Creation and Modification Rules_hmm_Declaring_Classes, Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemCallResult_hmm_IWbemCallResult

‹^# $ K + ›IWbemServices::PutClassAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::PutClassAsync method creates a new class, or it updates an existing one. The class specified by the pObject parameter must be correctly initialized with all of the required property values. The call immediately returns. Success or failure is supplied to the object sink specified by the pResponseHandler parameter.

HRESULT IWbemServices::PutClassAsync(

[in] IWbemClassObject *pObject,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

pObject

Points to the object containing the class definition.

lFlags

Flag	Description
WBEM_FLAG_CREATE_OR_UPDATE	This flag causes this class to be created if it does not exist or be overwritten if it exists already.
WBEM_FLAG_UPDATE_ONLY	Updates an existing class
WBEM_FLAG_CREATE_ONLY	This flag is for class creation only. The call will fail if the class already exists.
WBEM_FLAG_SEND_STATUS	registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.
WBEM_FLAG_OWNER_UPDATE	Push providers must specify this flag when calling PutClassAsync to indicate that this class has changed.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is receiving the requested class. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the status of the Put request when the status becomes available using the SetStatus_hmm_IWbemObjectSink_SetStatus method. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef to the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to create classes.
WBEM_E_ALREADY_EXISTS	WBEM_FLAG_CREATE_ONLY flag was specified, but the class already exists.
WBEM_E_FAILED	This is an unspecified failure.
WBEM_E_INVALID_CLASS	The class specified is invalid. You will see this error if a instance object is specified in the pObject parameter
WBEM_E_CLASS_HAS_CHILDREN	An attempt was made to make a change that would invalidate a subclass.
WBEM_E_INCOMPLETE_CLASS	The required properties for classes have not all been set.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_NOT_FOUND	WBEM_FLAG_UPDATE_ONLY flag was specified, but the class does not exist.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

Other status or error codes are reported to the object sink specified by the pReponseHandler parameter.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, Class Creation and Modification Rules_hmm_Declaring_Classes, IWbemServices::PutClass_hmm_IWbemServices_PutClass

‹^# $ K + ›IWbemServices::DeleteClass�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::DeleteClass method deletes the specified class from the current namespace. If a dynamic instance provider is associated with the class, the provider is unregistered, and it is no longer called for by that class. Any classes that derive from the deleted class are also deleted, and their associated providers are unregistered. All outstanding static instances of the specified class and its subclasses are also deleted when the class is deleted.

If a dynamic class provider provides the class, the success of the deletion depends on whether the provider supports class deletion.

Note

System classes cannot be deleted.

HRESULT IWbemServices::DeleteClass(

[in] BSTR strClass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

strClass

The name of the class targeted for deletion.

lFlags

One of the following values can be set:

Flag	Description
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisychronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_OWNER_UPDATE	Indicates that the caller is a push or push-verify provider.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is deleting the class. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppCallResult

If NULL, this parameter is not used. If ppCallResult is specified, it must be set to point to NULL on entry. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call will return immediately with WBEM_S_NO_ERROR. The ppCallResult parameter will receive a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which can then be polled to obtain the result using the GetCallStatus_hmm_IWbemCallresult_GetCallStatus method.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications.

Return Values

WBEM_E_ACCESS_DENIED		The current user does not have permission to delete classes.
WBEM_E_FAILED		This indicates other unspecified errors.
WBEM_E_INVALID_CLASS		The specified class does not exist.
WBEM_E_CLASS_HAS_CHILDREN	Deleting this class would invalidate a subclass.
WBEM_E_INVALID_OPERATION		Deletion is not supported for the specified class. It may have been a system class or a class supplied by a dynamic provider that does not support class deletion.
WBEM_E_INVALID_PARAMETER		An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY		There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE		This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR		The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes may also be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemServices::DeleteClassAsync_hmm_IWbemServices_DeleteClassAsync

‹^# $ K + ›IWbemServices::DeleteClassAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::DeleteClassAsync method deletes the specified class from the current namespace. This method is identical to IWbemServices::DeleteClass_hmm_IWbemServices_DeleteClass except that the call returns immediately. Confirmation or failure is asynchronously reported to the specified object sink using the IWbemObjectSink::SetStatus method after the operation is complete.

HRESULT IWbemServices::DeleteClassAsync(

[in] BSTR strClass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strClass

The name of the class targeted for deletion.

lFlags

Flag	Description
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.
WBEM_FLAG_OWNER_UPDATE	Push providers must specify this flag when calling DeleteClassAsync to indicate that this class has changed.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is deleting the class. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to an implementation of IWbemObjectSink_hmm_IWbemObjectSink implemented by the caller. This handler receives the status of the deletion request when it becomes available through the IWbemObjectSink::SetStatus method. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call.

Return Values

WBEM_E_FAILED	This indicates other unspecified failures.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_CLASS_HAS_CHILDREN	Deleting this class would invalidate a subclass.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

All other return codes are provided to the object sink specified by the pReponseHandler parameter through the SetStatus method. Error conditions, such as when the class does not exist or the user does not have permission to delete classes, are reported to the handler. They are not reported in the return code of this method.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

If a dynamic instance provider is associated with the class, the provider is unregistered, and is no longer called for that class. Any classes that derive from the deleted class are also deleted, and their associated providers become unregistered. All outstanding static instances of the specified class and its subclasses are also deleted when the class is deleted.

If the class is provided by a dynamic class provider, the success of the deletion depends on whether class deletion is supported by that provider.

Note

Standard system classes cannot be deleted.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, Asynchronous Methods_hmm_making_an_asynchronous_call, IWbemServices::DeleteClass_hmm_IWbemServices_DeleteClass

‹^# $ K + ›IWbemServices::CreateClassEnum�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::CreateClassEnum method returns an enumerator for all classes satisfying the selection criteria.

The caller must then use the returned enumerator to retrieve the class definitions, calling IEnumWbemClassObject::Next_hmm_IEnumWbemClassObject_Next to obtain each class or blocks of classes. It finishes by calling IEnumWbemClassObject::Release_hmm_IEnumWbemClassObject_Release.

Note

It is not an error for the returned enumerator to have zero elements.

HRESULT IWbemServices::CreateClassEnum(

[in] BSTR strSuperclass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out] IEnumWbemClassObject **ppEnum

);

Parameters

strSuperclass

If not NULL or blank, specifies a superclass name. Only classes that are subclasses of this class are returned in the enumerator. If it is NULL or blank, and lFlags is WBEM_FLAG_SHALLOW, only the top-level classes, that is, classes that have no parent class or superclass, are returned. If it is NULL or blank and lFlags is WBEM_FLAG_DEEP, all classes within the namespace are returned.

lFlags

The following flags affect the behavior of this method. The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY | WBEM_FLAG_FORWARD_ONLY for best performance.

Flag	Description
WBEM_FLAG_DEEP	This flag forces the enumeration to include all of class in the hierarchy.
WBEM_FLAG_SHALLOW	This flag forces the enumeration to include only immediate subclasses of the specified superclass.
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisycnronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is providing the requested classes. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppEnum

Receives the pointer to the enumerator. The returned object has a positive reference count. The caller must call Release on the pointer when it is no longer required.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to view one or more of the classes that the call can return.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemServices::CreateClassEnumAsync_hmm_IWbemServices_CreateClassEnumAsync, IEnumWbemClassObject_hmm_IEnumWbemClassObject

‹^# $ K + ›IWbemServices::CreateClassEnumAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::CreateClassEnumAsync method performs the same function as IWbemServices::CreateClassEnum_hmm_IWbemServices_CreateClassEnum except that the classes are asynchronously provided to the specified response handler.

In cases where the call succeeds, CIMOM calls AddRef on the pointer pResponseHandler, and then returns immediately. It then asynchronously calls pResponseHandler – >Notify from another thread with class definitions until the query has been satisfied.

HRESULT IWbemServices::CreateClassEnumAsync(

[in] BSTR strSuperclass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in]IWbemObjectSink *pResponseHandler

);

Parameters

strSuperclass

If not NULL or blank, this parameter specifies a superclass name. Only classes that are subclasses of this class are returned in the enumerator. If NULL or blank, and lFlags is WBEM_FLAG_SHALLOW, only top-level classes, that is, those which have no parent class or superclass, are returned. If it is NULL or blank and lFlags is WBEM_FLAG_DEEP, all classes within the namespace are returned.

lFlags

Flag	Description
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.
WBEM_FLAG_DEEP .	This flag forces recursive enumeration into all subclasses derived from the specified superclass
WBEM_FLAG_SHALLOW	This flag forces the enumeration to include only immediate subclasses of the specified superclass.
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus..

Note

If strSuperclass is NULL or blank and WBEM_FLAG_DEEP is specified, all classes are returned.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is returning the requested classes. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the objects as they become available using the IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate method. When no more objects are available, the IWbemObjectSink::SetStatus method is called by CIMOM. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see Asynchronous Methods_hmm_making_an_asynchronous_call.

Return Values

WBEM_E_FAILED	This is an unspecified error.
WBEM_E_INVALID_CLASS	The specified class does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications,Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, IWbemServices::CreateClassEnum_hmm_IWbemServices_CreateClassEnum, IWbemObjectSink_hmm_IWbemObjectSink

‹^# $ K + ›IWbemServices::PutInstance�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::PutInstance method creates or updates an instance of an existing class. The instance is written to the CIMOM repository.

HRESULT IWbemServices::PutInstance(

[in] IWbemClassObject *pInst,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

pInst

Points to the instance to be written. The caller cannot make assumptions about the reference count at the completion of this call.

lFlags

One or more of the following values can be set:

Flag	Description
WBEM_FLAG_CREATE_OR_UPDATE	This flag causes the instance to be created if it does not exist or overwritten if it exists already.
WBEM_FLAG_UPDATE_ONLY	This flag causes this call to update. The instance must exist for the call to be successful.
WBEM_FLAG_CREATE_ONLY	This flag is used for creation only. The call will fail if the instance already exists.
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisychronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_OWNER_UPDATE	Push and push-verify providers must specify this flag when calling PutInstance to update the repository.

pCtx

Typically NULL, indicating that every property in the instance is to be updated. Otherwise, this is a pointer to an IWbemContext_hmm_IWbemContext object containing additional information about the instance. The data in the context object must be documented by the provider responsible for the instance. A non-NULL IWbemContext object can indicate whether supports exists for partial instance updates.

For more information about how to support full and partial instance updates, see Implementing IWbemServices::PutInstanceAsync_hmm_Implementing_IWbemServices_PutInstanceAsync.

For more information about requesting a partial or full instance update operation, see Updating an Instance_hmm_Updating_an_Instance.

ppCallResult

If NULL, this parameter is not used. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call will return immediately with WBEM_S_NO_ERROR. The ppCallResult parameter will then receive a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which can then be polled to obtain the result using the IWbemCallResult::GetCallStatus_hmm_IWbemCallResult_GetCallStatus method.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to update an instance of the specified class.
WBEM_E_ALREADY_EXISTS	WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.
WBEM_E_INVALID_CLASS	The class supporting this instance is invalid.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_ILLEGAL_NULL	A NULL value was specified for a property that may not be NULL, such as one that is marked by a key_hmm_standard_qualifier_reference, indexed_hmm_standard_qualifier_reference, or not_null_hmm_standard_qualifier_reference qualifier.
WBEM_E_INVALID_OBJECT	The specified instance is invalid (for example, PutInstance with a Class will invoke this return).
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_NOT_FOUND	WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

Applications and providers call PutInstance to create or update an instance of an existing class. Depending on how the pCtx parameter is set, either some or all of the properties of the instance are updated. For information about how to support partial instance updating, see Implementing IWbemServices::PutInstanceAsync_hmm_Implementing_IWbemServices_PutInstanceAsync. For information about requesting a partial instance update, see Updating an Instance_hmm_Updating_an_Instance.

PutInstance supports creating instances and updating instances only. It does not support moving instances. That is, a caller cannot set the pInst parameter to an instance that has a key that is the same as another instance in a sibling class. For example, suppose ClassA is the base class to ClassB and ClassC. ClassA defines the KeyProp property as its key and ClassB has an instance that has KeyProp set to 1. To create an instance of ClassC with KeyProp set to1, an application must first delete the ClassB instance by calling DeleteInstance_hmm_IWbemServices_DeleteInstance and then save it with PutInstance.

When the instance pointed to by pInst belongs to a subclass, CIMOM calls all of the providers responsible for the classes from which the subclass derives. All of these providers must succeed in order for the original PutInstance request to succeed. The provider supporting the topmost class in the hierarchy is called first. The calling order continues with the subclass of the topmost class and proceeds from top to bottom until CIMOM reaches the provider for the class owning the instance pointed to by pInst.

CIMOM does not call the providers for any of the child classes of an instance. Therefore, if an application wants to change the values of inherited properties, the application must call PutInstance on the full instance of the child class rather than a corresponding instance of the parent class.

Calling PutInstance on an instance of an abstract class is not allowed.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemCallResult_hmm_IWbemCallResult, IWbemServices::PutInstanceAsync_hmm_IWbemServices_PutInstanceAsync, Instance Creation and Modification Rules_hmm_creating_an_instance

‹^# $ K + ›IWbemServices::PutInstanceAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::PutInstanceAsync method asynchronously creates or updates an instance of an existing class. Update confirmation or error reporting is provided through the IWbemObjectSink_hmm_IWbemObjectSink interface implemented by the caller.

HRESULT IWbemServices::PutInstanceAsync(

[in] IWbemClassObject pInst,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

pInst

Points to the instance to be written to the CIMOM repository. The caller cannot make assumptions about the reference count at the completion of this call. .

lFlags

One or more of the following values can be specified:

Flag	Description
WBEM_FLAG_CREATE_OR_UPDATE	This flag causes this instance to be created if it does not exist or be overwritten if it exists already.
WBEM_FLAG_UPDATE_ONLY	Updates an existing instance
WBEM_FLAG_CREATE_ONLY	This flag is for instance creation only. The call will fail if the class already exists.
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.
WBEM_FLAG_OWNER_UPDATE	Push providers must specify this flag when calling PutInstanceAsync to indicate that this class has changed.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the status of this call when it becomes available using the IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus method. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of how to make asychronous calls, see Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call.

Return Values

WBEM_E_ALREADY_EXISTS	WBEM_FLAG_CREATE_ONLY flag was specified, but the instance already exists.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_ACCESS_DENIED	The user does not have permission to add or update the instance specified.
WBEM_E_INVALID_OBJECT	The specified instance is invalid. You will see this error if the supplied object is not an instance object.
WBEM_E_ILLEGAL_NULL	A NULL value was specified for a property that is not NULL, such as one marked by a key_hmm_standard_qualifier_reference, indexed_hmm_standard_qualifier_reference, or not_null_hmm_standard_qualifier_reference qualifier.
WBEM_E_INVALID_CLASS	The specified class was invalid.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_NOT_FOUND	WBEM_FLAG_UPDATE_ONLY flag was specified, but the instance does not exist.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

Clients that call PutInstanceAsync must always expect the results of the call to be reported using their IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate method.

When the instance pointed to by pInst belongs to a class that is derived from other classes, the success of PutInstanceAsync depends on the success of the providers responsible for the superclasses. For example, if pInst belongs to ClassB and ClassB derives from ClassA, a call to the PutInstanceAsync method implemented by the provider for ClassA must succeed in order for the update operation on ClassB to succeed. For more information, see the Remarks section for IWbemServices::PutInstance_hmm_IWbemServices_PutInstance.

See Also

Asynchronous Methods_hmm_making_an_asynchronous_call, IWbemContext_hmm_IWbemContext, Instance Creation and Modification Rules_hmm_creating_an_instance

‹^# $ K + ›IWbemServices::DeleteInstance�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::DeleteInstance method deletes an instance of an existing class in the current namespace.

HRESULT IWbemServices::DeleteInstance(

[in] BSTR strObjectPath,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

strObjectPath

A valid BSTR containing the object path to the instance to be deleted.

lFlags

One of the following values are valid:

Flag	Description
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisychronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_OWNER_UPDATE	Push and push-verify providers must set this flag when deleting an instance.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is deleting the instance. The values in the context object must be specified in the documentation for the provider in question.

ppCallResult

If NULL, this parameter is not used. If ppCallResult is specified, it must be set to point to NULL on entry. If the lFlags parameter contains WBEM_FLAG_RETURN_IMMEDIATELY, this call will return immediately with WBEM_S_NO_ERROR. The ppCallResult parameter will receive a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which can then be polled to obtain the result using the GetCallStatus_hmm_IWbemCallresult_GetCallStatus method.

Return Values

WBEM_E_ACCESS_DENIED	The current context does not have adequate rights to delete the object.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class does not exist.
WBEM_E_INVALID_PARAMETER	One of the parameters was not valid. This will be attempting to delete a class object.
WBEM_E_NOT_FOUND	The object did not exist.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

IWbemServices::DeleteInstance is called to delete an existing instance in the current namespace. Instances in other namespaces cannot be deleted. When DeleteInstance is called to delete an instance that belongs to a class in a hierachy, CIMOM calls the DeleteInstanceAsync method for all of the providers responsible for non-abstract classes in the hierarchy. That is, if the strObjectPath parameter identifies an instance of ClassB, and ClassB derives from ClassA, a non-abstract class, and is the parent class of ClassC and ClassD, also non-abstract classes, the providers for all four classes are called.

CIMOM calls each provider with an object path that is modified to point to their class. For example, if strObjectPath for the original call is set to "ClassB.k=1", the call to the provider of ClassA would set strObjectPath to "ClassA.k=1".

The success of a DeleteInstance call depends only on the success of a DeleteInstanceAsync call to the provider of the top-most non-abstract class. A non-abstract class has an abstract class as its parent. If the provider for any one of such classes succeeds, the operations succeeds, if all such classes fail, the operation fails.

For example, assume that ClassX is the base class for the following hierarchy:

1. ClassA derives from ClassX.

2. ClassB derives from ClassA.

3. ClassC and ClassD derive from ClassB.

If ClassX is the only abstract class in the hierarchy and the strObjectPath parameter in DeleteInstance points to an instance of ClassB, only the provider for ClassA needs to succeed in its DeleteInstanceAsync call.

If ClassX, ClassA, and ClassB are all abstract and the strObjectPath parameter in DeleteInstance again points to an instance of ClassB, either the provider for ClassC or the provider for ClassD must succeed.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemCallResult_hmm_IWbemCallResult, IWbemServices::DeleteInstanceAsync_hmm_IWbemServices_DeleteInstanceAsync, Object Paths_hmm_Object_Paths

‹^# $ K + ›IWbemServices::DeleteInstanceAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::DeleteInstanceAsync method asynchronously deletes an instance of an existing class in the current namespace. The confirmation or failure of the operation is reported through the IWbemObjectSink_hmm_IWbemObjectSink interface implemented by the caller.

HRESULT IWbemServices::DeleteInstanceAsync(

[in] BSTR strObjectPath,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strObjectPath

A valid BSTR containing the object path_hmm_Object_Paths of the object to be deleted.

lFlags

Flag	Description
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.
WBEM_FLAG_OWNER_UPDATE	Push and push-verify providers must specify this flag when calling DeleteInstanceAsync to indicate that this class has changed.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is deleting the instance. The values in the context object must be specified in the documentation for the provider in question.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the status of the delete operation as it becomes available through the SetStatus_hmm_IWbemObjectSink_SetStatus method. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of making a call asynchronously, see Making an Asynchronous Call_hmm_making_an_asynchronous_call.

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class was invalid.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error conditions are reported asynchronously to the object sink supplied by the pResponseHandler parameter.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Note

Clients that call DeleteInstanceAsync must always expect the results of the call to be reported using their IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate method.

When the instance pointed to by strObjectPath belongs to a class that is a member of a class hierarchy, the success of DeleteInstanceAsync depends on the top-most non-abstract provider. For a detailed explanation of the dependencies involved that determine the success of this operation, see the Remarks section for IWbemServices::DeleteInstance_hmm_IWbemServices_Deletenstance.

See Also

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, IWbemServices::DeleteInstance_hmm_IWbemServices_DeleteInstance, Object Paths_hmm_Object_Paths

‹^# $ K + ›IWbemServices::CreateInstanceEnum�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::CreateInstanceEnum method creates an enumerator that returns the instances of a specified class according to user-specified selection criteria. This method supports simple WQL queries; more complex queries can be processed using the IWbemServices::ExecQuery_hmm_IWbemServices_ExecQuery method.

HRESULT IWbemServices::CreateInstanceEnum(

[in] BSTR strClass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out] IEnumWbemClassObject **ppEnum

);

Parameters

strClass

A valid BSTR containing the name of the class for which instances are desired. This parameter cannot be NULL.

lFlags

The following flags affect the behavior of this method. The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY | WBEM_FLAG_FORWARD_ONLY for best performance.

Flag	Description
WBEM_FLAG_DEEP	This flag forces the enumeration to include all of class in the hierarchy.
WBEM_FLAG_SHALLOW	This flag forces the enumeration to include only immediate subclasses of the specified superclass.
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisycnronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is providing the requested instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppEnum

Receives the pointer to the enumerator, which has a positive reference count. The caller must call IUnknown::Release on the pointer after it is no longer required.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to view instances of the specified class.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class does not exist or is invalid.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

It is not an error for the returned enumerator to have zero elements.

See Also

Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemServices::CreateInstanceEnumAsync_hmm_IWbemServices_CreateInstanceEnumAsync

‹^# $ K + ›IWbemServices::CreateInstanceEnumAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::CreateInstanceEnumAsync method creates an enumerator that asynchronously returns the instances of a specified class according to user-specified selection criteria. This method supports simple WQL queries; more complex queries can be processed using the IWbemServices::ExecQueryAsync_hmm_IWbemServices_ExecQueryAsync method.

HRESULT IWbemServices::CreateInstanceEnumAsync(

[in] BSTR strClass,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strClass

A valid BSTR containing the name of the class for which instances are desired. This parameter cannot be NULL.

lFlags

Flag	Description
WBEM_FLAG_DEEP	This flag forces the enumeration to include all of class in the hierarchy.
WBEM_FLAG_SHALLOW	This flag forces the enumeration to include only immediate subclasses of the specified superclass.
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus.
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is returning the requested instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the objects as they become available. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see Making an Asynchronous Call_hmm_making_an_asynchronous_call.

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_CLASS	The specified class does not exist or is invalid.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain additional information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

IWbemObjectSink::SetStatus is called to indicate the end of the result set. It may also be called with no intervening calls to IWbemObjectSink::Indicate if error conditions occur.

See Also

IWbemServices::CreateInstanceEnum_hmm_IWbemServices_CreateInstanceEnum

‹^# $ K + ›IWbemServices::ExecQuery�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecQuery method executes a query to retrieve objects.

For the valid types of queries that can be performed, see Queries_hmm_wbem_query_language.

HRESULT IWbemServices::ExecQuery(

[in] BSTR strQueryLanguage,

[in] BSTR strQuery,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out] IEnumWbemClassObject **ppEnum

);

Parameters

strQueryLanguage

A valid BSTR containing one of the query languages supported by CIMOM. This must be the "WQL," the acronym for WBEM Query Language.

strQuery

A valid BSTR containing the text of the query. This parameter cannot be NULL.

lFlags

The following flags affect the behavior of this method. The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY | WBEM_FLAG_FORWARD_ONLY for best performance.

Flag	Value
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.
WBEM_FLAG_RETURN_IMMEDIATELY	This flag causes this to be a semisycnronous call. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.
WBEM_FLAG_ENSURE_LOCATABLE	This flag ensures that any returned objects have enough information in them so that the system properties such as __PATH, __RELPATH, and __SERVER are non-NULL.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is providing the requested classes or instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter. ‹If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these cases, the parameter should be NULL.›

ppEnum

If no error occurs, this receives the enumerator that allows the caller to retrieve the instances in the result set of the query. It is not an error for the query to have a result set with zero instances. This is determined only by attempting to iterate through the instances. This object returns with a positive reference count. The caller must call Release when the object is no longer needed.

Return Values

WBEM_E_ACCESS_DENIED	The current user does not have permission to view the result set.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_QUERY	The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE	The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_E_INVALID_CLASS	The query specifies a class that does not exist.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

IWbemServices::ExecQuery processes the query specified in the strQuery parameter and creates an enumerator through which the caller can access the query results. The enumerator is a pointer to an IEnumWbemClassObject_hmm_IEnumWbemClassObject interface; the query results are instances of class objects made available through the IWbemClassObject_hmm_IWbemClassObject interface.

See Also

IWbemServices::ExecQueryAsync_hmm_IWbemServices_ExecQueryAsync

Data Queries_hmm_Data_Queries

Event Queries_hmm_Event_Queries

Schema Queries_hmm_Schema_Queries

‹^# $ K + ›IWbemServices::ExecQueryAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecQueryAsync method The IWbemServices::ExecQuery method executes a query to retrieve objects asynchronously.

HRESULT IWbemServices::ExecQueryAsync(

[in] BSTR strQueryLanguage,

[in] BSTR strQuery,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strQueryLanguage

A valid BSTR containing one of the query languages supported by CIMOM. This must be WQL.

strQuery

A valid BSTR containing the text of the query. This cannot be NULL.

lFlags

Flag	Description
WBEM_FLAG_BIDIRECTIONAL	This flag causes CIMOM to retain pointers to objects of the enumeration until the client releases the enumerator.
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators.
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus.
WBEM_FLAG_ENSURE_LOCATABLE	This flag ensures that any returned objects have enough information in them so that the system properties such as __PATH, __RELPATH, and __SERVER are non-NULL.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is returning the requested classes or instances. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.‹If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these cases, set the parameter to NULL.›

pResponseHandler

Points to the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the objects in the query result set as they become available. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM calls IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate with the objects any number of times, followed by a single call to IWbemObjectSink::SetStatus to indicate the final status.

CIMOM only calls AddRef to the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of call methods asynchronously, see Making an Asynchronous Call_hmm_making_an_asynchronous_call.

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The query specifies a class that does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error codes are returned to the object sink specified by the pResponseHandler parameter.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

Remarks

The caller's IWbemObjectSink::Indicate method may be called to report intermittant status. IWbemObjectSink::SetStatus is called to indicate the end of the result set.

See Also

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, IWbemServices::ExecQuery_hmm_IWbemServices_ExecQuery, Queries_hmm_wbem_query_language

‹^# $ K + ›IWbemServices::ExecNotificationQuery�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecNotificationQuery method executes a query to receive events. The call returns immediately, and the user can poll the returned enumerator for events as they arrive. Releasing the returned enumerator cancels the query.

HRESULT IWbemServices::ExecNotificationQuery(

[in] BSTR strQueryLanguage,

[in] BSTR strQuery,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[out] IEnumWbemClassObject **ppEnum

);

Parameters

strQueryLanguage

A valid BSTR containing one of the query languages supported by CIMOM. This cannot be NULL. Currently, only the WBEM Query Language (WQL)_hmm_WBEM_Query_Language is supported.

strQuery

A valid BSTR containing the text of the event-related query. This cannot be NULL.

lFlags

The following flags affect the behavior of this method. The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY | WBEM_FLAG_FORWARD_ONLY for best performance.

Flag	Description
WBEM_FLAG_FORWARD_ONLY	This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_RETURN_IMMEDIATELY	The user must specify this flag or the call will fail.This is because events are received continuously, which means the user must poll the returned enumerator. Blocking this call indefinitely while waiting for a possible event would block the thread for an indefinite amount of time. See Making a Semisynchronous Call_hmm_making_a_semisynchronous_call for more information on semisynchronous calls.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is providing the requested events. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppEnum

If no error occurs, this receives the enumerator that allows the caller to retrieve the instances in the result set of the query. The caller periodically calls IEnumWbemClassObject::Next_hmm_IEnumWbemClassObject_Next to see if any events are available. Notice that in this usage, Reset_hmm_IEnumWbemClassObject_Reset does not move the enumerator back to the beginning of the event sequence; it has no effect. The parameter can continue to receive events until Release is called on the returned enumerator.

Return Values

WBEM_E_ACCESS_DENIED	The current user is not authorized to view the result set.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The query specifies a class that does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_INVALID_QUERY	The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE	The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Temporary Event Consumers_hmm_Temporary_Event_Consumers, Error Handling for Applications_hmm_Error_Handling_for_Applications, IWbemServices::ExecNotificationQueryAsync_hmm_IWbemServices_ExecNotificationQueryAsync, Queries_hmm_wbem_query_language

‹^# $ K + ›IWbemServices::ExecNotificationQueryAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecNotificationQueryAsync method performs the same task as IWbemServices::ExecNotificationQuery_hmm_IWbemServices_ExecNotificationQuery except that events are supplied to the specified response handler until CancelAsyncCall_hmm_IWbemServices_CancelAsyncCall is called to stop the event notification.

HRESULT IWbemServices::ExecNotificationQueryAsync(

[in] BSTR strQueryLanguage,

[in] BSTR strQuery,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strQueryLanguage

A valid BSTR containing one of the query languages supported by CIMOM. This must be WQL.

strQuery

A valid BSTR containing the text of the event-related query. This cannot be NULL.

lFlags

Flag	Description
WBEM_FLAG_SEND_STATUS	This flag registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus..

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is returning the requested events. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pResponseHandler

Points to a the caller's implementation of IWbemObjectSink_hmm_IWbemObjectSink. This handler receives the objects in the query result set as they become available. To cease receiving events, the caller must call IWbemServices::CancelAsyncCall_hmm_IWbemServices_CancelAsyncCall using the same pointer value for pResponseHandler. As events become available, the supplied IWbemObjectSink::Indicate implementation is called to deliver the event objects. IWbemObjectSink::SetStatus is not called at any time, since there is no final or terminating condition. The call executes indefinitely until canceled. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation. CIMOM only calls AddRef on the pointer in cases where WBEM_S_NO_ERROR returns. In cases where an error code returns, the reference count is the same as on entry. For a detailed explanation of this parameter, see Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call.

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The query specifies a class that does not exist.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other error codes are returned to the object sink specified by the pResponseHandler parameter.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Temporary Event Consumers_hmm_Temporary_Event_Consumers

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call

Event Queries_hmm_Event_Queries

IWbemServices::ExecQuery_hmm_IWbemServices_ExecQuery

‹^# $ K + ›IWbemServices::ExecMethod�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecMethod method executes a method exported by a CIM object. The method call is forwarded to the appropriate provider where it executes. Information and status are returned to the caller, which blocks until the call is complete.

Methods are not directly implemented by CIMOM, but are exported by method providers. For any given CIM class, the available methods and their parameters must be specified in the documentation for the provider in question.

See Calling a Method_hmm_Calling_a_Method for additional information about executing methods.

HRESULT IWbemServices::ExecMethod(

[in] BSTR strObjectPath,

[in] BSTR MethodName,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemClassObject *pInParams,

[out, OPTIONAL] IWbemClassObject **ppOutParams,

[out, OPTIONAL] IWbemCallResult **ppCallResult

);

Parameters

strObjectPath

A valid BSTR containing the object path_hmm_Object_Paths of the object for which the method is executed.

MethodName

The name of the method for the object.

lFlags

This parameter can be set to zero to make this a synchronous call. Otherwise, to make this a semisynchronous call set lFlags to WBEM_FLAG_RETURN_IMMEDIATELY, provide a valid pointer for the ppCallResult parameter and this call will return immediately. See Making a Semisynchronous Call_hmm_Making_a_Semisynchronous_Call for more information on semisynchronous calls.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is executing the method. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pInParams

May be NULL if no inbound parameters are required to execute the method. Otherwise, this points to an IWbemClassObject that contains the properties acting as inbound parameters for the method execution. The contents of the object are method-specific, and are part of the specification for the provider in question.

ppOutParams

If not NULL, receives a pointer to the outbound parameters and return values for the method execution. The contents of this object are method-specific, and are part of the specification for the provider in question. The caller must call Release on the returned object when it is no longer required.

ppCallResult

If NULL, this is not used. If ppCallResult is specified it must be set to point to NULL on entry. In this case, the call returns immediately with WBEM_S_NO_ERROR. ppCallResult receives a pointer to a new IWbemCallResult_hmm_IWbemCallResult object, which must be polled to obtain the result of the method execution using the GetCallStatus method. The out-parameters for the call are available by calling IWbemCallResult::GetResultObject_hmm_IWbemCallResult_GetResultObject

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_CLASS	The specified class was invalid.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_PROVIDER_NOT_CAPABLE	The provider does not support method calls.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_E_INVALID_METHOD	The requested method was not available.
WBEM_E_ACCESS_DENIED	The current user was not authorized to execute the method.
WBEM_E_INVALID_METHOD_PARAMETERS	The supplied pInParams object was determined by the provider to be invalid.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Calling a Method_hmm_Calling_a_Method, IWbemServices::ExecMethodAsync_hmm_IWbemServices_ExecMethodAsync, IWbemCallResult::GetResultObject_hmm_IWbemCallResult_GetResultObject

‹^# $ K + ›IWbemServices::ExecMethodAsync�@�

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecMethodAsync method asynchronously executes a method exported by a CIM object. The call immediately returns to the client while the inbound parameters are forwarded to the appropriate provider where it executes. Information and status are returned to the caller through the supplied object sink.

Methods are not directly implemented by CIMOM, but are exported by method providers. For any given CIM class, the available methods and their parameters are part of the documentation for the provider in question.

HRESULT IWbemServices::ExecMethodAsync(

[in] BSTR strObjectPath,

[in] BSTR strMethodName,

[in] LONG lFlags,

[in] IWbemContext *pCtx,

[in] IWbemClassObject *pInParams,

[in] IWbemObjectSink *pResponseHandler

);

Parameters

strObjectPath

A valid BSTR containing the object path_hmm_Object_Paths of the object for which the method is to be executed.

strMethodName

The name of the method for the object.

lFlags

WBEM_FLAG_SEND_STATUS registers with CIMOM a request to receive intermediate status reports through the clients implementation of IWbemObjectSink::SetStatus.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that may be used by the provider that is executing the method. The values in the context object must be specified in the documentation for the provider in question. See Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

pInParams

Can be NULL if no inbound parameters are required to execute the method. Otherwise, this points to an IWbemClassObject that contains the properties acting as inbound parameters for the method execution. The contents of the object are method-specific, and are part of the specification for the provider in question.

pResponseHandler

Must not be NULL. The object sink receives the result of the method call. The outbound parameters are sent to IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate.The result of the call mechanism itself will be sent to IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus. Notice that IWbemObjectSink::SetStatus does not receive the return code of the CIM method. However, it receives the return code of the actual call-return mechanism, and is only useful for verifying that the call occurred or that it failed for mechanical reasons. The result code returned from the CIM method is returned in the outbound parameter object supplied to IWbemObjectSink::Indicate. If any error code is returned, then the supplied IWbemObjectSink pointer will not be used. If WBEM_S_NO_ERROR is returned, then the user's IWbemObjectSink implementation will be called to indicate the result of the operation.

Return Values

WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_PARAMETER	An invalid parameter was specified.
WBEM_E_OUT_OF_MEMORY	There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE	This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM.
WBEM_E_ACCESS_DENIED	The current user was not authorized to execute the method.
WBEM_S_NO_ERROR	The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

Other errors will be reported asynchronously to the object sink supplied in the pReponseHandler parameter

DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.

See Also

Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call, IWbemServices::ExecMethod_hmm_IWbemServices_ExecMethod