IWbemServices::OpenNamespace method (wbemcli.h)

Article
10/13/2021

The IWbemServices::OpenNamespace method provides the caller with a new IWbemServices pointer that has the specified child namespace as its operating context. All operations through the new pointer, such as class or instance creation, only affect that namespace. The namespace must be a child namespace of the current object through which this method is called.

Syntax

HRESULT OpenNamespace(
  [in]  const BSTR      strNamespace,
  [in]  long            lFlags,
  [in]  IWbemContext    *pCtx,
  [out] IWbemServices   **ppWorkingNamespace,
  [out] IWbemCallResult **ppResult
);

Parameters

[in] strNamespace

Path to the target namespace. For more information, see Creating Hierarchies within WMI. This namespace can only be relative to the current namespace associated with the IWbemServices interface pointer. This parameter cannot be an absolute path or NULL.

[in] lFlags

This parameter can be set to 0 to make this a synchronous call. To make this a semisynchronous call, set lFlags to WBEM_FLAG_RETURN_IMMEDIATELY, provide a valid pointer for the ppResult parameter, and this call will return immediately. For more information, see Calling a Method.

[in] pCtx

Reserved. This parameter must be NULL.

[out] ppWorkingNamespace

Receives the object that represents the new namespace context. The returned pointer has a positive reference count. The caller must call Release on this pointer when it is no longer needed. This pointer is set to NULL when there are errors. If this parameter is specified, then ppResult must be NULL.

[out] ppResult

Typically NULL. If not NULL, then ppWorkingNamespace must be NULL. In this case, the parameter receives a pointer to a new IWbemCallResult object. If the lFlags parameter is set to WBEM_FLAG_RETURN_IMMEDIATELY this call returns immediately. Then the caller can periodically poll the IWbemCallResult::GetResultServices method until the pointer for the requested namespace becomes available. This parameter is set to point to NULL when there is an error and a new object is not returned.

Note It is important to note that when you use this parameter, you must set ppResult to point to NULL before calling the method. This is a COM rule.

Return value

This method returns an HRESULT indicating the status of the method call. The following list lists the value contained within an HRESULT.

On failure, you can obtain any available information from the COM function GetErrorInfo.

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

Remarks

The IWbemLocator::ConnectServer method can also be used to open the same namespace. The only difference is that the OpenNamespace method allows you to place relative object paths in the Namespace parameter to open child namespaces recursively; IWbemLocator::ConnectServer requires a full object path. For more information, see Describing a WMI Namespace Object Path.

For example, if the current namespace associated with the IWbemServices interface pointer is root, then using Default in the Namespace parameter yields a new pointer bound to the root\default namespace.

The namespace is closed when Release is called and the reference count reaches 0 (zero).

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	wbemcli.h (include Wbemidl.h)
Library	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll