Export (0) Print
Expand All

SWbemLocator.ConnectServer method

The ConnectServer method of the SWbemLocator object connects to the namespace on the computer that is specified in the strServer parameter. The target computer can be either local or remote, but it must have WMI installed. For examples and a comparison with the moniker type of connection, see Creating a WMI Script.

Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address in the strServer parameter. For more information, see IPv6 and IPv4 Support in WMI.

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

For an explanation of this syntax, see Document Conventions for the Scripting API.

Syntax

objwbemServices = .ConnectServer( _
  [ ByVal strServer ], _
  [ ByVal strNamespace ], _
  [ ByVal strUser ], _
  [ ByVal strPassword ], _
  [ ByVal strLocale ], _
  [ ByVal strAuthority ], _
  [ ByVal iSecurityFlags ], _
  [ ByVal objwbemNamedValueSet ] _
)

Parameters

strServer [in, optional]

Computer name to which you are connecting. If the remote computer is in a different domain than the user account under which you log in, then use the fully qualified computer name. If you do not provide this parameter, the call defaults to the local computer.

Example: server1.network.fabrikam

You also can use an IP address in this parameter. If the IP address is in IPv6 format, the target computer must be running IPv6. An address in IPv4 looks like 111.222.333.444

An IP address in IPv6 format looks like 2010:836B:4179::836B:4179

strNamespace [in, optional]

String that specifies the namespace to which you log on. For example, to log on to the root\default namespace, use root\default. If you do not specify this parameter, it defaults to the namespace that is configured as the default namespace for scripting. For more information, see Creating a WMI Application or Script.

Example: "root\CIMV2"

strUser [in, optional]

User name to use to connect. The string can be in the form of either a user name or a Domain\Username. Leave this parameter blank to use the current security context. The strUser parameter should only be used with connections to remote WMI servers. If you attempt to specify strUser for a local WMI connection, the connection attempt fails. If Kerberos authentication is in use, then the username and password that is specified in strUser and strPassword cannot be intercepted on a network. You can use the UPN format to specify the strUser.

Example: "DomainName\UserName"

Note  If a domain is specified in strAuthority, then the domain must not be specified here. Specifying the domain in both parameters results in an Invalid Parameter error.

strPassword [in, optional]

String that specifies the password to use when attempting to connect. Leave the parameter blank to use the current security context. The strPassword parameter should only be used with connections to remote WMI servers. If you attempt to specify strPassword for a local WMI connection, the connection attempt fails. If Kerberos authentication is in use then the username and password that is specified in strUser and strPassword cannot be intercepted on the network.

strLocale [in, optional]

String that specifies the localization code. If you want to use the current locale, leave it blank. If not blank, this parameter must be a string that indicates the desired locale where information must be retrieved. For Microsoft locale identifiers, the format of the string is "MS_xxxx", where xxxx is a string in the hexadecimal form that indicates the LCID. For example, American English would appear as "MS_409".

strAuthority [in, optional]
ValueMeaning
""

This parameter is optional. However, if it is specified, only Kerberos or NTLMDomain can be used.

Kerberos:

If the strAuthority parameter begins with the string "Kerberos:", then Kerberos authentication is used and this parameter should contain a Kerberos principal name. The Kerberos principal name is specified as Kerberos:domain, such as Kerberos:fabrikam where fabrikam is the server to which you are attempting to connect.

Example: "Kerberos:DOMAIN"

NTLMDomain:

To use NT Lan Manager (NTLM) authentication, you must specify it as NTLMDomain:domain, such as NTLMDomain:fabrikam where fabrikam is the name of the domain.

Example: "NTLMDomain:DOMAIN"

 

If you leave this parameter blank, the operating system negotiates with COM to determine whether NTLM or Kerberos authentication is used. This parameter should only be used with connections to remote WMI servers. If you attempt to set the authority for a local WMI connection, the connection attempt fails.

Note  If the domain is specified in strUser, which is the preferred location, then it must not be specified here. Specifying the domain in both parameters results in an Invalid Parameter error.

iSecurityFlags [in, optional]

Used to pass flag values to ConnectServer.

