Export (0) Print
Expand All

IWbemLocator::ConnectServer method

The IWbemLocator::ConnectServer method creates a connection through DCOM to a WMI namespace on the computer specified in the strNetworkResource parameter.

Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address in the strNetworkResource parameter. For more information, see IPv6 and IPv4 Support in WMI.

Windows Server 2003:  You can only use SWbemLocator.ConnectServer to connect to computers with IPv4 addresses.

Syntax


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

Parameters

strNetworkResource [in]

Pointer to a valid BSTR that contains the object path of the correct WMI namespace. For local access to the default namespace, use a simple object path: "root\default" or "\\.\root\default". For access to the default namespace on a remote computer using COM or Microsoft-compatible networking, include the computer name: "\\myserver\root\default". For more information, see Describing a WMI Namespace Object Path. The computer name also can be a DNS name or IP address. Starting with Windows Vista, SWbemLocator.ConnectServer can connect with computers running IPv6 using an IPv6 address. For more information, see IPv6 and IPv4 Support in WMI.

strUser [in]

Pointer to a valid BSTR, which contains the user name you need for a connection. A NULL value indicates the current security context. If the user name is from a domain different from the current domain, the string may contain the domain name and user name separated by a backslash.

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

The strUser parameter cannot be an empty string. Note that if the domain is specified in strAuthority, then it must not be specified here. Specifying the domain in both parameters results in an invalid parameter error.

You can use the user principal name (UPN) format, which is Username@DomainName to specify the strUser.

strPassword [in]

Pointer to a valid BSTR that contains the password you need for a connection. A NULL value indicates the current security context. A blank string "" specifies a valid zero-length password.

strLocale [in]

If NULL, the current locale is used. If not NULL, this parameter must be a valid BSTR, which indicates the correct locale for information retrieval. For Microsoft locale identifiers, the format of the string is "MS_xxx", where xxx is a string in hexadecimal form that indicates the Local Identification (LCID), for example, American English would appear as "MS_409". If an invalid locale is specified, then the method returns WBEM_E_INVALID_PARAMETER.

Windows 7:  If an invalid locale is specified, then the default locale of the server is used unless there is a server-supported locale provided by the user application.

lSecurityFlags [in]

Long value used to pass flag values to ConnectServer. A value of zero (0) for this parameter results in the call to ConnectServer returning only after connection to the server is established. This could result in your program ceasing to respond indefinitely if the server is broken. The following table lists the other valid values for lSecurityFlags.

ValueMeaning
WBEM_FLAG_CONNECT_REPOSITORY_ONLY
64 (0x40)

Reserved for internal use. Do not use.

WBEM_FLAG_CONNECT_USE_MAX_WAIT
128 (0x80)

The ConnectServer call returns in 2 minutes or less. Use this flag to prevent your program from ceasing to respond indefinitely if the server is broken.

 

strAuthority [in]

This parameter contains the name of the domain of the user to authenticate.

strAuthority can have the following values:

  • blank

    If you leave this parameter blank, NTLM authentication is used and the NTLM domain of the current user is used. If the domain is specified in strUser, which is the recommended location, then it must not be specified here. Specifying the domain in both parameters results in an invalid parameter error.

  • Kerberos:<principal name>

    Kerberos authentication is used and this parameter should contain a Kerberos principal name.

  • NTLMDOMAIN:<domain name>

    NT LAN Manager authentication is used and this parameter should contain an NTLM domain name.

pCtx [in]

Typically, this is NULL. Otherwise, this is a pointer to an IWbemContext object required by one or more dynamic class providers. The values in the context object must be specified in the documentation for the providers in question. For more information about this parameter, see Making Calls to WMI.

ppNamespace [out]

Receives a pointer to an IWbemServices object bound to the specified namespace. This pointer has a positive reference count. The caller must call IWbemServices::Release on the pointer when it is no longer required. This pointer is set to point to NULL when there is an error.

Return value

This method returns an HRESULT that indicates the status of the method call. The following table lists the value contained within an HRESULT.

COM-specific error codes may be returned if network problems cause you to lose the remote connection to WMI.

These error return codes are defined in the Wbemcli.h file in the WMI section of the PSDK \Include directory. For more information see WMI Error Constants.

Return codeDescription
WBEM_E_ACCESS_DENIED

The current or specified user name and password were not valid or authorized to make the connection.

WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_INVALID_NAMESPACE

The specified namespace did not exist on the server.

WBEM_E_INVALID_PARAMETER

A specified parameter is not valid.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_TRANSPORT_FAILURE

This indicates the failure of the remote procedure call (RPC) link between the current process and WMI.

WBEM_E_LOCAL_CREDENTIALS

WMI is passing the user credential on local connection.

WBEM_S_NO_ERROR

The call succeeded.

 

Remarks

Do not specify strUser, strPassword, or strAuthority when making a connection to a local namespace. For more information, see Connecting to WMI on a Remote Computer.

For more information on how to use ConnectServer, see Creating a Connection to a WMI Namespace. Note that the connection to IWbemLocator is one of the connections that you must shut down at the end of your application, as described in Cleaning up and Shutting Down a WMI Application.

Examples

For multiple samples that use the ConnectServer method, see WMI C++ Application Examples.

For an example of using ConnectServer in a C++ code sample to connect to a WMI namespace, see the Check OS bitness in C++ sample in the MSDN Code gallery.

The following C++ code sample describes how to use ConnectServer to connect to a specified namespace. For the complete code sample, including necessary #include files, see the Enable NetBIOS over TCP/IP sample in the MSDN Code gallery.


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; 
    hres = pLoc->ConnectServer(L"ROOT\\CimV2", NULL,NULL, 0, NULL, 0,  0,  &pSvc); 
 
    if (FAILED(hres)) 
    { 
        pLoc->Release(); 
        CoUninitialize(); 
        wcout << "ConnectServer() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
    ...
}

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Wbemcore.dll;
Wbemupgd.dll

See also

IWbemLocator
IWbemServices
Connecting to WMI on a Remote Computer
Creating a WMI Application Using C++

 

 

Show:
© 2014 Microsoft