Interface IWbemLocator

Interface IWbemLocatorŚ@Ś

[This is preliminary documentation and subject to change.]

Use the IWbemLocator 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 IWbemServices_hmm_IWbemServices pointer, which is returned by the ConnectServer method on this interface.

A client or provider that needs CIMOM services first obtains a pointer to the locator using CoCreateInstance or CoCreateInstanceEx, as specified in COM documentation in the Microsoft Platform SDK. The IWbemLocator 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 IWbemLocator::ConnectServer_hmm_IWbemLocator_ConnectServer method, which is the only method on this interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface_hmm_IWbemLocator_QueryInterface	Determines if the current object supports a given interface.
AddRef_hmm_IwbemLocator_AddRef	Increases the object's reference count by 1.
Release_hmm_IWbemLocator_Release	Decrements the object's reference count, and frees the object when the reference count is zero.

IWbemLocator Methods	Description
ConnectServer_hmm_IWbemLocator_ConnectServer	Connects to CIMOM on the specified machine.

‹^# $ K + ›IWbemLocator::QueryInterfaceŚ@Ś

[This is preliminary documentation and subject to change.]

The IWbemLocator::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 IWbemLocator::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 WBEM_S_NO_ERROR 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 + ›IWbemLocator::AddRefŚ@Ś

[This is preliminary documentation and subject to change.]

The IWbemLocator::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 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 + ›IWbemLocator::ReleaseŚ@Ś

[This is preliminary documentation and subject to change.]

The IWbemLocator::Release method decreases the object's reference count by 1.

ULONG 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_IWbemLocator_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 + ›IWbemLocator::ConnectServerŚ@Ś

[This is preliminary documentation and subject to change.]

The IWbemLocator::ConnectServer method connects to CIMOM on the machine specified in the strNetworkResource parameter. This is typically a MicrosoftŽ Windows NTŽ machine or a MicrosoftŽ WindowsŽ 95/98 target machine, which must have an operational CIMOM.

HRESULT IWbemLocator::ConnectServer(

[in] BSTR strNetworkResource,

[in] BSTR strUser,

[in] BSTR strPassword,

[in] BSTR strLocale,

[in] LONG lSecurityFlags,

[in] BSTR strAuthority,

[in] IWbemContext *pCtx,

[out] IWbemServices **ppNamespace

);

Parameters

strNetworkResource

A pointer to a valid BSTR containing the object path of the desired CIMOM and namespace.

For local machine access to the default namespace, use a simple object path: "root\default" or "\\.\root\default."

For access to the default namespace on a remote machine using Distributed COM (DCOM) or Microsoft-compatible networking, include the machine name: "\\myserver\root\default". The machine name can also be a DNS name or IP address.

See Object Paths_hmm_Object_Paths.

strUser

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.

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:

StrUserName = SysAllocString(L"Domain\\UserName");

strPassword

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. "", specifies a valid zero length password.

strLocale

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 "MS\xxxx", where xxxx is a string in hexadecimal form that indicates the LCID.

For example, American English would appear as "MS\\0x409" (C++ requires two backslashes because the first is considered an escape character).

The string format is required since WBEM accommodates other localization schemes besides Microsoft 32-bit LCIDs, such as ISO 639 or RFC 1766.

lSecurityFlags

Reserved. This must be zero.

strAuthority

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:<domain name>.

pCtx

Typically NULL. Otherwise, this is a pointer to an IWbemContext 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 Making Calls to CIMOM_hmm_Making_Calls_to_CIMOM for more information about this parameter.

ppNamespace

Receives a pointer to an IWbemServices object bound to the specified namespace. This pointer has a positive reference count. The caller must call Release_hmm_IWbemServices_Release on the pointer when it is no longer required. This pointer is set to point to NULL when there is an error.

Return Values

WBEM_E_ACCESS_DENIED	The current or specified user name and password were not valid or authorized to make the connection.
WBEM_E_FAILED	This indicates other unspecified errors.
WBEM_E_INVALID_NAMESPACE	The specified namespace did not exist on the server.
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.

Note

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

See Also

IWbemServices_hmm_IWbemServices