Flag/valueMeaning
0 (0x0)

A value of 0 for this parameter causes the call to ConnectServer to return only after the connection to the server is established. This could cause your program to stop responding indefinitely if the connection cannot be established.

wbemConnectFlagUseMaxWait
128 (0x80)

The ConnectServer call is guaranteed to return in 2 minutes or less. Use this flag to prevent your program from ceasing to respond indefinitely if the connection cannot be established.

 

objwbemNamedValueSet [in, optional]

Typically, this is undefined. Otherwise, this is an SWbemNamedValueSet object whose elements represent the context information that can be used by the provider that is servicing the request. A provider that supports or requires such information must document the recognized value names, data type of the value, allowed values, and semantics.

Return value

If successful, WMI returns an SWbemServices object that is bound to the namespace that is specified in strNamespace on the computer that is specified in strServer.

Error codes

After the completion of the ConnectServer method, the Err object may contain one of the error codes in the following table.

Error (Name/Dec/Hex)Meaning
wbemErrAccessDenied
2147749891 (0x80041003)

The current or specified user name and password were not valid or authorized to make the connection.

wbemErrFailed
2147749889 (0x80041001)

Unspecified error.

wbemErrInvalidNamespace
2147749902 (0x8004100E)

The specified namespace did not exist on the server.

wbemErrInvalidParameter
2147749896 (0x80041008)

An invalid parameter was specified, or the namespace could not be parsed.

wbemErrOutOfMemory
2147749894 (0x80041006)

Not enough memory to complete the operation.

wbemErrTransportFailure
2147749909

A networking error occurred, preventing normal operation.

Remarks

The ConnectServer method is often used when connecting to an account with a different username and password—credentials—on a remote computer because you cannot specify a different password in a moniker string. For more information, see Connecting to WMI on a Remote Computer.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

The following VBScript code example describes how to connect to a remote computer to obtain Win32_IP4RouteTable data. The domain name that is specified in strDomain is used in strAuthority.

Const intMin = 3600
strComputer = "RemoteComputer" 
strDomain = "DomainName"  
Wscript.StdOut.Write "Please enter your user name:"
strUser = Wscript.StdIn.ReadLine 
Set objPassword = CreateObject("ScriptPW.Password")
Wscript.StdOut.Write "Please enter your password:"
strPassword = objPassword.GetPassword()
Wscript.Echo

Set objSWbemLocator = CreateObject("WbemScripting.SWbemLocator") 
Set objWMIService = objSWbemLocator.ConnectServer(strComputer, _ 
    "root\CIMV2", _ 
    strUser, _ 
    strPassword, _ 
    "MS_409", _ 
    "NTLMDomain:" + strDomain) 
Set colItems = objWMIService.ExecQuery( _
    "SELECT * FROM Win32_IP4RouteTable",,48) 
For Each objItem in colItems
    WScript.Echo "Age in Minutes: " _
        & int(objItem.Age/intMin) & VBNewLine _
    & "Description: " & objItem.Description & VBNewLine _
    & "Destination: " & objItem.Destination & VBNewLine _
    & "InterfaceIndex: " & objItem.InterfaceIndex & VBNewLine _
    & "Mask: " & objItem.Mask & VBNewLine _
    & "Metric1: " & objItem.Metric1 & VBNewLine _
    & "Metric2: " & objItem.Metric2 & VBNewLine _
    & "Metric3: " & objItem.Metric3 & VBNewLine _
    & "Metric4: " & objItem.Metric4 & VBNewLine _
    & "Metric5: " & objItem.Metric5 & VBNewLine _
    & "Name: " & objItem.Name & VBNewLine _
    & "NextHop: " & objItem.NextHop & VBNewLine _
    & "Protocol: " & objItem.Protocol & VBNewLine _
    & "Type: " & objItem.Type
    WScript.Echo
Next

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Type library

Wbemdisp.tlb

DLL

Wbemdisp.dll

See also

SWbemLocator
SWbemServices
Connecting to WMI on a Remote Computer
Creating a WMI Script

 

 

Show:
© 2014 Microsoft