IWbemLocator：：ConnectServer 方法 (wbemcli.h)

發行項
03/09/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

有效 BSTR 的指標，其中包含正確 WMI 命名空間的物件路徑。針對預設命名空間的本機存取，請使用簡單的物件路徑：“root\default” 或 “\.\root\default”。若要使用 COM 或 Microsoft 相容網路來存取遠端電腦上的預設命名空間，請包含電腦名稱稱：「\myserver\root\default」。如需詳細資訊，請參閱描述 WMI 命名空間對象路徑。電腦名稱也可以是 DNS 名稱或 IP 位址。從 Windows Vista 開始， SWbemLocator.ConnectServer 可以使用 IPv6 位址來連線到執行 IPv6 的電腦。如需詳細資訊，請參閱 WMI 中的 IPv6 和 IPv4 支援。

[in] strUser

有效 BSTR 的指標，其中包含連線所需的用戶名稱。 NULL 值表示目前的安全性內容。如果使用者名稱來自與目前網域不同的網域，字串可能包含以反斜杠分隔的域名和用戶名稱。

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

strUser 參數不能是空字串。請注意，如果網域是在 strAuthority 中指定，則不得在此指定。在兩個參數中指定定義域會導致參數錯誤無效。

您可以使用UPN) 格式 (用戶主體名稱，這是 Username@DomainName來指定strUser。

[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 的 Long 值。這個參數的零值 (0) ，只會在建立與伺服器的連線之後呼叫 ConnectServer 。這可能會導致程式在伺服器中斷時無限期地回應。下列清單列出 lSecurityFlags 的其他有效值。

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40) )

保留供內部使用。請勿使用。

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80) )

ConnectServer 呼叫會在 2 分鐘內傳回。使用此旗標可防止程式在伺服器中斷時無限期地回應。

[in] strAuthority

此參數包含要驗證之使用者網域的名稱。

strAuthority 可以有下列值：

空白
如果您將此參數保留空白，則會使用NTLM驗證，並使用目前使用者的NTLM網域。如果網域是在 strUser 中指定，這是建議的位置，則不得在此指定。在兩個參數中指定定義域會導致參數錯誤無效。
Kerberos：<principal 名稱>
使用 Kerberos 驗證，此參數應包含 Kerberos 主體名稱。
NTLMDOMAIN：<功能變數名稱>
使用 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)
程式庫	Wbemuuid.lib
Dll	Wbemcore.dll