IWbemLocator::ConnectServer メソッド (wbemcli.h)

  • [アーティクル]

IWbemLocator::ConnectServer メソッドは、strNetworkResource パラメーターで指定されたコンピューター上の WMI 名前空間への接続を DCOM 経由で作成します。

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 へのポインター。 NULL 値は、現在のセキュリティ コンテキストを示します。 ユーザー名が現在のドメインとは異なるドメインの場合、文字列にはドメイン名とユーザー名を円記号で区切って含める場合があります。

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

strUser パラメーターを空の文字列にすることはできません。 ドメインが strAuthority で指定されている場合は、ここで指定しないでください。 両方のパラメーターでドメインを指定すると、無効なパラメーター エラーが発生します。

ユーザー プリンシパル名 (UPN) 形式を使用できます。この形式は、strUser を指定するためにUsername@DomainNameです。

[in] strPassword

接続に必要なパスワードを含む有効な BSTR へのポインター。 NULL 値は、現在のセキュリティ コンテキストを示します。 空白の文字列 "" は、長さ 0 の有効なパスワードを指定します。

[in] strLocale

NULL の場合、現在のロケールが使用されます。 NULL でない場合、このパラメーターは有効な BSTR である必要があります。これは、情報を取得するための正しいロケールを示します。 Microsoft ロケール識別子の場合、文字列の形式は "MS_xxx" で、xxx はローカル ID (LCID) を示す 16 進数形式の文字列です。たとえば、アメリカ英語は "MS_409" と表示されます。 無効なロケールが指定されている場合、メソッドは WBEM_E_INVALID_PARAMETERを返します。

Windows 7: 無効なロケールが指定されている場合、ユーザー アプリケーションによってサーバーでサポートされるロケールがない限り、サーバーの既定のロケールが使用されます。

[in] lSecurityFlags

フラグ値を ConnectServer に渡すために使用される Long 値。 このパラメーターの値が 0 (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 名>

    Kerberos 認証が使用され、このパラメーターには Kerberos プリンシパル名が含まれている必要があります。

  • NTLMDOMAIN:<ドメイン名>

    NT LAN Manager 認証が使用され、このパラメーターには NTLM ドメイン名が含まれている必要があります。

[in] pCtx

通常、これは NULL です。 それ以外の場合、これは、1 つ以上の動的クラス プロバイダーに必要な IWbemContext オブジェクトへのポインターです。 コンテキスト オブジェクトの値は、該当するプロバイダーのドキュメントで指定する必要があります。 このパラメーターの詳細については、「 WMI への呼び出しの作成」を参照してください。

[out] ppNamespace

指定した名前空間にバインドされた IWbemServices オブジェクトへのポインターを受け取ります。 このポインターには正の参照カウントがあります。 呼び出し元は、不要になったときにポインターで IWbemServices::Release を呼び出す必要があります。 このポインターは、エラーが発生した場合に NULL をポイントするように設定されます。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。 次の一覧は、 HRESULT に含まれる値の一覧です。

ネットワークの問題によって WMI へのリモート接続が失われると、COM 固有のエラー コードが返される可能性があります。

これらのエラー リターン コードは、PSDK \Include ディレクトリの WMI セクションの Wbemcli.h ファイルで定義されています。 詳細については、「 WMI エラー定数」を参照してください。

注釈

ローカル名前空間への接続時に strUser、 strPassword、または strAuthority を指定しないでください。 詳細については、「リモート コンピューター上の WMI への接続」を参照してください。

ConnectServer の使用方法の詳細については、「WMI 名前空間への接続の作成」を参照してください。 「WMI アプリケーションのクリーンアップとシャットダウン」で説明されているように、IWbemLocator への接続は、アプリケーションの最後にシャットダウンする必要がある接続の 1 つです。

例

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

こちらもご覧ください

リモート コンピューター上の WMI への接続

C++ を使用した WMI アプリケーションの作成

IWbemLocator

IWbemServices

WBEM_CONNECT_OPTIONS