IWbemLocator::ConnectServer 메서드(wbemcli.h)

아티클
08/27/2023

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에 대한 포인터입니다. NULL 값은 현재 보안 컨텍스트를 나타냅니다. 사용자 이름이 현재 도메인과 다른 도메인에서 온 경우 문자열에는 백슬래시로 구분된 도메인 이름과 사용자 이름이 포함될 수 있습니다.

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

strUser 매개 변수는 빈 문자열일 수 없습니다. 도메인이 strAuthority로 지정된 경우 여기에 지정해서는 안 됩니다. 두 매개 변수에서 도메인을 지정하면 잘못된 매개 변수 오류가 발생합니다.

Username@DomainName UPN(사용자 계정 이름) 형식을 사용하여strUser를 지정할 수 있습니다.

[in] strPassword

연결에 필요한 암호를 포함하는 유효한 BSTR 에 대한 포인터입니다. NULL 값은 현재 보안 컨텍스트를 나타냅니다. 빈 문자열 ""은 유효한 0 길이 암호를 지정합니다.

[in] strLocale

NULL인 경우 현재 로캘이 사용됩니다. NULL이 아닌 경우 이 매개 변수는 정보 검색에 대한 올바른 로캘을 나타내는 유효한 BSTR이어야 합니다. Microsoft 로캘 식별자의 경우 문자열 형식은 "MS_xxx"입니다. 여기서 xxx는 LCID(로컬 ID)를 나타내는 16진수 형식의 문자열입니다. 예를 들어 미국 영어는 "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 에는 다음 값이 있을 수 있습니다.

비어 있음
이 매개 변수를 비워 두면 NTLM 인증이 사용되고 현재 사용자의 NTLM 도메인이 사용됩니다. 도메인이 권장 위치인 strUser에 지정된 경우 여기에 지정해서는 안 됩니다. 두 매개 변수에서 도메인을 지정하면 잘못된 매개 변수 오류가 발생합니다.
Kerberos:<principal name>
Kerberos 인증이 사용되며 이 매개 변수에는 Kerberos 보안 주체 이름이 포함되어야 합니다.
NTLMDOMAIN:<domain name>
NT LAN 관리자 인증이 사용되며 이 매개 변수에는 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