ConnectServer Method

The IWbemLocator.ConnectServer method creates a connection through DCOM to a WMI namespace on the computer specified in the strNetworkResource parameter.

Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address in the strNetworkResource parameter.

Windows Server 2003, Windows XP, and Windows 2000: You can only use SWbemLocator.ConnectServer to connect to computers with IPv4 addresses.

HRESULT ConnectServer(

[in] const BSTR strNetworkResource,

[in] const BSTR strUser,

[in] const BSTR strPassword,

[in] const BSTR strLocale,

[in] LONG lSecurityFlags,

[in] const BSTR strAuthority,

[in] IWbemContext *pCtx,

[out] IWbemServices **ppNamespace

);

METHOD ConnectServer ( _

BYVAL strNetworkResource AS DWORD, _

BYVAL strUser AS DWORD, _

BYVAL strPassword AS DWORD, _

BYVAL strLocale AS DWORD, _

BYVAL lSecurityFlags AS LONG, _

BYVAL strAuthority AS DWORD, _

BYVAL pCtx AS IWbemContext, _

BYREF ppNamespace AS IWbemServices _

) AS LONG

Pointer to a valid BSTR that contains the object path of the correct WMI namespace. For local access to the default namespace, use a simple object path: "root\default" or "\\.\root\default". For access to the default namespace on a remote computer using COM or Microsoft-compatible networking, include the computer name: "\\myserver\root\default". The computer name also can be a DNS name or IP address. Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address.

Pointer to a valid BSTR, which contains the user name you need for a connection. A NULL value indicates the current security context. If the user name is from a domain different from the current domain, the string may contain the domain name and user name separated by a backslash.

The strUser parameter cannot be an empty string. Note that if the domain is specified in strAuthority, then it must not be specified here. Specifying the domain in both parameters results in an invalid parameter error.

You can use the user principal name (UPN) format, which is Username@DomainName to specify the strUser.

Windows 2000 and Windows NT 4.0: You cannot use the user principal name (UPN) format.

Pointer to a valid BSTR that contains the password you need for a connection. A NULL value indicates the current security context. A blank string "" specifies a valid zero-length password.

If NULL, the current locale is used. If not NULL, this parameter must be a valid BSTR, which indicates the correct locale for information retrieval. For Microsoft locale identifiers, the format of the string is "MS_xxx", where xxx is a string in hexadecimal form that indicates the Local Identification (LCID), for example, American English would appear as "MS_409".

Long value used to pass flag values to ConnectServer. A value of zero (0) for this parameter results in the call to ConnectServer returning only after connection to the server is established. This could result in your program hanging indefinitely if the server is broken. The following table lists the other valid values for lSecurityFlags.

Value

Meaning

WBEM_FLAG_CONNECT_REPOSITORY_ONLY

&H40

Reserved for internal use. Do not use.

WBEM_FLAG_CONNECT_USE_MAX_WAIT

128

&H80

The ConnectServer call returns in 2 minutes or less. Use this flag to prevent your program from hanging indefinitely if the server is broken.

Windows 2000 and Windows NT 4.0: This value is not available.

If you leave this parameter blank, NTLM authentication is used and the NTLM domain of the current user is used. If the domain is specified in strUser, which is the recommended location, then it must not be specified here. Specifying the domain in both parameters results in an invalid parameter error.

Kerberos authentication is used and this parameter should contain a Kerberos principal name.

NT LAN Manager authentication is used and this parameter should contain an NTLM domain name.

Typically, this is 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.

Receives a pointer to an IWbemServices object bound to the specified namespace. This pointer has a positive reference count. This pointer is set to point to NULL when there is an error.

This method returns an HRESULT that indicates the status of the method call. The following table lists the value contained within an HRESULT.

COM-specific error codes may be returned if network problems cause you to lose the remote connection to WMI.

These error return codes are defined in the Wbemcli.h file in the WMI section of the PSDK \Include directory. For more information see WMI Error Constants.

Return code	Description
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 WMI.
WBEM_E_LOCAL_CREDENTIALS	WMI is passing the user credential on local connection.
WBEM_S_NO_ERROR	The call succeeded.

Do not specify strUser, strPassword, or strAuthority when making a connection to a local namespace.

Client	Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Server	Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Header	Declared in Wbemcli.h; include Wbemidl.h.
Library	Use Wbemuuid.lib.
DLL	Requires Wbemcore.dll. Requires Wbemupgd.dll.