dubey/WindowsXP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
WindowsXP/admin/wmi/wbem/winmgmt/specs/html/interface_iwbemlocator.htm
Tanishq Dubey cb60ae51e5
Initial Commit
2025-04-27 07:49:33 -04:00

424 lines
18 KiB
HTML
Raw Blame History

<html>
<head>
<title>Interface IWbemLocator</title>
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
</head>
<body>
<p>&nbsp;<font FACE="Arial Narrow" SIZE="6" COLOR="#800000"></p>
<p></font><b><font FACE="Arial Narrow" SIZE="6">Interface IWbemLocator</font><font
FACE="Arial Narrow" SIZE="1" COLOR="#800000">¦@¦</font></b><font SIZE="2"
COLOR="#ff00ff"></p>
<p>&lt;span style=color:#FF0000&gt;</font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff">&lt;/span&gt;</font><font
FACE="Arial" SIZE="2"> </p>
<p>Use the <b>IWbemLocator</b> interface to obtain the initial namespace pointer to the
CIM Object Manager (CIMOM) on a particular host machine. You can access CIMOM itself using
the <u><b>IWbemServices</b></u></font><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemServices</font><font
FACE="Arial" SIZE="2"> pointer, which is returned by the <b>ConnectServer</b> method on
this interface.</p>
<p>A client or provider that needs CIMOM services first obtains a pointer to the locator
using <b>CoCreateInstance</b> or <b>CoCreateInstanceEx</b>, as specified in COM
documentation in the Microsoft Platform SDK. The <b>IWbemLocator</b> object is always an
in-process COM server. The interface pointer to the desired namespace on the desired
target machine is then obtained through the <u><b>IWbemLocator::ConnectServer</b></u></font><font
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemLocator_ConnectServer</font><font
FACE="Arial" SIZE="2"> method, which is the only method on this interface.</p>
<p>&nbsp;<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>Description</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_IWbemLocator_QueryInterface</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_IwbemLocator_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_IWbemLocator_Release</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>
<tr>
<td VALIGN="TOP" COLSPAN="2"></td>
</tr>
<tr>
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>IWbemLocator Methods</b></font></td>
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Description</b></font></td>
</tr>
<tr>
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>ConnectServer</b></u></font><font
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemLocator_ConnectServer</font></td>
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Connects to CIMOM on the
specified machine.</font></td>
</tr>
</table>
<p>&nbsp;<font FACE="Arial" SIZE="1"></p>
<p>&nbsp;</font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
<p>&#139;^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
FACE="Arial Narrow" SIZE="5" COLOR="#800000">&#155;</font><b><font FACE="Arial Narrow"
SIZE="5">IWbemLocator::QueryInterface</font><font FACE="Arial Narrow" SIZE="1"
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
<p>&lt;span style=color:#FF0000&gt;</font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff">&lt;/span&gt;</font><font
FACE="Arial" SIZE="2"> </p>
<p>The <b>IWbemLocator::QueryInterface</b> 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 IWbemLocator::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>&nbsp;</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>&nbsp;<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>&nbsp;</p>
</blockquote>
<p>&nbsp;<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><i>. </i>It returns
WBEM_S_NO_ERROR 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>&#139;^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
FACE="Arial Narrow" SIZE="5" COLOR="#800000">&#155;</font><b><font FACE="Arial Narrow"
SIZE="5">IWbemLocator::AddRef</font><font FACE="Arial Narrow" SIZE="1" COLOR="#800000">¦@¦</font></b><font
SIZE="2" COLOR="#ff00ff"></p>
<p>&lt;span style=color:#FF0000&gt;</font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff">&lt;/span&gt;</font><font
FACE="Arial" SIZE="2"> </p>
<p>The <b>IWbemLocator::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>&nbsp;</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 <b>Release</b> 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>&#139;^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
FACE="Arial Narrow" SIZE="5" COLOR="#800000">&#155;</font><b><font FACE="Arial Narrow"
SIZE="5">IWbemLocator::Release</font><font FACE="Arial Narrow" SIZE="1" COLOR="#800000">¦@¦</font></b><font
SIZE="2" COLOR="#ff00ff"></p>
<p>&lt;span style=color:#FF0000&gt;</font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff">&lt;/span&gt;</font><font
FACE="Arial" SIZE="2"> </p>
<p>The <b>IWbemLocator::Release</b> method decreases the object's reference count by 1. </font><b><font
FACE="Lucida Sans Typewriter" SIZE="2"></p>
<p>ULONG Release( );</p>
<p></font><font FACE="Arial Narrow">&nbsp;</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_IWbemLocator_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>&#139;^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
FACE="Arial Narrow" SIZE="5" COLOR="#800000">&#155;</font><b><font FACE="Arial Narrow"
SIZE="5">IWbemLocator::ConnectServer</font><font FACE="Arial Narrow" SIZE="1"
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
<p>&lt;span style=color:#FF0000&gt;</font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff">&lt;/span&gt;</font><font
FACE="Arial" SIZE="2"> </p>
<p>The <b>IWbemLocator::ConnectServer</b> method connects to CIMOM on the machine
specified in the <i>strNetworkResource</i></font><font FACE="Arial"> </font><font
FACE="Arial" SIZE="2">parameter. This is typically a Microsoft</font><font FACE="Arial"
SIZE="1">®</font><font FACE="Arial" SIZE="2"> Windows NT</font><font FACE="Arial"
SIZE="1">®</font><font FACE="Arial" SIZE="2"> machine or a Microsoft</font><font
FACE="Arial" SIZE="1">®</font><font FACE="Arial" SIZE="2"> Windows</font><font
FACE="Arial" SIZE="1">®</font><font FACE="Arial" SIZE="2"> 95/98 target machine, which
must have an operational CIMOM.</font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
<p>HRESULT IWbemLocator::ConnectServer(</p>
<p>[in] BSTR</b><i> strNetworkResource</i><b>, </p>
<p>[in] BSTR</b><i> strUser</i><b>,</p>
<p>[in] BSTR</b><i> strPassword</i><b>,</p>
<p>[in] BSTR</b><i> strLocale</i><b>,</p>
<p>[in] LONG </b><i>lSecurityFlags</i><b>,</p>
<p>[in] BSTR </b><i>strAuthority</i>,</p>
<p>&nbsp;<b></p>
<p>[in] IWbemContext</b><i> *pCtx</i><b>, </b></p>
<p><b>[out] IWbemServices</b> <i>**ppNamespace</i> </p>
<p>&nbsp;<b></p>
<p>);</b></p>
<p></font><font FACE="Arial Narrow"><b>&nbsp;</p>
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
<p>strNetworkResource</p>
<blockquote>
</i><p>A pointer to a valid BSTR containing the object path of the desired CIMOM and
namespace. </p>
<p>For local machine access to the default namespace, use a simple object path:
&quot;root\default&quot; or &quot;\\.\root\default.&quot;</p>
<p>For access to the default namespace on a remote machine using Distributed COM (DCOM) or
Microsoft-compatible networking, include the machine name:
&quot;\\myserver\root\default&quot;. The machine name can also be a DNS name or IP
address.</p>
<p>See <u>Object Paths</u></font><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_Object_Paths</font><font
FACE="Arial" SIZE="2">.</p>
</blockquote>
<p>&nbsp;<i></p>
<p>strUser</p>
<blockquote>
</i><p>A pointer to a valid BSTR, which contains the user name you need for a connection.
A NULL value indicates the currently logged on user.</p>
<p>If the user name is from a domain other than the current domain, the string may contain
the domain name and user name, separated by a backslash:</p>
<p>StrUserName = SysAllocString(L&quot;Domain\\UserName&quot;);</p>
</blockquote>
<p>&nbsp;<i></p>
<p>strPassword</p>
<blockquote>
</i><p>A pointer to a valid BSTR, which contains the password you need for a connection. A
NULL value indicates the currently logged on user's current password, while a blank
string, i.e. &quot;&quot;, specifies a valid zero length password.</p>
</blockquote>
<p>&nbsp;<i></p>
<p>strLocale</p>
<blockquote>
</i><p>If NULL, the current locale is used. If not NULL, this parameter must be a valid
BSTR, which indicates the desired locale for information retrieval. For Microsoft locale
identifiers, the format of the string is &quot;MS\xxxx&quot;, where xxxx is a string in
hexadecimal form that indicates the LCID.</p>
<p>For example, American English would appear as &quot;MS\\0x409&quot; (C++ requires two
backslashes because the first is considered an escape character).</p>
<p>The string format is required since WBEM accommodates other localization schemes
besides Microsoft 32-bit LCIDs, such as ISO 639 or RFC 1766. </p>
</blockquote>
<p>&nbsp;<i></p>
<p>lSecurityFlags</p>
<blockquote>
</i><p>Reserved. This must be zero.</p>
</blockquote>
<p>&nbsp;<i></p>
<p>strAuthority</p>
<blockquote>
</i><p>If not NULL this parameter can contain the name of the Windows NT domain in which
to obtain the user to authenticate. This parameter must be passed as follows:
NTLMDOMAIN:&lt;domain name&gt;.</p>
</blockquote>
<p>&nbsp;<i></p>
<p>pCtx</p>
<blockquote>
</i><p>Typically NULL. Otherwise, this is a pointer to an <b>IWbemContext</b> object
required by one or more dynamic class providers The values in the context object must be
specified in the documentation for the providers in question. See <u>Making Calls to CIMOM</u></font><font
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_Making_Calls_to_CIMOM</font><font FACE="Arial"
SIZE="2"> for more information about this parameter.</p>
</blockquote>
<p>&nbsp;<i></p>
<p>ppNamespace</p>
<blockquote>
</i><p>Receives a pointer to an <b>IWbemServices</b> object bound to the specified
namespace. This pointer has a positive reference count. The caller must call <u><b>Release</b></u></font><font
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemServices_Release</font><font FACE="Arial"
SIZE="2"> on the pointer when it is no longer required. This pointer is set to point to
NULL when there is an error.</p>
</font><font FACE="Arial" SIZE="1"><p></font>&nbsp;</p>
</blockquote>
<p>&nbsp;<font FACE="Arial Narrow"><b></p>
<p>Return Values</b></font></p>
<table CELLSPACING="0" BORDER="0" WIDTH="463">
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_ACCESS_DENIED</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The current or specified user
name and password were not valid or authorized to make the connection.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates other unspecified
errors. </font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_NAMESPACE</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The specified namespace did not
exist on the server.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
specified.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_OUT_OF_MEMORY</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
complete the operation.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates the failure of the
remote procedure call (RPC) link between the current process and CIMOM.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call succeeded.</font></td>
</tr>
</table>
<p>&nbsp;<font FACE="Arial" SIZE="1"></p>
<blockquote>
</font><font FACE="Arial Narrow" SIZE="3"><b><p>Note</p>
</b></font><font FACE="Arial" SIZE="2"><p>DCOM-specific error codes also may be returned
if network problems cause you to lose the remote connection to CIMOM.</font></p>
</blockquote>
<p>&nbsp;<b><font FACE="Arial Narrow"></p>
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
<p>IWbemServices</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemServices</font></p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink