Interface IUnsecuredApartment¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The Iunsecured Apartment interface is used to simplify the process of making asynchronous calls from a client process. When a client is making asynchronous calls, the roles of the client and the server are reversed. In this case the client implements an object (IWbemObjectSink interface) and the server calls the methods of that object. Because of this, DCOM security rules for servers make it difficult for clients to make asynchronous calls. The primary difficulty is the fact that the client needs to inform DCOM that it is willing to allow CIMOM to invoke methods on the client's object (IWbemObjectSink).
Methods in Vtable Order
| Iunknown Methods | Properties |
| QueryInterface_hmm_IUnsecuredApartment_QueryInterface | Determines if the current object supports a given interface. |
| AddRef_hmm_IUnsecuredApartment_AddRef | Increases the object's reference count by 1. |
| Release_hmm_IUnsecuredApartment_QueryInterface | Decrements the object's reference count, and frees the object when the reference count is zero. |
| IUnsecuredApartment Methods | Properties |
| CreateObjectStub_hmm_IUnsecuredApartment_CreateObjectStub | Creates an object stub to assist making asynchronous calls from a client process. |
‹^# $ K + ›IUnsecuredApartment::QueryInterface¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IUnsecuredApartment::QueryInterface_hmm_IUnsecuredApartment_QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, and the application can use that interface immediately.
HRESULT IUnsecuredApartment::QueryInterface(
[in] REFIID riid,
[out] LPVOID *ppv
);
Parameters
riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.
Return Values
Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.
Remarks
When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IUnsecuredApartment::AddRef¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IUnsecuredApartment::AddRef method increases the object's reference count by 1.
ULONG AddRef( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release_hmm_IWbemUnboundObjectSink_Release method to decrease the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see IUnknown Programming Basics.
For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IUnsecuredApartment::Release¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IUnsecuredApartment::Release method decreases the object's reference count by 1.
ULONG IUnsecuredApartment::Release( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
The object deallocates itself when its reference count reaches zero. Use the AddRef_hmm_IUnsecuredApartment_AddRef method to increase the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IUnsecuredApartment::CreateObjectStub¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IUnsecuredApartment::CreateObjectStub creates an object forwarder sink to assist in receiving asynchronous calls from CIMOM. This function binds an unsecured object sink to a local object sink so that DCOM security will not interfere with asynchronous retrieval of CIM objects. Because of the fact that DCOM security is being bypassed, the remote WinMgmt server is assumed to be a trusted component.
The general paradigm is that the original implementation of IWbemObjectSink in the client process is not directly used in asynchronous calls to IWbemServices. Rather, both the original implementation and a substitute object are created, bound together, and then the substitute object is used in the asynchronous methods of IWbemServices.
HRESULT IUnsecuredApartment::CreateObjectStub(
[in] IUnknown *pObject,
[out] IUnknown **ppStub,
;
Parameters
pObject
A pointer to the client's in-process implementation of IWbemObjectSink.
ppstub
Receives a pointer to a substitute object to be used in asynchronous IWbemServices calls. The user receives an IUnknown pointer and must do a QueryInterface for IID_WbemObjectSink before using this object in asynchronous IWbemServices calls.
Return Values
Returns standard COM error codes for QueryInterface. It returns S_OK if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.
DCOM-specific error codes also may be returned if network problems cause you to lose the remote connection to CIMOM.
Sample Code
// Create the object which spawns new substitute sinks
IUnsecuredApartment *pSpawner = 0;
CoCreateInstance(CLSID_UnsecuredApartment, NULL, CLSCTX_ALL, IID_IUnsecuredApartment, (void **) pSpawner);
// Create a substitute sink
IWbemObjectSink *pUserSink = ... // Create an instance of the user's sink by a private mechanism
IUnknown *pSubstitute = 0;
pSpawner->CreateObjectStub(pUserSink, &pSubstitute);
IWbemObjectSink *pSubstituteSink = 0;
pSubstitute->QueryInterface(IID_IWbemObjectSink, &pSubstituteSink);
pSubstitute->Release( ); // we don't need this interface any more
// We now use pSubstituteSink in IWbemServices calls and objects are delivered to the pUserSink.
See Also
IWbemObjectSink_hmm_IWbemObjectSink, Making an Asynchronous Call_hmm_Making_an_Asynchronous_Call