Метод IWbemLocator::ConnectServer (wbemcli.h)

Статья
08/27/2023

Метод IWbemLocator::ConnectServer создает подключение через DCOM к пространству имен WMI на компьютере, указанном в параметре strNetworkResource .

SWbemLocator.ConnectServer может подключаться к компьютерам под управлением IPv6, используя IPv6-адрес в параметре strNetworkResource . Дополнительные сведения см. в статье Поддержка IPv6 и IPv4 в WMI.

Синтаксис

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 или Корпорацией Майкрософт, добавьте имя компьютера: "\myserver\root\default". Дополнительные сведения см. в разделе Описание пути объекта пространства имен WMI. Имя компьютера также может быть DNS-именем или IP-адресом. Начиная с Windows Vista , SWbemLocator.ConnectServer может подключаться к компьютерам под управлением IPv6, используя IPv6-адрес. Дополнительные сведения см. в статье Поддержка IPv6 и IPv4 в WMI.

[in] strUser

Указатель на допустимый BSTR, содержащий имя пользователя, необходимое для подключения. Значение NULL указывает на текущий контекст безопасности. Если имя пользователя отличается от текущего домена, строка может содержать имя домена и имя пользователя, разделенные обратной косой чертой.

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

Параметр strUser не может быть пустой строкой. Обратите внимание, что если домен указан в strAuthority, он не должен указываться здесь. Указание домена в обоих параметрах приводит к ошибке недопустимого параметра.

Для указания strUser можно использовать формат имени участника-пользователя (UPN), который Username@DomainName.

[in] strPassword

Указатель на допустимый BSTR , содержащий пароль, необходимый для подключения. Значение NULL указывает на текущий контекст безопасности. Пустая строка "" указывает допустимый пароль нулевой длины.

[in] strLocale

Если значение РАВНО NULL, используется текущий языковой стандарт. Если значение не равно NULL, этот параметр должен быть допустимым значением BSTR, который указывает правильный языковой стандарт для получения информации. Для идентификаторов языкового стандарта Майкрософт строка имеет формат "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 может иметь следующие значения:

пустой
Если оставить этот параметр пустым, используется проверка подлинности NTLM и используется домен NTLM текущего пользователя. Если домен указан в strUser, который является рекомендуемой папкой, то здесь его не следует указывать. Указание домена в обоих параметрах приводит к ошибке недопустимого параметра.
Kerberos:<principal name>
Используется проверка подлинности Kerberos, и этот параметр должен содержать имя участника Kerberos.
NTLMDOMAIN:<доменное имя>
Используется проверка подлинности NT LAN Manager, и этот параметр должен содержать доменное имя NTLM.

[in] pCtx

Как правило, это ЗНАЧЕНИЕ NULL. В противном случае это указатель на объект IWbemContext , необходимый одному или нескольким поставщикам динамических классов. Значения в объекте контекста должны быть указаны в документации для рассматриваемых поставщиков. Дополнительные сведения об этом параметре см. в статье Вызовы WMI.

[out] ppNamespace

Получает указатель на объект IWbemServices , привязанный к указанному пространству имен. Этот указатель имеет положительное число ссылок. Вызывающий объект должен вызывать IWbemServices::Release в указателе, когда это больше не требуется. Для этого указателя задано значение NULL при возникновении ошибки.

Возвращаемое значение

Этот метод возвращает HRESULT , указывающий состояние вызова метода. В следующем списке перечислены значения, содержащиеся в HRESULT.

Коды ошибок, относящиеся к COM, могут быть возвращены, если проблемы с сетью приводят к потере удаленного подключения к WMI.

Эти коды возврата ошибок определяются в файле Wbemcli.h в разделе WMI каталога PSDK \Include. Дополнительные сведения см. в разделе Константы ошибок 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
Header	wbemcli.h (включая Wbemidl.h)
Библиотека	Wbemuuid.lib
DLL	Wbemcore.dll