WMI--Windows API--ConnectServer

原文来自MSDN Library for Visual Studio 2008 SP1，翻译部分仅为个人观点，想要看更多信息请看MSDN，如有版权问题请联系QQ 643166601，邮件643166601@qq.com

 

ConnectServer Method of the IWbemLocator Interface
The IWbemLocator::ConnectServer method creates a connection through DCOM to a WMI namespace on the computer specified in the strNetworkResource parameter.
这个IWbemLocator::ConnectServer 方法创建一个连接通过DCOM到一个指定计算机上的strNetworkResource参数到WMI空间。
Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address in the strNetworkResource parameter.
从Windows Vista开始SWbemLocator.ConnectServer可以在strNetworkResource参数中使用计算机运行的IPv6使用的IPv6地址连接。
For more information, see IPv6 and IPv4 Support in WMI.
更多信息，请看IPv6 and IPv4 Support in WMI。
Windows Server 2003, Windows XP, and Windows 2000:  You can only use SWbemLocator.ConnectServer to connect to computers with IPv4 addresses.
Windows Server 2003, Windows XP, 和 Windows 2000:  SWbemLocator.ConnectServer你只能使用IPv4地址连接到计算机。
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
);

Parameters
strNetworkResource
Pointer to a valid BSTR that contains the object path of the correct WMI namespace.
指向一个有效的BSTR包含正确的WMI命名空间的对象路径。
For local access to the default namespace, use a simple object path: "root\default" or "\\.\root\default".
对于本地访问的默认命名空间，使用一个简单对象路径："root\default" 或 "\\.\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".
对于访问默认命名空间，在远程计算机上使用COM或Microsoft兼容网络，包含计算机名称： "\\myserver\root\default"。
For more information, see Describing a WMI Namespace Object Path.
更多信息，看Describing a WMI Namespace Object Path。
The computer name also can be a DNS name or IP address.
计算机名也可以是一个DNS名或IP地址。
Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address.
从Windows Vista开始SWbemLocator.ConnectServer可以使用计算机运行的IPv6使用的IPv6地址连接。
For more information, see IPv6 and IPv4 Support in WMI.
更多信息，请看IPv6 and IPv4 Support in WMI。
strUser
Pointer to a valid BSTR, which contains the user name you need for a connection.
指向一个有效的BSTR内容是用包含你需要连接的用户名。
A NULL value indicates the current security context.
NULL值指示当前安全上下文。
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.
如果用户名来自和当前域不同的域，这个字符串可能包含这个域名和用户名通过反斜杠。
StrUserName = SysAllocString(L"Domain\\UserName");

The strUser parameter cannot be an empty string.
这个strUser参数不能是空字符串。
Note that if the domain is specified in strAuthority, then it must not be specified here.
注意如果在strAuthority指定域，它必须不能在这里指定。
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.
你可以使用用户主体名称(UPN)格式，它是用户名@域名去指定strUser。
Windows 2000 and Windows NT 4.0:  You cannot use the user principal name (UPN) format.
Windows 2000 and Windows NT 4.0:  你不能使用用户主体名称(UPN)格式。
strPassword
Pointer to a valid BSTR that contains the password you need for a connection.
指向一个有效的BSTR包含你须要连接的密码。
A NULL value indicates the current security context.
NULL值指示当前安全上下文。
A blank string "" specifies a valid zero-length password.
空字符串""指定一个有效的0长度密码。
strLocale
If NULL, the current locale is used.
如果是NULL,使用当前区域设置。
If not NULL, this parameter must be a valid BSTR, which indicates the correct locale for information retrieval.
如果是是NULL，这个参数必须是一个有效的BSTR，指示正确的区域设置的信息取得。
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".
对于Microsoft区域设置标识符，字符串格式是"MS_xxx"，其中xxx是十六进制的一个字符串指示本地标识符(LCID)，例如美国英语将显示"MS_409"。
lSecurityFlags
Long value used to pass flag values to ConnectServer.
使用LONG值传递flag值到ConnectServer。
A value of zero (0) for this parameter results in the call to ConnectServer returning only after connection to the server is established.
这个参数的一个值0在调用ConnectServer结果返回仅仅是之后建立到服务器的连接。
This could result in your program hanging indefinitely if the server is broken.
如果服务器坏掉可能你的程序结果无限期地挂起。
The following table lists the other valid values for lSecurityFlags.
以下表列出lSecurityFlags其它有效值。
Value Meaning
WBEM_FLAG_CONNECT_REPOSITORY_ONLY
64
0x40
 Reserved for internal use. Do not use.
 内部使用被保留。不要使用。
