IWbemLocator：：ConnectServer 方法 (wbemcli.h)

项目
03/13/2024

IWbemLocator：：ConnectServer 方法通过 DCOM 创建与 strNetworkResource 参数中指定的计算机上的 WMI 命名空间的连接。

SWbemLocator.ConnectServer 可以使用 strNetworkResource 参数中的 IPv6 地址与运行 IPv6 的计算机连接。有关详细信息，请参阅 WMI 中的 IPv6 和 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
);

参数

[in] strNetworkResource

指向包含正确 WMI 命名空间的对象路径的有效 BSTR 的指针。若要对默认命名空间进行本地访问，请使用简单的对象路径：“root\default”或“\.\root\default”。若要使用 COM 或 Microsoft 兼容的网络来访问远程计算机上的默认命名空间，则需包含计算机名称："\myserver\root\default"。有关详细信息，请参阅描述 WMI 命名空间对象路径。计算机名称还可以是 DNS 名称或 IP 地址。从 Windows Vista 开始， SWbemLocator.ConnectServer 可以使用 IPv6 地址与运行 IPv6 的计算机连接。有关详细信息，请参阅 WMI 中的 IPv6 和 IPv4 支持。

[in] strUser

指向有效 BSTR 的指针，该 BSTR 包含连接所需的用户名。 NULL 值指示当前安全上下文。如果用户名来自与当前域不同的域，则字符串可能包含用反斜杠分隔的域名和用户名。

StrUserName = SysAllocString(L"Domain\UserName");

strUser 参数不能为空字符串。请注意，如果在 strAuthority 中指定了域，则不得在此处指定域。在两个参数中指定域会导致参数错误无效。

可以使用用户主体名称 (UPN) 格式，这是指定 strUserUsername@DomainName。

[in] strPassword

指向包含连接所需密码的有效 BSTR 的指针。 NULL 值指示当前安全上下文。空白字符串“”指定有效的零长度密码。

[in] strLocale

如果 为 NULL，则使用当前区域设置。如果不是 NULL，此参数必须是有效的 BSTR，它指示信息检索的正确区域设置。对于 Microsoft 区域设置标识符，字符串的格式为“MS_xxx”，其中 xxx 是十六进制格式的字符串，指示本地标识 (LCID) ，例如，美国英语将显示为“MS_409”。如果指定了无效的区域设置，该方法将返回 WBEM_E_INVALID_PARAMETER。

Windows 7： 如果指定了无效的区域设置，则使用服务器的默认区域设置，除非用户应用程序提供了服务器支持的区域设置。

[in] lSecurityFlags

用于将标志值传递给 ConnectServer 的长值。此参数的值为零 (0) 会导致对 ConnectServer 的调用仅在与服务器建立连接后返回。如果服务器损坏，这可能会导致程序停止无限期地响应。以下列表列出了 lSecurityFlags 的其他有效值。

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40) )

保留以供内部使用。请勿使用。

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80) )

ConnectServer 调用将在 2 分钟或更短的时间内返回。使用此标志可防止程序在服务器损坏时停止无限期地响应。

[in] strAuthority

此参数包含要进行身份验证的用户的域的名称。

strAuthority 可以具有以下值：

blank
如果将此参数留空，则使用 NTLM 身份验证并使用当前用户的 NTLM 域。如果在 strUser（建议的位置）中指定了域，则不得在此处指定域。在两个参数中指定域会导致参数错误无效。
Kerberos：<principal name>
使用 Kerberos 身份验证，此参数应包含 Kerberos 主体名称。
NTLMDOMAIN：<domain name>
使用 NT LAN Manager 身份验证，此参数应包含 NTLM 域名。

[in] pCtx

通常，这是 NULL。否则，这是指向一个或多个动态类提供程序所需的 IWbemContext 对象的指针。上下文对象中的值必须在相关提供程序的文档中指定。有关此参数的详细信息，请参阅调用 WMI。

[out] ppNamespace

接收指向绑定到指定命名空间的 IWbemServices 对象的指针。此指针具有正引用计数。当不再需要时，调用方必须在指针上调用 IWbemServices：：Release 。发生错误时，此指针设置为指向 NULL 。

返回值

此方法返回指示方法调用状态的 HRESULT。以下列表列出了 HRESULT 中包含的值。

如果网络问题导致你失去与 WMI 的远程连接，可能会返回特定于 COM 的错误代码。

这些错误返回代码在 PSDK \Include 目录的 WMI 部分的 Wbemcli.h 文件中定义。有关详细信息，请参阅 WMI 错误常量。

注解

与本地命名空间建立连接时，请勿指定 strUser、 strPassword 或 strAuthority 。有关详细信息，请参阅连接到远程计算机上的 WMI。

有关如何使用 ConnectServer 的详细信息，请参阅创建与 WMI 命名空间的连接。请注意，与 IWbemLocator 的连接是在应用程序结束时必须关闭的连接之一，如清理和关闭 WMI 应用程序中所述。

示例

有关使用 ConnectServer 方法的多个示例，请参阅 WMI C++ 应用程序示例。

以下 C++ 代码示例介绍如何使用 smi2smir.xml 连接到指定的命名空间。

int _tmain(int argc, _TCHAR* argv[]) 
{ 
    // Initialize COM. ------------------------------------------ 
    HRESULT hres = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED); 
    if (FAILED(hres)) 
    { 
        wcout << "CoInitializeEx() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Obtain the initial locator to Windows Management 
    // on a particular host computer. 
    IWbemLocator *pLoc = NULL; 
    hres = CoCreateInstance(CLSID_WbemLocator, 0, CLSCTX_INPROC_SERVER,IID_IWbemLocator, (LPVOID *)&pLoc); 
    if (FAILED(hres)) 
    { 
        CoUninitialize(); 
        wcout << "CreateInstance failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Connect to WMI through the IWbemLocator::ConnectServer method 
    // Connect to the local ROOT\CIMV2 namespace 
    // and obtain pointer pSvc to make IWbemServices calls. 
    IWbemServices *pSvc = NULL;
    BSTR namespace = SysAllocString(L"ROOT\\CimV2");
    hres = pLoc->ConnectServer(namespace, NULL, NULL, 0, NULL, 0, 0, &pSvc);
    SysFreeString(namespace);
 
    if (FAILED(hres)) 
    { 
        pLoc->Release(); 
        CoUninitialize(); 
        wcout << "ConnectServer() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
    ...
}

要求

要求	值
最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	wbemcli.h (包括 Wbemidl.h)
Library	Wbemuuid.lib
DLL	Wbemcore.dll