Syntax

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

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"

Windows 2000, Windows NT 4.0, and Windows Me/98/95:  strUser cannot be specified in the UPN format.

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]

Value	Meaning
""	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/value	Meaning
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 hang 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 hanging 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.

objwbemServices [out]

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.

Return Value

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

See Also

SWbemLocator

SWbemServices

Connecting to WMI on a Remote Computer

Creating a WMI Script

Send comments about this topic to Microsoft

Build date: 6/15/2009