Método IWbemLocator::ConnectServer (wbemcli.h)

Artículo
08/27/2023

El método IWbemLocator::ConnectServer crea una conexión a través de DCOM a un espacio de nombres WMI en el equipo especificado en el parámetro strNetworkResource .

SWbemLocator.ConnectServer puede conectarse con equipos que ejecutan IPv6 mediante una dirección IPv6 en el parámetro strNetworkResource . Para más información, consulte Compatibilidad con IPv6 e IPv4 en WMI.

Sintaxis

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
);

Parámetros

[in] strNetworkResource

Puntero a un BSTR válido que contiene la ruta de acceso del objeto del espacio de nombres WMI correcto. Para el acceso local al espacio de nombres predeterminado, use una ruta de acceso de objeto simple: "root\default" o "\.\root\default". Para obtener acceso al espacio de nombres predeterminado en un equipo remoto mediante redes COM o compatibles con Microsoft, incluya el nombre de equipo: "\myserver\root\default". Para obtener más información, vea Descripción de una ruta de acceso del objeto de espacio de nombres WMI. El nombre de equipo también puede ser un nombre DNS o una dirección IP. A partir de Windows Vista, SWbemLocator.ConnectServer puede conectarse con equipos que ejecutan IPv6 mediante una dirección IPv6. Para más información, consulte Compatibilidad con IPv6 e IPv4 en WMI.

[in] strUser

Puntero a un BSTR válido, que contiene el nombre de usuario que necesita para una conexión. Un valor NULL indica el contexto de seguridad actual. Si el nombre de usuario es de un dominio diferente del dominio actual, la cadena puede contener el nombre de dominio y el nombre de usuario separados por una barra diagonal inversa.

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

El parámetro strUser no puede ser una cadena vacía. Tenga en cuenta que si el dominio se especifica en strAuthority, no debe especificarse aquí. Si se especifica el dominio en ambos parámetros, se produce un error de parámetro no válido.

Puede usar el formato de nombre principal de usuario (UPN), que es Username@DomainName para especificar strUser.

[in] strPassword

Puntero a un BSTR válido que contiene la contraseña que necesita para una conexión. Un valor NULL indica el contexto de seguridad actual. Una cadena en blanco "" especifica una contraseña válida de longitud cero.

[in] strLocale

Si es NULL, se usa la configuración regional actual. Si no es NULL, este parámetro debe ser un BSTR válido, que indica la configuración regional correcta para la recuperación de información. En el caso de los identificadores de configuración regional de Microsoft, el formato de la cadena es "MS_xxx", donde xxx es una cadena en formato hexadecimal que indica la identificación local (LCID), por ejemplo, el inglés americano aparecería como "MS_409". Si se especifica una configuración regional no válida, el método devuelve WBEM_E_INVALID_PARAMETER.

Windows 7: Si se especifica una configuración regional no válida, la configuración regional predeterminada del servidor se usa a menos que la aplicación de usuario proporcione una configuración regional compatible con el servidor.

[in] lSecurityFlags

Valor largo usado para pasar valores de marca a ConnectServer. Un valor de cero (0) para este parámetro da como resultado la llamada a ConnectServer que devuelve solo después de establecer la conexión con el servidor. Esto podría dar lugar a que el programa dejara de responder indefinidamente si el servidor está roto. En la lista siguiente se enumeran los demás valores válidos para lSecurityFlags.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Reservado para uso interno. No debe usarse.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

La llamada ConnectServer devuelve en 2 minutos o menos. Use esta marca para evitar que el programa no responda indefinidamente si el servidor está roto.

[in] strAuthority

Este parámetro contiene el nombre del dominio del usuario que se va a autenticar.

strAuthority puede tener los siguientes valores:

en blanco
Si deja este parámetro en blanco, se usa la autenticación NTLM y se usa el dominio NTLM del usuario actual. Si el dominio se especifica en strUser, que es la ubicación recomendada, no se debe especificar aquí. Si se especifica el dominio en ambos parámetros, se produce un error de parámetro no válido.
Kerberos:<nombre principal>
Se usa la autenticación Kerberos y este parámetro debe contener un nombre principal de Kerberos.
NTLMDOMAIN:<nombre de dominio>
Se usa la autenticación NT LAN Manager y este parámetro debe contener un nombre de dominio NTLM.

[in] pCtx

Normalmente, esto es NULL. De lo contrario, se trata de un puntero a un objeto IWbemContext requerido por uno o varios proveedores de clases dinámicas. Los valores del objeto de contexto deben especificarse en la documentación de los proveedores en cuestión. Para obtener más información sobre este parámetro, vea Realizar llamadas a WMI.

[out] ppNamespace

Recibe un puntero a un objeto IWbemServices enlazado al espacio de nombres especificado. Este puntero tiene un recuento de referencias positivo. El llamador debe llamar a IWbemServices::Release en el puntero cuando ya no sea necesario. Este puntero se establece en NULL cuando se produce un error.

Valor devuelto

Este método devuelve un valor HRESULT que indica el estado de la llamada al método. En la lista siguiente se muestra el valor contenido en un HRESULT.

Se pueden devolver códigos de error específicos de COM si los problemas de red provocan que pierda la conexión remota a WMI.

Estos códigos de retorno de error se definen en el archivo Wbemcli.h de la sección WMI del directorio PSDK \Include. Para obtener más información, vea Constantes de error de WMI.

Comentarios

No especifique strUser, strPassword o strAuthority al realizar una conexión a un espacio de nombres local. Para obtener más información, consulte Conexión a WMI en un equipo remoto (puede estar en inglés).

Para obtener más información sobre cómo usar ConnectServer, vea Creating a Connection to a WMI Namespace. Tenga en cuenta que la conexión a IWbemLocator es una de las conexiones que debe apagar al final de la aplicación, como se describe en Limpieza y apagado de una aplicación WMI.

Ejemplos

Para obtener varios ejemplos que usan el método ConnectServer , vea Ejemplos de aplicaciones de C++ de WMI.

En el ejemplo de código de C++ siguiente se describe cómo usar smi2smir.xml para conectarse a un espacio de nombres especificado.

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; 
    } 
    ...
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	wbemcli.h (include Wbemidl.h)
Library	Wbemuuid.lib
Archivo DLL	Wbemcore.dll