WBEM_FLAG_CONNECT_USE_MAX_WAIT
128
0x80
 The ConnectServer call returns in 2 minutes or less.
 这个ConnectServer调用在2分钟或更少返回。
 Use this flag to prevent your program from hanging indefinitely if the server is broken.
 使用这个flag防止如果服务器坏掉你的程序无限期地挂起。
Windows 2000 and Windows NT 4.0:  This value is not available.
Windows 2000 and Windows NT 4.0:  这个值是不可用的。
strAuthority
This parameter contains the name of the domain of the user to authenticate.
这个参数包含认证域的名称。

strAuthority can have the following values:
strAuthority可以有以下值：

blank
If you leave this parameter blank, NTLM authentication is used and the NTLM domain of the current user is used.
如果你留下这个参数为空白，将使用NTLM身份验证并且NTLM域的使用当前用户。
If the domain is specified in strUser, which is the recommended location, then it must not be specified here.
如果在strUser中指定域是被推荐的位置，那么它必须不能在这里指定。
Specifying the domain in both parameters results in an invalid parameter error.
指定域在两个参数中结果在一个参数错误。
Kerberos:<principal name>
Kerberos authentication is used and this parameter should contain a Kerberos principal name.
使用Kerberos身份验证，这个参数应包含一个Kerberos主体名称。
NTLMDOMAIN:<domain name>
NT LAN Manager authentication is used and this parameter should contain an NTLM domain name.
使用NT LAN Manager身份验证这个参数应包含一个NTLM域名。
pCtx
Typically, this is NULL.
通常情况下，这个是NULL。
Otherwise, this is a pointer to an IWbemContext object required by one or more dynamic class providers.
否则，这个是一个指向一个或多个动态类提供的一个IWbemContext对象请求。
The values in the context object must be specified in the documentation for the providers in question.
在上下文对象中的值必须在供应商问的问题文档中指定。
For more information about this parameter, see Making Calls to WMI.
更多信息有关这个参数，请看Making Calls to WMI。
ppNamespace
Receives a pointer to an IWbemServices object bound to the specified namespace.
接收一个指针指向指定命名空间的IWbemServices对象的界限。
This pointer has a positive reference count.
这个指针有一个积极参考数。

The caller must call IWbemServices::Release on the pointer when it is no longer required.
当不再需要时调用者必须在这个指针上调用IWbemServices::Release。
This pointer is set to point to NULL when there is an error.
这个指针设置为NULL时有一个错误。
Return Value
This method returns an HRESULT that indicates the status of the method call.
这个方法返回一个HRESULT，指示方法调用状态。
The following table lists the value contained within an HRESULT.
下表列出的值包含一个HRESULT。
COM-specific error codes may be returned if network problems cause you to lose the remote connection to WMI.
如果网络问题引起你关闭远程连接到的WMI将可以返回COM指定错误代码。
These error return codes are defined in the Wbemcli.h file in the WMI section of the PSDK \Include directory.
在Wbemcli.h文件中的WMI部分的PSDK \Include 目录中定义这些错误返回代码。
For more information see WMI Error Constants.
更多信息请看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.
 这个指示远程程序调用(RPC)链接在当前进程和WMI之间失败。
WBEM_E_LOCAL_CREDENTIALS
 WMI is passing the user credential on local connection.
 WMI传递用户在本地连接的凭据。
WBEM_S_NO_ERROR
 The call succeeded.
 调用成功。

Remarks
Do not specify strUser, strPassword, or strAuthority when making a connection to a local namespace.
生成一个连接到本地命名空间不用指定strUser, strPassword 或 strAuthority。
For more information, see Connecting to WMI on a Remote Computer.
更多信息，请看Connecting to WMI on a Remote Computer。
Example Code
For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.
有关脚本代码例子，请看WMI Tasks for Scripts and Applications和TechNet ScriptCenter脚本库。
For C++ code examples, see WMI C++ Application Examples.
有关C++代码例子，请看 WMI C++ Application Examples。
Requirements
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.
 

See Also
IWbemServices
Connecting to WMI on a Remote Computer
Creating a WMI Application Using C++

 

Send comments about this topic to Microsoft

Build date: 8/15/2007