IWbemLocator::ConnectServer

[This is preliminary documentation and subject to change.]

The IWbemLocator::ConnectServer method connects to CIMOM on the machine specified in the bstrNetworkResource 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 bstrNetworkResource, 
  [in] BSTR bstrUser,
  [in] BSTR bstrPassword,
  [in] BSTR bstrLocale,
  [in] long lSecurityFlags,
  [in] BSTR bstrAuthority,
  [in] IWbemContext *pCtx, 
  [out] IWbemServices **ppNamespace 
);

Parameters

bstrNetworkResource
A pointer to a valid BSTR containing the object path of the desired CIMOM and namespace. For local machine access to the default namespace, for example, 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".

See Object Paths.

bstrUser
A pointer to a valid BSTR, which contains the user name you need for a connection.. This can be NULL if you use the current logged-on user name.
bstrPassword
A pointer to a valid BSTR, which contains the password you need for a connection. This can be NULL, but not a blank string, if you are using the current password. In contrast, treat a blank string as a valid password.
bstrLocale
If NULL, use the current locale. 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. See WBEM Localization Guidelines.

lSecurityFlags
Must be one of the following constants:

If you use WBEM_AUTHENTICATION_DEFAULT, bstrUser, bstrPassword, and bstrAuthority must remain NULL. In this case, log on using the currently logged-on Windows NT LanMan user. If that fails, try the WBEM Guest account (an anonymous logon). If both fail, the user is denied access.

If you use WBEM_AUTHENTICATION_NTLM, set bstrUser and bstrPassword to the desired Windows NT LanMan Domain account and password. Set the bstrAuthority parameter to the LanMan Domain name to which the user account belongs.

If WBEM_AUTHENTICATION_WBEM is specified, set bstrUser and bstrPassword to a valid WBEM user name and its corresponding password. bstrAuthority can be set to either "WBEM" or NULL.

bstrAuthority
TBD
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that produces the class instances. The values in the context object must be specified in the documentation for the provider in question.
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 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 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, 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 A networking error occurred, preventing normal operation.
WBEM_E_SERVER_NOT_FOUND The specified server could not be located.
WBEM_NO_ERROR Success.

See Also

IWbemServices