IWbemServices::OpenNamespace

[This is preliminary documentation and subject to change.]

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.

HRESULT IWbemServices::OpenNamespace(
  [in]  BSTR bstrNamespace,               
  [in]  LONG lFlags,                  
  [in] IWbemContext *pCtx,              
  [out, OPTIONAL] IWbemServices **ppWorkingNamespace,  
  [out, OPTIONAL] IWbemCallResult **ppResult  
);

Parameters

bstrNamespace
The object path to the target namespace. See Namespaces. This namespace can only be relative to the current namespace associated with the IWbemServices interface pointer. This cannot be an absolute path. This parameter cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Reserved. It must be NULL.
ppWorkingNamespace
Receives the object representing 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.
ppResult
Typically NULL. If not NULL, then ppWorkingNamespace must be NULL. In this case, the parameter receives a pointer to a new IWbemCallResult object, and the 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 then set to point to NULL when there is an error, and a new object is not returned.

IMPORTANT  If you use this parameter, then you must set ppResult to point to NULL before calling the method. This is a DCOM rule.

Return Values

WBEM_E_ACCESS_DENIED The user does not have permission to access the requested context.
WBEM_E_FAILED Other unspecified errors.
WBEM_E_INVALID_NAMESPACE The specified namespace does not exist.
WBEM_E_INVALID_PARAMETER An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_OUT_OF_MEMORY There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE The communications link between the current process and CIMOM has failed.
WBEM_NO_ERROR The call succeeded.

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

Remarks

IWbemLocator::ConnectServer 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. See Object Paths.

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 zero.

See Also

Error Objects, IWbemLocator::ConnectServer, Namespaces