339 lines
14 KiB
HTML
339 lines
14 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Interface IUnsecuredApartment</title>
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<p> <font FACE="Arial Narrow" SIZE="6" COLOR="#800000"></p>
|
|
|
|
<p></font><b><font FACE="Arial Narrow" SIZE="6">Interface IUnsecuredApartment</font><font
|
|
FACE="Arial Narrow" SIZE="1" COLOR="#800000">¦@¦</font></b><font SIZE="2"
|
|
COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>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).</p>
|
|
|
|
<p> </p>
|
|
|
|
<p> <b></p>
|
|
|
|
<p>Methods in Vtable Order</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Iunknown Methods</b></font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Properties</b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>QueryInterface</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnsecuredApartment_QueryInterface</font><font
|
|
FACE="Arial" SIZE="2"> </font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Determines if the current object
|
|
supports a given interface.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>AddRef</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnsecuredApartment_AddRef</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Increases the object's reference
|
|
count by 1.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>Release</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnsecuredApartment_QueryInterface</font><font
|
|
FACE="Arial" SIZE="2"> </font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Decrements the object's reference
|
|
count, and frees the object when the reference count is zero.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> </p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td VALIGN="TOP" COLSPAN="2"></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>IUnsecuredApartment Methods</b></font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Properties</b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>CreateObjectStub</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnsecuredApartment_CreateObjectStub</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Creates an object stub to assist
|
|
making asynchronous calls from a client process. </font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> <font FACE="Arial" SIZE="1"></p>
|
|
|
|
<p> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IUnsecuredApartment::QueryInterface</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <u><b>IUnsecuredApartment::QueryInterface</b></u></font><font FACE="Arial" SIZE="2"
|
|
COLOR="#800000">_hmm_IUnsecuredApartment_QueryInterface</font><font FACE="Arial" SIZE="2">
|
|
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.</font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT IUnsecuredApartment::QueryInterface(</p>
|
|
|
|
<p>[in] REFIID</b><i> riid</i><b>,</p>
|
|
|
|
<p>[out] LPVOID</b><i> *ppv</i><b></p>
|
|
|
|
<p>);</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>riid</p>
|
|
|
|
<blockquote>
|
|
</i><p>The COM interface identifier of the requested interface.</p>
|
|
</blockquote>
|
|
|
|
<p> <i></p>
|
|
|
|
<p>obp</p>
|
|
|
|
<blockquote>
|
|
</i><p>Address of a pointer that will be filled with the interface pointer if the query
|
|
succeeds.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p> <font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns standard COM error codes for <b>QueryInterface</b>. It returns S_OK if the call
|
|
succeeds. If the call fails because the requested interface was not supported, the method
|
|
returns E_NOINTERFACE.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>When the application no longer needs the interface retrieved by a call to this method,
|
|
it must call the <b>Release</b> method for that interface to free it. The <b>QueryInterface</b>
|
|
method allows the extension of objects without interfering with each object's existing or
|
|
future functionality.</p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For more
|
|
information about this method, see the COM documentation in the Microsoft Platform SDK.</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IUnsecuredApartment::AddRef</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IUnsecuredApartment::AddRef</b> method increases the object's reference count by
|
|
1.</font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>ULONG AddRef( );</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>None.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns the new reference count.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>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 <b>AddRef</b> method, the object's
|
|
reference count is increased by 1. Use the <u><b>Release</b></u></font><font FACE="Arial"
|
|
SIZE="2" COLOR="#800000">_hmm_IWbemUnboundObjectSink_Release</font><font FACE="Arial"
|
|
SIZE="2"> method to decrease the object's reference count by 1. </p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For a
|
|
complete discussion of <b>IUnknown</b> methods, see <b>IUnknown Programming Basics</b>.</p>
|
|
|
|
<p>For more information about this method, see the COM documentation in the Microsoft
|
|
Platform SDK.</font><b><font FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IUnsecuredApartment::Release</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IUnsecuredApartment::Release</b> method decreases the object's reference count
|
|
by 1.</font><b><font FACE="Lucida Sans Typewriter" SIZE="2"></p>
|
|
|
|
<p>ULONG IUnsecuredApartment::Release( );</p>
|
|
|
|
<p></font><font FACE="Arial Narrow"> </p>
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>None.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns the new reference count.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>The object deallocates itself when its reference count reaches zero. Use the <u><b>AddRef</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnsecuredApartment_AddRef</font><font
|
|
FACE="Arial" SIZE="2"> method to increase the object's reference count by 1.</p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For more
|
|
information about this method, see the COM documentation in the Microsoft Platform SDK.</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IUnsecuredApartment::CreateObjectStub</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</font><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT IUnsecuredApartment::CreateObjectStub</b>(</p>
|
|
|
|
<p><b>[in] IUnknown</b> <i>*</font><font FACE="Courier New" SIZE="2">pObject</font></i><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2">,</p>
|
|
|
|
<p>[<b>out] IUnknown</b> <i>**</font><font FACE="Courier New" SIZE="2">ppStub</font></i><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2">,</p>
|
|
|
|
<p> <b></p>
|
|
|
|
<p>;</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>pObject</p>
|
|
|
|
<blockquote>
|
|
</i><p>A pointer to the client's in-process implementation of IWbemObjectSink.</p>
|
|
</blockquote>
|
|
|
|
<p> <i></p>
|
|
|
|
<p>ppstub</p>
|
|
|
|
<blockquote>
|
|
</i><p>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.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p> <font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns standard COM error codes for <b>QueryInterface</b>. It returns S_OK if the call
|
|
succeeds. If the call fails because the requested interface was not supported, the method
|
|
returns E_NOINTERFACE.</p>
|
|
|
|
<p>DCOM-specific error codes also may be returned if network problems cause you to lose
|
|
the remote connection to CIMOM.</p>
|
|
|
|
<p> </font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Sample Code</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>// Create the object which spawns new substitute sinks</p>
|
|
|
|
<p>IUnsecuredApartment *pSpawner = 0;</p>
|
|
|
|
<p>CoCreateInstance(CLSID_UnsecuredApartment, NULL, CLSCTX_ALL, IID_IUnsecuredApartment,
|
|
(void **) pSpawner);</p>
|
|
|
|
<p>// Create a substitute sink</p>
|
|
|
|
<p>IWbemObjectSink *pUserSink = ... // Create an instance of the user's sink by a private
|
|
mechanism</p>
|
|
|
|
<p>IUnknown *pSubstitute = 0;</p>
|
|
|
|
<p>pSpawner->CreateObjectStub(pUserSink, &pSubstitute);</p>
|
|
|
|
<p>IWbemObjectSink *pSubstituteSink = 0;</p>
|
|
|
|
<p>pSubstitute->QueryInterface(IID_IWbemObjectSink, &pSubstituteSink);</p>
|
|
|
|
<p>pSubstitute->Release( ); // we don't need this interface any more</p>
|
|
|
|
<p>// We now use pSubstituteSink in IWbemServices calls and objects are delivered to the
|
|
pUserSink.</p>
|
|
|
|
<p> </font><b><font FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IWbemObjectSink</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemObjectSink</font><font
|
|
FACE="Arial" SIZE="2">, <u>Making an Asynchronous Call</u></font><font FACE="Arial"
|
|
SIZE="2" COLOR="#800000">_hmm_Making_an_Asynchronous_Call</font><font FACE="Arial"
|
|
SIZE="2"><b></p>
|
|
|
|
<p> </b></font></p>
|
|
</body>
|
|
</html>
|